Kernloom Shield (klshield) — Full reference

Kernloom Shield is the XDP dataplane. It attaches an XDP program to an interface and exposes pinned maps for enforcement and telemetry.

Attach / detach XDP

attach-xdp

Attach the XDP program to an interface.

Flags:

• -iface (string, default eth0)
• -obj (string, default bpf/klshield.bpf.o)
• -force (bool, default false): detaches any existing XDP program from the interface first

Examples:

sudo ./klshield attach-xdp -iface eth0 -obj bpf/klshield.bpf.o
sudo ./klshield attach-xdp -iface eth0 -obj bpf/klshield.bpf.o -force

Behavior:

• tries driver mode first, falls back to generic mode
• pins the link at /sys/fs/bpf/kernloom_shield_xdp_link

detach-xdp

sudo ./klshield detach-xdp

Allow list (LPM)

add-allow-cidr <cidr>

Adds a CIDR to the allow list (IPv4 or IPv.

Examples:

sudo ./klshield add-allow-cidr 203.0.113.0/24
sudo ./klshield add-allow-cidr 2001:db8::/32

list-allow

sudo ./klshield list-allow

Allow enforcement mode

Enable/disable allow enforcement:

sudo ./klshield enforce-allow on
sudo ./klshield enforce-allow off

Meaning:

• off: allow list can be used as a fast allow mechanism (but non-allowed sources may still pass depending on deny/RL rules)
• on: allow list becomes mandatory (only allowed sources pass)

Deny list (hash)

add-deny-ip <ip>

Adds an exact IP to the deny list (IPv4 or IPv.

sudo ./klshield add-deny-ip 203.0.113.7
sudo ./klshield add-deny-ip 2001:db8::dead:beef

del-deny-ip <ip>

sudo ./klshield del-deny-ip 203.0.113.7

list-deny

sudo ./klshield list-deny

Rate limiting (token buckets)

Shield supports:

• one global token bucket (default policy)
• per-IP overrides (used heavily by Kernloom IQ)

rl-set -rate <pps> -burst <n>

Set the global token bucket:

• rate: tokens per second (packets per second)
• burst: maximum tokens

sudo ./klshield rl-set -rate 2000 -burst 4000

rl-set-ip -rate <pps> -burst <n> <ip>

Set a per-IP override.

sudo ./klshield rl-set-ip -rate 50 -burst 100 203.0.113.7
sudo ./klshield rl-set-ip -rate 10 -burst 20 2001:db8::1

rl-unset-ip <ip>

sudo ./klshield rl-unset-ip 203.0.113.7

list-rl

sudo ./klshield list-rl

Telemetry and stats

stats

Print totals counters (summed across per-CPU entries).

sudo ./klshield stats

top-src [-n N] [-by pkts|bytes|drops|droprl]

Shows top IPv4 sources from /sys/fs/bpf/kernloom_src4_stats.

Examples:

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

What “drops” mean:

• drop_allow: dropped by allow policy
• drop_deny: dropped by deny policy
• drop_rl: dropped by rate limiter (token bucket)

Events (ring buffer)

Events are optional and sampled to avoid overhead.

set-sampling <mask>

• 0 disables events
• 1 ≈ ~1/2
• 3 ≈ ~1/4
• 1023 ≈ ~1/1024 (default)

sudo ./klshield set-sampling 1023
sudo ./klshield set-sampling 3
sudo ./klshield set-sampling 1
sudo ./klshield set-sampling 0

events

Listen for events (Ctrl+C to stop).

sudo ./klshield events

Pinned maps (what each one is for)

Debug: quick pin check

ls -la /sys/fs/bpf/kernloom_shield_xdp_link /sys/fs/bpf/kernloom_src4_stats /sys/fs/bpf/kernloom_rl_policy4 /sys/fs/bpf/kernloom_deny4_hash