TUI Guide
The OpenShield-XDP terminal dashboard provides real-time visibility into your firewall state across 10 interactive screens. Built on Bubbletea, ntcharts, and lipgloss.
Launching
# Option 1: Load and view TUI in one command
sudo openshield load
# Option 2: Daemon + standalone TUI viewer
sudo openshield load --stats-off
sudo openshield tui
# Option 3: Minimal text mode
sudo openshield load --stats-minimalScreens at a glance
| Key | Screen | What it shows |
|---|---|---|
1 | Dashboard | Global PPS/BPS, packets passed/dropped, mitigation stats, protocol distribution, drop path breakdown, panic status |
2 | Traffic | Live PPS/BPS braille charts, peak/average stats, protocol distribution with bar charts |
3 | Attacks | Attack state, type, duration, spike intensity, top offender IPs with scores, attack timeline |
4 | Bans | Paginated ban table with IP, reason, score, remaining time, star rating, search/filter |
5 | Logs | Scrolling combined event+system log, search/filter, vi-style navigation, line wrapping |
6 | Status | System info (version, kernel, uptime), health badges, map utilization, drop path breakdown |
7 | Config | Live configuration browser/editor with pending change tracking, validation, and confirmation dialogs |
8 | Attack History | Past attacks with duration, peak rates, and forensics bundle locations |
9 | Access | Whitelist/blacklist management, ban notes, file import, clear-all, and the auto-fetch blocklist view |
0 | Geo | One-keypress country blocking backed by GeoLite2 data |
Navigation
| Action | Key(s) |
|---|---|
| Switch to screen N | 0–9 |
| Cycle screens forward | Tab |
| Cycle screens backward | Shift+Tab |
| Click nav tab | Mouse left-click |
| Toggle help overlay | ? |
| Quit | q or Ctrl+C |
Screen-specific controls
Logs screen (5)
| Action | Key |
|---|---|
| Scroll down/up | j / k or ↓ / ↑ |
| Page down/up | PgDn / PgUp |
| Jump to bottom | G |
| Jump to top | g |
| Search/filter | / (type query, Esc to clear, Enter to confirm) |
| Toggle wrap mode | w |
| Mouse scroll | Scroll wheel |
Bans screen (4)
| Action | Key |
|---|---|
| Next/previous page | n / p |
| Search by IP or reason | / (type query, Esc to clear) |
| Mouse scroll | Scroll wheel |
Attacks screen (3)
| Action | Key |
|---|---|
| Next/previous page of offenders | n / p |
Access screen (9)
Manages the live whitelist and blacklist. Entries show their ban note next to the IP when one is set.
| Action | Key |
|---|---|
| Switch whitelist / blacklist | w / b (or Tab) |
Add entry (IP, CIDR, note after a space, or path to a .txt list file) | a |
| Delete selected entry | d |
| Move entry to the other list | m |
| Clear the entire list (confirmation dialog) | C |
| Open the auto-fetch blocklist view | f |
| Refresh | r |
| Scroll | j / k or scroll wheel |
The auto-fetch view (f) shows fetcher status, last/next fetch, applied IP/CIDR counts, and manages the never_block list: t toggle, f fetch now, a add never-block, d remove, r refresh. See Auto-Fetch Blocklists.
Geo screen (0)
One-keypress country blocking. Enter/Space toggles the selected country; ◌ means a block is being applied, ✗ means it failed (reason in the notice line). b/a switch between block and allow-only mode, / searches. See Geo Blocking.
Config screen (7) — Live editor
| Mode | Action | Key |
|---|---|---|
| Browse | Navigate fields | ↑ / ↓ or j / k or Tab |
| Browse | Edit selected field | Enter (runtime-safe fields only) |
| Browse | Toggle read-only fields | r |
| Browse | Preview pending changes | a |
| Browse | Discard all pending changes | d |
| Browse | Revert individual field | x |
| Edit | Save value | Enter |
| Edit | Cancel | Esc |
| Edit | Backspace | Backspace |
| Confirm | Apply changes | y |
| Confirm | Cancel | n or Esc |
Config editor workflow
Charts & visualization
Braille resolution graphs
PPS and BPS are rendered as streamline charts using ntcharts with braille-dot resolution (8× higher than ASCII). The Y-axis auto-scales with 10% headroom above the rolling max (~60 data points). The X-axis scrolls left over time, showing recent traffic patterns.
Gradient status bar
The top status bar uses a 10-color gradient (green → yellow → red) based on attack intensity:
- Green: Normal operation, all clear
- Yellow: Elevated traffic, approaching thresholds
- Red: Under attack, spike factor displayed
Drop paths
The drop path breakdown (shown on Dashboard and Status screens) displays where packets are being dropped:
- Banned — matched existing ban entry
- RateDrop — exceeded per-IP rate threshold
- PanicDrop — panic circuit breaker engaged (bulk drop)
- DNS Amp — DNS amplification detected
- BogusTCP/L7 Drop/PrivSrc/Malform — validation filters
Reconnection behavior
The TUI connects to the loader's Unix socket at /var/run/openshield/telemetry.sock. If the connection drops (loader crash, socket removed):
- Display shows "Connecting to OpenShield-XDP..."
- Automatically retries every 3 seconds
- Full dashboard resumes when the loader comes back
This works whether you launched via openshield tui (standalone) or openshield load (embedded).
Mouse support
| Action | Gesture |
|---|---|
| Switch screen | Click nav tab in the navigation bar |
| Scroll logs | Scroll wheel on logs screen |
| Scroll bans | Scroll wheel on bans screen |
Environment
The TUI uses the alternate screen buffer (tea.WithAltScreen()) — your terminal scrollback is preserved when you quit. Terminal dimensions are auto-detected and layout adjusts: wide terminals get side-by-side panels, narrow terminals stack vertically.
CLI variants
openshield load # Full TUI (embedded in loader)
openshield load --stats-off # Daemon mode (no display)
openshield load --stats-minimal # Text snapshots printed to stdout
openshield tui # Standalone viewer (connects to running loader)
openshield stats # Alias for 'tui'