Configuration: Environment Variables

Relevant source files

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

• README.md
• cgi-bin/controller.py
• AGENTS.md
• lib/ubiquity/ubiquity.py
• lib/pihole/base.py
• lib/pihole/pihole_router.py

The Overlord Network Kill Switch application utilizes a hybrid configuration model, primarily driven by a config.ini file, but with robust support for environment variables. Environment variables are essential for containerized deployments (e.g., Docker, Podman) and provide a convenient way to supply sensitive information or override default settings without modifying configuration files.

The application logic is designed to treat environment variables as a fallback. During initialization, the system first attempts to read configuration values from ../etc/config.ini. If a specific setting is not found in the file, it then attempts to retrieve it from the corresponding environment variable. This ensures flexibility across different deployment scenarios.

Sources: cgi-bin/controller.py:70-169, README.md:32-40

Configuration Loading Flow

The configuration is loaded at application startup within the init_config function. The process prioritizes the config.ini file and uses environment variables as a secondary source.

The following diagram illustrates the fallback logic for loading a configuration parameter.

This diagram shows that for each configuration key, the application first checks config.ini. If the key is absent, it then checks for a corresponding environment variable.

Sources: cgi-bin/controller.py:70-169

Environment Variable Summary

The following environment variables are recognized by the application, primarily as fallbacks for config.ini settings.

Variable	Description	Default Value (if not set)	Sources
REMOTE_PI_LIST	A space-separated list of Pi-hole instance IP addresses or hostnames.	None	README.md:34, cgi-bin/controller.py:101-105
REMOTE_PI_PASSWORD	The admin password for the Pi-hole instances.	None	README.md:33, cgi-bin/controller.py:107-111
MQTT_BROKER	The IP address or hostname of the MQTT broker.	localhost	README.md:35, cgi-bin/controller.py:144-148
MQTT_PORT	The port number for the MQTT broker.	1883	README.md:36, cgi-bin/controller.py:149-155
REMOTE_UBIQUITI_DEVICE	The IP address or hostname of the UniFi controller.	None	README.md:37, cgi-bin/controller.py:118-123
REMOTE_UBIQUITI_API_KEY	The API key for authenticating with the UniFi controller API.	None	README.md:38, cgi-bin/controller.py:118-123
DNS_SERVERS	A comma-separated list of DNS server IPs. Used for container setup.	None	README.md:32

An example envfile for use with container runtimes like Podman is provided in the repository.

DNS_SERVERS=<DNS_SERVER_IP_1>,<DNS_SERVER_IP_2>
REMOTE_PI_PASSWORD=<YOUR_REMOTE_PI_PASSWORD>
REMOTE_PI_LIST="<PI_1> <PI_2> <PI_3>"
MQTT_BROKER=<MQTT_BROKER_IP>
MQTT_PORT=<MQTT_BROKER_PORT>
REMOTE_UBIQUITI_DEVICE=<YOUR_UNIFI_DEVICE_IP>
REMOTE_UBIQUITI_API_KEY=<YOUR_UNIFI_API_KEY>

Sources: README.md:42-49

Component-Specific Configuration

Pi-hole Integration

The Pi-hole modules (PiHoleOverlord and MasterEnabler) are configured using parameters loaded from REMOTE_PI_LIST and REMOTE_PI_PASSWORD.

1. The init_config function in controller.py loads these values into the app_config dictionary.
2. The pihole_router.init() function is called, which instantiates PiHoleOverlord and MasterEnabler.
3. The BaseHTTPHandler class, which both Pi-hole handlers inherit from, receives the app_config and sets the piList and password attributes.

This sequence shows how environment variable values are propagated from the main application controller down to the specific handler classes.

Sources: cgi-bin/controller.py:99-111, lib/pihole/pihole_router.py:28-35, lib/pihole/base.py:20-27

Ubiquiti Integration

The Ubiquiti controller integration is configured via REMOTE_UBIQUITI_DEVICE and REMOTE_UBIQUITI_API_KEY.

1. init_config in controller.py loads the environment variables REMOTE_UBIQUITI_DEVICE and REMOTE_UBIQUITI_API_KEY as fallbacks.
2. These values are stored in the app_config dictionary under the keys ubiquiti_device and ubiquiti_api_key.
3. During application startup, ubiquity.init(app_config) is called, which instantiates the UbiquitiOverlord class.
4. The UbiquitiOverlord constructor uses these values to set its controller and ubiquiti_api_key attributes, which are used to build API URLs and authenticate.

# cgi-bin/controller.py:117-123
            for i in ["DEVICE", "API_KEY"]:
                key = "ubiquiti_%s" % (i.lower())
                app_config[key] = config.get(
                    "ubiquiti",
                    f"remote_{key}",
                    fallback=os.environ.get(f"REMOTE_UBIQUITI_{i}"),
                )

# lib/ubiquity/ubiquity.py:73-86
        super().__init__(
            app_config=app_config,
            macs=app_config["ubiquiti_targets"],
            controller=app_config["ubiquiti_device"],
            session=None,
            base_api_url=f"https://{app_config['ubiquiti_device']}/proxy/network/api",
            base_api_v2_url=f"https://{app_config['ubiquiti_device']}/proxy/network/v2/api",
            # ...
            ubiquiti_api_key=app_config["ubiquiti_api_key"],
        )

Sources: cgi-bin/controller.py:116-123, lib/ubiquity/ubiquity.py:73-86

MQTT Integration

The MQTT client, used for publishing status updates (Last Will and Testament), is configured using MQTT_BROKER and MQTT_PORT.

1. The init_config function loads these variables, applying default values of localhost and 1883 if they are not found in config.ini or the environment.
2. If MQTT is enabled, the publish_to_mqtt function is called, which uses these values from the app_config["mqtt"] dictionary to connect to the broker.

Sources: cgi-bin/controller.py:142-155, AGENTS.md:52-53

Summary

Environment variables play a crucial role in the configuration of the Overlord Network Kill Switch, providing a necessary layer of abstraction for container-based deployments and for managing sensitive credentials. The application's fallback mechanism ensures that settings from a config.ini file are prioritized, but environment variables can seamlessly provide any missing values. This dual approach offers both the structured readability of an INI file and the deployment flexibility of environment variables.

Sources: README.md:32-49, cgi-bin/controller.py:70-169