doona
Service management
Demo
English
Service management

Service management

This page runs honk as a systemd or OpenWrt procd service: it creates the service once, then lists the commands that start, stop, restart and reload honk and read its log. It has no OpenRC steps. Finish Minimal configuration first.

No doona package installs a honk service, and honk’s release archives carry none, so step 1 creates it.

System Service manager Tabs to use
Debian, Ubuntu, Fedora, RHEL, Arch Linux, Gentoo with systemd systemd sudo or root
OpenWrt procd OpenWrt
Gentoo or Alpine with OpenRC OpenRC Not covered: see OpenRC below

OpenRC

doona and honk ship no OpenRC script. To reach First sign-in, start honk in the foreground with the command from step 6 of Minimal configuration:

sudo

sudo /usr/local/bin/honk-core --config /etc/honk/config.dae

root

/usr/local/bin/honk-core --config /etc/honk/config.dae

honk runs until you press Ctrl+C or close the terminal, and prints its log there. It does not start at boot. The rest of this page applies to systemd and procd only.

1. Create the service

Do this once. The systemd unit is the one honk’s quick start gives; the procd script starts the same command with OpenWrt’s paths.

sudo

sudo tee /etc/systemd/system/honk-core.service > /dev/null <<'EOF'
[Unit]
Description=honk transparent proxy engine
Wants=network-online.target
After=network-online.target

[Service]
Type=notify
User=root
WorkingDirectory=/var/lib/honk
ExecStart=/usr/local/bin/honk-core --config /etc/honk/config.dae --disable-timestamp
ExecReload=/usr/local/bin/honk-core reload
Restart=on-failure
RestartSec=2s
TimeoutStopSec=30s
LimitNOFILE=1048576
LimitMEMLOCK=infinity
UMask=0077

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload

root

cat > /etc/systemd/system/honk-core.service <<'EOF'
[Unit]
Description=honk transparent proxy engine
Wants=network-online.target
After=network-online.target

[Service]
Type=notify
User=root
WorkingDirectory=/var/lib/honk
ExecStart=/usr/local/bin/honk-core --config /etc/honk/config.dae --disable-timestamp
ExecReload=/usr/local/bin/honk-core reload
Restart=on-failure
RestartSec=2s
TimeoutStopSec=30s
LimitNOFILE=1048576
LimitMEMLOCK=infinity
UMask=0077

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload

OpenWrt

cat > /etc/init.d/honk-core <<'EOF'
#!/bin/sh /etc/rc.common

START=99
STOP=10
USE_PROCD=1

start_service() {
	procd_open_instance
	procd_set_param command /usr/bin/honk-core --config /etc/honk/config.dae --data-dir /etc/honk/data --disable-timestamp
	procd_set_param limits nofile="1048576 1048576"
	procd_set_param env MIMALLOC_PURGE_DELAY=0
	procd_set_param respawn
	procd_set_param stdout 1
	procd_set_param stderr 1
	procd_close_instance
}

reload_service() {
	/usr/bin/honk-core reload
}
EOF
chmod 0755 /etc/init.d/honk-core

Do not add NoNewPrivileges=yes, capability limits or a read-only /proc/sys to the unit: honk needs BPF, network administration, namespace, mount and sysctl privileges at startup.

On OpenWrt with a mimalloc build, keep MIMALLOC_PURGE_DELAY=0 in the procd script above so freed memory is returned promptly. Builds using the system allocator do not use this setting.

2. Start honk and start it at boot

sudo

sudo systemctl enable --now honk-core

root

systemctl enable --now honk-core

OpenWrt

/etc/init.d/honk-core enable
/etc/init.d/honk-core start

systemd prints Created symlink '/etc/systemd/system/multi-user.target.wants/honk-core.service' → '/etc/systemd/system/honk-core.service'. The command returns once honk reports that it is ready.

3. Check that honk is running

sudo

sudo systemctl status honk-core

root

systemctl status honk-core

OpenWrt

/etc/init.d/honk-core status

A running honk looks like this. systemd on Debian 13:

● honk-core.service - honk transparent proxy engine
     Loaded: loaded (/etc/systemd/system/honk-core.service; enabled; preset: enabled)
     Active: active (running) since …

procd prints running; after a stop it prints inactive.

The log also shows honk-core is running. Press Ctrl+C to stop., and curl http://192.168.1.1:9527/api, with your address, answers as in step 5 of Minimal configuration.

A reachable API does not prove transparent routing works. Check System status for datapath degradations and test traffic from a LAN client.

Read the log

sudo

sudo journalctl -u honk-core -e

root

journalctl -u honk-core -e

OpenWrt

logread -e honk-core

To follow new lines as they arrive:

sudo

sudo journalctl -u honk-core -f

root

journalctl -u honk-core -f

OpenWrt

logread -f -e honk-core

Press Ctrl+C to stop following. The systemd journal keeps lines from earlier starts too; read from the last starting line.

Reload the configuration

After editing a .dae file, reload honk. A reload re-reads the configuration without stopping honk.

sudo

sudo systemctl reload honk-core

root

systemctl reload honk-core

OpenWrt

/etc/init.d/honk-core reload

The log shows SIGHUP reload request 1 started, then applied, or rejected with reload rejected: changed fields require process restart fields=[…]. The listed fields, which include everything under native_api, log_level and the interfaces, need a restart. doona’s Configuration page reloads by itself after saving.

Restart

A restart stops honk and starts it again.

sudo

sudo systemctl restart honk-core

root

systemctl restart honk-core

OpenWrt

/etc/init.d/honk-core restart

Stop

sudo

sudo systemctl stop honk-core

root

systemctl stop honk-core

OpenWrt

/etc/init.d/honk-core stop

honk stays stopped until the next start or boot.

Stop starting at boot

sudo

sudo systemctl disable honk-core

root

systemctl disable honk-core

OpenWrt

/etc/init.d/honk-core disable

Next: First sign-in.

If it doesn’t work

You see Cause and fix
Active: failed or activating (auto-restart) honk stopped at startup. The log names the reason on a fatal error, shutting down: line; Minimal configuration lists the common ones.
systemd cannot find honk-core.service Step 1 was skipped, or systemctl daemon-reload did not run after it.
Error: no running honk-core instance; /run/honk-core.lock does not exist on reload honk is not running, or it runs with --mock-ebpf, which takes no lock. Start the service instead of reloading.
A change has no effect after a reload The log shows reload rejected. Restart instead.

For more messages, see Troubleshooting.

doona

doona documentation

English
doona documentationFor a direct-only first run, follow Quick start. Quick startStart the standard edition of doona with a direct-only honk configuration, sign in, and verify traffic from the gateway itself. Standard edition and doona liteThe standard edition manages configuration and observes traffic. Requirements Install on Debian or UbuntuInstall doona from the doona-web .deb package and honk-core from the same release on Debian, Ubuntu or another APT-based system. Install on Fedora or RHELInstall doona from its .rpm package and honk-core from the same release on Fedora, RHEL or another DNF-based system. Install on Arch LinuxInstall doona from its .pkg.tar.zst package and honk-core from the same release on Arch Linux or another pacman-based system. Install on GentooInstall doona with Portage from the repository's ebuild in a local ebuild repository, and honk-core from the same release. Install on OpenWrtInstall doona from a release package or archive and honk-core from the same release on OpenWrt 25.12. Install on other systemsInstall doona and honk-core from release archives on an x86_64 or aarch64 Linux system that meets the kernel requirements below. Installation detailsInstall honk, write its configuration, then install doona and start honk. Minimal configurationThis page writes the smallest honk configuration that starts honk and serves doona, then checks it by starting honk by hand. Service managementThis page runs honk as a systemd or OpenWrt procd service: it creates the service once, then lists the commands that start, stop, restart and reload honk and read its log. Route your first connectionContinue from Quick start, with honk running and your administrator signed in. First sign-inThis page opens doona in a browser, creates the administrator account and checks that doona shows the running honk. Interface tourUse the navigation to open a page, the top bar to search or refresh, and the page tabs to change views. Watching trafficUse Activity and System status to read engine health, and Connections, Routing log and DNS to inspect traffic. Routing, nodes and rulesPolicies manages group selection and membership. Config and settingsConfiguration reads, validates and applies honk's configuration files. Common tasksThis page covers the standard edition; for doona lite, see doona lite. FeaturesFor each feature’s prerequisites and disabled-action explanations, see Feature requirements. doona litedoona lite edits honk configuration through a smaller interface for beginners. Connect doona liteConnect doona lite to the honk native API, or open the demo without a backend. Common tasks in doona liteUse doona lite to import resources and edit honk configuration. ConfigurationUse this reference for honk's DAE settings exposed by doona, their defaults, and their application paths. What doona can changedoona changes configuration sources, runtime state, persistent geodata settings, and browser preferences through different controls. Feature requirementsFind your standard-edition feature in the table, then use its section to check prerequisites and enable it. Troubleshooting DevelopmentRead CONTRIBUTING.md before opening a pull request.