Agent CLI Reference

Complete reference for all ftagent command-line flags, the setup wizard, systemd service management, health check endpoint, and common workflows.

Synopsis

ftagent [--version] [--config PATH] [--setup] [--test] [--update]
       [--install-service] [--no-update-check] [--tui]
       [--api-key KEY] [--node-uuid UUID] [--limited]

All CLI Flags

Flag	Default	Description
--version		Print the agent version (e.g. `ftagent 1.9.31`) and exit.
--config PATH	/etc/ftagent/config.json	Path to config file. Useful when running multiple agents on one host or testing with a non-default config.
--setup		Run the interactive setup wizard. Prompts for API key, Node UUID, interface, PCAP mode, mirror mode, and GRE tunnel settings. Writes config and exits.
--api-key KEY		Set API key non-interactively. Must be used together with `--node-uuid`. Writes config and exits without prompts.
--node-uuid UUID		Set Node UUID non-interactively. Must be used together with `--api-key`.
--test		Test API connectivity to the Flowtriq backend. Loads config, sends a test request, prints OK or FAILED, and exits.
--install-service		Write a systemd service unit to `/etc/systemd/system/ftagent.service` and run `systemctl daemon-reload`. Requires root.
--update		Check GitHub/PyPI for a newer version and prompt to install. Rolls back on post-install verification failure.
--no-update-check		Skip the automatic (non-blocking, log-only) update check on startup.
--tui		Launch the terminal UI dashboard (requires `rich` package).
--limited		Run without root. Disables PCAP, IOC matching, TCP flag analysis, and source IP tracking. Monitors PPS/BPS via `/proc/net/dev` counters only.

Setup Wizard Walkthrough

Run sudo ftagent --setup and the wizard prompts for API key, Node UUID, interface, PCAP mode (scapy or tcpdump), monitoring mode (agent or mirror/SPAN), and GRE tunnel settings. For non-interactive setup:

sudo ftagent --api-key "ft_live_abc123..." --node-uuid "a1b2c3d4-..."

Running as systemd Service

sudo ftagent --install-service
sudo systemctl enable --now ftagent

The service unit runs as root with CAP_NET_RAW and CAP_NET_ADMIN capabilities, PrivateTmp=true, ProtectSystem=strict, and restarts on failure with 10-second delay.

sudo systemctl start ftagent    # Start agent
sudo systemctl stop ftagent     # Stop agent
sudo systemctl restart ftagent  # Restart after config change
sudo systemctl status ftagent   # Check status
sudo journalctl -u ftagent -f   # Tail logs

Health Check Endpoint

The agent exposes a JSON health endpoint on 127.0.0.1:9100 (configurable via health_port). Returns status, version, uptime, interface, current PPS/BPS, baseline state, and attack state.

curl -s http://127.0.0.1:9100/

Binds to 127.0.0.1 only. Set "health_port": 0 to disable.

Version Checking and Updates

sudo ftagent --update

Queries GitHub and PyPI, prompts for upgrade, handles --break-system-packages automatically, verifies the installed version and module imports, and rolls back on failure. After updating, restart: sudo systemctl restart ftagent.