Configuration Reference

Configuration Reference

EZ-Kea reads settings from three places. Later entries override earlier ones:

1. Built-in defaults
2. ez-kea-settings.json (written by Global Settings in the UI)
3. Environment variables

Application

Variable	Default	Notes
HOST	127.0.0.1	Bind address. Non-loopback values require a real SECRET_KEY.
PORT	8080	Listen port.
SECRET_KEY	dev	Signs sessions and CSRF tokens. Must be set before binding off-loopback; EZ-Kea refuses to start otherwise.
DATABASE_URL	sqlite:///./data/ez-kea.db	Users, 2FA secrets, license key, SMTP settings.
SETTINGS_FILE	./data/ez-kea-settings.json	Where UI-saved Kea paths persist.
BACKUP_DIR	./data/backups/	Config backups created from the UI.

DHCPv4

Variable	Default	Notes
DHCP_CONFIG_FILE	./data/kea-dhcp4.conf	The config file EZ-Kea edits.
DHCP_LEASES_FILE	./data/kea-leases4.csv	Read for the Leases page. In LIVE mode discovery sets /var/lib/kea/kea-leases4.csv.
DHCP_LOG_FILE	./data/kea-dhcp4.log	Read for the Logs page. In LIVE mode discovery sets /var/log/kea/kea-dhcp4.log.
KEA_DHCP4_CMD	kea-dhcp4	Used for syntax checks (-t).

DHCPv6

Variable	Default	Notes
DHCP6_CONFIG_FILE	./data/kea-dhcp6.conf
DHCP6_LEASES_FILE	./data/kea-leases6.csv
DHCP6_LOG_FILE	./data/kea-dhcp6.log
KEA_DHCP6_CMD	kea-dhcp6

Reload behaviour

Variable	Default	Notes
KEA_CTRL_CMD	keactrl	Used by the default reload strategy.
KEA_RELOAD_STRATEGY	keactrl	keactrl runs <KEA_CTRL_CMD> reload. sighup runs docker kill -s HUP <container>. Never inferred.
KEA_DOCKER_CONTAINER	(empty)	Container name for the sighup strategy.

Docker filesystem namespace

Only needed when the Kea binary runs inside a container and sees different paths than EZ-Kea does. Blank means "same as the host path", which is correct for bare-metal installs.

Variable	Default
DHCP_CONFIG_FILE_IN_CONTAINER	(empty)
DHCP_LOG_FILE_IN_CONTAINER	(empty)
DHCP6_CONFIG_FILE_IN_CONTAINER	(empty)
DHCP6_LOG_FILE_IN_CONTAINER	(empty)

See Installation for how these fit together.

The settings file

ez-kea-settings.json holds the same values under snake_case keys, written whenever you save Global Settings in the UI:

{
  "dhcp_config_file": "/etc/kea/kea-dhcp4.conf",
  "dhcp_leases_file": "/var/lib/kea/kea-leases4.csv",
  "dhcp_log_file": "/var/log/kea/kea-dhcp4.log",
  "dhcp6_config_file": "/etc/kea/kea-dhcp6.conf",
  "kea_dhcp4_cmd": "kea-dhcp4",
  "kea_dhcp6_cmd": "kea-dhcp6",
  "kea_ctrl_cmd": "keactrl",
  "kea_reload_strategy": "keactrl",
  "kea_docker_container": ""
}

Environment variables win over this file. If you set DHCP_CONFIG_FILE in a systemd unit, changing the path in the UI will appear to save but the environment value keeps being used on restart — pick one mechanism per setting.

Log file resolution

The Logs page doesn't necessarily read DHCP_LOG_FILE. On non-Docker installs it reads the path out of the loggers[].output_options[].output value in your Kea config, so that hand-edits made outside EZ-Kea are respected. When an in-container log path is configured, it trusts DHCP_LOG_FILE instead, because the value written into Kea's config is a container path the host process can't open.

If the Logs page is empty, check where your Kea config actually points its logger.