Edge Server Configuration Schema

      +

      You can configure Couchbase Edge Server through use of a JSON configuration file.

      The configuration file is parsed as JSON5 format.

      JSON Schema

      Below you can find a JSON configuration schema for Couchbase Edge Server. Default values are displayed when they exist, if not, the value type is displayed.

      Couchbase does not recommend setting enable_adhoc_queries to true for production environments.
      {
         $schema: "https://packages.couchbase.com/couchbase-edge-server/config_schema.json",
         databases: {
            {database_name...}: {
               collections: array,object,
               create: false,
               enable_adhoc_queries: false,
               enable_client_sync: boolean or string,
               enable_client_writes: false,
               password: "string",
               path: "string",
               placeholder_uuid: "string",
               queries: {
                  {query...}: "string"
               }
            }
         },
         enable_anonymous_users: false,
         https: {
            client_cert_path: "string",
            tls_cert_path: "string",
            tls_key_path: "string"
         },
         interface: "0.0.0.0:59840",
         logging: {
            audit: {
               disable: string,array,
               enable: string,array,
               file: "string",
               omit_description: false
            },
            console: true,
            domains: {
               {domain...}: "warning"
            },
            file: {
               dir: "string",
               format: "binary",
               maxSize: 1000000,
               rotateCount: 0
            }
         },
         replications: [
            auth: {
               openid_token: "string",
               password: "string",
               session_cookie: "string",
               tls_client_cert: "string",
               tls_client_cert_key: "string",
               user: "string"
            },
            bidirectional: false,
            channels: ["string"...],
            collections: _default,
            continuous: false,
            doc_ids: ["string"...],
            headers: {
               {header...}: "string"
            },
            pinned_cert: "string",
            proxy: {
               auth: {
                  openid_token: "string",
                  password: "string",
                  tls_client_cert: "string",
                  tls_client_cert_key: "string",
                  user: "string"
               },
               host: "string",
               port: 0,
               type: "HTTP"
            },
            source: "string",
            target: "string",
            trusted_root_certs: "string"
         ],
         users: "string"
      }
      

      $schema

      Type

      string

      Default

      https://packages.couchbase.com/couchbase-edge-server/config_schema.json

      Description

      Allows config files to declare they conform to this schema. Otherwise ignored.

      databases

      Type

      object

      Description

      The databases to be served. Keys are the URI names to use.

      databases.{database_name…​}

      Type

      object

      Description

      A database configuration.

      databases.{database_name…​}.collections

      Type

      array,object

      Description

      Collections to share. If omitted, all collections are shared. If it's an array, the items are the names of the collections to share (and create, if create is true). If it's an object, each key is a collection name and the value is an object describing the collection.

      databases.{database_name…​}.create

      Type

      boolean

      Description

      If true, database will be created on startup if it doesn't exist.

      databases.{database_name…​}.enable_adhoc_queries

      Type

      boolean

      Description

      If true, clients can submit freeform SQL++ SELECT queries.

      Not recommended in production due to potential for abuse: slow-running queries can be used as DoS attacks.

      databases.{database_name…​}.enable_client_sync

      Type

      boolean or string

      Description

      Enables client sync connections. pull is read-only, push is write-only, bidirectional or true enables both. Defaults to false, that is, sync is not allowed.

      databases.{database_name…​}.enable_client_writes

      Type

      boolean

      Description

      Enables writing to database via PUT / POST / DELETE requests. Lets clients write to the documents via the REST API. It does not affect clients syncing. So it's possible to disallow writes via REST but allow them via push replication, or vice versa.

      This does not affect upstream replication or client sync. To prevent clients from writing to the database via sync, enable_client_sync must be omitted or set to pull.

      databases.{database_name…​}.password

      Type

      string

      Description

      Database password, or raw AES256 key encoded as 64 hex digits.

      databases.{database_name…​}.path

      Type

      string

      Description

      Path of database file.

      databases.{database_name…​}.placeholder_uuid

      Type

      string

      Description

      Database UUID to be replaced on first launch. The placeholder_uuid property should be used if the database has been copied from elsewhere. Every database file contains a universally unique ID (UUID); copying a database file means this is no longer unique, and that will cause problems with replication. If a canned initial database file is to be deployed to a number of Edge Servers, its current UUID can be set as the value of this property. The first time each server starts up, it will replace that UUID with a new, actually-unique one. You can find a database file's UUID via cblite info -v db.cblite2.

      databases.{database_name…​}.queries

      Type

      object

      Description

      SQL++ queries clients can invoke. Keys are query names, values are SQL++.

      databases.{database_name…​}.queries.{query…​}

      Type

      string

      Description

      A SQL++ 'SELECT' query.

      enable_anonymous_users

      Type

      boolean

      Description

      If true, unauthenticated requests are allowed (guest access).

      https

      Type

      object

      Description

      TLS settings. If present, tls_cert_path and tls_key_path are required.

      https.client_cert_path

      Type

      string

      Description

      Path of file containing CA cert for authenticating clients (mTLS).

      If present, clients must connect using TLS client certificates. Only certs signed by this CA cert will be accepted. The Common Name (CN) field of the client cert will be used as the username for purposes of logging.

      https.tls_cert_path

      Type

      string

      Description

      Path of file containing TLS server certificate.

      https.tls_key_path

      Type

      string

      Description

      Path of file containing matching private key.

      interface

      Type

      string

      Default

      0.0.0.0:59840

      Description

      Listening interface IP address and port, separated by a colon. The interface address is optional and defaults to 0.0.0.0, i.e. all interfaces. A useful value for testing is 127.0.0.1, which allows only clients on the same device to connect. The default port number is 59840.

      logging

      Type

      object

      Description

      Logging configuration.

      logging.audit

      Type

      object

      Description

      Configuration for audit logging.

      logging.audit.disable

      Type

      string,array

      Description

      Array of integer event IDs to disable, or "*" to disable all - (enable overrides these).

      logging.audit.enable

      Type

      string,array

      Description

      Array of integer event IDs to enable, or "*" to enable all. (Takes priority over 'disable').

      logging.audit.file

      Type

      string

      Description

      Filename of audit log.

      logging.audit.omit_description

      Type

      boolean

      Description

      If true, audit events will omit the description property.

      The description property can be useful for human readers, but is quite verbose and will significantly increase log file size.

      logging.console

      Type

      boolean

      Default

      true

      Description

      Whether to log to stdout/stderr.

      logging.domains

      Type

      object

      Description

      Custom levels for specific logging domains. Keys are domain names. Common domains are Default, REST, Listener, DB, Query, Sync.

      logging.domains.{domain…​}

      Type

      string

      Default

      warning

      Description

      Log level of the domain: verbose, info, warning or error

      logging.file

      Type

      object

      Description

      Configuration for file-based logging.

      logging.file.dir

      Type

      string

      Description

      Path of existing directory where log files will be created.

      logging.file.format

      Type

      string

      Default

      binary

      Description

      Format of log files: binary or text.

      logging.file.maxSize

      Type

      integer

      Default

      1000000

      Description

      Size in bytes at which log files are rotated.

      logging.file.rotateCount

      Type

      integer

      Description

      Number of older log files that are preserved.

      replications

      Type

      array

      Description

      Replications to run when the server starts.

      replications.auth

      Type

      object

      Description

      Authorization credentials.

      replications.auth.openid_token

      Type

      string

      Description

      An OpenID Connect token.

      replications.auth.password

      Type

      string

      Description

      Password for HTTP Basic auth to remote server. Requires 'user'.

      Type

      string

      Description

      A Sync Gateway session cookie.

      replications.auth.tls_client_cert

      Type

      string

      Description

      This Edge Server's TLS client certificate, for mTLS. (Requires 'tls_client_cert_key'.)

      replications.auth.tls_client_cert_key

      Type

      string

      Description

      Private key of TLS client certificate. (Requires 'tls_client_cert'.)

      replications.auth.user

      Type

      string

      Description

      Username for HTTP Basic auth to remote server. Requires 'password'.

      replications.bidirectional

      Type

      boolean

      Description

      If true, replication is bidirectional.

      replications.channels

      Type

      array

      Description

      Channel filter (incompatible with 'collections')

      replications.collections

      Type

      array,object

      Default

      _default

      Description

      Collections to replicate. If omitted, only the default collection is replicated.

      replications.continuous

      Type

      boolean

      Description

      If true, replication is continuous, i.e. keeps running forever.

      replications.doc_ids

      Type

      array

      Description

      Document IDs to replicate (incompatible with 'collections')

      replications.headers

      Type

      object

      Description

      Extra HTTP headers; keys are header names, values are header values.

      replications.headers.{header…​}

      Type

      string

      Description

      Header value

      replications.pinned_cert

      Type

      string

      Description

      Path of file containing the required server certificate.

      replications.proxy

      Type

      object

      Description

      HTTP proxy settings

      replications.proxy.auth

      Type

      object

      Description

      Proxy authorization credentials.

      replications.proxy.auth.openid_token

      Type

      string

      Description

      An OpenID Connect token.

      replications.proxy.auth.password

      Type

      string

      Description

      Password for HTTP Basic auth to proxy. Requires 'user'.

      replications.proxy.auth.tls_client_cert

      Type

      string

      Description

      This Edge Server's TLS client certificate, for mTLS. (Requires 'tls_client_cert_key'.)

      replications.proxy.auth.tls_client_cert_key

      Type

      string

      Description

      Private key of TLS client certificate. (Requires 'tls_client_cert'.)

      replications.proxy.auth.user

      Type

      string

      Description

      Username for HTTP Basic auth to proxy. Requires 'password'.

      replications.proxy.host

      Type

      string

      Description

      Hostname of proxy server

      replications.proxy.port

      Type

      integer

      Description

      Port number of proxy server

      replications.proxy.type

      Type

      string

      Default

      HTTP

      Description

      Proxy type: 'HTTP' or 'HTTPS'

      replications.source

      Type

      string

      Description

      The source database: a local name or remote 'wss:' URL.

      replications.target

      Type

      string

      Description

      The destination database: a local name or remote 'wss:' URL.

      replications.trusted_root_certs

      Type

      string

      Description

      Path of file containing one or more additional root certificates to be trusted.

      users

      Type

      string

      Description

      Path to JSON file containing users and roles.