DOCSEARCHbyAlgolia
Submit Docs

PyUnifi

repository·master·Indexed 42 days ago

https://github.com/finish06/pyunifi

A Python library for interacting with UniFi controllers via their JSON API. It provides a Requests-based implementation to manage clients, access points, guest access, RADIUS users, switch ports, and network statistics. Includes CLI utilities such as unifi-ls-clients, unifi-low-snr-reconnect, and unifi-save-statistics.

Tokens
1.3K
Snippets
2
Records
10
Agent score
4%

What's inside PyUnifi

  1. Install PyUnifi via pip

    master

    Install the pyunifi package using pip to interact with your UniFi controller via Python.

    sudo pip install -U pyunifi

  2. Manage switch ports and power

    master

    Control switch port settings and PoE power via the Controller class.

    • get_switch_port_overrides(target_mac): Get port overrides (index, config ID, PoE mode, name) for a device.
    • switch_port_power_off(target_mac, port_idx): Power off a specific port on a switch.
    • switch_port_power_on(target_mac, port_idx): Power on a specific port on a switch.

  3. Initialize the Controller class

    master

    The Controller class is the primary interface for interacting with a UniFi controller using its JSON interface on port 8443 (HTTPS).

    Parameters:

    • host: The address of the controller host (IP or name).
    • username: The login username.
    • password: The login password.
    • port: The port of the controller host.
    • version: The base version of the controller API (v4, v5, unifiOS, or UDMP-unifiOS).
    • site_id: The site ID to access.
    • ssl_verify: Verify the controller's SSL certificate. Defaults to True. Can be set to False or a path to a custom .pem certificate file.
    from pyunifi.controller import Controller
c = Controller('192.168.1.99', 'admin', 'p4ssw0rd')

  4. Backup and statistics

    master

    Perform administrative tasks like backups and data retrieval.

    Backups:

    • create_backup(): Triggers a backup on the controller (note: this can be resource-intensive).
    • get_backup(targetfile): Creates a backup and downloads it to targetfile (should use .unf extension). Defaults to unifi-backup.unf in the current directory.

    Statistics:

    • get_statistics_last_24h(): Get statistical data for the last 24 hours.
    • get_statistics_24h(endtime): Get statistical data for the 24 hours preceding endtime.

  5. Manage guest access and vouchers

    master

    The Controller class provides methods for managing guest networks and vouchers.

    Guest Authorization:

    • authorize_guest(guest_mac, minutes, up_bandwidth=None, down_bandwidth=None, byte_quota=None, ap_mac=None): Authorize a guest by MAC address for a specific duration.
      • guest_mac: Format aa:bb:cc:dd:ee:ff.
      • minutes: Duration of authorization.
      • up_bandwidth/down_bandwidth: Speed in kbps.
      • byte_quota: Total bytes allowed in MB.
      • ap_mac: Specific AP MAC (UniFi >= 3.x).
    • unauthorize_guest(guest_mac): Revoke guest access.

    Vouchers:

    • create_voucher(number, quota, expire, up_bandwidth=None, down_bandwidth=None, byte_quota=None, note=None): Create a batch of guest vouchers.
    • list_vouchers(**filter): List vouchers using filters like code, quota, used, etc. Example: c.list_vouchers(code='12345-67890').
    • delete_voucher(id): Delete or revoke a voucher by its ID.

  6. Manage clients and access points

    master

    Use the Controller instance to manage network devices and clients.

    Client Management:

    • block_client(mac): Add a client to the block list using its MAC address.
    • unblock_client(mac): Remove a client from the block list.
    • disconnect_client(mac): Force a client to reassociate (useful for poor quality connections).
    • set_client_alias(mac, alias): Set a custom name for a client. Use "" to reset to default.
    • get_clients(): Get a list of all active clients.
    • get_users(): Get a list of all known clients.

    Access Point Management:

    • get_aps(): Get a list of all APs with significant information.
    • restart_ap(mac): Restart an AP by its MAC address.
    • restart_ap_name(name): Restart an AP by its name.

  7. Manage RADIUS users

    master

    Interact with RADIUS users via the Controller class.

    • get_radius_users(): Returns a list of all RADIUS users (name, password, 24-digit user ID, and 24-digit site ID).
    • add_radius_user(name, password): Create a new RADIUS user.
    • update_radius_user(name, password, id): Update an existing user. Requires the 24-digit user ID.
    • delete_radius_user(id): Delete a user. Requires the 24-digit user ID.

  8. CLI Utility: unifi-low-snr-reconnect

    master

    A utility that periodically checks clients for low Signal-to-Noise Ratio (SNR) values and disconnects them to force a reassociation to a better Access Point.

    Usage: Uses the same parameters as unifi-ls-clients, plus settings for intervals and the SNR threshold. The default threshold is 15 dB.

    Example (setting a 30 dB threshold):

    unifi-low-snr-reconnect -c localhost -u admin -p p4ssw0rd -v v3 -s default --minsnr 30

  9. CLI Utility: unifi-save-statistics

    master

    Exports UniFi statistics to a CSV file.

    Example:

    unifi-save-statistics -c localhost -u admin -p p4ssw0rd -v v3 -s default -f filename.csv

  10. CLI Utility: unifi-ls-clients

    master

    A command-line tool to list currently active clients on the network.

    Arguments:

    • -c: Controller address (default: unifi)
    • -u: Controller username (default: admin)
    • -p: Controller password
    • -b: Controller port (default: 8443)
    • -v: Controller base version (e.g., v5)
    • -s: Site ID (UniFi >= 3.x only)
    • -V: Ignore SSL certificates
    • -C: Verify with a specific SSL certificate .pem file

    Example:

    unifi-ls-clients -c localhost -u admin -p p4ssw0rd -v v3 -s default