Minimal configuration

This page writes the smallest honk configuration that starts honk and serves doona, then checks it by starting honk by hand. It assumes doona is in /usr/share/doona and honk-core is installed, as the install pages leave them.

Note

On Debian and Ubuntu, the packages are doona-web and doona-web-fonts, installed under /usr/share/doona-web. Use ui: '/usr/share/doona-web' instead of ui: '/usr/share/doona' in the examples below.

This example uses two files. /etc/honk/config.dae is the main file. /etc/honk/config.d/api.dae turns on the native API that doona talks to. Every connection goes out directly until you add nodes and rules; Configuration has a fuller example.

Before you start

• A shell on the gateway: a user with sudo, or root. On OpenWrt, pick the OpenWrt tab wherever one is offered; it runs as root and keeps honk’s data in /etc/honk/data, because /var on OpenWrt is in memory and is cleared at reboot.
• A second way into the machine, such as a console, for step 6. honk changes the gateway’s networking when it starts for real.

1. Find the gateway’s LAN address

doona is opened at this address from the LAN.

ip -4 addr show

Find the interface your LAN devices connect to (on OpenWrt, br-lan) and note the address after inet, without the /24. For example:

    inet 192.168.1.1/24 brd 192.168.1.255 scope global eth0

Set it for the next steps:

LAN_IP=192.168.1.1

2. Create the directories

sudo install -d -m 0700 /etc/honk /etc/honk/config.d /var/lib/honk

install -d -m 0700 /etc/honk /etc/honk/config.d /var/lib/honk

mkdir -p /etc/honk/config.d /etc/honk/data
chmod 0700 /etc/honk /etc/honk/config.d /etc/honk/data

The directories are readable by root only: the configuration and the state database hold credentials.

3. Write the main file

sudo tee /etc/honk/config.dae > /dev/null <<'EOF'
include {
    config.d/*.dae
}

global {
    wan_interface: auto
}

routing {
    fallback: direct
}
EOF

cat > /etc/honk/config.dae <<'EOF'
include {
    config.d/*.dae
}

global {
    wan_interface: auto
}

routing {
    fallback: direct
}
EOF

cat > /etc/honk/config.dae <<'EOF'
include {
    config.d/*.dae
}

global {
    wan_interface: auto
    lan_interface: br-lan
    data_dir: '/etc/honk/data'
    bootstrap_resolver: '127.0.0.1:53'
}

routing {
    fallback: direct
}
EOF

On OpenWrt, bootstrap_resolver: '127.0.0.1:53' uses dnsmasq to resolve hosts for direct downloads. Geodata URLs must not redirect: use a final URL such as raw.githubusercontent.com, not a GitHub release URL.

Choose lan_interface for the traffic you want honk to handle:

• Main router: use br-lan; clients already use this router as their gateway.
• Side router: use br-lan and set clients’ gateway and DNS to its LAN address, either on each client or through the main router’s DHCP settings.
• This machine only: omit lan_interface, as in the sudo and root examples.

lan_interface: auto selects the default-route interface, usually the WAN on a main router.

4. Write the API file

This file uses LAN_IP from step 1.

sudo tee /etc/honk/config.d/api.dae > /dev/null <<EOF
experimental {
    native_api {
        enabled: true
        listen: '${LAN_IP}:9527'
        password_auth: true
        config_write: true
        ui: '/usr/share/doona'
    }
}
EOF
sudo cat /etc/honk/config.d/api.dae

cat > /etc/honk/config.d/api.dae <<EOF
experimental {
    native_api {
        enabled: true
        listen: '${LAN_IP}:9527'
        password_auth: true
        config_write: true
        ui: '/usr/share/doona'
    }
}
EOF
cat /etc/honk/config.d/api.dae

cat > /etc/honk/config.d/api.dae <<EOF
experimental {
    native_api {
        enabled: true
        listen: '${LAN_IP}:9527'
        password_auth: true
        config_write: true
        ui: '/usr/share/doona'
    }
}
EOF
cat /etc/honk/config.d/api.dae

The printed file shows your address on the listen line, such as listen: '192.168.1.1:9527'.

For a hostname such as openwrt.lan, configure both allowed_hosts for the host and port and allow_origins for the browser origin, then restart honk. See hostname and origin access for the syntax and 403 checks.

Every native_api field takes effect only after a restart. The field table lists the rest.

The honk-core debug.2026.10.9.native-api.2 assets for doona beta.19 (commit eac5e0c5fba5078a7ff4517a3e3851e7fa0f4f8e) embed doona 0.1.0-beta.19. To serve the bundled UI at /ui/, replace the ui line above with:

ui: embedded

For doona lite, install its archive into /usr/share/doona-lite and set ui: /usr/share/doona-lite. ui: embedded is the standard edition only. Changing ui requires restarting honk.

With ui: embedded, the standalone UI package is optional. The bundled UI omits Noto Sans TC/SC, so the browser uses system fonts. To serve external UI files or those fonts, install doona and doona-fonts and point ui at their installation directory, such as /usr/share/doona; on Debian or Ubuntu, use doona-web, doona-web-fonts and /usr/share/doona-web.

5. Check the configuration

honk has no separate check command. Start it once with --mock-ebpf: it reads and admits the whole configuration, starts the API and serves doona, but leaves the network alone.

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

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

honk-core --config /etc/honk/config.dae --data-dir /etc/honk/data --mock-ebpf

honk keeps running in the foreground. Each line starts with a timestamp; among them you should see:

INFO honk_core: honk-core debug.2026.10.9.native-api.2 starting
INFO honk_core: Config: /etc/honk/config.dae
INFO honk_core: Loaded 2 nodes, 0 groups, 0 routing rules
WARN honk_core: NFQUEUE is unavailable at startup; continuing with NFQUEUE staging disabled requested=true reason=the mock eBPF backend was selected
INFO honk_core: Using mock eBPF backend
INFO honk_core: listen=192.168.1.1:9527 native API listener ready
INFO honk_core: honk-core is running. Press Ctrl+C to stop.

The WARN line is expected under --mock-ebpf. While honk runs, ask the API from a second terminal, with your address in place of 192.168.1.1:

curl http://192.168.1.1:9527/api

It answers with one line; setup_required: true means no administrator exists yet:

{"api_major":1,"auth":{"mode":"password","setup_required":true},"links":{"auth_login":"/api/v1/auth/login","auth_setup":"/api/v1/auth/setup"},"name":"dae/honk-native"}

Press Ctrl+C in the first terminal. honk logs Received SIGINT, shutting down... and ends with honk-core stopped.

6. Start honk for real once

This start loads eBPF programs and attaches them to the configured interfaces. Keep the second way into the machine ready.

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

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

honk-core --config /etc/honk/config.dae --data-dir /etc/honk/data

The log shows the same native API listener ready and honk-core is running. Press Ctrl+C to stop. lines, without the mock lines. Press Ctrl+C to stop honk; the service in the next step runs it from now on.

Next: Service management.

If it doesn’t work

honk prints the reason on a line starting fatal error, shutting down: or as an ERROR.

A clean start does not prove that every value means what you intended: honk accepts some unknown values without an error. For more messages, see Troubleshooting.