CLI Reference

OpenShield-XDP provides two binaries:

openshield — full-featured user CLI with TUI, config generation, repair, and upgrade
openshield-loader — minimal systemd daemon binary (reduced surface, fewer commands)

`openshield` commands

`openshield load`

Load and attach the XDP program, then start telemetry collection and (by default) launch the TUI dashboard.

bash

sudo openshield load [flags]

Flag	Type	Default	Description
`-t`	int	`0`	Auto-unload after N seconds (`0` = run forever)
`--refresh`	int	`1000`	Stats refresh interval in milliseconds
`--stats-off`	bool	`false`	No stats display (daemon mode for systemd)
`--stats-minimal`	bool	`false`	Minimal text stats instead of full TUI
`-i`	string	(from config)	Override config interface
`-m`	string	(from config)	Override XDP mode: `native`, `generic`, `skb`

See Load Command Deep-Dive for the full loading lifecycle, safety confirmation, and auto-repair flow.

`openshield unload`

Gracefully unload the XDP program, detach from the NIC, remove BPF pins, stop the loader process, and clean up socket/PID files.

bash

sudo openshield unload

Three-phase process:

Stop running loader process (SIGINT → SIGTERM → SIGKILL fallback)
Remove all BPF pins via bpf.Unload()
Force-detach any orphaned XDP program from the NIC

`openshield status`

Show the current state of the XDP program, loader process, telemetry socket, and configuration.

bash

sudo openshield status

See Status Output Format for detailed field descriptions.

`openshield reload`

Reload configuration without unloading the XDP program. Connects to the running loader's Unix socket and sends a config_update message.

bash

sudo openshield reload

Requires the loader to be running (the telemetry socket at /var/run/openshield/telemetry.sock must exist). All runtime-safe fields are applied immediately to the BPF config map.

`openshield fix`

Auto-detect and repair 7 categories of common issues.

bash

sudo openshield fix           # Standard repair
sudo openshield fix -v        # Verbose (show detail for each step)

See Fix Command Reference for the full list of fixable issues.

`openshield doctor` (v2.12.0+)

One-command environment health check: kernel version, BTF availability, XDP attach state, NIC driver, configuration validity, forensics disk space, and license status.

bash

sudo openshield doctor           # human-readable report
sudo openshield doctor --json    # machine-readable output for support tickets

`openshield tui` / `openshield stats`

Launch the TUI dashboard (if the loader is already running with stats enabled).

bash

sudo openshield tui
sudo openshield stats          # Alias

Connects to the loader's Unix socket and renders the 10-screen dashboard. Requires the loader to be running (start with openshield load --stats-off for daemon + openshield tui for dashboard).

`openshield config`

Interactive configuration generator. Walks you through each config section and saves to /etc/openshield/openshield.yaml.

bash

sudo openshield config

`openshield upgrade` (EXPERIMENTAL)

Automated 5-step upgrade: git pull → build BPF → generate bindings → build Go → stop/install/restart.

bash

sudo openshield upgrade

DANGER

Runs git clone and make as root. For production, prefer manual git pull && sudo ./install.sh --update.

`openshield install`

Run the installer script if present at /opt/openshield/lib/install.sh.

bash

sudo openshield install

`openshield whitelist` / `openshield blacklist`

Manage the live whitelist (bypasses all mitigation) and manual bans.

bash

sudo openshield whitelist add 203.0.113.10        # or a CIDR, or a file of IPs
sudo openshield whitelist remove 203.0.113.10
sudo openshield whitelist list
sudo openshield whitelist clear                   # remove ALL entries (asks for confirmation)

sudo openshield blacklist add 5.6.7.8 3600        # manual ban, duration in seconds (default 24h)
sudo openshield blacklist add 5.6.7.8 3600 "ssh brute force"   # with an optional note (v2.2.0+)
sudo openshield blacklist add bad_ips.txt         # bulk import from file
sudo openshield blacklist remove 5.6.7.8
sudo openshield blacklist list
sudo openshield blacklist clear                   # remove ALL bans (asks for confirmation)

Ban notes (v2.2.0+). Blacklist entries accept an optional free-text note — everything after the duration (or after the IP, if you omit the duration) is stored as the note. Notes are shown in blacklist list, the TUI access/bans views, and persist across restarts. Bulk bans created by geo blocking and attack mitigation are auto-tagged (e.g. geoblock: US (United States) — 241,377 prefixes), so you can always tell where a ban came from.

File import. Passing a path to a .txt file instead of an IP bulk-imports it — one IP or CIDR per line. The import validates every line, de-duplicates, and skips # comments, blanks, and invalid entries (skipped lines are printed to stderr). Works for both whitelist add <file> and blacklist add <file>, and in the TUI access tab's add input (type a path instead of an IP).

Clear (v2.2.0+). whitelist clear / blacklist clear empty the respective map entirely after a y/N confirmation. blacklist clear removes single-IP bans (v4 + v6); config-driven subnet bans (static.ban_subnets) are left untouched. The same operation is available in the TUI access tab with the C key (confirmation dialog included).

Whitelist entries persist (v2.0+)

whitelist add / whitelist remove write through to whitelist.ips in /etc/openshield/openshield.yaml, so entries survive loader restarts. Previously they lived only in the BPF map and were lost on restart. Whitelisting an IP also unbans it and mirrors it into auto_fetch.never_block so the blocklist fetcher can never re-ban it.

`openshield key`

Show the Metrics API URL and API key (only when metrics.enabled: true), or manage the key. Changes are hot-applied — no restart.

bash

sudo openshield key                  # show URL + key + curl example
sudo openshield key set <your-key>   # use your own key (min 8 chars)
sudo openshield key regen            # rotate to a fresh random key

See Metrics API.

`openshield behavior`

Show the behavior engine's learned per-port baselines and candidate source clusters (states, confidence scores, reasons).

bash

sudo openshield behavior

`openshield schedule`

Pause behavior-engine learning or auto-blocking ahead of a known traffic spike (launch day, migration).

bash

sudo openshield schedule list
sudo openshield schedule suppress baseline 6h
sudo openshield schedule suppress auto-block 6h
sudo openshield schedule clear baseline|auto-block|all

`openshield report`

Print a network analysis report (daily, weekly, or monthly).

bash

sudo openshield report [daily|weekly|monthly]

`openshield uninstall`

Remove OpenShield-XDP from the system (also available as uninstall.sh).

bash

sudo openshield uninstall

`openshield version`

bash

openshield version
# Output: OpenShield-XDP v2.1.1

Also accessible via openshield --version or openshield -v.

`openshield behavior`

Show the adaptive behavior engine's live state: learned per-port baselines (observations, median PPS, average packet size) and candidate clusters with confidence scores and reasons. See Adaptive Behavior.

bash

openshield behavior

`openshield schedule`

Manage suppression windows for baseline learning and auto pattern blocking — use ahead of a known legitimate traffic spike (launch, match start) so the surge neither poisons baselines nor gets auto-blocked. Schedules persist across restarts and expire automatically.

bash

openshield schedule list                          # show active windows
sudo openshield schedule suppress baseline 2h     # pause baseline learning 2h
sudo openshield schedule suppress auto-block 90m  # pause auto-blocking 90m
sudo openshield schedule clear baseline           # remove one window
sudo openshield schedule clear all                # remove all windows

`openshield whitelist` / `openshield blacklist`

bash

sudo openshield whitelist add 1.2.3.4            # or a CIDR, or a file of entries
sudo openshield whitelist remove 1.2.3.4
openshield whitelist list
sudo openshield whitelist clear                  # empty the whitelist (confirmation prompt)
sudo openshield blacklist add 5.6.7.8 3600       # manual ban (default 24h)
sudo openshield blacklist add 5.6.7.8 3600 "ssh brute force"  # optional note (v2.2.0+)
sudo openshield blacklist remove 5.6.7.8
openshield blacklist list
sudo openshield blacklist clear                  # empty the blacklist (confirmation prompt)

`openshield license`

bash

sudo openshield license activate <key>           # save and activate a license key
sudo openshield license refresh                  # force a re-check now
openshield license status                        # tier, HWID, expiry, grace

`openshield report`

Print a network analysis report (daily by default; weekly/monthly optional).

bash

openshield report [daily|weekly|monthly]

`openshield webhook-test` / `openshield alert test`

Send a dummy attack alert to the configured webhook to verify delivery and formatting.

Aliases

Alias	Command
`st`	`status`
`wl`	`whitelist`
`bl`	`blacklist`
`lic`	`license`
`cfg`	`config`
`dash`	`stats`

`openshield-loader` commands

The openshield-loader binary is a minimal daemon-oriented CLI used by the systemd service. It has fewer commands and no TUI integration.

bash

openshield-loader <command> [flags]

Command	Description
`load`	Load XDP with live stats display (text-based)
`unload`	Unload XDP and clean up
`stats`	Show live text statistics (requires XDP loaded)
`status`	Show current status
`reload`	Reload configuration without unloading
`version`	Show version
`help`	Show help

Load flags (loader variant)

Flag	Description
`-t <seconds>`	Auto-unload after N seconds
`--stats-off`	No stats display (daemon mode)
`-i <interface>`	Override config interface
`-m <mode>`	Override XDP mode

The systemd service runs: openshield-loader load --stats-off

System paths

Path	Purpose
`/etc/openshield/openshield.yaml`	Configuration file
`/var/run/openshield/telemetry.sock`	Unix socket for TUI/reload communication
`/var/run/openshield/loader.pid`	Loader process PID file
`/var/log/openshield/openshield.log`	Log file
`/opt/openshield/bin/`	Installed binaries
`/opt/openshield/lib/`	BPF object and libraries
`/sys/fs/bpf/`	BPF filesystem (pinned maps and programs)

Next steps

TUI Guide · Metrics API · Config Values in Plain Language · Load Deep-Dive

CLI Reference ​

openshield commands ​

openshield load ​

openshield unload ​

openshield status ​

openshield reload ​

openshield fix ​

openshield doctor (v2.12.0+) ​

openshield tui / openshield stats ​

openshield config ​

openshield upgrade (EXPERIMENTAL) ​

openshield install ​

openshield whitelist / openshield blacklist ​

openshield key ​

openshield behavior ​

openshield schedule ​

openshield report ​

openshield uninstall ​

openshield version ​

openshield behavior ​

openshield schedule ​

openshield whitelist / openshield blacklist ​

openshield license ​

openshield report ​

openshield webhook-test / openshield alert test ​

Aliases ​

openshield-loader commands ​

Load flags (loader variant) ​

System paths ​

Next steps ​

CLI Reference

`openshield` commands

`openshield load`

`openshield unload`

`openshield status`

`openshield reload`

`openshield fix`

`openshield doctor` (v2.12.0+)

`openshield tui` / `openshield stats`

`openshield config`

`openshield upgrade` (EXPERIMENTAL)

`openshield install`

`openshield whitelist` / `openshield blacklist`

`openshield key`

`openshield behavior`

`openshield schedule`

`openshield report`

`openshield uninstall`

`openshield version`

`openshield behavior`

`openshield schedule`

`openshield whitelist` / `openshield blacklist`

`openshield license`

`openshield report`

`openshield webhook-test` / `openshield alert test`

Aliases

`openshield-loader` commands

Load flags (loader variant)

System paths

Next steps