Agent Enrollment
Agent enrollment and admission
Purpose
Admit an Agent without leaving agents.auto_register on. Production example sets auto_register: false and comments say it must remain false.
Audience
Administrators creating the one-time bootstrap and operators starting the Agent unit.
Edition
SHARED register/heartbeat. Enterprise adds optional security_level: maximum (mTLS), Hosting profile fields, and Hosting env unset after load. Community rejects a fourth Agent.
Status
SUPPORTED.
Prerequisites
- Manager reachable at the URL the Agent will use (
server.manager_url) - TLS verification planned (
verify_tls: true) - Administrator session
- For Hosting: Hosting units and
hosting.enabled: true - For Virtualization: root unit
zwall-agent.service
Required permissions
Admin for POST /api/v1/agents/pre-register and /create. Root on the node to start units and place environment.
Dependencies
Clock skew small enough for JWT expiry. Manager auth.agent_token_ttl example 8h.
Configuration
Agent YAML server.token: "". Bootstrap via environment AGENT_TOKEN or AGENT_PRE_TOKEN, then local persistence.
Pre-register body (admin):
Scroll sideways to see the full table. Use the arrow keys when focused.
| Field | Required | Notes |
|---|---|---|
hostname | yes | |
expected_ip | yes | |
agent_id | no | |
description | no | |
expiry_hours | no | |
security_level | no | default standard; maximum = mTLS |
profile_type / profile_platform / profile_version | no | Hosting identity |
observation_only | no | Hosting |
Invalid security_level → 400. Invalid profile identity → 400.
Procedure (admin-created / pre-register)
- Log in (
POST /api/v1/auth/loginor console /zwallctl login --manager-url https://manager.example.com:8443 --username admin). - Create or pre-register:
POST /api/v1/agents/createPOST /api/v1/agents/pre-register
- Place the one-time bootstrap token in the Agent environment (
AGENT_TOKENper example comments), not as a long-lived YAML JWT. - Start the Agent:
- Virtualization:
systemctl enable --now zwall-agent - Hosting: loader first, then
zwall-hosting-agentorzwall-hosting-agent-v2
- Virtualization:
- Agent calls
POST /api/v1/agents/register(rate limited). Response includestoken,agent_id,expires_at,is_temporary. - Confirm
GET /api/v1/agentsshows the Agent. - Hosting: leftover
AGENT_TOKEN/AGENT_PRE_TOKENis unset by the Hosting-enabled Agent after config load. Identity file/var/lib/zwall-hosting/agent.identity. - Subsequent traffic:
POST /api/v1/agents/heartbeat,POST /api/v1/agents/token/refresh.
Enterprise scripts/setup.sh --agent-only exists with --manager-url, --pre-token, --hostname, --interface, --host-type, --protection-model. Do not set --protection-model hybrid on a Hosting node (the hybrid example is for a different profile).
Verification
zwallctl login --username admin --manager-url https://manager.example.com:8443
zwallctl list-agentszwallctl login --password exists but is not recommended.
Hosting: GET /api/v1/agents/:id/hosting/status and heartbeat observation_only.
Virtualization: Agent online; rules assignable (Hosting assign → 409).
Expected result
Agent JWT issued, heartbeat continuing, auto_register still false. Community: at most three Agents.
Failure modes
Scroll sideways to see the full table. Use the arrow keys when focused.
| Cause | Diagnostic | Remediation |
|---|---|---|
| auto_register false and no pre-register | 4xx on register | pre-register / create first |
| Community 4th Agent | rejection | stay at 3 or move to Enterprise |
| TLS verify | Agent log TLS errors | valid Manager cert; do not flip allow_insecure_remote_tls except break-glass |
| Wrong Manager URL / port | Agent log | match server.manager_url |
| Bootstrap token missing | register unauthorized | AGENT_TOKEN once, then local persist |
| Hosting vs virt unit mix | unit names | Hosting vs Virtualization |
| Re-enroll with stale identity | old agent.identity | clear local credential after backup decision |
security_level typo | 400 | standard or maximum |
See Agent cannot enroll.
Troubleshooting
journalctl on the Agent unit. Manager RegisterRateLimiter may reject sprays. Revoke via POST /api/v1/agents/:id/revoke-token if the token leaked — that does not uninstall the unit.
Security considerations
- One-time bootstrap, not YAML JWT.
maximummTLS is transport trust, not Hosting packet policy.- Do not publish live pre-tokens.
- Hosting must not keep bootstrap env in the unit after start.
Limitations
Exact JSON field name for the register token (body vs header) is not duplicated here as a second schema. Follow the Agent runtime. No OIDC.
Related documentation
- Agent/Manager trust
- CLI auth
- Agent register/heartbeat HTTP details are provided separately to Enterprise customers.
- Identity