panel.conf(5)

panel configuration file

Name

panel.conf — panel configuration file

Description

panel.conf is read by panel-masterd(8) and by each process it starts. Every directive has a default, so a working configuration is short; the installed example sets only what a given machine is likely to differ on.

Directives are one per line:

key = value

A ‘#’ begins a comment. Values are not quoted. Where a directive takes a list, the entries are separated by commas.

General

db path: The panel database. Created if absent, and migrated in place at startup. Default /var/db/panel/panel.db.
module_dir path: Where installed modules are looked for. Each subdirectory containing a module.json is a module. Default /usr/local/share/panel/modules.
web_dir path: The static interface, and the manual under docs/. Default /usr/local/share/panel/web.
dev yes| no: Relaxes production defaults and logs more. Not for a machine anyone else can reach. Default no.

Supervisor

panel_user account: The account the API tier runs as, and the account given read access to the private key when tls_self_signed is set. Default _panel.
panel_group group: The group of the module daemons' sockets and their directory, so panel-api(8) can reach them and the module daemons cannot reach each other. Default _panel.
module_group group: The group of the broker's socket and of the directory it is in (since 1.147.0): each module daemon's own account (_panel-id) is in it, and so is panel_user. The master makes the group, the accounts, and the memberships at every start. Default _panel-mod.
dmi_tables path: The firmware's tables, which the master reads at start for the kind of memory a PC has (since 1.148.0), and passes to the System module. Default /sys/firmware/dmi/tables/DMI.
module_useradd command, module_groupadd command, module_usermod command: For tests: the tools the master makes the module accounts and their group with. Defaults /usr/sbin/useradd, /usr/sbin/groupadd and /usr/sbin/usermod.
sbin_dir path: Where panel-api(8) and panel-brokerd(8) are installed. Default /usr/local/sbin.
libexec_dir path: Where module daemons are installed. A module without an exec in its manifest is started from libexec_dir/panel-mod-⟨id⟩. Default /usr/local/libexec/panel.
modules_disabled id,id ...: Modules present in module_dir that are forced off: not started, their verbs refused, and not offered on the Modules page. Wins over modules_state, and applies to base modules too.
modules_state path: Which modules are enabled, as chosen on the Modules page. Written by the broker and nobody else; read by the master, which starts and stops module daemons to match within about a second. A module the file does not mention is enabled. Default /var/db/panel/modules/state.json.
dpkg_status path: The dpkg database, read to tell whether a module's packages are installed before it is enabled. Default /var/lib/dpkg/status.
modules_catch_up yes| no: Whether, after an update, the broker installs by itself the packages the new version gives a module that is on and that are not installed yet. It waits until the update is confirmed and for any job running, installs one module at a time as the Modules page's “Install what it needs” does, and does so once for each version, also when that fails. Default yes.
vpn_up_at_start yes| no: Whether the broker brings the VPN tunnel up when it starts (1.134.0): with the VPN module on, a tunnel configured, and the tunnel not taken down on the VPN page since it last changed; tried every 30 seconds until it is up. Default yes.
os_updates yes| no: Whether the broker looks after Debian's own updates (1.129.0): each night, in this machine's slot between 02:00 and 05:00, it installs what the machine's apt sources offer for its installed packages, unless that is switched off on the Maintenance page; and it looks at whether a restart is needed. It never restarts the machine itself. With no nothing of this runs, not even the look; the Maintenance page can still install them by hand. Default yes.
update_url url: The download site panel-api looks at once a day for a new version of the panel (1.174.0): its latest.json, believed only when latest.json.sig is the signature of the key built into the panel, names the release for this kind of machine, which is fetched, checked and offered on the Maintenance page to be installed. The look can be switched off there. Default: the address the release was built with (UPDATE_URL or DOWNLOAD_URL); empty, nothing is looked for.
debian_keyring path: The keys a module bundle must be signed with: installing one from the Modules page trusts Debian's own signature and nothing else. Default /usr/share/keyrings/debian-archive-keyring.gpg.
containers_on command: What switching Containers on (which switching Self-hosted on does) runs once Podman is installed: one command, its arguments separated by commas. Default systemctl enable --now podman.socket.
containers_socket path: Podman's API socket, through which the broker lists the containers. Default /run/podman/podman.sock.
containers_systemctl command: The command, with any arguments of its own separated by commas, that starts, stops or restarts one of the panel's containers; it is given --no-block, the action and the container's unit. For tests. Default systemctl.
media_state_dir path: Where the broker keeps the panel's key for Jellyfin (it was Media's). Default /var/db/panel/media.
apps_state_dir path: Where the broker records which apps are on, and that Syncthing's password was set. Default /var/db/panel/apps.
apps_urls id=url, ...: Where apps answer the panel, by app, for tests: for example jellyfin=http://127.0.0.1:1234. When set, credentials are sent without checking which account holds the port. Default: each app on 127.0.0.1 at its own port.
apps_folders folder=path, ...: The folders an app is first offered, by folder, for tests (media, sync); they are chosen on the Self-hosted page. Default: each recipe's own (/srv/media, /srv/sync).
apps_systemctl command: The command, with any arguments of its own separated by commas, that starts and stops the apps' units. For tests. Default systemctl.
apps_dns_every duration: How often the broker looks at the machine's name servers (1.137.0): when they come or change, every running app started before is restarted, so it has them too. 0 turns it off. Default 30s.
apps_resolv_conf path: The file those name servers are read from, for tests. Default /etc/resolv.conf.
nas_sys path, nas_proc path, nas_run path: Where the broker reads the disks, for tests: a /sys, /proc and /run (udev's records) of a test's own. Only read. Defaults /sys, /proc, /run.
nas_units path: Where the broker reads the units of the disks the NAS module mounts, for tests. Default /etc/systemd/system.
nas_state_dir path: Where the broker keeps the shares, the accounts that may sign in to them, and Samba's username map and password file. Default /var/db/panel/nas.
nas_smb_conf path: Samba's configuration, written by the broker while NAS is on. Default /etc/samba/smb.conf.
nas_passwd path, nas_useradd command, nas_userdel command, nas_groupadd command, nas_systemctl command: For tests: the passwd read for the share accounts, the tools that make and remove them, and the systemctl that starts Samba. Defaults /etc/passwd, useradd, userdel, groupadd, systemctl.
nas_smbstatus command: For tests: what says who is using the shares, as smbstatus --json does. Default smbstatus.
ping_group_range path, ip_forward_proc path, sysctl_dir path: For tests: the kernel's net.ipv4.ping_group_range and net.ipv4.ip_forward, and where the broker writes the files that keep them after a restart (90-panel-ping.conf, 90-panel-forwarding.conf). Defaults /proc/sys/net/ipv4/ping_group_range, /proc/sys/net/ipv4/ip_forward and /etc/sysctl.d.
hostapd_conf path: The Wi-Fi access point's file, written whole by the broker from the Wi-Fi page's settings. A file there that the panel did not write is replaced by the first change and kept as the first of its rollbacks. Default /etc/hostapd/hostapd.conf.
wifi_state_dir path: Where the broker keeps the Wi-Fi's settings, the change waiting to be kept, and the files it can go back to. Default /var/db/panel/wifi.
boot_config path: A Raspberry Pi's config.txt, read for dtoverlay=disable-wifi, which the Wi-Fi page says is in the way. Default /boot/firmware/config.txt.
dnsmasq_on command, dnsmasq_off command: How switching Router on and off starts dnsmasq and has it start at boot, or stops it and keeps it stopped: one command, its arguments separated by commas. Default: what the machine's init does (systemctl enable --now dnsmasq) and systemctl disable --now dnsmasq under systemd.
dnsmasq_conf path: The file the panel writes dnsmasq's settings to. Default /etc/dnsmasq.d/panel.conf, which Debian's dnsmasq reads through CONFIG_DIR in /etc/default/dnsmasq; where that does not name /etc/dnsmasq.d, /etc/dnsmasq.conf. Settings the panel wrote to /etc/dnsmasq.conf before 1.106.0 are moved at the first start, unless this key is set.
shutdown_grace duration: How long a child is given to exit after SIGTERM before it is killed. Default 10s.
allow_core_dumps yes| no: Let the panel's processes leave core dumps. Off by default: a dump of the broker or the api holds what they held, keys and sessions included.
allow_unprivileged_master yes| no: Let the supervisor start without root, for development. Default no.
module_state_dir path: Where the module daemons keep what they write, apart from the broker's own root-only state. Default /var/db/panel/mod.
fleet_dir path: The panel's identity and its paired panels' certificates. Default: a fleet directory beside db.
log_dir path: For tests: the only logs the broker's log verbs read, in place of the journal.

The network

lan_iface, lan_addr and wan_iface are written by the panel when Router is switched on or its ports are chosen; set by hand, they are read the same way.

lan_iface name, lan_addr address/prefix: The home network's port and the panel's address on it. Set, the machine is a router: Router, DNS, DHCP and the Firewall are on after an upgrade from before 1.96.0.
wan_iface name: The uplink. Empty: the port holding the default route.
wg_iface name: The VPN's WireGuard interface. Default wg0.
ssh_port port: The port the firewall opens for SSH on the home network. Default 22.

Where the broker keeps things

Each is written by the broker only; a restore and the commit windows keep their state here.

fw_conf path: The nftables ruleset the panel renders and loads. Default /etc/panel/nftables.conf.
fw_state_dir path, dhcp_state_dir path, interfaces_state_dir path, split_state_dir path, wg_state_dir path: The models, pending changes and rollbacks of the firewall, DHCP and DNS, the interfaces, split tunnelling and the VPN; the paused devices are in fw_state_dir. Defaults /var/db/panel/fw, /var/db/panel/dhcp, /var/db/panel/net, /var/db/panel/split, /var/db/panel/wg.
interfaces_conf path: The interfaces file the panel edits, one stanza at a time; interfaces.d beside it is read, not written. Default /etc/network/interfaces.
dnsmasq_log path, dnsmasq_pidfile path: dnsmasq's log, which its settings name and the DNS page counts today from, and the file holding its process id. The broker keeps the log to today: emptied at midnight and when it passes 200 MB, then dnsmasq is told to reopen it (SIGUSR2). Defaults /var/log/dnsmasq.log and /run/dnsmasq/dnsmasq.pid.
blocklist_dir path, blocklist_file path: Where the fetched blocklists are kept, and the file of blocked names dnsmasq reads. Defaults /var/db/panel/blocklists, and .panel-blocked.servers beside dnsmasq_conf.
owners_dir path, owners_url url: Where the owner list is kept, and where it is fetched from: iptoasn.com's list of who holds each internet address, fetched weekly, for the Network page's connections. Defaults /var/db/panel/owners and https://iptoasn.com/data/ip2asn-combined.tsv.gz.
restore_dir path: A restore's snapshot of what it replaced, until it is kept or undone. Default /var/db/panel/restore.
upgrade_dir path: Where the installer stages an upgrade; the broker reads it. Default /var/db/panel/upgrade.
wg_dir path: WireGuard's configuration directory. Default /etc/wireguard.

Programs

A path empty or unset is the program by name, found on PATH.

nft_path path, ip_path path, ifup_path path, ifdown_path path, wg_path path, wg_quick_path path, dnsmasq_path path: nft(8), ip(8), ifup(8), ifdown(8), wg(8), wg-quick(8) and dnsmasq(8).
tc_path path: tc(8), which shares the line fairly (since 1.149.0).
speedtest_url url: The speed-test server the line is measured against, for sharing it fairly: downloads from <url>/__down and uploads to <url>/__up. Default https://speed.cloudflare.com.
acme_state_dir path: The panel's name's account at Let's Encrypt, the name, and the Cloudflare token its DNS challenge is answered with: root's alone, mode 0700 (since 1.150.0). Default /var/db/panel/acme.
acme_cert_dir path: The name's certificate and its key, and the name, where panel-api reads them: the master makes it root's, group panel_group, mode 02750. Default /etc/panel/acme.
acme_directory url: The certificate authority asked, for tests. Default Let's Encrypt's, https://acme-v02.api.letsencrypt.org/directory.
dnsmasq_restart command, panel_service_cmd command: How dnsmasq is restarted, and how the panel restarts itself after an upgrade: one command, its arguments separated by commas. Default: what this machine's init does; an init the panel does not recognise gives no command, and it says so.

SSH accounts

An administrator's account is also an SSH login, keys only.

ssh_accounts yes| no: Default yes; no leaves the logins out, and the Accounts page says so.
ssh_dropin path: The sshd configuration the panel writes for them. Default /etc/ssh/sshd_config.d/10-panel-accounts.conf.
ssh_keys_dir path: Their public keys, one file per account. Default /etc/ssh/panel_keys.
ssh_state_dir path: Which Linux accounts are the panel's. Default /var/db/panel/ssh.

Listening

listen address:port,...

Where to accept connections. Sockets are bound by the supervisor, so a privileged port needs no privilege in the process that serves it.

127.0.0.1:8080: this host only, IPv4
[::1]:8080: this host only, IPv6
0.0.0.0:8080: every IPv4 address
:8080: every address

A hostname is refused; give an address. Default 127.0.0.1:8080.

redirect_listen address:port,...

Answer plain HTTP here and send browsers to the listen address over https. Somebody typing this machine's address gets http, because that is what a browser assumes; with nothing listening they get a connection refused and no sign the panel is running. Nothing else is served on it. No session, no form, no message carrying anything: plain HTTP is where somebody on the network reads what is sent, so nothing is sent. The reply is a 308 with a Location header and no body, which keeps the method and body of a request that should never have arrived here in the first place. Refused when no tls_cert is set, unless allow_plaintext_public is on, because the redirect would otherwise point at a port with nothing behind it. The port to redirect to is taken from listen, so a panel on 8443 does not send anybody to 443. Empty by default: opening a port nobody asked for is not a favour.

tls_cert path, tls_key path

Serve TLS directly. Both must be set. Read at startup, so a renewed certificate needs a restart.

tls_self_signed yes| no

Issue a self-signed certificate at first start if tls_cert is absent, covering the machine's name and every address configured on it. The fingerprint is written to the log, to be compared with what the browser reports on the first connection. Default no.

allow_plaintext_public yes| no

Permits binding a non-loopback address with no certificate, which is otherwise refused at startup. Set this only when something else terminates TLS. Default no.

trusted_proxy address| cidr,...

Whose X-Forwarded-For may be believed. The header is checked against the address the kernel reports for the connection, so a client reaching the panel directly cannot choose the address that reaches the audit trail or the rate limiter. Set to none where clients connect directly. Default 127.0.0.0/8,::1/128, which suits a reverse proxy on the same host.

Sessions

session_ttl duration: How long a session lasts without being used: each request moves its end this far on, at most once a minute, an open page's own asking included. Default 12h. However much it is used, a session ends 30 days after it was made. A paired phone's sessions last as long; the app asks for another with its token when one runs out, so this does not sign a phone out.
cookie_name name: Default panel_session.
cookie_secure yes| no: Marks the session cookie as requiring HTTPS. Defaults to the opposite of dev.
heartbeat_interval duration: How often the core publishes on core.heartbeat. Default 5s.

Broker

broker_socket path: Default /var/run/panel/broker.sock.
broker_audit_log path: The privileged tier's own trail, kept apart from the database so that a tier being held to account cannot edit the record of what it asked for. Default /var/log/panel/broker-audit.log.
broker_socket_group group: The group that may connect to broker_socket; unset, root's alone.
allow_unprivileged_broker yes| no: Let the broker and the installer start without root, for development. Default no.
broker_call_timeout duration: How long the web tier waits for the broker to answer a call. Installing, keeping or going back on a release waits up to ten minutes whatever this says: the installer copies every program. Default 30s.
broker_unveil yes| no: Whether panel-brokerd(8) confines itself with Landlock when panel-masterd(8) starts it. Default yes. Set no for a machine where the confinement gets in the way; the log then says the broker is not confined.
installer_socket path: Where panel-installd(8) is asked for its jobs. Only the broker is answered. Default installer.sock beside broker_socket.
api_unveil yes| no: Whether panel-api(8) confines itself with Landlock, on every thread. Default yes. Set no only to rule the sandbox out when something the web tier does is refused; the log then says it runs unconfined.
broker_callers user:module,...: Which accounts may call the broker, and as which module. Under panel-masterd(8) this is derived from the installed manifests and the directive is ignored. It applies only to a broker started by hand.

Files

/etc/panel/panel.conf

etc/panel.conf in the source tree is the configuration the release installs. The compiled-in defaults above still describe the OpenBSD layout, such as /var/run rather than /run, which is why that file sets its paths explicitly.

Examples

An appliance reachable on every address, with a certificate of its own:

listen          = 0.0.0.0:443
tls_self_signed = yes
trusted_proxy   = none

Behind a reverse proxy on the same machine:

listen = 127.0.0.1:8080