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​

Validation includes the aif_enforcement_mode value (enforce or observe) and rejects unsupported mode values before startup.

  • 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.8.2 release and to verify the active AIF enforcement mode:

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;
  • usage_guard_enabled true without usage_guard_url;
  • usage_guard_enabled true without usage_guard_api_key;
  • invalid Security/Usage Guard block-response mode;
  • 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 supported when controlled streaming is enabled:

streaming_enabled true;
max_stream_upstream_bytes 8M;

Static configuration validation checks the streaming directives, but it cannot prove that the selected upstream actually supports OpenAI-compatible SSE. Validate provider streaming with a runtime stream=true request.

For controlled streams, upstream_timeout_seconds also limits the maximum idle gap between provider SSE chunks, while a separate 15-minute absolute generation ceiling prevents indefinite drip-feed streams.

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_timeout_seconds 5;
audit_retry_max_attempts 5;
audit_retry_initial_backoff_ms 250;
audit_retry_max_backoff_ms 5000;

The batch size must not exceed the queue capacity. Numeric queue, batch, interval, timeout, retry-count, initial-backoff, and maximum-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.