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

Integrations

Integration failures

Status: SUPPORTED for implemented integrations only. Terraform/Ansible/Puppet/OIDC/Kubernetes/GraphQL are NOT_SUPPORTED.

SharedAudience: integration engineer, Manager administrator

Symptom

An integration that is documented as implemented does not connect, sync, notify, scrape, or observe. This is not one code path — diagnose by integration name.

Likely verified causes (class)

  1. Edition mismatch: Cloudflare HTTP group and unblock portal are Enterprise-only in V1 routers. Community does not ship those groups.
  2. Missing or wrong secret (token, MaxMind key, SMTP password, webhook secret, captcha secret).
  3. Feature not enabled in Manager YAML / security settings.
  4. License gate on Enterprise writes (403 LicenseErrorResponse).
  5. Agent profile mismatch (libvirt on Hosting; ModSecurity per-site files vs global metadata).
  6. /metrics scraped without admin auth.
  7. Treating optional sync as always-on bidirectional.

Diagnostic commands/endpoint

Manager must be ready. Admin JWT unless noted.

Per-integration endpoints are listed below. Generic:

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

Do not put tokens, SMTP passwords, or webhook secrets on argv.

Cloudflare (ENTERPRISE_ONLY)

Symptom. Blocks do not appear in Cloudflare; connect/health fails.

Causes. Not Community. Missing cloudflare_api_token / zone. License feature gate. Sync not triggered (auto_sync / sync_on_block not assumed always-on).

Diagnostics.

PUT  /api/v1/integrations/cloudflare/config
POST /api/v1/integrations/cloudflare/connect
POST /api/v1/integrations/cloudflare/verify
GET  /api/v1/integrations/cloudflare/health
GET  /api/v1/integrations/cloudflare/status
POST /api/v1/integrations/cloudflare/sync
GET  /api/v1/integrations/cloudflare/rules

Results. 403 license → entitlement. Connect fail → token/zone. Health OK but rules missing → trigger /sync; do not assume bidirectional certified sync.

Remediation. Scope a zone token; store as systemd credential cloudflare_api_token / CLOUDFLARE_API_TOKEN. Manual /sync after a lab block.

Do not. Document as Community. Document as always-on. Use the token as a global Cloudflare admin if a zone token suffices.

GeoIP / MaxMind

Symptom. Country rules do not match; /geoip/status empty or error.

Causes. Database file missing or not on an allowlisted path. security.geoip.enabled false. MaxMind credentials wrong. Agent geoip.database_path unset if local lookup is expected.

Diagnostics.

GET  /api/v1/geoip/status
POST /api/v1/geoip/rules
POST /api/v1/geoip/lookup

Config keys: security.geoip.* (database_path, maxmind_account_id, maxmind_license_key, auto_update, allow_on_lookup_failure). Secret: maxmind_license_key / ZCS_MAXMIND_LICENSE_KEY.

Results. Status without a DB → place file under validated allowlists (/usr/share/GeoIP, /var/lib, /opt/zcs, /etc/zcs). Lookup of TEST-NET may not exist in the DB.

Remediation. Install the GeoIP database; enable GeoIP; keep the MaxMind key in credential custody, not git.

Do not. Treat lookup as a public unauthenticated API. Claim zero performance penalty.

External blocklists

Symptom. Lists do not update; check-IP misses entries.

Causes. security.blocklists.enabled false (example default false). URL fetch timeout. Format mismatch. License gate on Enterprise writes.

Diagnostics.

GET  /api/v1/blocklists/stats
POST /api/v1/blocklists/sync
GET  /api/v1/blocklists/check/:ip

Sources: HTTP or file; update_interval, timeout, example cron 0 2 * * *.

Remediation. Enable, add a source, /sync, verify with a TEST-NET address you inserted.

Do not. Name unaudited third-party feeds as certified. Treat list URLs as supply chain.

DNS RBL

Symptom. RBL hits missing; auto-block not occurring.

Causes. security.rbl.enabled false (example). Zones not configured. DNS to RBL operators failing. auto_block off.

Diagnostics.

POST /api/v1/security/rbl-check
GET  /api/v1/security/rbl-stats

Remediation. Enable sources; understand auto_block / block_duration / whitelist. Enterprise writes may be license-gated.

Do not. Treat RBL as a compliance certification. DNS to public RBLs leaks query IPs to those operators.

Notifications (email / webhook / Slack)

Symptom. No mail or webhook delivery.

Causes. SMTP host/recipients missing (validation requires SMTP host and at least one recipient when email enabled). Wrong smtp_password. Webhook URL unset. Slack is incoming-webhook URL only.

Diagnostics.

GET /api/v1/notifications/health
GET /api/v1/notifications/:id/deliveries
GET /api/v1/settings/notifications

POST /settings/notifications/test sends real mail — prefer a lab notification object.

Remediation. Configure SMTP (notifications.email.*, example port 587) or webhook (timeout example 10s) without committing secrets. Confirm health and delivery attempts.

Do not. Treat this as SIEM/Splunk. Put SMTP passwords in tickets.

ModSecurity observation

Symptom. No alerts; Hosting ModSecurity collector blocked.

Causes. Webhook secret mismatch. Hosting per-site audit files absent (global metadata-only collector). permission_blocked on /var/log/modsec_audit.log (example). Not a hosted WAF.

Diagnostics.

POST /api/v1/modsecurity/webhook    # HMAC/signature; not JWT
GET  /api/v1/security/modsecurity/stats
GET  /api/v1/security/modsecurity/alerts

Hosting: collector id hosting.modsecurity.global.metadata.v1 (and related observe IDs). Secret: modsecurity_webhook_secret / ZCS_MODSECURITY_WEBHOOK_SECRET.

Remediation. Align HMAC secret; Hosting: exact-path ACL. Lab signed webhook → alert list.

Do not. Claim OWASP CRS as a Zwall-operated WAF. chmod 777 /var/log. Publish webhook URLs.

libvirt / KVM

Symptom. Empty VM list; no interface inventory.

Causes. Not KVM/libvirt. Wrong URI (typical qemu:///system). Hosting Agent used. Wrong vm_bridge_name (example viifbr0). Agent not root.

Diagnostics. Operator virsh -c qemu:///system list --all (not a Zwall command).

GET /api/v1/virtualization/vms
POST /api/v1/virtualization/vm-data    # Agent

Remediation. Install Virtualization Agent on the hypervisor host; correct URI/bridge. See libvirt.

Do not. Claim VMware/Hyper-V/Kubernetes. Enrich Hosting with VM inventory.

Prometheus

Symptom. Scrape 401/403 or empty.

Causes. metrics.enabled false. Scrape without admin JWT/session + RoleAuth("admin"). Wrong path (metrics.path, default /metrics).

Diagnostics. GET /metrics as an admin-capable client. 200 Prometheus text when enabled.

Remediation. Enable metrics; scrape with admin credentials. Import shipped Grafana JSON into your Grafana. Agent metrics default disabled, bind example 127.0.0.1:9090.

Do not. Expose unauthenticated /metrics on the internet. Enable cluster-ha.json as certified HA (cluster is not a public HA product).

Unblock portal (ENTERPRISE_ONLY)

Symptom. Public form missing or requests not listed.

Causes. Not in Community V1 router. security.messenger disabled. Captcha secrets missing (recaptcha_secret_key / hcaptcha_secret_key).

Diagnostics.

GET  /api/v1/public/messenger/config
POST /api/v1/public/unblock-request
GET  /api/v1/admin/unblock-requests
POST /api/v1/admin/unblock-requests/:id/review

Remediation. Enable messenger + captcha; review as admin. Implemented UX, not a certified support product.

Do not. Log capability tokens from GET .../unblock-request/:token.

What each result means

See tables above. 403 LicenseErrorResponse is the Enterprise license envelope (success, code, message, license). Community 404 on Cloudflare/unblock routes is edition, not a broken Manager.

Safe remediation

Fix edition, secret custody, enable flags, and Agent profile. Re-test the integration’s health/status endpoint. Do not widen CORS or disable TLS to make a webhook easier.

Do-not-do warnings

  • Do not document Cloudflare or the unblock portal as Community.
  • Do not put integration secrets in YAML git or argv.
  • Do not claim bidirectional Cloudflare or certified ACME DNS-01.
  • Do not treat /metrics as unauthenticated.
  • Do not invent Terraform/Ansible/OIDC/Kubernetes integrations.

Escalation condition

Escalate when health endpoints succeed, credentials are valid, license allows the feature, and the remote system still never receives a lab change — after capturing redacted health JSON (no tokens).

Edition

SHARED: GeoIP, blocklists, RBL, notifications, ModSecurity observe, libvirt, Prometheus. ENTERPRISE_ONLY: Cloudflare HTTP group, unblock portal. Community ignores letsencrypt YAML.

Status

SUPPORTED for implemented health/status diagnosis. Not certified always-on integrations.