Configuration
The Cerbos server is configured with a YAML file. Start the server by passing the configuration file using the --config
flag. The values defined in the file can be overridden from the command-line by using the --set
flag. The --set
flag can be used multiple times. For example, to override server.httpListenAddr
and engine.defaultPolicyVersion
, the --set
flag can be used as follows:
./cerbos server --config=/path/to/config.yaml --set=server.httpListenAddr=:3592 --set=engine.defaultPolicyVersion=staging
Config values can reference environment variables by enclosing them between ${} . E.g. ${HOME} .
|
./cerbos server --config=/path/to/config.yaml --set=server.httpListenAddr=:3592 --set=engine.defaultPolicyVersion=staging
Minimal Configuration
At a minimum, Cerbos requires a storage driver to be configured in order to start. You must provide a configuration file when starting the Cerbos binary. The Cerbos container ships with a default configuration that has a disk
driver configured to look for policies mounted at /policies
.
.Default configuration file shipped in the container
---
server:
httpListenAddr: ":3592"
grpcListenAddr: ":3593"
storage:
driver: "disk"
disk:
directory: /policies
watchForChanges: true
Full Configuration
Cerbos has many configuration options that are either optional or has reasonable defaults built-in. The following section describes all user-configurable options and their defaults.
---
server:
httpListenAddr: ":3592" # The dedicated HTTP address to listen.
grpcListenAddr: ":3593" # The dedicated HTTP address to listen.
metricsEnabled: true # Set to false to disable the /_cerbos/metrics endpoint
logRequestPayloads: false # Set to true to log full request and response payloads. Affects performance.
playgroundEnabled: false # Set to true to enable the playground API.
tls: # Optional
cert: /path/to/certificate # Path to the TLS certificate file.
key: /path/to/private_key # Path to the TLS private key file.
caCert: /path/to/CA_certificate # Path to the optional CA certificate for verifying client requests.
cors: # Optional
disabled: false
allowedOrigins: ['*'] # The contents of the allowed-origins header.
allowedHeaders: ['content-type', 'access-control-allow-origin'] # The contents of the allowed-headers header
maxAge: 10s # The max age of the CORS preflight check.
adminAPI:
enabled: true # Defines whether the admin API is enabled.
adminCredentials: # Defines the admin user credentials.
username: cerbos # The hardcoded username to use for authentication.
passwordHash: JDJ5JDEwJEdEOVFzZDE2VVhoVkR0N2VkUFBVM09nalc0QnNZaC9xc2E4bS9mcUJJcEZXenp5OUpjMi91Cgo= # BCrypt hashed and base64 encoded password to use for authentication.
auxData: # Optional
jwt:
disableVerification: false # Set to true to disable JWT verification
keySets: # Keysets for verifying JWTs
- id: ks1 # Unique ID that can be used in API requests to indicate the keyset to use to verify a particular token.
remote: # Fetch from a JWKS URL.
url: https://domain.tld/.well-known/keys.jwks
- id: ks2
remote:
url: https://other-domain.tld/.well-known/keys.jwks
refreshInterval: 1h # Explicitly set the refresh interval.
- id: ks3
local: # Load from a local file
file: /path/to/keys.jwks
- id: ks4
local: # Load from a base64-encoded key data defined inline.
data: BASE64-ENCODED-KEY-DATA
- id: ks5
local:
file: /path/to/keys.pem
pem: true # Treat the file (or data) as PEM.
engine: # Optional
defaultPolicyVersion: "default" # Default policy version to assume if the request does not specify one.
storage:
driver: "disk" # Valid values are "disk", "git" or "sqlite3"
disk: # Only required if "driver" is "disk"
directory: pkg/test/testdata/store # Directory to store policies
watchForChanges: false # Enables watching the directory for changes.
git: # Only required if the "driver" is "git"
protocol: file # Valid values are "file", "ssh", "https"
url: file://${HOME}/tmp/cerbos/policies # the URL to the Git repo.
branch: policies # Branch that should be used as the source. Defaults to "master"
subDir: policies # Set this if the policies are stored in a subdirectory
checkoutDir: ${HOME}/tmp/cerbos/work # Work directory of the server
updatePollInterval: 60s # How often the source git repo should be polled for updates
https: # Only required if the "protocol" is "https"
username: cerbos # The username to use for authentication.
password: ${GITHUB_TOKEN} # The password (or token) to use for authentication.
ssh: # Only required if the "protocol" is "ssh"
user: git # The git user. Defaults to git.
privateKeyFile: ${HOME}/.ssh/id_rsa # the path to the SSH private key file.
# password: pw # the password to the SSH private key.
blob: # Only required if the "driver" is "blob"
bucket: "s3://my-bucket-name?region=us-east-2" # the URL of the bucket
prefix: policies # Set this if the policies are stored in a bucket subdirectory
workDir: ${HOME}/tmp/cerbos/work # Directory to store policies
updatePollInterval: 15s # how often the bucket should be polled for updates. Defaults to 0, which disables polling.
requestTimeout: 10s # HTTP request timeout. Defaults to 5s.
downloadTimeout: 30s # Timeout to download all requested policies.
sqlite3: # Only required if the "driver" is "sqlite3"
dsn: ":memory:?_fk=true" # Data source name
postgres: # Only required if the "driver" is "postgres"
url: "postgres://user:password@localhost:port/db"
connPool: # common SQL connection pool settings.
maxLifeTime: 60m
maxIdleTime: 45s
maxOpen: 4
maxIdle: 1
mysql: # Only required if the "driver" is "mysql"
dsn: "user:password@tcp(localhost:3306)/db?interpolateParams=true" # Data source name
connPool: # common SQL connection pool settings.
maxLifeTime: 60m
maxIdleTime: 45s
maxOpen: 4
maxIdle: 1
tls:
mytls:
cert: /path/to/certificate # Path to the TLS certificate file.
key: /path/to/private_key # Path to the TLS private key file.
caCert: /path/to/CA_certificate # Path to the optional CA certificate for verifying client requests.
serverPubKey:
mykey: testdata/server_public_key.pem
tracing: # Optional
sampleProbability: 0.1 # Sampling probability value between 0.0 and 1.0
exporter: jaeger # Trace exporter to use. Currently only Jaeger is supported
jaeger: # Required only if exporter is "jaeger"
serviceName: cerbos # Optional service name to report to Jaeger. Defaults to cerbos.
agentEndpoint: "localhost:6831" # Export to Jaeger agent. Takes precedence if both "agentEndpoint" and "collectorEndpoint" are defined.
collectorEndpoint: "http://localhost:14268" # Export to Jaeger collector.
audit: # Optional
enabled: false # Enable audit logging
accessLogsEnabled: true # Log API access attempts
decisionLogsEnabled: true # Log policy decisions
backend: local # Audit backend to use.
local: # Configuration for the local audit backend
storagePath: /path/to/dir # Path to store the data
retentionPeriod: 168h # How long to keep records for
advanced:
bufferSize: 256
maxBatchSize: 32
flushInterval: 1s
gcInterval: 60s
schema: # Optional
enforcement: reject # How to enforce schema validation (none: no enforcement, warn: log warnings, reject: reject invalid requests)