OPAL Configuration Guide
Getting Started with OPAL Configuration
OPAL supports multiple ways to configure your deployment:
- Environment Variables (recommended) -
export OPAL_SERVER_URL=http://localhost:7002
- Command Line Arguments -
opal-server run --server-url http://localhost:7002
- Configuration Files -
.env
or.ini
files in your project
Essential Configuration
Let's get OPAL running! You'll need to set a few environment variables that tell OPAL where to find your policies and how to connect everything together.
OPAL Server
# Where your policies are stored (Git repo)
export OPAL_POLICY_REPO_URL=https://github.com/your-org/policy-repo.git
# Where clients get initial data
export OPAL_DATA_CONFIG_SOURCES='{
"config": {
"entries": [{
"url": "http://localhost:7002/policy-data",
"topics": ["policy_data"],
"dst_path": "/static"
}]
}
}'
# Broadcast channel for scaling (use Redis or PostgreSQL)
export OPAL_BROADCAST_URI=postgres://postgres:postgres@localhost:5432/postgres
OPAL Client
# Connect to your OPAL server
export OPAL_SERVER_URL=http://localhost:7002
# Authentication token (change in production!)
export OPAL_CLIENT_TOKEN=your-secret-token
# Policy engine type (OPA is default, Cedar also available)
export OPAL_POLICY_STORE_TYPE=opa
Production Configuration
When you're ready to deploy to production, you'll need to configure a few more things to ensure security and reliability.
- Use HTTPS for all OPAL server communication
- Generate strong cryptographic keys for JWT authentication
- Store secrets securely (never commit to repositories)
- Use webhooks instead of polling for policy updates
Common Configuration
Below are some common configuration options that you may want to consider:
🔐 Security Configuration
# Enable secure mode with proper authentication
export OPAL_AUTH_PRIVATE_KEY="your-rsa-private-key"
export OPAL_AUTH_PUBLIC_KEY="your-rsa-public-key"
export OPAL_AUTH_MASTER_TOKEN="secure-random-token"
# Use HTTPS
export OPAL_SERVER_URL=https://opal.your-domain.com
⚡ Performance & Scaling
# Scale with multiple server workers
export UVICORN_NUM_WORKERS=4
# Use webhooks instead of polling for better performance
export OPAL_POLICY_REPO_POLLING_INTERVAL=0
export OPAL_POLICY_REPO_WEBHOOK_SECRET=your-webhook-secret
📊 Monitoring & Logging
# Enhanced logging and statistics
export OPAL_LOG_FORMAT_INCLUDE_PID=true
export OPAL_LOG_LEVEL=INFO
export OPAL_STATISTICS_ENABLED=true
Read more about secure mode setup.
Configuration Reference
Common OPAL Configs
These configuration variables are shared between OPAL Client and OPAL Server.
General Configuration
OPAL_ALLOWED_ORIGINS
Default: *
Comma-separated list of allowed origins for CORS. Use *
to allow all origins.
OPAL_PROCESS_NAME
Default: opal
The process name to be shown in logs.
OPAL_CLIENT_SELF_SIGNED_CERTIFICATES_ALLOWED
Default: False
Whether OPAL Client will trust HTTPS connections protected by self-signed certificates. Not recommended for production use.
Read more about using self-signed certificates.
OPAL_CLIENT_SSL_CONTEXT_TRUSTED_CA_FILE
Default: None
Path to your own CA public certificate file (usually a .crt or .pem file). Certificates signed by this issuer will be trusted by OPAL Client.
Read more about using self-signed certificates.
OPAL_POLICY_REPO_POLICY_EXTENSIONS
Default: [".rego"]
List of file extensions to serve as policy modules.
OPAL_ENABLE_METRICS
Default: False
Enable metrics collection.
For more information, see monitoring OPAL.
OPAL_ENABLE_DATADOG_APM
Default: False
Enable tracing with DataDog APM. Note: OPAL uses ddtrace v3.0.0+ which requires Python 3.8+.
For more information, see monitoring OPAL.
OPAL_HTTP_FETCHER_PROVIDER_CLIENT
Default: aiohttp
The client to use for fetching data. Options: aiohttp
, httpx
.
Added in OPAL v0.7.7
OPAL_GIT_SSH_KEY_FILE
Default: ~/.ssh/opal_repo_ssh_key
Path to the SSH key file for Git operations.
For more information, see tracking a Git repository.
OPAL_STATISTICS_ENABLED
Default: False
Collect statistics about OPAL clients.
For more information, see monitoring OPAL.
OPAL_STATISTICS_ADD_CLIENT_CHANNEL
Default: __opal_stats_add
The topic to update about new OPAL client connections.
For more information, see monitoring OPAL.
OPAL_STATISTICS_REMOVE_CLIENT_CHANNEL
Default: __opal_stats_rm
The topic to update about OPAL client disconnections.
For more information, see monitoring OPAL.
Logging Configuration
OPAL_LOG_FORMAT_INCLUDE_PID
Default: False
Whether to include the process ID in log messages.
OPAL_LOG_FORMAT
Default: {time} | {process} | {name} | {level} | {message}
The format string for log messages.
OPAL_LOG_TRACEBACK
Default: True
Whether to include traceback information in log messages.
OPAL_LOG_DIAGNOSE
Default: True
Include diagnosis in log messages.
Added in OPAL v0.6.0
When OPAL_LOG_DIAGNOSE
is enabled, logs may contain sensitive information such as secrets.
OPAL_LOG_COLORIZE
Default: True
Whether to colorize log messages.
OPAL_LOG_SERIALIZE
Default: False
Serialize log messages into JSON format (useful for log aggregation platforms).
Added in OPAL v0.6.0
OPAL_LOG_SHOW_CODE_LINE
Default: True
Whether to include the source code line number in log messages.
OPAL_LOG_LEVEL
Default: INFO
The minimum log level to display. Options: DEBUG
, INFO
, WARNING
, ERROR
, CRITICAL
.
OPAL_LOG_MODULE_EXCLUDE_LIST
Default: ["uvicorn"]
List of module names to exclude from logging.
OPAL_LOG_MODULE_INCLUDE_LIST
Default: ["uvicorn.protocols.http"]
List of module names to include in logging (if empty, all modules are included).
OPAL_LOG_PATCH_UVICORN_LOGS
Default: True
Take over Uvicorn's logs so they appear in the main logger.
OPAL_LOG_PIPE_TO_STDERR
Default: True
Whether to send logs to stderr instead of stdout.
Added in OPAL v0.8.2
OPAL_LOG_TO_FILE
Default: False
Whether to write logs to a file in addition to console output.
OPAL_LOG_FILE_PATH
Default: opal_{process_name}{time}.log
Path to define where to save the log file.
OPAL_LOG_FILE_ROTATION
Default: 250 MB
Log file rotation size (e.g., "10 MB", "1 GB").
OPAL_LOG_FILE_RETENTION
Default: 10 days
How long to keep rotated log files (e.g., "30 days", "1 week").
OPAL_LOG_FILE_COMPRESSION
Default: None
Compression format for rotated log files.
OPAL_LOG_FILE_SERIALIZE
Default: True
Serialize log messages in file into JSON format (useful for log aggregation platforms).
OPAL_LOG_FILE_LEVEL
Default: INFO
The minimum log level for file logging.
Authentication Configuration
OPAL_AUTH_PUBLIC_KEY_FORMAT
Default: SSH
Format of the public key. Options: PEM
, JWK
, SSH
.
Read more about secure mode setup.
OPAL_AUTH_PUBLIC_KEY
Default: None
The public key for JWT verification.
Read more about secure mode setup.
OPAL_AUTH_JWT_ALGORITHM
Default: RS256
JWT algorithm for token verification. See possible values here.
Read more about secure mode setup.
OPAL_AUTH_JWT_AUDIENCE
Default: https://api.opal.ac/v1/
The expected audience in JWT tokens.
Read more about secure mode setup.
OPAL_AUTH_JWT_ISSUER
Default: https://opal.ac/
The expected issuer in JWT tokens.
Read more about secure mode setup.
Fetching Configuration
OPAL_FETCH_PROVIDER_MODULES
Default: ["opal_common.fetcher.providers"]
List of custom fetch provider modules to load.
For more information, see writing your own fetch provider and available fetch providers.
OPAL_FETCHING_WORKER_COUNT
Default: 6
The number of workers to use for fetching data concurrently.
OPAL_FETCHING_CALLBACK_TIMEOUT
Default: 10
The timeout for fetching callbacks, in seconds.
OPAL_FETCHING_ENQUEUE_TIMEOUT
Default: 10
The timeout for enqueueing a fetch operation, in seconds.
OPAL Server Configs
These configuration variables are specific to the OPAL Server.
Server Configuration
OPAL_SERVER_WORKER_COUNT
Default: auto
(calculated based on CPU cores)
Worker count for the server (when run using CLI).
OPAL_SERVER_HOST
Default: 127.0.0.1
Address for the server to bind to (when run using CLI).
OPAL_SERVER_PORT
Default: None
DEPRECATED - Use OPAL_SERVER_BIND_PORT instead.
OPAL_SERVER_BIND_PORT
Default: 7002
Port for the server to bind to (when run using CLI).
Added in OPAL v0.6.0
OPAL_BASE_DIR
Default: ~/.local/state/opal
Base directory for OPAL server.
OPAL_NO_RPC_LOGS
Default: True
Disable RPC logging.
OPAL_WS_LOCAL_URL
Default: ws://localhost:7002/ws
The local WebSocket URL for OPAL.
OPAL_WS_TOKEN
Default: THIS_IS_A_DEV_SECRET
The WebSocket token for OPAL.
OPAL_CLIENT_LOAD_LIMIT_NOTATION
Default: None
If supplied, rate limiting will be enforced on the server's WebSocket endpoint. Format is limits
-style notation (e.g., "10 per second"). Learn more.
OPAL_SCOPES
Default: False
Enable scopes for multi-tenancy.
Added in OPAL v0.2.0
OPAL_SCOPES_REPO_CLONES_SHARDS
Default: 1
The max number of local clones to use for the same repo (reused across scopes).
OPAL_LEADER_LOCK_FILE_PATH
Default: /tmp/opal_server_leader.lock
Path to the leader lock file for distributed deployments.
OPAL_MAX_CHANNELS_PER_CLIENT
Default: 15
Maximum number of records per client. After this number, it will not be added to statistics (relevant only if OPAL_STATISTICS_ENABLED
is true).
OPAL_STATISTICS_WAKEUP_CHANNEL
Default: __opal_stats_wakeup
The topic a waking-up OPAL server uses to notify others it needs their statistics data.
OPAL_STATISTICS_STATE_SYNC_CHANNEL
Default: __opal_stats_state_sync
The topic other servers with statistics provide their state to a waking-up server.
OPAL_STATISTICS_SERVER_KEEPALIVE_CHANNEL
Default: __opal_stats_server_keepalive
The topic workers use to signal they exist and are alive.
OPAL_STATISTICS_SERVER_KEEPALIVE_TIMEOUT
Default: 20
Timeout for forgetting a server from which a keep-alive haven't been seen (keep-alive frequency would be half of this value).
Broadcasting Configuration
OPAL_BROADCAST_URI
Default: None
URI for the broadcast backend (Redis, PostgreSQL, etc.).
For more information, see running OPAL with Kafka and running OPAL with Apache Pulsar.
OPAL_BROADCAST_CHANNEL_NAME
Default: EventNotifier
The channel name for broadcasting messages.
For more information, see running OPAL with Kafka and running OPAL with Apache Pulsar.
OPAL_BROADCAST_CONN_LOSS_BUGFIX_EXPERIMENT_ENABLED
Default: True
Enable experimental fix for broadcast connection loss issues.
OPAL_BROADCAST_KEEPALIVE_INTERVAL
Default: 3600
The time to wait between sending two consecutive broadcaster keepalive messages, in seconds.
OPAL_BROADCAST_KEEPALIVE_TOPIC
Default: __broadcast_session_keepalive__
The topic on which to send broadcaster keepalive messages.
OPAL_PUBLISHER_ENABLED
Default: True
Enable the publisher for broadcasting updates.