System Setup & Initialization

Initialize CheeseWAF via the browser Web wizard or the cheesewaf setup terminal command with hardware probing, profiling, and credential configuration.

Following a fresh installation, CheeseWAF requires initial administrator provisioning and hardware baseline profiling. CheeseWAF provides both a Terminal CLI Wizard and a Web GUI Wizard.

Option 1: Terminal Setup Wizard (Recommended)

Run the interactive setup command directly in your terminal:

BASH

cheesewaf setup

1. Automated Hardware Probing & Profiling

The wizard inspects host resources (logical CPU cores, visible RAM, and an 8 MiB sequential write test) and recommends a runtime profile:

low (Lightweight): Best for 1–2 CPU cores / 1–2 GB RAM; requests exceeding inspection budgets automatically fall back here.
smart (Smart, default): Recommended for standard servers (2–4 CPU cores / 4–8 GB RAM); dynamically tunes inspection depth based on request risk.
medium (Balanced): Fixed inspection depth 2 with a 50 ms timeout per request.
high (Performance): Best for 4+ CPU cores / 8+ GB RAM on core gateways; performs full deep semantic analysis.
custom (Custom): Allows manual tuning of inspection depth and timeout budgets.

The probe runs for at most 30 seconds. If it times out, is cancelled, or the Web probe request fails, the wizard recommends the conservative low tier. In non-interactive mode, --skip-probe also selects low unless an explicit --profile is provided.

2. Guided Credentials & Transactional Safety

Username: Enter a username of 3–32 ASCII characters. It must start with an ASCII letter, end with an ASCII letter or digit, and contain only ASCII letters, digits, ., _, and -. Non-ASCII characters, Unicode whitespace, control characters (Cc), and format/invisible characters (Cf) are rejected; the server preserves the exact value and does not trim or lowercase it.
Password: New passwords need at least 10 characters and at least 3 of 4 classes: uppercase, lowercase, non-repeating digits, and special characters. Common or simple patterns are rejected, and the password cannot equal or contain the username. The Web review step shows that a password is set; it never displays the password, a password hash, a system master key, or an administrator credential digest.
Optional integrations: The interactive terminal wizard can apply selected GeoIP, Prometheus /metrics, and VictoriaLogs settings when it commits the configuration. The Web wizard records integration choices in the setup draft for review; it does not apply them to the live configuration. Configure supported integrations after setup from the relevant System Settings, Storage, or Monitoring pages. The PostgreSQL option is an asynchronous access-log sink, not the management database.
Transactional Cleanliness: Configuration, database, certificate, and administrator state are accumulated in memory and are committed only at the final step. Aborting does not leave partial setup state. The selected CLI language is a separate user preference and may be persisted in data/cli.lang; this file is not the runtime configuration or management database.

3. Headless Scripted Automation

For CI/CD pipelines or cloud-init automation, use non-interactive command-line flags:

BASH

cheesewaf setup --yes \
  --username admin \
  --password-stdin < /etc/cheesewaf/secrets/admin_pass.txt \
  --admin-listen 0.0.0.0:9443 \
  --skip-probe

Note: In automated mode, --yes strictly requires --password-stdin to guarantee that the administrator password satisfies the credential policy. Upon completion, the wizard prints the canonical http:// or https:// panel URL according to the current administrative TLS state.

Option 2: Browser Web Wizard

1. Open the Setup URL

During initialization, open the https://PUBLIC_IP:9443/setup#setup_token=ONE_TIME_TOKEN URL printed by the installer. The setup route is always /setup; the token is one-time and short-lived.

The management plane is HTTPS and publicly reachable by default for the one-line installation path. Restrict port 9443 with cloud security groups, host firewalls, and an administrator IP allowlist before production use. Replace a locally generated certificate with a trusted certificate when the service is put on a public hostname.

The URL fragment carries a short-lived one-time token. The browser reads it, clears the address bar, and sends it only in X-CheeseWAF-Setup-Token; it is never placed in a query parameter, cookie, or localStorage. The token is revoked after setup and the protected setup.url file is removed or invalidated.

After setup, open https://PUBLIC_IP:9443/SECURITY_ENTRY. The entry contains ASCII letters and digits only, is generated by default or accepted after validation, signs an access Cookie, and redirects to the login page. Keep the setup route and the post-setup security entry as separate paths.

The setup token remains required in X-CheeseWAF-Setup-Token until setup completes, when it is revoked. If CHEESEWAF_SETUP_TOKEN was set before startup, keep that value out of logs and shell history. The browser reads setup_token from the URL fragment, clears it from the address bar, and sends it only in that header.

If you open bare /setup, paste the token from the protected file. It remains in page memory and is cleared after submission. Never put the token in a query parameter or include it in tickets, screenshots, or logs.

2. Create Root Administrator Account

Follow the on-screen steps:

Enter a username that follows the canonical username rule above.
Enter a password of at least 10 characters that satisfies at least 3 of the 4 password classes and does not contain the username.
Review the summary. It shows the username, that the password is set, the environment check, and selected integrations; it does not display the password, a password hash, a system master key, or an administrator credential digest.

3. Configure Admin Network Boundaries

Keep server.admin_tls enabled and restrict ingress using cloud security groups, host firewall rules, and IP allowlists.
If you intentionally need loopback-only administration, override server.admin_listen to 127.0.0.1:9443 and use an SSH tunnel; this is an explicit hardening choice, not the default one-line path.

Upon completing initialization, navigating to the admin endpoint redirects to the Web Console login view. Local credentials can subsequently be managed using waf-cli or cheesewaf user.

The generated configuration may contain an update.ota.server value, but OTA is disabled by default and the current binary has no updater worker. It cannot download or install rules or binaries through OTA; keep update.ota.enabled: false.