Customizing Firewall Rules
Relevant source files
The following files were used as context for generating this wiki page:The Overlord Network Kill Switch provides functionality to enable and disable firewall rules on a Ubiquiti Network Controller. This feature is designed to simplify network access control for non-technical users, allowing for one-touch toggling of predefined rules via integrations like HomeKit. The core logic is encapsulated within the UbiquitiOverlord class, which interacts directly with the Ubiquiti Network API.
This system works by mapping simple names defined in a configuration file to specific firewall rules on the controller. The application then exposes a set of REST API endpoints to check the status of these rules or change their state (enabled/disabled). This allows external systems, such as Node-RED, to control network policies based on MQTT messages from home automation platforms.
Sources: README.md, lib/ubiquity/ubiquity.py:1-20, cgi-bin/controller.py:80-90
Architecture and Core Components
The firewall rule management is handled by the UbiquitiOverlord class, which is initialized and managed by the main FastAPI application.
*Sources: lib/ubiquity/ubiquity.py, cgi-bin/controller.py *
UbiquitiOverlord Class
The UbiquitiOverlord class is the central component for all interactions with the Ubiquiti controller. It manages the API session, fetches and caches firewall rules, and sends commands to modify their state.
The diagram below shows the key attributes and methods of the UbiquitiOverlord class related to firewall rule management.
Diagram showing the structure of the UbiquitiOverlord class.
*Sources: lib/ubiquity/ubiquity.py:59-106, 158-185, 335-420 *
Initialization
The UbiquitiOverlord module is initialized during the FastAPI application's startup lifespan event if ubiquiti_control_enabled is set to true in the configuration. The main controller reads the configuration, initializes the ubiquity.udm global instance, and includes the associated API router.
This flowchart illustrates the initialization process for the Ubiquiti module.
Sources: cgi-bin/controller.py:79-82, 209-211, 222-224
Configuration
Firewall rule management must be enabled and configured in the config.ini file. The application reads this file on startup to get the Ubiquiti controller details and the names of the firewall rules to be managed.
Sources: cgi-bin/controller.py:68-151
config.ini Settings
The following table describes the relevant sections and keys in config.ini.
| Section | Key | Description | Source File |
|---|---|---|---|
[general] | ubiquiti_control_enabled | Must be true or yes to enable the Ubiquiti integration. | cgi-bin/controller.py:79-82 |
[ubiquiti] | remote_ubiquiti_device | The IP address or hostname of the Ubiquiti Network Controller. | cgi-bin/controller.py:118-124 |
[ubiquiti] | remote_ubiquiti_api_key | The API key for authenticating with the Ubiquiti Network API. | cgi-bin/controller.py:118-124 |
[ubiquiti_rules] | (custom rule names) | A list of user-defined names, where each name corresponds to a firewall rule's name on the controller. | cgi-bin/controller.py:133-137 |
Example [ubiquiti_rules] section:
[ubiquiti_rules]
# Each line is a name of a firewall rule on the controller
school_work_blocker
streaming_service_throttle
Sources: cgi-bin/controller.py:133-137
API Endpoints
The system exposes several API endpoints under the /ubiquiti prefix to interact with the firewall rules.
| Method | Endpoint | Description | Source File |
|---|---|---|---|
GET | /ubiquiti/status_rule/{target} | Get the current status (true/false) of a rule. | lib/ubiquity/ubiquity.py:488-490 |
GET | /ubiquiti/enable_rule/{target} | Enable a specific firewall rule. | lib/ubiquity/ubiquity.py:502-504 |
GET | /ubiquiti/disable_rule/{target} | Disable a specific firewall rule. | lib/ubiquity/ubiquity.py:507-509 |
GET | /ubiquiti/refresh | Force a refresh of the local firewall rule cache. | lib/ubiquity/ubiquity.py:512-516 |
*Sources: lib/ubiquity/ubiquity.py:482-516, AGENTS.md *
Firewall Rule Management Logic
The logic for managing firewall rules involves fetching, caching, and updating them via the Ubiquiti API.
Rule Parsing and Caching
When a request is made, the system first checks if the local rule cache is fresh using check_rules_freshness(). By default, the cache is valid for 60 seconds (rule_cache_ttl). If the cache is stale, parse_firewall_rules() is called. This method sends a GET request to the controller's firewall policies endpoint, retrieves all rules, and updates the internal firewall_rules dictionary with the full rule object for each rule name defined in the configuration.
This flowchart details the process of checking cache freshness and parsing rules from the controller.
Sources: lib/ubiquity/ubiquity.py:158-185, 320-333
Changing a Rule's State
The change_rule method handles enabling or disabling a firewall rule. It validates the requested state and rule name, ensures the rule cache is fresh, and then constructs a payload to send to the Ubiquiti API. The API call is a PUT request to a batch update endpoint, sending an array containing the rule's _id and the new enabled state (true or false). After the change, parse_firewall_rules() is called again to refresh the local state.
The sequence diagram below illustrates the process of disabling a firewall rule.
This sequence diagram shows the flow for changing a firewall rule's state.
Sources: lib/ubiquity/ubiquity.py:382-420
Integration with Node-RED
The API endpoints are designed to be called by orchestration tools like Node-RED. The provided dns.json flow demonstrates how an MQTT message can trigger a call to the firewall rule endpoints. A "Common Parsing" node extracts the target rule name and the desired action from the MQTT topic, and a function node constructs the correct URL for the FastAPI server.
This flowchart shows how Node-RED processes an MQTT command to change a firewall rule.
Sources: node_red_flows/dns.json
Summary
The firewall rule customization feature provides a robust and abstracted way to control network policies on a Ubiquiti controller. By leveraging a simple configuration file and a clear REST API, it integrates smoothly into the broader home automation ecosystem, allowing users to toggle complex network rules with a single action from a user interface like HomeKit. The UbiquitiOverlord class effectively manages the complexities of API authentication, rule parsing, and state management, providing a reliable service for the Overlord Network Kill Switch project.
*Sources: README.md, lib/ubiquity/ubiquity.py *