Skip to main content

Configuration Validation

--test-config performs static configuration validation.

Local binary​

./target/release/ai-firewall --config configs/ai-firewall.conf --test-config

Or, if not built yet:

cargo run -- --config configs/ai-firewall.conf --test-config

Expected output:

configuration OK

Docker Compose​

docker compose run --rm firewall \
  --config /configs/ai-firewall.conf \
  --test-config

What it checks​

  • syntax
  • required directives
  • value formats and ranges
  • semantic cache settings
  • model validation configuration

What it does not check​

It does not connect to Redis, Qdrant, embedding providers, or upstream providers. Runtime startup and reload diagnostics perform dependency initialization separately.

./target/release/ai-firewall --config configs/ai-firewall.conf --print-config

Docker Compose:

docker compose run --rm firewall \
  --config /configs/ai-firewall.conf \
  --print-config

Examples of provider URL validation errors:

configuration error: invalid upstream_base_url 'http://ollama:11434/v1/chat/completions': configure a base URL, not a full endpoint path
configuration error: invalid embedding_base_url 'http://ollama:11434/v1/embeddings': configure a base URL, not a full endpoint path

For local providers without authentication, upstream_api_key and embedding_api_key should still be present but may use placeholder values such as dummy, none, null, or -.

Version validation​

After starting the service, use /version to confirm that the running binary is the expected v0.2.0 release:

curl -s http://localhost:8080/version

Guard configuration validation​

--test-config validates guard directive syntax and required fields when guards are enabled.

Examples of invalid guard configuration include:

  • security_guard_enabled true without security_guard_url;
  • security_guard_enabled true without security_guard_api_key;
  • privacy_guard_enabled true without privacy_guard_url;
  • privacy_guard_enabled true without privacy_guard_api_key;
  • invalid guard timeout values;
  • invalid guard_fail_open value.

Static configuration validation does not prove that the guard services are reachable. Runtime guard availability is enforced during request processing and depends on guard_fail_open.

Streaming validation​

stream=true is a valid OpenAI-style request field, but AI Firewall v0.4.2 rejects it at runtime with HTTP 422. This is a request validation outcome rather than a static configuration error.

The rejection occurs before cache, guard, or upstream processing and emits a terminal request.failed evidence event after request.received.

Audit delivery validation​

When Audit delivery is enabled, validate the endpoint and queue controls together:

audit_enabled true;
audit_url http://vcal-audit:8092;
audit_api_key replace-with-shared-audit-token;
audit_queue_capacity 10000;
audit_batch_size 100;
audit_flush_interval_ms 1000;
audit_request_timeout_seconds 5;
audit_retry_max_attempts 5;
audit_retry_initial_backoff_ms 250;

The batch size must not exceed the queue capacity. Numeric queue, batch, interval, timeout, retry, and backoff values must be positive. Static validation does not prove that the Audit hostname resolves, the API key is accepted, or /v1/events/batch is reachable. Confirm those conditions through startup logs and an end-to-end evidence test.