Skip to content
Documentation
keen-pbr CLI usage

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
  --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.
--no-api Disable the REST API even if enabled in config.
--version Print version and exit.
--help Print help and exit.

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
ConceptsREST API