doona
Configuration
Demo
English

Configuration

Use this reference for honk's DAE settings exposed by doona, their defaults, and their application paths. For configuration syntax, use honk's nodes, subscriptions, groups, routing, and DNS references. Start with Quick start or follow Route your first connection.

The tables show defaults for honk 1b95e2e. The example deliberately overrides some defaults. The Applies column links to the corresponding write-permission or restart row in What doona can change.

Native API and authentication

Key Default What doona does with it Applies honk reference
experimental.native_api.enabled false Enables the native API used by doona. Restart experimental
experimental.native_api.listen 127.0.0.1:9527 API address. Use a numeric IP and a nonzero port. Restart experimental
experimental.native_api.password_auth false Enables administrator sign-in; cannot coexist with secret or anonymous loopback. Restart experimental
experimental.native_api.secret '' Token sign-in. Visible ASCII without whitespace or commas. Restart experimental
experimental.native_api.allow_anonymous_loopback false Allows uncredentialed loopback access; does not grant protected writes. Restart experimental
experimental.native_api.config_write false Permits source writes and geodata updates with credentials. Restart experimental
experimental.native_api.ui '' Serves doona at /ui/: a directory containing index.html, or embedded with a native-ui build. Restart experimental
experimental.native_api.allow_origins [] Additional browser origins, such as https://panel.example. Restart experimental
experimental.native_api.allowed_hosts [] Additional HTTP host authorities, such as panel.example. Restart experimental

Data directory and state database

Key Default What doona does with it Applies honk reference
global.data_dir /var/lib/honk Runtime root; state database is state/honk.db below it. Restart global
global.store_subscribe true Retains subscription bodies for offline startup; per-entry cache must also allow it. Restart subscription
experimental.cache_file.enabled Unset Unset keeps Selector choices and delay samples; false disables this cache; true also keeps Clash mode and permits DNS persistence. Restart experimental
experimental.cache_file.store_dns false Retains DNS answers when enabled: true. Restart experimental

The state database also holds administrator credentials and geodata settings. --store db selects database-backed configuration revisions; it is a startup option, not a DAE key. See revision requirements.

Assets and subscription defaults

Key Default What doona does with it Applies honk reference
assets.route Empty; routing rules Default download route: routing, direct, or a group. Inherited by geodata, UI and subscriptions. Restart assets
assets.geodata.geosite ''; built-in URLs with state DB HTTP(S) source for loaded domain categories. Restart assets
assets.geodata.geoip ''; built-in URLs with state DB HTTP(S) source for loaded IP categories. Restart assets
assets.geodata.route Inherits assets.route Download route for data and checksums. An unset route preserves a stored override. Restart assets
assets.ui.url zashboard dist.zip Clash dashboard download, not the doona directory. HONK_UI_DOWNLOAD_URL overrides it. Restart assets
assets.ui.route Inherits assets.route Clash dashboard download route; also accepts a node tag. Restart assets
assets.subscription.ua honk/<version> Default subscription User-Agent; an entry can override it. Reload assets
assets.subscription.interval 86400s Default refresh interval; 0 disables scheduled refresh. Reload assets
assets.subscription.cache true Default per-entry body cache, subject to global.store_subscribe. Reload assets

Entry options override subscription defaults. Sub-block routes override assets.route. An effective change to inherited geodata or UI settings requires a restart; subscription-only changes can reload. Explicit startup geodata URLs and routes replace stored overrides. Defining a URL does not load an asset. See geodata requirements.

Recording permissions

Key Default What doona does with it Applies honk reference
experimental.native_api.record_traffic true Traffic history charts. Restart experimental
experimental.native_api.record_memory true Memory history charts. Restart experimental
experimental.native_api.record_flows true Permits flow recording for Routing log and rule-hit evidence. Restart experimental
experimental.native_api.record_logs true Permits the Logs recorder. Restart experimental
experimental.native_api.record_dns_log true Permits the DNS resolution log recorder. Restart experimental

These file keys grant recorder permission. Flows, logs and DNS logs start in on-demand mode. Their runtime switches cannot override a configured prohibition. Connections lists active userspace connections separately from the flow recorder. See Connections, flows, and runtime overrides.

Health checks

Key Default What doona does with it Applies honk reference
global.tcp_check_url https://www.gstatic.com/generate_204 Global HTTP probe target list; the health loop uses the first URL. Restart global
global.tcp_check_http_method HEAD Global HTTP health-check method. Restart global
global.udp_check_dns dns.google:53, 8.8.8.8, 2001:4860:4860::8888 UDP probe targets; the first literal IP takes precedence over names. Restart global
global.check_interval 30s Global health-check interval. Restart global
global.check_tolerance 50ms Default latency improvement required to switch URLTest members. Reload global

Logging

Key Default What doona does with it Applies honk reference
global.log_level info Startup filter. A valid RUST_LOG takes precedence, then --debug. Restart global
global.log_file '' Optional file output. Relative paths resolve below data_dir; --log-file overrides this value. Restart global

Interfaces and kernel

Key Default What doona does with it Applies honk reference
global.lan_interface [] LAN interfaces for forwarded traffic; no LAN hooks when empty. Restart global
global.wan_interface [] Interfaces for host traffic; auto follows the lowest-metric IPv4 default route. Restart global
global.tproxy_port 12345 Transparent TCP/UDP listener port. Restart global
global.so_mark_from_dae 0 Effective mark is 0x100 at zero; otherwise the configured socket bypass mark. Restart global
global.nfqueue_enable true Requests NFQUEUE staging for ambiguous forwarded LAN UDP. Requires the real eBPF backend. Restart global

Dialing and warm-up

Key Default What doona does with it Applies honk reference
global.dial_mode domain Domain discovery and rerouting mode: ip, domain, domain+, domain++. Reload global
global.bootstrap_resolver '' Resolver for node names and control-plane dials. Direct geodata downloads from hostnames need it. Reload global
global.tls_implementation tls Selects regular TLS or utls ClientHello emulation. Restart global
global.max_concurrent_dials 64 Requested cap on physical proxy connects and handshakes; resource budgeting can lower it. Reload global
global.udp_warm_node_count 0 UDP warm-up candidate count; zero disables it. Reload global
global.preconnect_node_count auto Startup-only bare-TCP warm-up; auto chooses at most eight eligible nodes. Reload does not repeat it. Restart for warm-up global

Accepted without runtime effect

Key Default What doona does with it Applies honk reference
global.tproxy_port_protect true Stored only; does not control port protection. Restart global
global.pprof_port 0 Stored only; starts no pprof server. Restart global
global.auto_config_kernel_parameter false Stored only; does not control the datapath's fixed sysctl setup. Restart global
global.disable_waiting_network false Stored only; does not alter startup waiting. Reload global
global.allow_insecure false Stored only; does not disable certificate verification globally. Reload global
global.sniffing_timeout 30ms Stored only; does not set the runtime sniffing timeout. Reload global
global.mptcp false Stored only; does not enable MPTCP. Reload global
global.fallback_resolver 8.8.8.8:53 Stored only; does not select a fallback resolver. Reload global
global.tls_fragment false Stored only; does not enable TLS fragmentation. Reload global
global.tls_fragment_length '' Stored only; does not set a fragment length. Reload global
global.tls_fragment_interval '' Stored only; does not set a fragment interval. Reload global
global.bandwidth_max_tx '' Stored only; does not limit transmit bandwidth. Reload global
global.bandwidth_max_rx '' Stored only; does not limit receive bandwidth. Reload global
global.utls_imitate chrome_auto Accepted fingerprint request; does not change the single supported Chrome profile. Reload global

DNS listener and Clash compatibility

Key Default What doona does with it Applies honk reference
dns.bind '' Standalone DNS listener; empty disables it. Edit outside doona. Restart dns
experimental.clash_api.external_controller '' Clash API listener; empty disables it. Restart experimental
experimental.clash_api.external_ui '' Clash dashboard directory. Restart experimental
experimental.clash_api.secret '' Clash bearer secret; declaring it makes its source read-only in doona. Restart experimental
experimental.clash_api.default_mode Rule Initial Clash mode: Rule, Global, or Direct. Restart experimental

Runtime API fields, not DAE keys

Key Default What doona does with it Applies honk reference
record_flows, record_logs, record_dns_log auto On-demand recorder modes: auto, on, off; configured prohibitions still apply. Live api
log.level From global.log_level Live log filter; also changes console and file output when overridden. Live api
log.buffered_records 512 Log ring capacity; 64–512. Live api
dns_log.max_records 512 DNS log capacity; 64–512. Live api
flows.max_flows 1024 Flow record capacity; 64–1024. Live api
flows.retention_seconds 300 Terminal flow retention; 1–300 seconds. Live api

You change these through Settings. Do not put them in a DAE file. An accepted activation or restart resets them. See runtime override requirements.

Stored geodata settings, not DAE keys

Key Default What doona does with it Applies honk reference
geodata.geosite.urls, geodata.geoip.urls GitHub + jsDelivr; geoip.dat for GeoIP Stored URL lists; startup file URLs take precedence. Live, stored api
geodata.download Routing rules Download route and optional group_id; configured startup routes take precedence. Live, stored api
geodata.verify_checksum true Checksum verification for downloads. Live, stored api
geodata.auto_update.enabled true Enables scheduled update checks. Live, stored api
geodata.auto_update.interval_hours 24 Interval between scheduled checks, in hours. Live, stored api

You change these through Settings with credentials and an available state database. Saving settings does not itself activate new asset files. See geodata settings requirements.

Aliases and migration keys

Old name Current name
experimental.native_api.geosite_download_url assets.geodata.geosite
experimental.native_api.geoip_download_url assets.geodata.geoip
experimental.native_api.geodata_download_detour assets.geodata.route
experimental.clash_api.external_ui_download_url assets.ui.url
experimental.clash_api.external_ui_download_detour assets.ui.route
experimental.udp_nfqueue.enabled global.nfqueue_enable

Use the current names in new files. Asset aliases emit legacy-assets-key; a nonempty old value combined with its new key fails with conflicting-assets-setting. The old NFQUEUE block emits a migration warning and supplies the value only when global.nfqueue_enable is absent. experimental.cache_file.path and cache_id are legacy import hints, not the active database location. store_fakeip has no effect.

Complete annotated example

Use these two files together. They extend the minimal configuration with the tutorial subscription, group, domain rule, DNS rule and download defaults. Replace the subscription URL and listener IP before starting honk. The UI path matches Debian and Ubuntu in Quick start; use your installed path on other systems, commonly /usr/share/doona. For the direct-only baseline, keep the files from Quick start instead.

Keep API credentials separate from the main file that Nodes modifies. See source write requirements.

Main file

# /etc/honk/config.dae
# Keep API credentials in a separate include.
include {
    config.d/*.dae
}

# Host traffic, storage, checks and connection settings.
global {
    wan_interface: auto
    # For LAN clients, uncomment and replace with their gateway interface.
    # lan_interface: br-lan
    data_dir: '/var/lib/honk'
    store_subscribe: true
    log_level: info
    # Optional append-only log file, relative to data_dir.
    # log_file: 'honk.log'
    tproxy_port: 12345
    so_mark_from_dae: 0
    nfqueue_enable: true
    tcp_check_url: 'https://www.gstatic.com/generate_204'
    tcp_check_http_method: HEAD
    udp_check_dns: 'dns.google:53', '8.8.8.8', '2001:4860:4860::8888'
    check_interval: 30s
    check_tolerance: 50ms
    dial_mode: domain
    bootstrap_resolver: '1.1.1.1:53'
    tls_implementation: tls
    max_concurrent_dials: 64
    preconnect_node_count: auto
    udp_warm_node_count: 0
}

# Replace the placeholder with your provider's subscription URL.
subscription {
    harbor: 'https://subscription.example/sub'
}

# Optional static nodes; uncomment only with your real node details.
node {
    # backup: 'socks5://192.0.2.2:1080'
}

# Select from harbor's nodes by moving-average latency.
group {
    # This group is used by both the traffic rule and the DNS upstream.
    proxy {
        filter: subtag('harbor')
        policy: min_moving_avg
    }
}

# Send only the tutorial domain through the group.
routing {
    domain(full: example.com) -> proxy
    fallback: direct
}

# Resolve the tutorial domain through the same group.
dns {
    # An IP-based HTTPS endpoint avoids a bootstrap hostname dependency.
    upstream {
        remote_dns: 'https://1.1.1.1/dns-query' -> proxy
    }
    # Other DNS requests keep their original destination.
    routing {
        # Match the same full domain as the traffic rule.
        request {
            qname(full: example.com) -> remote_dns
            fallback: asis
        }
        # Keep the selected upstream's answer.
        response {
            fallback: accept
        }
    }
}

# Download defaults; these URLs alone do not load geodata assets.
assets {
    route: routing
    # Sources for updates after routing rules load the relevant assets.
    geodata {
        geosite: 'https://raw.githubusercontent.com/MetaCubeX/meta-rules-dat/release/geosite.dat'
        geoip: 'https://raw.githubusercontent.com/MetaCubeX/meta-rules-dat/release/geoip.dat'
        route: direct
    }
    # Applies only to a separately configured Clash dashboard, not doona.
    ui {
        url: 'https://github.com/Zephyruso/zashboard/releases/latest/download/dist.zip'
        route: direct
    }
    # Individual subscription options can override these defaults.
    subscription {
        interval: 86400s
        cache: true
        # ua: 'clash.meta'
    }
}

API file

# /etc/honk/config.d/api.dae
# Listener settings must be edited outside doona and require a restart.
experimental {
    # Password sign-in and the installed standard-edition UI.
    native_api {
        enabled: true
        listen: '192.168.1.1:9527'
        password_auth: true
        # For token sign-in, remove password_auth and set a real secret.
        # secret: 'replace-with-a-long-random-token'
        config_write: true
        ui: '/usr/share/doona-web'
        # Add these only for the actual origin and host you use.
        # allow_origins: 'https://panel.example'
        # allowed_hosts: 'panel.example'
        record_traffic: true
        record_memory: true
        record_flows: true
        record_logs: true
        record_dns_log: true
    }
    # Unset enabled retains Selector choices and delay samples.
    cache_file {
        store_dns: false
    }
}

After placing the files at the shown paths, use the checks in Minimal configuration and the restart procedure in Service management. To build this setup in the UI from the direct-only baseline, follow Route your first connection.

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.