keen-pbr CLI usage

Documentation

keen-pbr CLI usage

keen-pbr can run the service, inspect live routing state, download list data, and print generated resolver configuration.

Usage

Usage: keen-pbr [options] <command>

Options:
  --config <path>    Path to JSON config file
  --log-level <lvl>  Log level: error, warn, info, verbose, debug
  --no-api           Disable REST API at runtime
  --use-raw-prerouting  Use raw PREROUTING for IPv4 forwarded traffic (iptables only)
  --use-raw6-prerouting Use raw PREROUTING for IPv6 forwarded traffic (iptables only)
  --version          Show version and exit
  --help             Show this help and exit

Commands:
  service
  status
  download
  generate-resolver-config <res>
  resolver-config-hash
  test-routing <ip-or-domain>

The config file is usually /etc/keen-pbr/config.json on OpenWrt and Debian, and /opt/etc/keen-pbr/config.json on Keenetic / NetCraze.

Options

Flag	Description
`--config <path>`	Path to the JSON config file.
`--log-level <lvl>`	Log verbosity: `error`, `warn`, `info`, `verbose`, or `debug`.
`--log-target <target>`	External log destination: `stderr`, `syslog`, or `both`. Defaults to `syslog` for `service` and `stderr` for interactive commands.
`--no-api`	Disable the REST API even if enabled in config.
`--use-raw-prerouting`	Opt in to raw-table IPv4 forwarded-traffic classification; available only with iptables.
`--use-raw6-prerouting`	Opt in to raw-table IPv6 forwarded-traffic classification; available only with iptables.
`--version`	Print version and exit.
`--help`	Print help and exit.

`--use-raw-prerouting`

This disabled-by-default option is intended for systems such as KeeneticOS where an external firewall manager periodically replaces the mangle table. It moves only IPv4 forwarded-traffic classification from mangle PREROUTING to raw PREROUTING; locally generated traffic remains in mangle OUTPUT, and IPv6 can be selected independently with --use-raw6-prerouting.

On Keenetic, the service independently probes and loads iptable_raw.ko and ip6table_raw.ko at startup. It enables each flag automatically only after that family’s raw table probe succeeds; otherwise it logs a warning and keeps that family on the normal mangle path. Raw PREROUTING deliberately does not use connmark acceleration: each forwarded packet is classified directly.

To force the Keenetic package to keep using mangle PREROUTING, set the following in /opt/etc/keen-pbr/defaults, then restart the service:

KEEN_PBR_RAW_PREROUTING="disable"

The default value is auto: IPv4 and IPv6 capabilities are probed independently, so one family can use RAW while the other remains in mangle. Set it to enable to require RAW for every enabled family; ipv4-only and ipv6-only force one family. The service fails to start rather than falling back for a forced family. RAW PREROUTING intentionally runs before conntrack and does not use CONNMARK acceleration. For the Keenetic-specific RAW versus mangle trade-off, see Keenetic / NetCraze installation.

Troubleshoot the required capability with:

ls -l "/lib/modules/$(uname -r)/iptable_raw.ko"
ls -l "/lib/modules/$(uname -r)/ip6table_raw.ko"
grep -x raw /proc/net/ip_tables_names
grep -x raw /proc/net/ip6_tables_names
iptables -t raw -S
ip6tables -t raw -S

Commands

Command	Description
`service`	Start the routing service in the foreground.
`status`	Show routing, route table, rule, and firewall verification status, then exit.
`download`	Download all URL-backed lists into cache, then exit.
`generate-resolver-config <res>`	Print generated resolver config to stdout. Supported resolvers: `dnsmasq-ipset`, `dnsmasq-nftset`.
`resolver-config-hash`	Print the MD5 hash of the generated domain-to-ipset mapping, then exit.
`test-routing <ip-or-domain>`	Compare expected and actual routing for the given IP or domain.

Signals

When keen-pbr is running as a managed service (daemon), you can also control it with Unix signals:

Signal	Action
`SIGUSR1`	Re-verify routing tables and trigger immediate `urltest` latency checks
`SIGHUP`	Full reload: re-download lists if changed, re-apply firewall and routing rules
`SIGTERM` / `SIGINT`	Graceful shutdown

Example full reload via signal:

bash

kill -HUP $(cat /var/run/keen-pbr.pid)

Examples

Check live routing and firewall state:

bash

keen-pbr status

Example output:

keen-pbr status - config: /etc/keen-pbr/config.json
Firewall backend: nftables

Outbounds:
  corp_vpn [interface] iface=corp_vpn fwmark=0x00010000 table=402
    route   table=402 default dev corp_vpn ............................... OK
    rule    0x00010000/0x00ff0000 -> table=402 pri=402 ........... OK [v4+v6]
  auto_vpn [urltest] fwmark=0x00060000 table=407
    route   table=407 default dev corp_vpn ............................... OK
    rule    0x00060000/0x00ff0000 -> table=407 pri=407 ........... OK [v4+v6]

Firewall:
  chain   KeenPbrTable / prerouting hook ............................... OK
  rule    kpbr4_generic -> MARK 0x00010000 ........................ MISSING
    rule not found in nftables prerouting chain

Overall: DEGRADED (2 check(s) failed)
Status values: OK / MISSING / MISMATCH / ERROR

Download all URL-backed lists:

bash

keen-pbr download

Example output:

[google] Not modified (304)
[internal.site] Skipped (no URL)
[generic] Skipped (no URL)

Generate resolver config:

bash

keen-pbr generate-resolver-config dnsmasq-ipset

Example output:

# Generated by keen-pbr (dnsmasq-ipset) - do not edit manually

address=/use-application-dns.net/

rebind-domain-ok=keen.pbr
server=/check.keen.pbr/127.0.0.88#53

server=10.100.100.100

# List: google
ipset=/google.com/www.google.com/.../kpbr4d_google,kpbr6d_google

Print the resolver config hash:

bash

keen-pbr resolver-config-hash

Example output:

6aa71fa9012013b242460b9d1e173d82

Test expected vs actual routing:

bash

keen-pbr test-routing google.com

Example output:

Target: google.com
Resolved IPs: 2001:4860:4860::8888, 142.250.74.14

IP                        | List Match               | Expected Outbound  | Actual Outbound    | Status
---------------------------------------------------------------------------------------------------
2001:4860:4860::8888      | google (via google.com)  | corp_vpn           | corp_vpn           | OK
142.250.74.14             | google (via google.com)  | corp_vpn           | corp_vpn           | OK

Concepts REST API