Ubiquiti Integration Library

Relevant source files

The following files were used as context for generating this wiki page:

• lib/ubiquity/ubiquity.py
• cgi-bin/controller.py
• AGENTS.md
• README.md
• node_red_flows/dns.json
• etc/webserver_requirements.txt

The Ubiquiti Integration Library provides a high-level interface to interact with a Ubiquiti Network Controller. It is a core component of the Overlord Network Kill Switch project, enabling the management of firewall rules and client device network access. The library is encapsulated within the UbiquitiOverlord class and exposed through a set of FastAPI endpoints.

This module is designed to be initialized and used by the main controller.py application. It abstracts the complexities of the Ubiquiti API, offering simple methods to enable/disable firewall rules and block/unblock devices identified by their MAC addresses. This functionality is crucial for implementing parental controls and focus time features through HomeKit.

Sources: lib/ubiquity/ubiquity.py, cgi-bin/controller.py:121-123, README.md:5-8

Architecture and Core Components

The integration is centered around the UbiquitiOverlord class, which manages the state, configuration, and communication with the Ubiquiti controller.

Sources: lib/ubiquity/ubiquity.py:60-509

UbiquitiOverlord Class

This Pydantic BaseModel is the main entry point for all Ubiquiti-related operations. It holds the session, configuration, API URLs, and a cache of firewall rules. An instance of this class is created and managed within the application's lifespan.

Sources: lib/ubiquity/ubiquity.py:60-120, cgi-bin/controller.py:122, cgi-bin/controller.py:171

The diagram below shows the key attributes and methods of the UbiquitiOverlord class.

Initialization

The Ubiquiti module is initialized during the application startup within the lifespan context manager in controller.py. It is only initialized if ubiquiti_control_enabled is set to True in the configuration. The ubiquity.init(app_config) function creates a global udm instance of the UbiquitiOverlord class.

Sources: cgi-bin/controller.py:170-172, lib/ubiquity/ubiquity.py:512-515

Configuration

The library is configured through ../etc/config.ini and corresponding environment variables. The main application parses these settings and passes them to the UbiquitiOverlord constructor.

Section	Key	Environment Variable	Description
[general]	ubiquiti_control_enabled	-	Enables or disables the entire Ubiquiti integration. Must be true or yes.
[ubiquiti]	remote_ubiquiti_device	REMOTE_UBIQUITI_DEVICE	The IP address or hostname of the UniFi controller.
[ubiquiti]	remote_ubiquiti_api_key	REMOTE_UBIQUITI_API_KEY	The API key for authenticating with the UniFi controller.
[ubiquiti_targets]	(dynamic)	-	Defines groups of MAC addresses. The key is the group name (e.g., kids_devices), and the value is a newline-separated list of MAC addresses.
[ubiquiti_rules]	(dynamic)	-	Defines firewall rule names to be managed. The key is an arbitrary provider name, and the value is a newline-separated list of rule names.

Sources: cgi-bin/controller.py:84-88, cgi-bin/controller.py:108-120, README.md:40-46, lib/ubiquity/ubiquity.py:108-109

Connection Management

Connection to the Ubiquiti controller is managed by the first_connect() method. The current implementation uses an API key for authentication, which simplifies the connection process. The requests library is used for all HTTP communication.

The first_connect() method is called by check_logged_in() if a session is not already active. It sets up a requests.Session and adds the X-API-KEY header for all subsequent requests. The previous username/password login flow has been deprecated.

Sources: lib/ubiquity/ubiquity.py:192-200, lib/ubiquity/ubiquity.py:277-285, etc/webserver_requirements.txt:29

This sequence diagram illustrates the connection and authentication flow.

Firewall Rule Management

The library provides functionality to get the status of and change the state of firewall rules.

Rule Parsing and Caching

Firewall rules are fetched from the controller via the parse_firewall_rules() method. The results are stored in the firewall_rules dictionary, mapping the rule name to the rule's full JSON object from the API. To avoid excessive API calls, the rules are cached for a default of 60 seconds (rule_cache_ttl). The check_rules_freshness() method ensures the cache is updated before any status check or state change.

Sources: lib/ubiquity/ubiquity.py:150-184, lib/ubiquity/ubiquity.py:301-315

Changing Rule State

The change_rule() method handles enabling or disabling a firewall rule. It takes a desired status ("enabled" or "disabled") and a rule name as input.

The process is as follows:

1. Verifies the user is logged in and the rule cache is fresh.
2. Looks up the rule's _id from the cached firewall_rules dictionary.
3. Constructs a payload containing the rule _id and the new boolean enabled state.
4. Sends a PUT request to the batch update endpoint (/proxy/network/v2/api/site/default/firewall-policies/batch).
5. Refreshes the rule cache to reflect the change.
6. Returns the new status.

Sources: lib/ubiquity/ubiquity.py:356-417

This flowchart shows the logic for changing a firewall rule.

Device (Client) Management

The library can block and unblock client devices by sending commands to the station manager (stamgr) API endpoint. Devices are grouped by target names in the [ubiquiti_targets] configuration section.

The change_device() method orchestrates this. It iterates through all MAC addresses defined for a given target group and sends the appropriate command (block-sta for "offline" or unblock-sta for "online").

Sources: lib/ubiquity/ubiquity.py:420-474, cgi-bin/controller.py:114-118

This flowchart illustrates the device blocking/unblocking process.

API Endpoints

The functionality of the UbiquitiOverlord class is exposed via a FastAPI APIRouter. These endpoints are the primary interface for external services like Node-RED to interact with the Ubiquiti controller.

Method	Path	Function	Description
GET	/ubiquiti/status_rule/{target}	get_status_rule	Returns the current status (true/false) of a firewall rule.
GET	/ubiquiti/enable_rule/{target}	set_enable_rule	Enables a specific firewall rule.
GET	/ubiquiti/disable_rule/{target}	set_disable_rule	Disables a specific firewall rule.
GET	/ubiquiti/status_device/{target}	get_status_target	Returns the current status (online/offline) of a device group.
GET	/ubiquiti/enable_device/{target}	set_enable_target	Unblocks all devices in a target group.
GET	/ubiquiti/disable_device/{target}	set_disable_target	Blocks all devices in a target group.
GET	/ubiquiti/refresh	refresh_rules	Forces a refresh of the firewall rule cache.

Sources: lib/ubiquity/ubiquity.py:480-509, AGENTS.md:50-59

The following sequence diagram shows how Node-RED interacts with these endpoints to change a firewall rule's state.

Summary

The Ubiquiti Integration Library is a vital module that connects the Overlord Network Kill Switch to the UniFi Network Controller. By providing a clean, API-key-based, and robust interface for managing firewall rules and device access, it enables the project's core automation features. Its use of caching and a well-defined class structure makes it an efficient and maintainable solution for network control.

Sources: README.md:5-8, lib/ubiquity/ubiquity.py