Configuration Reference
All runtime settings are environment variables prefixed with BANGUI_. Values are validated at startup — missing required fields or invalid values cause the application to refuse to start.
For setup instructions, see Instructions.md. For deployment, see Deployment.md.
Database
| Variable |
Type |
Default |
Description |
BANGUI_DATABASE_PATH |
string |
bangui.db |
Filesystem path to the SQLite application database. Parent directory must exist and be writable at startup. |
Session & Security
| Variable |
Type |
Default |
Description |
BANGUI_SESSION_SECRET |
string |
(required) |
Secret key for signing session tokens. Must be ≥ 32 characters. Generate with python -c "import secrets; print(secrets.token_hex(32))". Never reuse across environments. |
BANGUI_SESSION_SECRET_PREVIOUS |
string |
null |
Previous session secret used during rotation. Set to the old secret while rotating; unset once all old tokens expire. |
BANGUI_SESSION_DURATION_MINUTES |
int |
60 |
Session lifetime in minutes. Must be ≥ 1. |
BANGUI_SESSION_CACHE_ENABLED |
bool |
false |
Enable in-memory session validation cache. Disable in multi-worker deployments to avoid stale revoked sessions. |
BANGUI_SESSION_CACHE_TTL_SECONDS |
float |
10.0 |
TTL for cached session entries. Ignored when BANGUI_SESSION_CACHE_ENABLED is false. Must be ≥ 0. |
BANGUI_SESSION_COOKIE_HTTPONLY |
bool |
true |
Mark the session cookie as HttpOnly (JavaScript cannot access it). |
BANGUI_SESSION_COOKIE_SAMESITE |
string |
lax |
SameSite policy for the session cookie. Valid values: lax, strict, none. |
BANGUI_SESSION_COOKIE_SECURE |
bool |
true |
Set the Secure flag on the session cookie. true required for HTTPS. Set to false only for local HTTP development. |
fail2ban Integration
| Variable |
Type |
Default |
Description |
BANGUI_FAIL2BAN_SOCKET |
string |
/var/run/fail2ban/fail2ban.sock |
Path to the fail2ban Unix domain socket. Socket must exist and be readable at startup (warning issued if not). |
BANGUI_FAIL2BAN_CONFIG_DIR |
string |
/config/fail2ban |
Path to the fail2ban configuration directory. Must contain jail.d/, filter.d/, and action.d/. |
BANGUI_FAIL2BAN_START_COMMAND |
string |
fail2ban-client start |
Shell command to start the fail2ban daemon (no shell interpretation). Used during recovery rollback. Must be parseable by shlex.split. |
BANGUI_ALLOWED_LOG_DIRS |
list |
/var/log,/config/log |
Allowed directory prefixes for jail log paths. Any log path must resolve within one of these directories. |
BANGUI_TRUSTED_PROXIES |
list |
[] |
Trusted reverse proxy IP addresses or CIDR ranges (e.g., 192.168.1.1,10.0.0.0/8). Only these sources can set X-Forwarded-For and X-Real-IP. |
HTTP Client
These settings control outbound HTTP requests made by the backend (geolocation fallback, blocklist downloads).
| Variable |
Type |
Default |
Description |
BANGUI_HTTP_REQUEST_TIMEOUT_SECONDS |
float |
20.0 |
Maximum total time for an outbound HTTP request. Must be ≥ 0. |
BANGUI_HTTP_CONNECT_TIMEOUT_SECONDS |
float |
5.0 |
Maximum time to establish a TCP connection. Must be ≥ 0. |
BANGUI_HTTP_MAX_CONNECTIONS |
int |
10 |
Maximum concurrent outbound HTTP connections. Must be ≥ 1. |
BANGUI_HTTP_KEEPALIVE_TIMEOUT_SECONDS |
float |
15.0 |
How long idle keepalive connections are retained. Must be ≥ 0. |
Geolocation
| Variable |
Type |
Default |
Description |
BANGUI_GEOIP_DB_PATH |
string |
null |
Path to a MaxMind GeoLite2-Country .mmdb file. Primary resolver for IP geolocation when set. Download from https://dev.maxmind.com/geoip/geolite2-country. |
BANGUI_GEOIP_ALLOW_HTTP_FALLBACK |
bool |
false |
Allow HTTP fallback to ip-api.com when the MMDB is unavailable. Warning: sends IP addresses unencrypted. Only enable when MMDB cannot be mounted. |
Cross-Origin (CORS)
| Variable |
Type |
Default |
Description |
BANGUI_CORS_ALLOWED_ORIGINS |
list |
http://localhost:5173,http://127.0.0.1:5173,https://localhost:5173,https://127.0.0.1:5173 |
Allowed CORS origins. Comma-separated string or YAML list. Empty list disables CORS. Never use "*" in production when credentials are enabled. |
Display
| Variable |
Type |
Default |
Description |
BANGUI_TIMEZONE |
string |
UTC |
IANA timezone name used when displaying timestamps in the UI (e.g., America/New_York, Europe/London). |
External Logging
Enable with BANGUI_EXTERNAL_LOGGING_ENABLED=true, then set the provider and provider-specific variables.
| Variable |
Type |
Default |
Description |
BANGUI_EXTERNAL_LOGGING_ENABLED |
bool |
false |
Send logs to a centralized logging platform instead of stdout only. |
BANGUI_EXTERNAL_LOGGING_PROVIDER |
string |
null |
Logging provider: datadog, papertrail, or elasticsearch. Required when external logging is enabled. |
BANGUI_EXTERNAL_LOGGING_BUFFER_SIZE |
int |
1000 |
Max log records buffered in memory before dropping oldest. Must be ≥ 10. |
BANGUI_EXTERNAL_LOGGING_FLUSH_INTERVAL_SECONDS |
float |
5.0 |
Max seconds before flushing a log batch. Must be > 0. |
Datadog
| Variable |
Type |
Default |
Description |
BANGUI_DATADOG_API_KEY |
string |
null |
Datadog API key. Required when provider is datadog. |
BANGUI_DATADOG_SITE |
string |
datadoghq.com |
Datadog site: datadoghq.com (US) or datadoghq.eu (EU). |
BANGUI_DATADOG_BATCH_SIZE |
int |
10 |
Number of log records per batch. Must be ≥ 1. |
Papertrail
| Variable |
Type |
Default |
Description |
BANGUI_PAPERTRAIL_HOST |
string |
null |
Papertrail host address (e.g., logs1.papertrailapp.com). Required when provider is papertrail. |
BANGUI_PAPERTRAIL_PORT |
int |
null |
Papertrail port. Required when provider is papertrail. Range: 1–65535. |
BANGUI_PAPERTRAIL_PROGRAM_NAME |
string |
bangui |
Program name in Syslog messages sent to Papertrail. |
Elasticsearch
| Variable |
Type |
Default |
Description |
BANGUI_ELASTICSEARCH_HOSTS |
list |
[] |
Elasticsearch host URLs (e.g., http://elasticsearch:9200). Required when provider is elasticsearch. |
BANGUI_ELASTICSEARCH_INDEX_PREFIX |
string |
bangui |
Prefix for Elasticsearch indices. |
BANGUI_ELASTICSEARCH_BATCH_SIZE |
int |
10 |
Number of log documents per batch. Must be ≥ 1. |
Rate Limiting
Per-IP rate limits applied to API endpoints.
| Variable |
Type |
Default |
Description |
BANGUI_RATE_LIMIT_BANS_PER_MINUTE |
int |
100 |
Max ban/unban requests per IP per minute. |
BANGUI_RATE_LIMIT_BLOCKLIST_IMPORT_PER_HOUR |
int |
100 |
Max blocklist import requests per IP per hour. |
BANGUI_RATE_LIMIT_CONFIG_UPDATE_PER_MINUTE |
int |
50 |
Max config update requests per IP per minute. |
Rate limit reset mechanism: Each limit is applied per-client IP. To bypass the blocklist import rate limit in automated tests (E2E-4), send a unique X-Forwarded-For header with each import request — e.g., X-Forwarded-For: 10.0.0.99. The header is only honoured when the client IP falls within BANGUI_TRUSTED_PROXIES; otherwise the real client IP is used.
Configurable limits that affect API response sizes and data retention.
| Variable |
Type |
Default |
Description |
BANGUI_MAX_PAGE_SIZE |
int |
500 |
Maximum records returned per paginated API response. Individual endpoints may further limit this. Must be 1–10000. |
BANGUI_PREVIEW_MAX_LINES |
int |
100 |
Maximum IP lines returned in a blocklist source preview. Must be ≥ 1. |
BANGUI_HISTORY_RETENTION_DAYS |
int |
90 |
Number of days historical ban records are retained before archival cleanup. Must be ≥ 1. |
Observability
| Variable |
Type |
Default |
Description |
BANGUI_LOG_LEVEL |
string |
info |
Application log level. Valid values: debug, info, warning, error, critical. |
BANGUI_ENABLE_DOCS |
bool |
false |
Enable FastAPI interactive docs at /api/docs (Swagger UI) and /api/redoc (ReDoc). Enable only in development. |
Quick Reference
manual-Jail Fail2ban Jail (E2E Test Dependency)
The E2E test E2E-3 (e2e/tests/02_ban_records.robot) writes authentication-failure lines via Docker/simulate_failed_logins.sh and asserts that the resulting ban appears in the BanGUI UI. The test depends on the following manual-Jail configuration in Docker/fail2ban-dev-config/fail2ban/jail.d/manual-Jail.conf:
| Parameter |
Value |
Relevance to E2E-3 |
maxretry |
3 |
Ban triggers after 3 matching lines. simulate_failed_logins.sh writes 5 lines by default — enough to trigger the ban reliably. |
findtime |
120 |
Time window in seconds during which maxretry failures accumulate. |
bantime |
60 |
Ban duration in seconds. Teardown unbans via check_ban_status.sh --unban regardless of bantime. |
logpath |
/remotelogs/bangui/auth.log |
fail2ban reads this path inside the container. simulate_failed_logins.sh writes to Docker/logs/auth.log, which must be volume-mapped to /remotelogs/bangui/auth.log. |
backend |
polling |
fail2ban re-reads the log file on its own interval (not event-driven). A 15 s sleep in the E2E test gives fail2ban time to detect the ban. |
ignoreip |
127.0.0.0/8 ::1 172.16.0.0/12 |
Test IP 192.168.100.99 is not ignored. Ensure local overrides do not add this IP to ignoreip. |
Log path mapping (Docker/Podman compose): The host file Docker/logs/auth.log must be mounted to /remotelogs/bangui/auth.log inside the bangui-fail2ban-dev container. If the volume mapping is changed, simulate_failed_logins.sh will write to a path fail2ban does not watch, and the test will fail at Step 2 with no ban recorded.
Test IP: 192.168.100.99 (non-routable link-local test subnet, RFC 3927). Safe to use because it is outside all ignoreip ranges and unlikely to appear in real traffic.
Scheduling note: The backend does not receive push notifications from fail2ban. GET /api/bans/active queries the fail2ban Unix socket directly (on-demand). The history archive is populated by history_sync, a periodic job running every 300 s (HISTORY_SYNC_INTERVAL in backend/app/tasks/history_sync.py). The E2E test uses GET /api/bans/active for the API assertion (avoids the archive lag) and the History page with ?page_size=500 for the UI assertion.
Cross-References
