Configuration

BoilStream uses a YAML configuration file for all settings. On first run, it generates a config.yaml with defaults.

Configuration File

# Uses config.yaml from current directory
./boilstream

# Use a specific configuration file
./boilstream --config /etc/boilstream/config.yaml

# Or use environment variable
CONFIG_FILE=/etc/boilstream/config.yaml ./boilstream

Settings priority (later overrides earlier):

1. Built-in defaults
2. Configuration file (YAML)
3. Environment variables

Complete Configuration Reference

# =============================================================================
# AWS Configuration
# =============================================================================
aws:
  region: "eu-west-1"
  access_key_id: null # Optional - uses AWS SDK credential chain
  secret_access_key: null # Optional - uses AWS SDK credential chain
  https_conn_pool_size: 100

# =============================================================================
# Storage Configuration
# =============================================================================
storage:
  backends:
    # S3 Backend (Primary)
    - name: "primary-s3"
      backend_type: "s3"
      enabled: true
      primary: true
      endpoint: "https://s3.eu-west-1.amazonaws.com"
      bucket: "my-bucket"
      prefix: ""
      region: "eu-west-1"
      access_key: null # Optional - uses AWS SDK credential chain
      secret_key: null
      use_path_style: false # true for MinIO
      max_concurrent_uploads: 10
      max_retries: 3
      initial_backoff_ms: 100
      max_retry_attempts: 3

    # Azure Blob Storage Backend
    # - name: "azure-backup"
    #   backend_type: "azure"
    #   enabled: false
    #   primary: false
    #   azure_account: "mystorageaccount"
    #   azure_container: "mycontainer"
    #   azure_access_key: null           # Optional - uses Azure SDK credential chain
    #   prefix: ""

    # Google Cloud Storage Backend
    # - name: "gcs-backup"
    #   backend_type: "gcp"
    #   enabled: false
    #   primary: false
    #   bucket: "my-gcs-bucket"
    #   prefix: ""
    #   gcp_service_account_key: null    # Path to service account JSON
    #   gcp_project_id: null

    # Filesystem Backend
    # - name: "local-backup"
    #   backend_type: "filesystem"
    #   enabled: false
    #   primary: false
    #   prefix: "/data/backup"

# =============================================================================
# Server Configuration
# =============================================================================
server:
  tokio_worker_threads: null # null = system CPU count
  flight_thread_count: 1
  flight_base_port: 50050
  admin_flight_port: 50160
  consumer_flight_port: 50250
  router:
    spsc_queue_capacity: 2 # Queue capacity per processing thread
    batch_size: 500 # Messages per batch
    retry_delay_ms: 1 # Retry delay when threads busy

# =============================================================================
# Processing Configuration
# =============================================================================
processing:
  data_processing_threads: 8
  buffer_pool_max_size: 50
  window_queue_capacity: 30000
  max_flush_latency_ms: 10000 # Max time before flush (ms)
  max_part_size_mb: 32 # Size threshold for early flush
  max_file_size_mb: 1024 # Max file size before completion
  snapshot_interval_minutes: 10 # Wall-clock aligned file completion (1-60)
  enable_5mb_part_padding: false # Pad to 5MB for S3 multipart
  include_metadata_columns: true
  schema_validation_enabled: true
  parquet:
    compression: "ZSTD"
    dictionary_enabled: true

# =============================================================================
# DuckDB Persistence Configuration
# =============================================================================
duckdb_persistence:
  enabled: true
  storage_path: "./data/duckdb/topics"
  max_writers: 10
  total_databases: 10 # Database instances for DataChunk API
  commit_interval_ms: 1000 # Transaction commit interval

# =============================================================================
# Embedded PostgreSQL Configuration
# =============================================================================
embedded_postgres:
  enabled: true
  port: 5433
  databases:
    - ducklake_catalog
    - ducklake_analytics
    - ducklake_default

# =============================================================================
# Rate Limiting Configuration
# =============================================================================
rate_limiting:
  disabled: false
  max_requests: 15000000 # Per producer
  burst_limit: 20000000
  global_limit: 150000000
  base_size_bytes: 4096

# =============================================================================
# TLS Configuration (FlightRPC)
# =============================================================================
tls:
  disabled: false
  cert_path: "/etc/ssl/certs/server.crt"
  key_path: "/etc/ssl/private/server.key"
  cert_pem: null # Alternative to cert_path
  key_pem: null # Alternative to key_path
  grpc_default_ssl_roots_file_path: null

# =============================================================================
# Authentication Configuration (FlightRPC JWT)
# =============================================================================
auth:
  providers: ["cognito"] # cognito, azure, gcp, auth0, okta
  authorization_enabled: true
  admin_groups: ["admin"]
  read_only_groups: ["viewers"]
  max_sessions_per_hour: 1000
  max_concurrent_sessions: 20
  max_session_ttl_hours: 8
  cognito:
    user_pool_id: "us-east-1_example"
    region: "us-east-1"
    audience: "client-id"
  azure:
    tenant_id: null
    client_id: null
    allow_multi_tenant: false
  gcp:
    client_id: null
    project_id: null
    require_workspace_domain: false
  auth0:
    tenant: null
    audience: null
    groups_namespace: null
  okta:
    org_domain: null
    audience: null
    auth_server_id: null

# =============================================================================
# Metrics Configuration
# =============================================================================
metrics:
  port: 8081
  flush_interval_ms: 1000

# =============================================================================
# Logging Configuration
# =============================================================================
logging:
  rust_log: "info"

# =============================================================================
# PGWire Configuration (PostgreSQL Protocol)
# =============================================================================
pgwire:
  enabled: true
  port: 5432
  refresh_interval_seconds: 5
  initialization_sql: |
    SET threads = 8;
    SET memory_limit = '24GB';
    SET max_temp_directory_size = '16GB';
    SET allowed_directories = ['/tmp'];
    SET allow_unredacted_secrets = false;
    INSTALL json;
    LOAD json;
    INSTALL httpfs;
    LOAD httpfs;
    INSTALL ducklake; 
    LOAD ducklake;
    INSTALL boilstream FROM community;
    LOAD boilstream;
    SET allow_unsigned_extensions = false;
    SET lock_configuration = true;
  metadata_db_path: "./metadata.duckdb"
  query_timeout_seconds: 300 # 5 minutes
  max_connections: 100
  idle_timeout_seconds: 900 # 15 minutes
  connection_timeout_seconds: 1800 # 30 minutes
  tenant_data_base_path: "/tmp/boilstream/tenants"
  metadata_backup_backend: null # Storage backend name
  metadata_backup_interval_seconds: 60
  metadata_backup_path: "pgwire/metadata-backup.tar.gz"
  tls:
    enabled: true
    cert_path: "/etc/ssl/certs/pgwire.crt"
    key_path: "/etc/ssl/private/pgwire.key"
    cert_pem: null
    key_pem: null

# =============================================================================
# Kafka Configuration
# =============================================================================
kafka:
  enabled: true
  port: 9092
  bind_address: "0.0.0.0"
  tls:
    enabled: true
    cert_path: "/etc/ssl/certs/kafka.crt"
    key_path: "/etc/ssl/private/kafka.key"
    cert_pem: null
    key_pem: null
  rate_limiting:
    disabled: false
    max_requests_per_second: 10000
    burst_limit: 15000
    global_limit: 100000

# =============================================================================
# HTTP/2 Ingestion Configuration
# =============================================================================
http_ingestion:
  enabled: true
  port: 8443
  bind_address: "0.0.0.0"
  token_secret_key: ""                   # BLAKE3 MAC key for browser tokens (32 bytes, base64)
  max_request_size: 131072 # 128KB
  tls:
    cert_path: "/etc/ssl/certs/http.crt"
    key_path: "/etc/ssl/private/http.key"
    cert_pem: ""
    key_pem: ""
  cors:
    allowed_origins: []
    max_age_seconds: 3600
    allow_credentials: false
  rate_limiting:
    enabled: true
    global_requests_per_second: 10000
    tenant_requests_per_second: 1000
    tenant_burst_size: 5000
    tenant_overrides: {}
  http2:
    max_connections: 100000
    accept_threads: 0 # 0 = CPU cores
    initial_stream_window_size: 262144
    initial_connection_window_size: 1048576
    max_frame_size: 131072
    max_concurrent_streams: 50
    keep_alive_interval_secs: 20
    keep_alive_timeout_secs: 10
  memory_pool:
    buffer_size: 131072 # 128KB
    buffer_count: 2000

# =============================================================================
# Auth Server Configuration (Web Auth GUI)
# =============================================================================
auth_server:
  enabled: true
  port: 443
  tls_cert: "/etc/ssl/certs/auth.crt"
  tls_key: "/etc/ssl/private/auth.key"
  tls_auto_reload: true
  tls_reload_check_interval_seconds: 21600 # 6 hours
  session_ttl_hours: 8
  users_db_path: "data/users.duckdb"
  encryption_key_path: "/etc/boilstream/encryption.key"
  superadmin_password_path: null # For automated deployments
  superadmin_mfa_secret_path: null # Base32 TOTP secret
  app_domain: "app.example.com"
  webauthn_rp_id: "app.example.com"
  webauthn_rp_origin: "https://app.example.com"
  cors_allowed_origins: []
  grants_db_path: "data/grants.duckdb"
  default_user_role: "reader"
  admin_username: null
  users_backup_backend: "primary-s3"
  users_backup_interval_seconds: 60
  users_backup_path: "auth/users.duckdb"
  superadmin_backup_backend: null # Defaults to users_backup_backend
  superadmin_backup_interval_seconds: 60
  superadmin_backup_path: "auth/superadmin.duckdb"
  email_encryption_pgp_public_key_path: null
  email_encryption_pgp_public_key: null
  enable_ducklake: true
  auto_create_default_ducklake: true
  enable_hydration: true

# =============================================================================
# OAuth Providers Configuration
# =============================================================================
oauth_providers:
  github:
    client_id: "github-client-id"
    client_secret: "github-client-secret"
    redirect_uri: "https://app.example.com/auth/callback"
    allowed_orgs: ["mycompany"]
    team_role_mappings:
      "mycompany/admins": "admin"
      "mycompany/engineers": "write"
      "mycompany/analysts": "read"
    audit_org_teams: false

  google:
    client_id: "google-client-id.apps.googleusercontent.com"
    client_secret: "google-client-secret"
    redirect_uri: "https://app.example.com/auth/callback"
    allowed_domains: ["mycompany.com"]

  oauth2:
    - name: "custom-provider"
      client_id: "client-id"
      client_secret: "client-secret"
      auth_url: "https://provider.com/oauth/authorize"
      token_url: "https://provider.com/oauth/token"
      userinfo_url: "https://provider.com/oauth/userinfo"
      redirect_uri: "https://app.example.com/auth/callback"
      scopes: ["openid", "profile", "email"]

  saml:
    - name: "entra-id"
      enabled: true
      sp_entity_id: "https://app.example.com"
      sp_acs_url: "https://app.example.com/auth/saml/acs"
      sp_slo_url: "https://app.example.com/auth/saml/logout"
      idp_entity_id: "https://sts.windows.net/{tenant-id}/"
      idp_sso_url: "https://login.microsoftonline.com/{tenant-id}/saml2"
      idp_slo_url: null
      idp_certificate: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      sp_certificate: "/etc/ssl/saml/sp.crt"
      sp_private_key: "/etc/ssl/saml/sp.key"
      attribute_mappings:
        email: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
        username: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
        groups: "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
        first_name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
        last_name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
        display_name: "http://schemas.microsoft.com/identity/claims/displayname"

# =============================================================================
# Audit Configuration
# =============================================================================
audit:
  enabled: true
  backend: ndjson # ndjson, duckdb, s3, disabled
  log_path: "/var/log/boilstream/audit.ndjson"
  buffer_size: 1000
  sample_rate: null # 0.0-1.0, null = no sampling
  include_query_text: true
  include_ip_address: true

# =============================================================================
# Cluster Mode Configuration
# =============================================================================
cluster_mode:
  enabled: false
  node_id_path: "./node_id"
  advertised_host: "node1.example.com"
  internal_api_port: 8443
  leader_heartbeat_interval_secs: 30
  leader_stale_threshold_secs: 120
  broker_heartbeat_interval_secs: 30
  broker_stale_threshold_secs: 120
  tls:
    enabled: true
    cert_path: "/etc/ssl/cluster/node.crt"
    key_path: "/etc/ssl/cluster/node.key"
    ca_cert_path: "/etc/ssl/cluster/ca.crt"
    require_client_cert: true

Configuration Sections

AWS Configuration

Global AWS settings. Per-backend credentials in storage.backends take precedence.

Field	Type	Default	Description
aws.region	string	"us-east-1"	AWS region
aws.access_key_id	string	null	AWS access key (optional)
aws.secret_access_key	string	null	AWS secret key (optional)
aws.https_conn_pool_size	number	100	HTTP connection pool size

Storage Configuration

Multiple storage backends can be configured simultaneously for redundancy.

Field	Type	Default	Description
backends[].name	string	required	Unique backend identifier
backends[].backend_type	string	required	s3, azure, gcp, filesystem, noop
backends[].enabled	boolean	required	Whether backend is active
backends[].primary	boolean	required	If true, operations must succeed here

S3 Backend

Field	Type	Default	Description
endpoint	string	AWS regional	S3 endpoint URL
bucket	string	required	S3 bucket name
prefix	string	""	Base prefix for object keys
region	string	required	AWS region
access_key	string	null	S3 access key (uses SDK chain if null)
secret_key	string	null	S3 secret key
use_path_style	boolean	auto	Path-style addressing (auto-detects MinIO)
max_concurrent_uploads	number	10	Max concurrent uploads
max_retries	number	3	Max retry attempts
initial_backoff_ms	number	100	Initial backoff (ms)
max_retry_attempts	number	3	Max retry attempts

Azure Blob Storage Backend

Field	Type	Default	Description
azure_account	string	required	Storage account name
azure_container	string	required	Container name
azure_access_key	string	null	Access key (uses SDK chain if null)
prefix	string	""	Base prefix for blob keys

Google Cloud Storage Backend

Field	Type	Default	Description
bucket	string	required	GCS bucket name
prefix	string	""	Base prefix for object keys
gcp_service_account_key	string	null	Path to service account JSON
gcp_project_id	string	null	GCP project ID

Filesystem Backend

Field	Type	Default	Description
prefix	string	required	Base directory path

Server Configuration

Field	Type	Default	Description
tokio_worker_threads	number	null	Tokio threads (null = CPU count)
flight_thread_count	number	1	FlightRPC threads
flight_base_port	number	50050	FlightRPC base port
admin_flight_port	number	50160	Admin Flight port
consumer_flight_port	number	50250	FlightSQL port

Router Configuration

Field	Type	Default	Description
router.spsc_queue_capacity	number	2	Queue capacity per thread
router.batch_size	number	500	Messages per batch
router.retry_delay_ms	number	1	Retry delay (ms)

Processing Configuration

Field	Type	Default	Description
data_processing_threads	number	8	Processing threads
buffer_pool_max_size	number	50	Buffer pool size
window_queue_capacity	number	30000	Window queue capacity
max_flush_latency_ms	number	10000	Max time before flush
max_part_size_mb	number	32	Size threshold for flush
max_file_size_mb	number	1024	Max file size
snapshot_interval_minutes	number	10	File completion interval (1-60)
enable_5mb_part_padding	boolean	false	Pad to 5MB for S3
include_metadata_columns	boolean	true	Include metadata columns
schema_validation_enabled	boolean	true	Enable schema validation

Parquet Configuration

Field	Type	Default	Description
parquet.compression	string	"ZSTD"	Compression algorithm
parquet.dictionary_enabled	boolean	true	Dictionary encoding

DuckDB Persistence Configuration

High-performance local DuckDB for hot tier storage.

Field	Type	Default	Description
enabled	boolean	true	Enable DuckDB persistence
storage_path	string	"./data/duckdb/topics"	Database directory
max_writers	number	10	Concurrent writers
total_databases	number	10	Database instances
commit_interval_ms	number	1000	Commit interval

Embedded PostgreSQL Configuration

In-memory PostgreSQL for DuckLake metadata catalogs.

In-Memory Mode

Embedded PostgreSQL runs on tmpfs. Data relies on S3 backups for recovery.

Field	Type	Default	Description
enabled	boolean	true	Enable embedded PostgreSQL
port	number	5433	PostgreSQL port
databases	array	see below	Databases to create

Default databases: ducklake_catalog, ducklake_analytics, ducklake_default

Rate Limiting Configuration

Field	Type	Default	Description
disabled	boolean	false	Disable rate limiting
max_requests	number	15000000	Max requests/sec per producer
burst_limit	number	20000000	Burst limit
global_limit	number	150000000	Global limit
base_size_bytes	number	4096	Base size for tokens

TLS Configuration

TLS for FlightRPC connections.

Field	Type	Default	Description
disabled	boolean	false	Disable TLS
cert_path	string	null	Certificate path
key_path	string	null	Private key path
cert_pem	string	null	Certificate as PEM
key_pem	string	null	Private key as PEM
grpc_default_ssl_roots_file_path	string	null	CA roots file

Auth Configuration (FlightRPC JWT)

JWT authentication for FlightRPC/DuckDB Airport connections.

Field	Type	Default	Description
providers	array	[]	Auth providers: cognito, azure, gcp, auth0, okta
authorization_enabled	boolean	false	Enable authorization
admin_groups	array	[]	Admin group names
read_only_groups	array	[]	Read-only group names
max_sessions_per_hour	number	1000	Session rate limit
max_concurrent_sessions	number	20	Max concurrent sessions
max_session_ttl_hours	number	8	Session TTL

Metrics Configuration

Field	Type	Default	Description
port	number	8081	Prometheus metrics port
flush_interval_ms	number	1000	Flush interval

Logging Configuration

Field	Type	Default	Description
rust_log	string	"info"	Log level (trace, debug, info, warn, error)

PGWire Configuration

PostgreSQL wire protocol server for BI tools and SQL clients.

Field	Type	Default	Description
enabled	boolean	true	Enable PGWire server
port	number	5432	PostgreSQL port
refresh_interval_seconds	number	5	Instance refresh interval
initialization_sql	string	""	SQL to run on init
metadata_db_path	string	"./metadata.duckdb"	Metadata database path
query_timeout_seconds	number	300	Query timeout (5 min)
max_connections	number	100	Max connections
idle_timeout_seconds	number	900	Idle timeout (15 min)
connection_timeout_seconds	number	1800	Connection timeout (30 min)
tenant_data_base_path	string	"/tmp/boilstream/tenants"	Tenant data directory
metadata_backup_backend	string	null	Backup backend name
metadata_backup_interval_seconds	number	60	Backup interval
metadata_backup_path	string	"pgwire/metadata-backup.tar.gz"	Backup path

PGWire TLS Configuration

Field	Type	Default	Description
tls.enabled	boolean	false	Enable TLS
tls.cert_path	string	null	Certificate path
tls.key_path	string	null	Private key path
tls.cert_pem	string	null	Certificate as PEM
tls.key_pem	string	null	Private key as PEM

Kafka Configuration

Kafka-compatible server for Kafka producers.

Built-in Schema Registry

BoilStream includes a Confluent-compatible Schema Registry at /schema-registry on the auth server (port 443). No additional configuration needed - it's automatically enabled when the auth server is running. See Schema Registry API for details.

Field	Type	Default	Description
enabled	boolean	true	Enable Kafka server
port	number	9092	Kafka port
bind_address	string	"0.0.0.0"	Bind address

Kafka TLS Configuration

Field	Type	Default	Description
tls.enabled	boolean	false	Enable TLS (SASL_SSL)
tls.cert_path	string	null	Certificate path
tls.key_path	string	null	Private key path
tls.cert_pem	string	null	Certificate as PEM
tls.key_pem	string	null	Private key as PEM

Kafka Rate Limiting

Field	Type	Default	Description
rate_limiting.disabled	boolean	false	Disable rate limiting
rate_limiting.max_requests_per_second	number	10000	Max requests/sec
rate_limiting.burst_limit	number	15000	Burst limit
rate_limiting.global_limit	number	100000	Global limit

HTTP/2 Ingestion Configuration

HTTP/2 Arrow ingestion server for browser-based data collection.

Field	Type	Default	Description
enabled	boolean	false	Enable HTTP/2 server
port	number	8443	Server port
bind_address	string	"0.0.0.0"	Bind address
token_secret_key	string	""	BLAKE3 MAC key for browser tokens (see below)
max_request_size	number	131072	Max request size (128KB)

Token Secret Key

The token_secret_key is a master secret used to generate and validate BLAKE3-authenticated tokens for browser-based ingestion. Tokens bind requests to domain, tenant, topic, and expiry time.

Requirements:

• Exactly 32 bytes (256 bits), base64 encoded
• Generate with: openssl rand -base64 32

Token formats:

• Standard (64 hex chars): 128-bit data + 128-bit BLAKE3 MAC
• Extended (128 hex chars): Standard + nonce + encrypted user_id (ChaCha20Poly1305)

Security

If empty or invalid, falls back to an insecure default key. Always configure in production.

HTTP TLS Configuration

Field	Type	Default	Description
tls.cert_path	string	""	Certificate path
tls.key_path	string	""	Private key path
tls.cert_pem	string	""	Certificate as PEM
tls.key_pem	string	""	Private key as PEM

HTTP CORS Configuration

Field	Type	Default	Description
cors.allowed_origins	array	[]	Allowed origins
cors.max_age_seconds	number	3600	Preflight cache max age
cors.allow_credentials	boolean	false	Allow credentials

HTTP Rate Limiting

Field	Type	Default	Description
rate_limiting.enabled	boolean	true	Enable rate limiting
rate_limiting.global_requests_per_second	number	10000	Global limit
rate_limiting.tenant_requests_per_second	number	1000	Per-tenant limit
rate_limiting.tenant_burst_size	number	5000	Per-tenant burst
rate_limiting.tenant_overrides	map	{}	Per-tenant overrides

HTTP/2 Settings

Field	Type	Default	Description
http2.max_connections	number	100000	Max connections
http2.accept_threads	number	0	Accept threads (0 = CPU)
http2.initial_stream_window_size	number	262144	Stream window
http2.initial_connection_window_size	number	1048576	Connection window
http2.max_frame_size	number	131072	Max frame size
http2.max_concurrent_streams	number	50	Max streams/connection
http2.keep_alive_interval_secs	number	20	Keep-alive interval
http2.keep_alive_timeout_secs	number	10	Keep-alive timeout

HTTP Memory Pool

Field	Type	Default	Description
memory_pool.buffer_size	number	131072	Buffer size (128KB)
memory_pool.buffer_count	number	2000	Buffer count

Auth Server Configuration (Web Auth GUI)

Web authentication server for browser-based access.

Field	Type	Default	Description
enabled	boolean	false	Enable auth server
port	number	443	HTTPS port
tls_cert	string	null	TLS certificate path
tls_key	string	null	TLS private key path
tls_auto_reload	boolean	true	Auto-reload certificates
tls_reload_check_interval_seconds	number	21600	Reload check interval (6h)
session_ttl_hours	number	8	Session TTL
users_db_path	string	"data/users.duckdb"	Users database path
encryption_key_path	string	null	Encryption key file path
superadmin_password_path	string	null	Superadmin password file
superadmin_mfa_secret_path	string	null	MFA TOTP secret file (base32)
app_domain	string	null	Application domain
webauthn_rp_id	string	"localhost"	WebAuthn RP ID
webauthn_rp_origin	string	"https://localhost"	WebAuthn origin
cors_allowed_origins	array	[]	CORS allowed origins
grants_db_path	string	"data/grants.duckdb"	Grants database path
default_user_role	string	"reader"	Default role for new users
admin_username	string	null	Admin username
users_backup_backend	string	null	Users backup backend
users_backup_interval_seconds	number	60	Users backup interval
users_backup_path	string	"auth/users.duckdb"	Users backup path
superadmin_backup_backend	string	null	Superadmin backup backend
superadmin_backup_interval_seconds	number	60	Superadmin backup interval
superadmin_backup_path	string	"auth/superadmin.duckdb"	Superadmin backup path
email_encryption_pgp_public_key_path	string	null	PGP public key path
email_encryption_pgp_public_key	string	null	PGP public key (inline)
enable_ducklake	boolean	true	Enable DuckLake manager
auto_create_default_ducklake	boolean	true	Auto-create default DuckLake
enable_hydration	boolean	true	Enable hydration API

OAuth Providers Configuration

OAuth/SAML providers for Web Auth GUI.

GitHub OAuth

Field	Type	Default	Description
client_id	string	required	GitHub OAuth client ID
client_secret	string	required	GitHub OAuth client secret
redirect_uri	string	null	OAuth callback URL
allowed_orgs	array	[]	Allowed organizations
team_role_mappings	map	{}	Team to role mappings
audit_org_teams	boolean	false	Audit org/team membership

Google OAuth

Field	Type	Default	Description
client_id	string	required	Google OAuth client ID
client_secret	string	required	Google OAuth client secret
redirect_uri	string	null	OAuth callback URL
allowed_domains	array	[]	Allowed email domains

Generic OAuth2

Field	Type	Default	Description
name	string	required	Provider identifier
client_id	string	required	OAuth client ID
client_secret	string	required	OAuth client secret
auth_url	string	required	Authorization endpoint
token_url	string	required	Token endpoint
userinfo_url	string	required	User info endpoint
redirect_uri	string	null	OAuth callback URL
scopes	array	required	OAuth scopes

SAML SSO

Field	Type	Default	Description
name	string	required	Provider identifier
enabled	boolean	false	Enable provider
sp_entity_id	string	required	SP entity ID
sp_acs_url	string	required	Assertion Consumer Service URL
sp_slo_url	string	null	Single Logout URL
idp_entity_id	string	required	IDP entity ID
idp_sso_url	string	required	IDP SSO endpoint
idp_slo_url	string	null	IDP logout endpoint
idp_certificate	string	required	IDP certificate (PEM)
sp_certificate	string	required	SP certificate path or PEM
sp_private_key	string	required	SP private key path or PEM

Audit Configuration

Audit logging for compliance (SOC2/ISO).

Field	Type	Default	Description
enabled	boolean	false	Enable audit logging
backend	string	"ndjson"	Backend: ndjson, duckdb, s3, disabled
log_path	string	null	Log file path (null = stdout)
buffer_size	number	1000	Event buffer size
sample_rate	number	null	Sampling rate 0.0-1.0
include_query_text	boolean	true	Include SQL in logs
include_ip_address	boolean	true	Include IP addresses

Cluster Mode Configuration

Horizontal scaling with S3-based leader election. See Cluster Mode for architecture.

Cluster Identity

Nodes belong to the same cluster when they share the same primary storage backend (S3 bucket/prefix).

Field	Type	Default	Description
enabled	boolean	false	Enable cluster mode
node_id_path	string	null	Persistent node ID file
advertised_host	string	"localhost"	Externally reachable hostname
internal_api_port	number	8443	Inter-node communication port
leader_heartbeat_interval_secs	number	30	Leader heartbeat interval
leader_stale_threshold_secs	number	120	Leader stale threshold
broker_heartbeat_interval_secs	number	30	Broker heartbeat interval
broker_stale_threshold_secs	number	120	Broker stale threshold

Cluster TLS Configuration (mTLS)

Field	Type	Default	Description
tls.enabled	boolean	false	Enable mTLS
tls.cert_path	string	null	Server certificate path
tls.key_path	string	null	Server private key path
tls.ca_cert_path	string	null	CA certificate path
tls.require_client_cert	boolean	true	Require client certificates

Validation

BoilStream validates configuration on startup and exits with an error if:

• Required fields are missing
• Invalid values are provided
• Referenced files don't exist (TLS certificates, etc.)
• Storage backend validation fails

Check logs for detailed validation error messages.