Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Operations › TLS

TLS

TLS operations

Status: SUPPORTED for replacing server.tls.cert_file / key_file and restarting. ACME = NOT_VERIFIED / not Community.

SharedAudience: deployment engineer

Purpose

Terminate TLS on the Manager listener using files referenced in YAML, rotate them, and know what is not a certified ACME product.

Prerequisites

  • server.tls.enabled: true (example)
  • server.tls.cert_file and server.tls.key_file readable by the Manager user (zwall-manager on the Enterprise unit)
  • For the helper script: openssl

Configuration

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

KeyTypeNotes
server.tls.enabledboolif true, cert and key are required
server.tls.cert_filepathexample /etc/ssl/certs/manager.crt; script default dir /etc/zcs/certs/manager.crt
server.tls.key_filepathsecret; mode 640 in the generator
mTLS nested keysEnterpriseAgent client certs when security_level maximum; not a public mTLS product cookbook

Cookie issuance on Enterprise login can require HTTPS (Secure HTTPS session required). CLI login uses Bearer JWT and is not the browser cookie path.

Procedure — generate a lab/internal certificate

scripts/generate_tls_certs.sh:

sudo ./scripts/generate_tls_certs.sh -d /etc/zcs/certs -h manager.example.com -o 365 --self-signed

Verified behavior:

  • Default dir /etc/zcs/certs, host manager.local, days 365
  • RSA 4096, SHA-384, SAN DNS=HOST + localhost, IP 127.0.0.1
  • Writes manager.key / manager.crt
  • Refuses to overwrite an existing manager.key
  • --real / --skip-gen skips generation and tells you to place files yourself

This is not a public CA. Browsers will warn. Use an organization CA or a publicly trusted certificate in production.

Point YAML at the files, ensure the Manager user can read the key, restart Manager.

Procedure — rotate files

  1. Install new cert + key beside or over the configured paths (respect overwrite refusal of the helper).
  2. sudo systemctl restart zwall-manager (HUP is not certified to re-read TLS files).
  3. Verify:
curl -fsS https://MANAGER_HOST:8443/health/live
# or openssl s_client -connect MANAGER_HOST:8443 </dev/null

Community installation guide mentions GET /cert/status. Enterprise admin GET /cert/status is authenticated. POST /cert/renew is admin-authenticated and is not Community ACME.

ACME (Enterprise only)

Enterprise contains HTTP-01 and Cloudflare DNS-01 configuration under letsencrypt.*. Community does not ship product ACME.

Status: not a certified customer ACME matrix. Do not document Auto ACME for arbitrary DNS providers. Do not document Let’s Encrypt staging as a production trust path (letsencrypt.use_staging).

If you use an external reverse proxy, keep server.trusted_client_ip off unless you terminate TLS on loopback and set exact /32 or /128 proxy CIDRs with max_hops: 1.

Verification

  • GET /health/live over HTTPS succeeds with a client that trusts the cert
  • Browser /login does not fail with Secure HTTPS session required when you intend cookie sessions
  • zwallctl login --manager-url https://MANAGER_HOST:8443 works (Bearer path)

Failure modes

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

SymptomMeaningAction
Manager fails to startmissing cert/key while enabledpaths + permissions for zwall-manager
generate_tls_certs.sh exits on existing keyoverwrite guardrotate with new filenames or move the old key
clients reject certhostname not in SANregenerate with -h matching the URL
HTTP 400 Secure HTTPS session requiredcookie policyuse HTTPS; CLI still uses JWT
Agent verify_tls: true failsAgent does not trust Manager CAserver.custom_ca_path / trust_mode on the Agent — do not set allow_insecure_remote_tls except break-glass

Security considerations

  • Product-enforced: TLS can be enabled and required for cookie issuance.
  • Operator recommendation: trusted certificates, restricted ReadWritePaths, no world-readable keys.
  • Not certified: ACME matrix, mTLS as a marketed product, split-mode plus external proxy as a hardened standard.

Limitations

Listen port vs zwallctl 8080 is a known mismatch. Certificate directory /etc/zcs/certs vs unit paths is a known prefix inconsistency. ACME is not certified.