Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Operations › Service Control

Service Control

SharedStatus: SUPPORTED for systemd. zwallctl start / stop are not remote control.Audience: Linux operator

Purpose

Start, stop, restart, and reload Manager and Agent processes using the units shipped in the product.

Prerequisites

  • Units installed from the edition you run
  • Root or an account allowed to manage those units

Units (Enterprise trees)

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

UnitRoleUserNotes
zwall-manager.serviceManagerzwall-managerExecStart=/opt/zwall-manager/bin/zwall-manager -config /etc/zwall-manager/manager.yml; ExecReload=/bin/kill -HUP $MAINPID; After postgresql.service
zwall-agent.serviceVirtualization AgentrootExecStart=/opt/zcs/bin/zwall-agent --config /etc/zcs/agent.yml; needs /sys/fs/bpf
zwall-hosting-ebpf-loader.servicepass-only loaderrootloads hosting_observe.o; ExecStop --detach; Before v2 Agent
zwall-hosting-agent.serviceHosting Agent v1 unitzwall-hosting--config /etc/zwall-hosting/agent.yml; SupplementaryGroups adm psaserv
zwall-hosting-agent-v2.serviceHosting Agent v2 unitzwall-hosting--config /etc/zwall-hosting/agent-v2.yml; SupplementaryGroups adm only

Path prefixes are not unified. Community scripts/setup.sh may install zwall-manager / zwall-agent with /etc/zcs paths. Use systemctl cat on the host.

Procedure — Manager 

sudo systemctl start zwall-manager
sudo systemctl stop zwall-manager
sudo systemctl restart zwall-manager
sudo systemctl reload zwall-manager

Reload sends SIGHUP (ExecReload). Treat HUP as “request reload,” not a certified live-apply of every YAML key. YAML listen port, TLS files, and database DSN still require a restart in practice.

After start, check health. TimeoutStartSec=60, TimeoutStopSec=30, Restart=on-failure, RestartSec=5 on the Enterprise Manager unit.

Procedure — Virtualization Agent 

sudo systemctl start zwall-agent
sudo systemctl stop zwall-agent
sudo systemctl restart zwall-agent

Enforcement requires this root unit, not the Hosting unit. Do not enable zwall-agent.service as a drop engine on a shared hosting node that runs Hosting observation.

Manager API restart: POST /api/v1/agents/:id/restart (zwallctl restart --agent ID). Hosting observation Agents return 409.

Procedure — Hosting Agent

Order:

  1. Start loader, then Agent.
  2. Stop Agent, then loader (ExecStop detaches programs).
sudo systemctl start zwall-hosting-ebpf-loader
sudo systemctl start zwall-hosting-agent      # or zwall-hosting-agent-v2

sudo systemctl stop zwall-hosting-agent
sudo systemctl stop zwall-hosting-ebpf-loader

Loader StartLimitBurst=3 / StartLimitIntervalSec=300. Agent the same. Do not restart-loop a failing loader.

CLI commands that are not service control 

zwallctl start
zwallctl stop

These print that remote start/stop is not implemented and tell the operator to use systemd.

zwallctl restart --agent 1
zwallctl restart --all

These call the Manager restart API. --all lists Agents then restarts each; Hosting IDs 409.

Verification 

systemctl is-active zwall-manager
systemctl is-active zwall-agent
curl -fsS https://MANAGER_HOST:8443/health/ready
zwallctl list-agents --manager-url https://MANAGER_HOST:8443

Hosting: both loader and Agent active; GET /api/v1/agents/:id/hosting/status.

Failure modes

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

SymptomMeaningAction
unit not foundwrong name or Community vs Enterprise layoutsystemctl list-units 'zwall*'
start timeoutbinary missing, config path wrong, PostgreSQLjournalctl
restart loopconfig validation fail, missing credentialsjournal; do not keep restarting
409 on zwallctl restartHosting observation Agentrestart the Hosting systemd unit instead
HUP appears to do nothingkey requires full restartsystemctl restart

Security considerations

  • Virt Agent runs as root with a bounded capability set.
  • Hosting Agent has empty CapabilityBoundingSet.
  • Manager has empty capabilities and ProtectSystem=strict.
  • Do not grant Hosting Agent extra groups to “make logs work” without an ACL review.

Limitations

  • No remote power control via zwallctl.
  • No certified live-reload of all keys.
  • Cluster failover is not a public HA procedure.