Skip to main content

Configuration

Chorus loads configurations from .yaml files. Use commands and flags to designate the path to these .yaml files:

  • -config. Example: proxy -config ./my-dir/my-conf.yaml
  • -config-override . Example: proxy -config ./my-dir/my-conf.yaml -config-override ./my-dir/my--secretconf.yaml

Both of these flags are optional. Values provided in -config override the default values. Values provided in -config-override override default values and -config values.

Configuration values can also be set as environment variables. For example: export CFG_REDIS_ADDRESS='127.0.0.1:6379' will override value from yaml config:

redis:
  address: 127.0.0.1:1234

CFG_ - mandatory prefix for chorus config value _ - separator for yaml properties.

log.level: info from .yaml is functionally equivalent to the environment variable CFG_LOG_LEVEL=info.

Configuration Files​

For full configuration options and default values, see the source files:

Key Configuration Sections​

Storage​

Define storages and designate one as main:

storage:
  main: "my_storage"  # name of main storage
  storages:
    my_storage:
      type: S3  # S3 or SWIFT
      address: s3.example.com
      provider: Ceph  # Ceph, Minio, or Other
      isSecure: true
      rateLimit:
        enabled: false
        rpm: 60  # requests per minute
      credentials:
        user1:
          accessKeyID: "..."
          secretAccessKey: "..."

The rateLimit option limits requests to a specific storage, useful when a destination storage has API rate limits or limited capacity.

Redis​

Configure Redis connection:

redis:
  addresses:
    - "127.0.0.1:6379"
  password: ""
  appDB: 0      # metadata storage
  queueDB: 1    # work queue
  lockDB: 2     # distributed locks
  configDB: 3   # policies

Logging, Metrics, Tracing​

log:
  json: true   # JSON format for production
  level: info

metrics:
  enabled: true
  port: 9090

trace:
  enabled: true
  endpoint: "http://jaeger:14268/api/traces"

Dynamic Credentials​

Manage storage credentials via API instead of config files:

storage:
  dynamicCredentials:
    enabled: true
    masterPassword: "secret"  # encrypts credentials in Redis
    pollInterval: 3s

When enabled, use chorctl set-user to add credentials at runtime.

Swift Storage​

OpenStack Swift requires different configuration for proxy and worker:

  • Worker: Uses Keystone authentication (authURL)
  • Proxy: Uses direct Swift endpoint (storageURL)

Example Swift storage:

storage:
  storages:
    swift-main:
      type: SWIFT
      # Worker uses Keystone
      authURL: http://keystone:5000/v3
      storageEndpointName: swift
      storageEndpointType: object-store
      region: RegionOne
      # Proxy uses direct endpoint (cannot use Keystone)
      storageURL: http://swift:8080/v1
      credentials:
        # Key must be OpenStack project ID
        b6ebf758c9894224a105e5531eaa4ce9:
          username: admin
          password: secret
          domainName: Default
          tenantName: admin

See Helm chart examples for complete S3 and Swift configuration examples.

Webhooks​

Webhooks are an alternative to Proxy for capturing storage changes. Use webhooks when:

  • You cannot deploy Proxy in front of your storage (e.g., managed S3 services)
  • Your storage is OpenStack Swift (which does not support proxy-based capture)

The Worker receives change events via HTTP webhook endpoints and creates replication tasks.

Worker Webhook Configuration​

Enable webhooks in the Worker config:

api:
  enabled: true
  webhook:
    enabled: true
    httpPort: 9673  # optional: separate port for webhook endpoints
    baseUrl: "http://worker.example.com:9673"  # externally reachable URL

Key settings:

  • baseUrl: Public URL where the Worker receives events. Must be reachable by the S3 storage (for S3 notifications) or the log parser (for Swift events).
  • httpPort: Optional separate port for webhook endpoints. Defaults to the management API port if not set.

See service/worker/config.yaml for full configuration options.

S3 Bucket Notifications​

For Ceph S3 storage, Chorus auto-configures SNS topics and bucket notifications. No manual S3 configuration is needed — Chorus creates the notification endpoint when replication is added.

Limitations

S3 notification-based replication supports bucket-level replication only (not user-level), because S3 bucket notifications are configured per-bucket.

Create replication with --event-source s3-notification:

chorctl repl add --user=user1 --from=main --to=follower \
    --from-bucket=mybucket --event-source=s3-notification

The Worker webhook endpoint for S3 notifications is: POST <baseUrl>/webhook/<storage>/s3-notifications

Swift Events​

For OpenStack Swift storage, an external log parser is required to convert Swift proxy-server access logs into webhook calls. A Fluent Bit sidecar is the recommended approach.

See Swift webhook design for architecture details and Fluent Bit configuration.

Create replication with --event-source webhook:

chorctl repl add --user=user1 --from=swift-main --to=follower \
    --from-bucket=mycontainer --event-source=webhook

The Worker webhook endpoint for Swift events is: POST <baseUrl>/webhook/<storage>/swift

Webhook Helm Chart Example​

See Helm chart webhook example for a complete deployment configuration.