Configuration

Look up honk's DAE settings exposed by doona, their defaults, and how they take effect. 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 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 / embedded-lite 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

To handle LAN clients, set global.lan_interface to the interface facing them:

• On a main router, use its LAN bridge, commonly br-lan; clients already use this router as their gateway.
• On a side router, also set clients' gateway and DNS to the side router's LAN address, either on each client or through the main router's DHCP settings.

Do not assume lan_interface: auto selects the LAN. It selects the interface with the lowest-metric IPv4 default route, usually the WAN interface on a main router.

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

Change these through Settings, not 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

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

This main file adds the tutorial subscription, group, domain rule, DNS rule and download defaults. Replace the subscription URL before starting honk.

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

Write the API block from Quick start to /etc/honk/config.d/api.dae, or use the separate UI configuration for installed UI files.

Then restart honk. For the corresponding UI steps, follow Route your first connection.

---

Source: doona upstream, licensed under CC BY 4.0.