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 configuration file
---
server:
  httpListenAddr: ":3592"
  grpcListenAddr: ":3593"
  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
    key: /path/to/private_key
    caCert: /path/to/CA_certificate # Optional
  cors: # Optional
    disabled: false
    allowedOrigins: ['*']
    allowedHeaders: []
  adminAPI:
    enabled: true
    adminCredentials:
      username: cerbos
      passwordHash: $2y$10$6v.PIn0zJ1xFdIDPlX3yheDZHM2iXI8CSKT5a3d35djtOxnOATxFi

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
    watchForChanges: false
    scratchDir: /tmp/cerbos # Directory to use for caching generated code
  git: # Only required if the "driver" is "git"
    protocol: file # Valid values are "file", "ssh", "https"
    url: file://${HOME}/tmp/cerbos/policies
    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
    scratchDir: /tmp/cerbos # Directory to use for caching generated code
    https: # Only required if the "protocol" is "https"
      username: cerbos
      password: ${GITHUB_TOKEN}
    ssh: # Only required if the "protocol" is "ssh"
      user: git
      privateKeyFile: ${HOME}/.ssh/id_rsa
  sqlite3: # Only required if the "driver" is "sqlite3"
    dsn: ":memory:?_fk=true"

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