Kernloom Shield (klshield) — Full reference

Kernloom Shield is the XDP dataplane. It attaches an XDP program to one or more network interfaces and exposes pinned maps for enforcement and telemetry.

Multi-interface note: klshield can attach to multiple interfaces simultaneously. However, kliq aggregates telemetry across all attached interfaces — it cannot distinguish which traffic arrived on which interface. Per-interface policy separation (e.g. DoS-only on a public interface, graph learning on an internal interface) is not supported in the current release.

Attach / detach XDP

status

Show XDP attach state, default RL config, deny counts, allow-enforce mode, and tuple enforcement mode:

klshield status

attach-xdp

Attach the XDP program to an interface.

Flags:

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

Examples:

sudo klshield attach-xdp --iface eth0 --obj /opt/kernloom/attested/bpf/xdp_kernloom_shield.bpf.o
sudo klshield attach-xdp --iface eth0 --obj /opt/kernloom/attested/bpf/xdp_kernloom_shield.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)

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

Set the global per-source XDP token bucket applied immediately by the kernel, before KLIQ reacts. Useful during bootstrap before autotune has converged:

klshield set-default-rl --rate 1000 --burst 2000
klshield disable-default-rl

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

Set the global token bucket (legacy alias for set-default-rl):

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

Tuple enforcement (graph microsegmentation)

Tuple enforcement gives Shield XDP-level control over specific (src IP, dst port, proto) tuples. It is only practical for internal nodes with a small, stable set of clients (IDP, database, internal API). On public-facing nodes with thousands of internet client IPs, the edge maps fill up immediately and the system degrades.

Two modes:

• deny-mode (on): blacklist — denied tuples are dropped; the first violation packet passes (~1s), then KLIQ writes the deny entry
• allow-mode (allow): whitelist / default-deny — only tuples in edge4_allow pass; unknown tuples are dropped immediately with no race window

klshield tuple-enforce on      # deny-mode
klshield tuple-enforce allow   # allow-mode (default-deny)
klshield tuple-enforce off     # disable

Deny-mode management:

klshield add-edge-deny  --src <ip> --port <n> --proto tcp|udp|icmp
klshield del-edge-deny  --src <ip> --port <n> --proto tcp|udp|icmp
klshield list-edge-deny

Allow-mode management:

klshield add-edge-allow --src <ip> --port <n> --proto tcp|udp|icmp
klshield del-edge-allow --src <ip> --port <n> --proto tcp|udp|icmp
klshield list-edge-allow

Per-tuple rate limit:

klshield set-edge-rl --src <ip> --port <n> --proto tcp|udp|icmp \
                     --rate <pps> --burst <n>

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)

Map capacity limits

Critical limit: xdp_flow4_stats holds only 32k tuples. On public-facing nodes with many internet clients this fills instantly, making graph learning unusable. Graph learning and tuple enforcement only make sense on internal nodes where source cardinality stays well below 32k.

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 /sys/fs/bpf/kernloom_flow4_stats

See also