Configuration: config.ini
Relevant source files
The following files were used as context for generating this wiki page:The config.ini file is the central static configuration for the Overlord Network Kill Switch application. It is used to enable or disable major features like Pi-hole and Ubiquiti control, define connection parameters for these services, and specify the targets for network control, such as domain groups, firewall rules, and device MAC addresses.
The configuration is loaded once at application startup into a dictionary, which is then passed to the respective controller modules. The application also supports environment variables as fallbacks for some settings. The primary parsing logic is located in the init_config function within the main application controller.
Sources: cgi-bin/controller.py:65-176, AGENTS.md
Configuration Loading Process
At startup, the FastAPI application's lifespan manager calls the init_config function. This function uses Python's configparser library to read and parse the ../etc/config.ini file. The parsed values are loaded into a global app_config dictionary, which is then used to initialize the Pi-hole, Ubiquiti, and MQTT modules.
Sources: cgi-bin/controller.py:65-68, cgi-bin/controller.py:181-183
This diagram illustrates the flow of configuration data from the .ini file to the application's modules.
Sources: cgi-bin/controller.py:179-199
Configuration Sections
The config.ini file is organized into sections, each controlling a specific aspect of the application.
Sources: AGENTS.md, cgi-bin/controller.py:72-158
[general]
This section contains master switches to enable or disable the main functionalities of the application, along with credentials for the Pi-hole instances.
| Option | Description | Type | Example Value |
|---|---|---|---|
ubiquiti_control_enabled | Enables or disables the Ubiquiti control module. Accepts yes, true, 1. | Boolean | true |
pihole_control_enabled | Enables or disables the Pi-hole control module. Accepts yes, true, 1. | Boolean | true |
mqtt_announce_enabled | Enables or disables publishing service status via MQTT Last Will and Testament (LWT). | Boolean | true |
remote_pi_list | A space-separated list of Pi-hole instance IP addresses or hostnames. | String | 192.168.1.5 192.168.1.6 |
remote_pi_password | The admin password for the Pi-hole instances. | String | your_pihole_password |
Sources: cgi-bin/controller.py:72-98, cgi-bin/controller.py:105-113
[mqtt]
This section configures the connection to the MQTT broker, used for integrating with home automation systems like Homebridge.
| Option | Description | Type | Example Value |
|---|---|---|---|
broker | The IP address or hostname of the MQTT broker. | String | localhost |
port | The port number for the MQTT broker. | Integer | 1883 |
lwt_topics | A multiline list of MQTT topics to publish the service's online/offline status (LWT). | String (multiline) | stat/dns_controller/master/service_status |
Sources: cgi-bin/controller.py:141-158
[ubiquiti]
This section defines the connection details for the Ubiquiti UniFi Network Controller.
| Option | Description | Type | Example Value |
|---|---|---|---|
remote_ubiquiti_device | The IP address or hostname of the UniFi Controller. | String | 192.168.1.1 |
remote_ubiquiti_api_key | The API key for authenticating with the UniFi Controller API. | String | your_unifi_api_key |
Sources: cgi-bin/controller.py:121-127, lib/ubiquity/ubiquity.py:63, lib/ubiquity/ubiquity.py:90
[ubiquiti_targets]
This section defines groups of client devices by their MAC addresses. Each option name becomes a target identifier that can be used in API calls.
| Option (Target Name) | Description | Type | Example Value |
|---|---|---|---|
kids_devices | A group of devices to be blocked/unblocked together. | String (multiline) | AA:BB:CC:DD:EE:01\nAA:BB:CC:DD:EE:02 |
The values are parsed into the app_config['ubiquiti_targets'] dictionary.
Sources: cgi-bin/controller.py:128-134, lib/ubiquity/ubiquity.py:69
[ubiquiti_rules]
This section lists the names of firewall rules on the UniFi controller that can be enabled or disabled via the API. Each rule name is a key, and the value is parsed but not used, effectively creating a set of manageable rule names.
| Option (Rule Name) | Description | Type | Example Value |
|---|---|---|---|
Block-Streaming-Services | The exact name of a firewall rule in the UniFi controller. | String (multiline) | Block-Streaming-Services |
The rule names are loaded into app_config['ubiquiti_rules']. The UbiquitiOverlord class later fetches the full rule details, including the _id, using these names.
Sources: cgi-bin/controller.py:136-140, lib/ubiquity/ubiquity.py:78, lib/ubiquity/ubiquity.py:155-163
[block_domains] and [allow_domains]
These sections define named groups of domains to be managed on the Pi-hole instances. The domains are treated as regular expressions.
[block_domains]: Defines domains to be added to the Pi-hole's denylist (blacklist).[allow_domains]: Defines domains to be added to the Pi-hole's allowlist (whitelist).
| Option (Group Name) | Description | Type | Example Value |
|---|---|---|---|
hbomax | A group of domains related to a specific service (e.g., HBO Max). | String (multiline) | hbo.com\nhbomax.com |
school_work | A group of domains required for school work. | String (multiline) | google.com\nwikipedia.org |
These groups are loaded into app_config['block_domains'] and app_config['allow_domains'] respectively.
Sources: cgi-bin/controller.py:100-104, lib/pihole/base.py:33-34, lib/pihole/pihole.py:84-87
In-Memory app_config Structure
The init_config function transforms the config.ini file into a nested Python dictionary. This diagram shows the resulting structure of the app_config object.
Sources: cgi-bin/controller.py:67-176
Environment Variable Fallbacks
Several configuration options can be provided via environment variables, which serve as a fallback if the corresponding value is not found in config.ini. This is particularly useful for containerized deployments.
config.ini Setting | Environment Variable |
|---|---|
[general].remote_pi_list | REMOTE_PI_LIST |
[general].remote_pi_password | REMOTE_PI_PASSWORD |
[ubiquiti].remote_ubiquiti_device | REMOTE_UBIQUITI_DEVICE |
[ubiquiti].remote_ubiquiti_api_key | REMOTE_UBIQUITI_API_KEY |
[mqtt].broker | MQTT_BROKER |
[mqtt].port | MQTT_PORT |
Sources: README.md:31-38, cgi-bin/controller.py:107-113, cgi-bin/controller.py:123-127, cgi-bin/controller.py:144-152
Summary
The config.ini file is a critical component that provides a clear and maintainable way to tailor the Overlord Network Kill Switch to a specific home network environment. It decouples the core logic from the operational parameters, allowing users to define targets for Pi-hole and Ubiquiti, manage credentials, and toggle major features without modifying the source code. Its structure directly maps to the application's internal configuration object, ensuring a straightforward relationship between the file and the running service.