CLI / Headless Operations Guide

1. Components

A headless deployment runs on the daemon + roamswitch CLI (plus roamswitch-mcp if desired). All autonomous defense mechanisms work without any GUI.

2. Daemon (systemd services)

Client Edition

sudo systemctl status  roamswitch.service      # Status
sudo systemctl enable  roamswitch.service      # Auto-start at boot (enabled at install)
sudo systemctl restart roamswitch.service      # Restart
journalctl -u roamswitch.service -f            # Follow logs
journalctl -u roamswitch.service --since "1h ago"

What the client daemon does autonomously on startup and every cycle (3 s):

• Identifies the connected gateway MAC and applies nftables profiles (open / balanced / lockdown) against trusted_networks
• Behavioural ransomware detection (fanotify + Shannon entropy + canaries)
• On-access malware scanning (fanotify, optionally ClamAV)
• ARP spoof monitoring and preventive gateway ARP/NDP pinning on untrusted networks
• Kernel hardening (sysctl / Yama / core dumps / /tmp noexec) per profile
• Threat-protection DNS enforcement (dns_enabled + dns_scope)
• Link guard (NFQUEUE) for phishing interception
• Runtime state output to /run/roamswitch/state.json

Server Edition

sudo systemctl status  roamswitch-server.service      # Status
sudo systemctl restart roamswitch-server.service      # Restart
journalctl -u roamswitch-server.service -f            # Follow logs

3. CLI Command Reference

Basic syntax: roamswitch <command> [options]. Running without arguments defaults to status. Output language automatically follows the OS locale (LC_ALL / LC_MESSAGES / LANG).

Isolation (Air-Gap) Policy

Releasing on a fixed timer alone lets a patient attacker wait it out, so the trigger of an isolation is classified by confidence (both editions).

• Low confidence (a manual Air-Gap, generic anomalies, eBPF Error / Warning and below): fully restored after a short timer (client: airgap_low_confidence_secs, 600 s by default; server: safety_timer_secs in guard.yaml, 300 s by default; 0 disables the timer).
• High confidence (canary tampering, ransomware-style mass rewriting, ARP spoofing under lockdown, eBPF Critical / Emergency / Alert, repeated firing of the same rule and so on): never restored silently. After the timer the cause (frozen PID, canary, ARP, re-firing rule) is re-checked and the isolation is released with a notification only when the cause is verified cleared. If that cannot be confirmed, nobody has acknowledged it and the cap is reached (client: airgap_hard_cap_secs; server: isolation_hard_cap_secs in server.conf; both 3600 s by default, 0 = no cap), it moves to DEGRADED mode.
• DEGRADED mode never opens on a timer (the client allows loopback only; the server allows only the maintenance-SSH and whitelisted-IP management paths). It is released only by a verified-cleared re-check, an explicit acknowledgement (server: roamswitch server ack) or a manual release (the GUI button / roamswitch emergency-restore). In the client’s DEGRADED mode the Wi-Fi rfkill is not lifted either, unless airgap_degraded_lift_rfkill is true.
• Established connections other than the management paths are cut (server: everything except the maintenance SSH ports and whitelisted IPs, so a C2 channel or reverse shell the attacker already has open is cut too). A manual Air-Gap is low confidence when it comes from the menu / GUI / roamswitch airgap enable with no warning context, but when it is started from the “block now” button of an ARP-spoofing warning it inherits that warning’s (high) confidence, and the gateway’s MAC is re-checked without sending any traffic until it matches the trusted MAC on consecutive checks (arp_recheck_consecutive checks spanning at least arp_recheck_min_secs seconds). Every transition is recorded in the incident timeline.

Ransomware Recovery (Snapshots & File Restore)

The following commands belong to roamswitch-ransomware-rollback (they are not roamswitch subcommands). Its state is stored in /var/lib/roamswitch.

Examples

sudo roamswitch status                 # Client full diagnostic (27 items)
sudo roamswitch status --server        # Server Edition full diagnostic (34 items)
sudo roamswitch ports -a               # All listening ports
roamswitch guards                      # Guard status
roamswitch audit-url https://examp1e-login.com
roamswitch audit-secrets ./deploy.env
roamswitch audit-secrets .                          # Recursively scan the current directory
roamswitch audit-logs 72               # Analyze logs from the last 72 hours
sudo roamswitch sharing on             # Auto-stop SSH/Samba/RDP on untrusted networks
sudo roamswitch fim verify             # FIM file integrity verification
sudo roamswitch fim update             # Update FIM baseline
sudo roamswitch emergency-restore      # Fully clear emergency lockdown and restore
sudo roamswitch airgap enable          # Emergency lockdown
sudo roamswitch airgap disable         # Disable
sudo roamswitch server ack             # Acknowledge the emergency isolation (keeps a FULL isolation strict, releases a DEGRADED one)
roamswitch canary                      # Canary incident history
roamswitch vuln-status                 # Shows the last scan result and days elapsed (pass_age)
roamswitch port-anomaly                # Port Anomaly Guard's incident history
roamswitch server ebpf                 # eBPF guard's containment status and incident history
roamswitch server bans                 # State of the SSH brute-force guard and the sources it has banned
sudo roamswitch server unban 203.0.113.9   # Lift an SSH-guard ban (needs root)
roamswitch notifications               # Notification history from the past 7 days
roamswitch frozen                      # List processes held in SIGSTOP
sudo roamswitch frozen resume 12345    # Release a false-positive freeze
sudo roamswitch sensor pair --addr 192.168.1.50 --code AB3DFGH2 --fingerprint 3F:45:89:E1:...:36:10  # Pairs with Sensor using a pairing code
sudo roamswitch sensor key             # Shows this endpoint's own public key/address
roamswitch port-scan                   # Port-scan detection history
roamswitch timeline --json             # all incident-timeline records as JSON
roamswitch notifications --export n.jsonl   # JSON Lines
sudo roamswitch events search --since 2h --exe curl
sudo roamswitch forward status
sudo roamswitch server allowlist add "<rule>" mytool --exe /usr/local/bin/mytool
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>
sudo roamswitch server tui

The Server Edition daemon runs as root, so commands that need to read the nftables ruleset or identify a process's owner (status / status --server / ports -a) return inaccurate results without sudo (a false “inactive” verdict, or missing process info). Commands that change configuration (sharing / fim update / airgap / emergency-restore, etc.) likewise require sudo. Every other, read-only command works correctly without it.

4. Configuration Files

Client Edition (~/.config/roamswitch/config.json)

The daemon runs as root and scans /home/*/.config/roamswitch/config.json, using the first valid file it finds (or /root/.config/roamswitch/config.json in root-only environments).

Server Edition (/etc/roamswitch/server.conf)

The server edition uses an INI-format configuration file protected with permissions 0600 (root only). The type, allowed values, default and restart requirement of every key are in Server Operations Manual §18. Change keys with roamswitch server config show|get|set or in the config editor of roamswitch server tui (all 146 keys of server.conf and guard.yaml). The server edition does not support reloading its configuration, so apply changes with sudo roamswitch server restart.

Shared machines: admin-only mode

On a machine shared by several people, sudo touch /etc/roamswitch/admin-only turns on admin-only mode. Changes that affect the whole machine (firewall, DNS, VPN, USB, kernel and mount hardening, radios, Sensor trust and the like) are then limited to root or users in the sudo, wheel or roamswitch group. Actions tied to your own files and processes (isolation, kill, freeze, scans) work as before. /etc/roamswitch/admin-only counts only when it is owned by root and not writable by others (a user cannot create it and switch the mode themselves). It is off by default (no file).

5. Logs & Runtime State Files

Calling IPC Directly (Advanced)

The daemon accepts newline-delimited JSON on /run/roamswitch/roamswitch.sock:

# Force-switch profile (Client Edition)
printf '{"id":1,"method":"set_security_level","params":{"level":"lockdown"}}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

# Reconcile gateway ARP lock now
printf '{"id":1,"method":"reconcile_gateway_lock","params":null}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

6. Programmatic Status (MCP)

roamswitch-mcp exposes read-only tools over JSON-RPC on stdio (get_security_report / verify_security_findings / get_exposed_ports / get_guard_status / audit_url_safety / audit_secrets / audit_security_logs / audit_mcp_configs / audit_agent_setup / get_app_help / get_quarantine_status / get_file_scan_guard_status / verify_fim / get_port_anomaly_incidents / get_ebpf_incidents / get_resource_guard_incidents / get_port_scan_incidents / get_ssh_guard_incidents / get_canary_status / get_vulnerability_scan_history / get_notification_history / search_exec_events / get_process_tree / get_incident_timeline / get_fleet_status / get_vpn_status / get_link_guard_status / get_air_gap_status / get_sharing_services_status / get_bluetooth_guard_status / get_usb_guard_status / run_active_vuln_scan / run_package_cve_scan / run_package_cve_scan_languages / run_package_lifecycle_script_scan / run_typosquat_scan / run_npm_audit_signatures / get_sensor_audit_results).

It does not connect to external hosts and talks locally to the daemon's Unix socket or calls roamswitch-core directly. get_security_report and verify_security_findings send nothing to the LAN either (the gateway is only looked up in the ARP cache and other local information). See MCP Setup Guide

• RoamSwitch for Linux Product Page
• Client Security Whitepaper
• Server Security Whitepaper
• Server Operations Manual
• AI Assistant & MCP Integration Guide
• FAQ