Auth and Config
zwallctl authentication and config
Purpose
Point zwallctl at a Manager and obtain a JWT without putting the password in shell history.
Prerequisites
zwallctlbinary matching the Manager edition- Manager URL (Enterprise example YAML
https://manager.example.com:8443) - Admin username and password (2FA code when enabled)
Config file
Default path: ~/.zwallctl/config.yml (created mode 0600 on save).
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Type | Default | Secret | Required |
|---|---|---|---|---|
manager_url | URL | http://localhost:8080 | no | no |
auth_token | string | empty | yes | after login |
pin_dir | path | /sys/fs/bpf/fw | no | local map commands |
output_mode | table | json | quiet | table | no | |
verbose | bool | false | no |
Port mismatch: example Manager listen is 8443; zwallctl default is http://localhost:8080. Always pass --manager-url until the file matches reality.
Load order: --config path → file → env (ZWALL_MANAGER_URL, ZWALL_AUTH_TOKEN, ZWALL_PIN_DIR, ZWALL_OUTPUT_MODE, ZWALL_VERBOSE=true) → flags (--manager-url, --token, --pin-dir, --output/-o, --verbose/-v, --quiet/-q, --json).
--config is a hidden cobra flag. Default file path is ~/.zwallctl/config.yml.
Global flags: Command Index.
zwallctl login
Syntax. zwallctl login [--username|-u NAME] [--password|-p PASS] [--no-save] [--manager-url URL]
Purpose. POST /api/v1/auth/login and store JWT in the config file unless --no-save.
Arguments. None.
Flags. --username/-u; --password/-p (not recommended); --no-save.
Defaults. Username prompted if omitted; password read hidden when --password omitted.
Edition. SHARED.
Prerequisites. Reachable Manager; HTTPS cookie policy does not block login JSON (JWT is still returned when cookie issuance succeeds).
Example.
zwallctl login --manager-url https://manager.example.com:8443 --username adminExpected output. Success text plus saved config path. JSON/table depending on --output. Token must not be copied into tickets.
Important errors. 401 Invalid credentials; 401 requires_2fa (pass TOTP via login JSON is not a cobra flag — use password+2FA in the Manager console or expect login failure until the CLI sends two_factor_code; if the cobra login command does not prompt for 2FA, use the API). 400 Secure HTTPS session required. 429 rate limit.
Security. Prefer interactive prompt. Config mode 0600. --token on argv is visible in ps.
Related. logout, ping.
zwallctl logout
Syntax. zwallctl logout
Purpose. Clear stored auth_token (and call Manager logout when implemented by the CLI client).
Arguments / flags. None.
Edition. SHARED.
Example. zwallctl logout
Expected output. Confirmation that the local token was cleared.
Security. Does not wipe systemd credentials.
Related. login.