This is the multi-page printable view of this section. .

Return to the regular view of this page.

Quick Start Guide

Three steps to complete initial system setup, onboard your first reverse proxy site, and configure asynchronous LLM threat review.

1: System Setup & Initialization
2: Onboard Your First Site
3: Connect Large Language Models

Start with the one-line Linux installer. It asks for a language, downloads and verifies the latest stable release, creates a public HTTPS management entry, and prints a short-lived setup URL. Then follow these three steps:

BASH

curl -fsSL https://github.com/LaokeQwQ/CheeseWAF/releases/latest/download/install-linux.sh | sudo bash

The installer asks for an application root after the language prompt. Enter /opt/cheesewaf to keep the binary, Web assets, configuration, data, and logs together, or press Enter to use the standard FHS layout. It prints public and detected private setup addresses; use CHEESEWAF_RELEASE=vX.Y.Z[-beta] when you need a specific release. See the Linux installation guide for automation variables, upgrades, and security-entry handling.

1. System Initialization

Access the /setup wizard, create your initial administrator account, securely archive master keys, and verify management boundaries.

2. Onboard Your First Site

Configure public domain names, backend upstream server addresses, and set the baseline paranoia level to Level 3 (Smart Protection).

3. Connect LLM Threat Review

Connect OpenAI- or Anthropic-compatible APIs to enable asynchronous ALAP threat reasoning and closed-loop rule synthesis.

Keep the complete HTTPS setup URL private. Its URL fragment contains a one-time token that the browser converts to the X-CheeseWAF-Setup-Token header; it is revoked after setup. If the server cannot reach GitHub, use the signed archive and checksum files from the release page and follow the offline installation section.

CheeseWAF’s Data Plane provides deterministic AST semantic protection immediately after startup, even without an LLM connected. Before configuring the ai block, the ALAP review queue simply remains idle.

1 - 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.

2 - Onboard Your First Site

Configure public domain names, backend upstream origin servers, and baseline paranoia protection in CheeseWAF.

1. Configure Public Domains

Enter the public hostnames used by your clients (e.g., app.example.com). CheeseWAF matches incoming HTTP Host headers against the configured sites[].domains list.

2. Configure Backend Upstream Origins

Specify the origin server address and port (e.g., 10.0.0.10:8000). When multiple upstreams are defined, the system distributes traffic according to the configured load balancing policy (round_robin by default).

3. Set Baseline Paranoia Level

New sites default to paranoia level 3 (Smart Standard Mode); if the current wizard exposes this option, leave it at 3. In this mode, the system blocks high-confidence standalone payloads while allowing embedded features through to asynchronous ALAP review, ensuring business continuity while collecting threat data.

4. Save & Hot-Reload

Click Save Site. CheeseWAF dynamically reloads site definitions in memory without terminating the main daemon or interrupting active connections.

After saving, update your DNS records or local hosts file to point the domain to the CheeseWAF Data Plane listener (http://127.0.0.1:8080 by default) to verify end-to-end reverse proxy forwarding.

For health checks, automatic SSL issuance, and path rewrite configurations, see Sites & Reverse Proxy.

3 - Connect Large Language Models

Configure OpenAI- or Anthropic-compatible API endpoints for ALAP asynchronous threat reasoning and self-learning rules.

CheeseWAF’s ALAP (AI Large-Language-Model Auto Pilot) engine integrates with industry-standard LLM APIs to perform out-of-band semantic reasoning on suspicious and borderline traffic.

In the Web management console, navigate to the AI section and configure the following parameters:

Setting	Configuration Key	Description & Examples
Enable AI	`ai.enabled`	Master toggle for ALAP functionality (boolean)
Provider	`ai.provider`	API protocol dialect: `openai` or `anthropic`
Base URL	`ai.api_base`	API Base URL (e.g., `https://api.openai.com/v1`)
Allow Private Endpoint	`ai.allow_private_api_base`	Allows connecting to private/local LLM gateways (Ollama, LocalAI; defaults to `false`)
API Key	`ai.api_key`	Secret access token / API key provided by your LLM vendor
Model Name	`ai.model`	Model identifier (e.g., `gpt-4o-mini`, `claude-3-5-sonnet-latest`)
Auto-Agreement	`sites[].waf.semantic_policy.auto_agree`	When enabled, threats evaluated as `high` or `critical` are automatically persisted as defensive rules

Legacy configuration migration: The old ai.base_url and ai.auto_agree keys are not read by the current release. Move ai.base_url to ai.api_base, and move the approval setting to each site’s sites[].waf.semantic_policy.auto_agree; save the configuration and reload/restart the service as required.

Best Practices & Security Guidelines

Enforce Asynchronous Execution: Always maintain ai.async: true in your configuration to guarantee that the Data Plane never blocks real-time traffic while waiting for model inference.
Connection Testing: Before enabling rules, click Test Connection in the console to validate network routing, DNS resolution, and credential authentication.
Gradual Rollout of Auto-Agreement: Keep sites[].waf.semantic_policy.auto_agree disabled during initial deployment. Review samples manually in the threat queue for 1–2 weeks to verify evaluation fidelity before enabling automated rule generation.

For details on assistant tool approvals, review queues, and automated self-learning, see ALAP & Review Queue.