Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Troubleshooting › CLI

CLI

zwallctl troubleshooting (pointer)

SharedStatus: SUPPORTED as a pointer. Do not duplicate the CLI book here.Audience: operator

The operator-usable CLI incident table lives in Troubleshooting. Command flags live in Command Index. Auth and config file live in Auth and Config.

This page only binds CLI failures to the rest of the troubleshooting set so operators do not copy folklore.

Symptom

zwallctl cannot talk to the Manager, prints “not implemented,” or secret rotation does not match the edition.

Likely verified causes (do not expand here)

Scroll sideways to see the full table. Use the arrow keys when focused.

SymptomCauseWhere to go
connection refusedDefault Manager URL http://localhost:8080; example Manager listen 8443Manager Unavailable, CLI troubleshooting
x509 / TLS errorsHTTP client vs TLS ManagerManager Unavailable, TLS
401Missing/expired admin JWTCLI auth; AUTHENTICATION
start / stop warningNot implemented remotelysystemd in SERVICE_CONTROL
restart --agent 409Hosting AgentAgent Disconnected
Enterprise secret-rotate errorAPI rotation retired; use setup.sh --manager-secret-custody rotate (not certified)Operator commands
Community secret-rotate jwt|db|allStill a live Manager API (POST /api/v1/admin/rotate-secret)Operator commands
Folklore firewall list / map dumpNot cobra commandsCommand Index
zwallctl deny created a rule but no dropPosts BLOCK_IP_INBOUND; Hosting cannot receive rulesEnforcement

Diagnostic commands/endpoint

Use the CLI book. Binding facts only:

zwallctl ping --manager-url https://manager.example.com:8443
zwallctl login --manager-url https://manager.example.com:8443 --username admin

zwallctl start prints that remote start is not implemented and suggests systemd. It also prints a stale path /etc/zwall/agent.yml — do not copy that path. Use the unit: Virtualization /etc/zcs/agent.yml, Hosting /etc/zwall-hosting/agent.yml.

What each result means

See Troubleshooting. Manager /health/ready failing is not a zwallctl bug.

Safe remediation

  1. Set --manager-url or ZWALL_MANAGER_URL to the real HTTPS Manager.
  2. Login interactively (avoid --password in shared scripts).
  3. Use systemd for process control.
  4. For secrets: follow edition-specific CLI notes in Operator commands. Do not put secret values on argv in examples.

Do-not-do warnings

  • Do not document start/stop as remote power.
  • Do not assume Community and Enterprise secret-rotate are the same command.
  • Do not put live JWTs in --token examples.
  • Do not copy README folklore commands.

Escalation condition

Escalate only after the Manager is ready and the CLI still fails against the same URL that curl /health/ready succeeds on.

Edition

SHARED CLI core. License subtree and retired Enterprise secret-rotate are ENTERPRISE. Community secret-rotate [jwt|db|all] remains live API.

Status

SUPPORTED as a pointer. The remote start/stop and port-mismatch issues remain product/docs gaps.