[ OPERATOR GUIDE 09 ]
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"
}
}