Kernloom — Exemptions, state, operations

This page covers:

• whitelist and feedback (what they are and when to use them)
• state.json persistence (what gets stored)
• observability and common triage workflows
• systemd examples
• troubleshooting
• cheat sheet

Exemptions

Whitelist (permanent)

Use the whitelist for sources that should never be enforced.

Default path:

• /etc/kernloom/iq/whitelist.txt

Format:

• IPv4/IPv6 or CIDR (one per line)
• # comments supported

Example:

# Office NAT / trusted gateway
203.0.113.7
203.0.113.0/24
2001:db8::1
2001:db8::/64

Reload:

• --whitelist-reload (default 10s)

Learning:

• --whitelist-learn=false by default (safer)

Feedback (temporary “forgive”)

Use feedback when you want a time-bound exemption without permanently whitelisting.

Default path:

• /var/lib/kernloom/iq/feedback.json

Format: JSON array

[
  {"target":"203.0.113.7","action":"forgive","ttl":"24h","notes":"partner NAT"},
  {"target":"198.51.100.0/24","action":"whitelist","until":"2026-03-01T12:00:00+01:00"}
]

Notes:

• Prefer until (RFC333 for stable expiry across restarts
• ttl is applied when the file is loaded

CIDR de-enforcement:

• --feedback-deenforce-cidr=true
• --feedback-cidr-every=30s
• --feedback-cidr-max=5000

State persistence (state.json)

Default path:

• /var/lib/kernloom/iq/state.json

State contains:

• tuned triggers (trig_pps, trig_syn, trig_scan)
• tuning metadata and history
• bootstrap metadata
• integrity hash (SHA25
• atomic writes via .tmp and .bak

Startup behavior:

• loads state if integrity matches and age <= --max-state-age

Observability

Shield totals and top sources

sudo ./klshield stats
sudo ./klshield top-src -n 20 -by pkts
sudo ./klshield top-src -n 20 -by droprl
sudo ./klshield top-src -n 20 -by drops

Events (sampled)

sudo ./klshield set-sampling 1023
sudo ./klshield events

systemd examples

Shield attach (oneshot)

/etc/systemd/system/kernloom-shield.service

[Unit]
Description=Kernloom Shield (XDP attach)
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/bin/klshield attach-xdp -iface eth0 -obj /usr/local/share/kernloom/bpf/klshield.bpf.o
ExecStop=/usr/local/bin/klshield detach-xdp

[Install]
WantedBy=multi-user.target

IQ controller

/etc/systemd/system/kernloom-iq.service

[Unit]
Description=Kernloom IQ (controller)
After=kernloom-shield.service
Requires=kernloom-shield.service

[Service]
Type=simple
Restart=always
RestartSec=2
ExecStart=/usr/local/bin/kliq \
  --profile ziti-controller-bootstrap \
  --interval 1s \
  --top 100 \
  --bootstrap=true \
  --state-file /var/lib/kernloom/iq/state.json \
  --whitelist /etc/kernloom/iq/whitelist.txt \
  --feedback-file /var/lib/kernloom/iq/feedback.json \
  --dry-run=true
# Switch to --dry-run=false after validation.

[Install]
WantedBy=multi-user.target

Troubleshooting

Shield attach fails

• verify interface: ip link
• verify bpffs mounted: mount | grep bpf
• use -force only if you know replacing XDP is safe

IQ cannot read pinned maps

ls -la /sys/fs/bpf/kernloom_src4_stats /sys/fs/bpf/kernloom_rl_policy4 /sys/fs/bpf/kernloom_deny4_hash /sys/fs/bpf/kernloom_src6_stats /sys/fs/bpf/kernloom_rl_policy6 /sys/fs/bpf/kernloom_deny6_hash

Too many false positives

Immediate mitigation: add feedback entry (24h) tighten blocking (increase block-min-sev and block-min-dur) increase hysteresis (up/down streaks + holds + cooldown)

Cheat sheet (fast actions)

Attach and validate

sudo ./klshield attach-xdp -iface eth0 -obj bpf/klshield.bpf.o
sudo ./klshield stats
sudo ./klshield top-src -n 20 -by pkts

Dry-run then enforce

sudo ./kliq --profile ziti-controller-bootstrap --interval 1s --top 50 --dry-run=true
sudo ./kliq --profile ziti-controller --interval 1s --top 100 --dry-run=false

Forgive quickly

• edit /var/lib/kernloom/iq/feedback.json and wait for reload (default 10s)