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.

Cerbos configuration file
---
audit:
  accessLogsEnabled: true # AccessLogsEnabled defines whether access logging is enabled.
  backend: local # Backend states which backend to use for Audits.
  decisionLogsEnabled: true # DecisionLogsEnabled defines whether logging of policy decisions is enabled.
  enabled: false # Enabled defines whether audit logging is enabled.
  local:
    advanced:
      bufferSize: 256
      flushInterval: 1s
      gcInterval: 60s
      maxBatchSize: 32
    retentionPeriod: 168h # How long to keep records for
    storagePath: /path/to/dir # Path to store the data
auxData:
  jwt: # JWT holds the configuration for JWTs used as an auxiliary data source for the engine.
    disableVerification: false # DisableVerification disables JWT verification.
    keySets: # KeySets is the list of keysets to be used to verify tokens.
      -
        id: ks1 # Required. ID is the unique reference to this keyset.
        local: # Local defines a local keyset. Mutually exclusive with Remote.
          data: base64encodedJWK # Data is the encoded JWK data for this keyset. Mutually exclusive with File.
          file: /path/to/keys.jwk # File is the path to file containing JWK data. Mutually exclusive with Data.
          pem: true # PEM indicates that the data is PEM encoded.
        remote: # Remote defines a remote keyset. Mutually exclusive with Local.
          refreshInterval: 1h # RefreshInterval is the refresh interval for the keyset.
          url: https://domain.tld/.well-known/keys.jwks # Required. URL is the JWKS URL to fetch the keyset from.
engine:
  defaultPolicyVersion: "default" # DefaultPolicyVersion defines what version to assume if the request does not specify one.
schema:
  enforcement: reject # Enforcement defines level of the validations. Possible values are none, warn, reject.
server:
  adminAPI: # AdminAPI defines the admin API configuration.
    adminCredentials: # AdminCredentials defines the admin user credentials.
      passwordHash: JDJ5JDEwJEdEOVFzZDE2VVhoVkR0N2VkUFBVM09nalc0QnNZaC9xc2E4bS9mcUJJcEZXenp5OUpjMi91Cgo= # PasswordHash is the base64-encoded bcrypt hash of the password to use for authentication.
      username: cerbos # Username is the hardcoded username to use for authentication.
    enabled: true # Enabled defines whether the admin API is enabled.
  cors: # CORS defines the CORS configuration for the server.
    allowedHeaders: ['content-type'] # AllowedHeaders is the contents of the allowed-headers header.
    allowedOrigins: ['*'] # AllowedOrigins is the contents of the allowed-origins header.
    disabled: false # Disabled sets whether CORS is disabled.
    maxAge: 10s # MaxAge is the max age of the CORS preflight check.
  grpcListenAddr: ":3593" # Required. GRPCListenAddr is the dedicated GRPC address.
  httpListenAddr: ":3592" # Required. HTTPListenAddr is the dedicated HTTP address.
  logRequestPayloads: false # LogRequestPayloads defines whether the request payloads should be logged.
  metricsEnabled: true # MetricsEnabled defines whether the metrics endpoint is enabled.
  playgroundEnabled: false # PlaygroundEnabled defines whether the playground API is enabled.
  tls: # TLS defines the TLS configuration for the server.
    caCert: /path/to/CA_certificate # CACert is the path to the optional CA certificate for verifying client requests.
    cert: /path/to/certificate # Cert is the path to the TLS certificate file.
    key: /path/to/private_key # Key is the path to the TLS private key file.
storage:
  # This section is required. The field driver must be set to indicate which driver to use.
  driver: "disk" # Required. Driver states which storage driver to use. Possible values are blob, mysql, postgres, sqlite3, disk and git.
  blob:
    # This section is required only if storage.driver is blob.
    bucket: "s3://my-bucket-name?region=us-east-2" # Required. Bucket URL (Examples: s3://my-bucket?region=us-west-1 gs://my-bucket azblob://my-container).
    downloadTimeout: 30s # DownloadTimeout specifies the timeout for downloading from cloud storage.
    prefix: policies # Prefix specifies a subdirectory to download.
    requestTimeout: 10s # RequestTimeout specifies the timeout for an HTTP request.
    updatePollInterval: 15s # UpdatePollInterval specifies the interval to poll the cloud storage. Set to 0 to disable.
    workDir: ${HOME}/tmp/cerbos/work # WorkDir is the local path to check out policies to.
  disk:
    # This section is required only if storage.driver is disk.
    directory: pkg/test/testdata/store # Required. Directory is the path on disk where policies are stored.
    watchForChanges: false # Required. WatchForChanges enables watching the directory for changes.
  git:
    # This section is required only if storage.driver is git.
    branch: policies # Branch is the branch to checkout.
    checkoutDir: ${HOME}/tmp/cerbos/work # CheckoutDir is the local path to checkout the Git repo to.
    https: # HTTPS holds auth details for the HTTPS protocol.
      password: ${GITHUB_TOKEN} # The password (or token) to use for authentication.
      username: cerbos # The username to use for authentication.
    operationTimeout: 60s # OperationTimeout specifies the timeout for git operations.
    protocol: file # Required. Protocol is the Git protocol to use. Valid values are https, ssh, and file.
    ssh: # SSH holds auth details for the SSH protocol.
      password: pw # The password to the SSH private key.
      privateKeyFile: ${HOME}/.ssh/id_rsa # The path to the SSH private key file.
      user: git # The git user. Defaults to git.
    subDir: policies # SubDir is the path under the checked-out Git repo where the policies are stored.
    url: file://${HOME}/tmp/cerbos/policies # Required. URL is the URL to the Git repo.
    updatePollInterval: 60s # UpdatePollInterval specifies the interval to poll the Git repository for changes. Set to 0 to disable.
  mysql:
    # This section is required only if storage.driver is mysql.
    connPool:
      maxLifeTime: 60m
      maxIdleTime: 45s
      maxOpen: 4
      maxIdle: 1
    dsn: "user:password@tcp(localhost:3306)/db?interpolateParams=true" # Required. DSN is the data source connection string.
    serverPubKey:
      mykey: testdata/server_public_key.pem
    tls:
      mytls:
        cert: /path/to/certificate
        key: /path/to/private_key
        caCert: /path/to/CA_certificate
  postgres:
    # This section is required only if storage.driver is postgres.
    connPool:
      maxLifeTime: 60m
      maxIdleTime: 45s
      maxOpen: 4
      maxIdle: 1
    url: "postgres://user:password@localhost:port/db" # Required. URL is the Postgres connection URL. See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
  sqlite3:
    # This section is required only if storage.driver is sqlite3.
    dsn: ":memory:?_fk=true" # Required. Data source name
tracing:
  exporter: jaeger # Exporter is the type of trace exporter to use.
  jaeger: # Jaeger configures the Jaeger exporter.
    agentEndpoint: "localhost:6831" # AgentEndpoint is the Jaeger agent endpoint to report to.
    collectorEndpoint: "http://localhost:14268" # CollectorEndpoint is the Jaeger collector endpoint to report to.
    serviceName: cerbos # ServiceName is the name of the service to report to Jaeger.
  sampleProbability: 0.1 # SampleProbability is the probability of sampling expressed as a number between 0 and 1.