OPERATOR CLI REFERENCE (HGCTL)

The hgctl binary provides administrative control, config validation, peer mesh diagnostics, and manual firewall interventions. It communicates with the local Hackergate daemon over a protected UNIX domain socket (/run/hackergate/admin.sock) with zero network overhead.

1. Daemon Status & Real-Time Diagnostics

Query system health, memory allocations, active TLS socket connections, and threat mesh status:

hgctl status --detailed
$ hgctl status --detailed [HACKERGATE CORE STATUS] Version: v4.0.1 (linux/amd64, go1.24) Uptime: 48d 14h 22m 10s Dataplane Status: HEALTHY (zero memory leaks, GC pause <45μs) Active Workers: 32 (GOMAXPROCS: 32) Open Connections: 1,429 (HTTP/1.1: 82, HTTP/2: 1,114, HTTP/3 QUIC: 233) Total Requests: 489,120,441 Blocked Attacks: 2,410,982 (0.49%) [VIRTUAL HOST SUBSYSTEM] Loaded VHosts: 18 domains active Pending Changes: 0 (all configs synced) ACME Certificates: 18 valid (next renewal in 42 days) [THREAT MESH PEERS] Connected Peers: 3 / 3 online (latency avg: 14.2ms) Active Mesh Bans: 894 IPs quarantined in kernel nftables

2. Virtual Host Inspection & Pre-Flight Testing

Validate configuration syntax before deploying to prevent routing outages:

VHOST COMMANDS
# List all active virtual hosts and their backend health: $ hgctl vhosts list DOMAIN BACKEND DRIVER TARGET WAF TLS STATUS api.example.com proxy http://10.0.0.15:8080 ON(PL2) VALID (exp: 2027-02-14) web.example.com loadbalancer 3 healthy origins ON(PL1) VALID (exp: 2027-02-14) static.example.com static /var/www/static OFF VALID (exp: 2027-03-01) # Pre-flight validate a new virtual host YAML file: $ hgctl test-config /etc/hackergate/vhosts.d/new-service.yaml ✓ Syntax: Valid YAML ✓ Backend: http://10.0.0.90:8080 reachable (latency 0.8ms) ✓ WAF Config: 2 custom rules parsed successfully ✓ Config OK. Safe to reload. # Hot-reload routing table with zero dropped client connections: $ hgctl reload ✓ Daemon notified. Atomic routing table swap completed in 1.4ms.

3. Threat Mesh Diagnostics & Emergency IP Bans

Intervene during zero-day incidents by injecting or revoking quarantine entries across the entire cluster:

THREAT MANAGEMENT COMMANDS
# Check status of peer threat gossip mesh: $ hgctl mesh peers PEER NODE ID ADDRESS RTT HEARTBEAT EVENTS SYNCED edge-iad-01.prod https://edge-iad-01.internal:8088 18.2ms 0.4s ago 14,920 edge-sin-01.prod https://edge-sin-01.internal:8088 88.5ms 0.2s ago 14,920 edge-tok-01.prod https://edge-tok-01.internal:8088 94.1ms 0.1s ago 14,920 # Manually ban an IP across all nodes and kernel nftables sets: $ hgctl ban add 203.0.113.88 --ttl 24h --reason "zero_day_probing" ✓ IP 203.0.113.88 added to local nftables set @hg_banned_ipv4 (timeout: 24h0m0s) ✓ Gossip event broadcast to 3 peer nodes. # List currently quarantined IPs and remaining TTLs: $ hgctl ban list --active TARGET TYPE REASON EXPIRES IN ORIGIN 203.0.113.88 IP zero_day_probing 23h 59m 48s local (operator) 198.51.100.42 IP owasp_crs_sqli_repeat 18h 12m 04s edge-iad-01.prod 192.0.2.0/24 CIDR mass_port_scanner 4d 06h 11m edge-sin-01.prod # Remove an IP ban immediately: $ hgctl ban remove 203.0.113.88 ✓ IP removed from local kernel set and unban broadcast sent to mesh.

4. Automation & Scripting Integration (--json)

Every hgctl command supports the --json flag, making it ideal for integration into CI/CD pipelines, automated incident response runbooks, and Prometheus blackbox scripts:

hgctl vhosts list --json | jq .
$ hgctl vhosts list --json | jq '.[0]' { "name": "api.example.com", "domains": ["api.example.com"], "backend": { "driver": "proxy", "target": "http://10.0.0.15:8080" }, "waf": { "enabled": true, "paranoia_level": 2 }, "tls": { "status": "valid", "expires_at": "2027-02-14T12:00:00Z" } }
← PREV: OBSERVABILITY & METRICSBACK TO DOCS HUB ↵