A newer version of this documentation is available.

View Latest

Bootstrap Configuration

      +

      Reference data on the contents of Sync Gateway’s bootstrap configuration, which determines its run time behavior.

      Pre-3.0 Legacy Configuration Equivalents

      This content describes configuration for Sync Gateway 3.0 and higher — for legacy configuration, see: Legacy Pre-3.0 Configuration

      Introduction

      The Sync Gateway bootstrap configuration is provisioned in a JSON format file. The configuration properties define sync gateway’s runtime behavior. See the schema below for more details on these properties.

      Sync gateway will look for the following configuration file unless you direct it otherwise:
      /home/sync_gateway/sync_gateway.json

      Use the following command to run Sync Gateway with a configuration file:

      sync_gateway sync-gateway-bootstrap.json

      Bootstrap Configuration Schema

      This schema identifies all the configurable properties.

      {
         api: {
            admin_interface: "127.0.0.1:4985",
            admin_interface_authentication: true,
            compress_responses: true,
            cors: {
               headers: [],
               login_origin: [],
               max_age: 0,
               origin: []
            },
            enable_advanced_auth_dp: true,
            hide_product_version: true,
            https: {
               tls_cert_path: "string",
               tls_key_path: "string",
               tls_minimum_version: "tlsv1.2"
            },
            idle_timeout: "90s",
            max_connections: 0,
            metrics_interface: "127.0.0.1:4986",
            metrics_interface_authentication: true,
            profile_interface: "string",
            public_interface: ":4984",
            read_header_timeout: "5s",
            server_read_timeout: "string",
            server_write_timeout: "string"
         },
         auth: {
            bcrypt_cost: 10
         },
         bootstrap: {
            ca_cert_path: "string",
            config_update_frequency: "10s",
            group_id: "default",
            password: "string",
            server: "string",
            server_tls_skip_verify: false,
            use_tls_server: true,
            username: "string",
            x509_cert_path: "string",
            x509_key_path: "string"
         },
         bucket_credentials: {
            {bucketname...}: {
               password: "string",
               username: "string",
               x509_cert_path: "string",
               x509_key_path: "string"
            }
         },
         database_credentials: {
            {databasename...}: {
               password: "string",
               username: "string",
               x509_cert_path: "string",
               x509_key_path: "string"
            }
         },
         heap_profile_collection_threshold: NaN,
         heap_profile_disable_collection: false,
         logging: {
            console: {
               collation_buffer_size: 10,
               color_enabled: false,
               enabled: false,
               file_output: "string",
               log_keys: [],
               log_level: "info",
               rotation: {
                  localtime: false,
                  max_age: 0,
                  max_size: 100,
                  rotated_logs_size_limit: 1024,
                  rotation_interval: "0"
               }
            },
            debug: {
               collation_buffer_size: 1000,
               enabled: false,
               rotation: {
                  localtime: false,
                  max_age: 2,
                  max_size: 100,
                  rotated_logs_size_limit: 1024,
                  rotation_interval: "0"
               }
            },
            error: {
               collation_buffer_size: 0,
               enabled: true,
               rotation: {
                  localtime: false,
                  max_age: 360,
                  max_size: 100,
                  rotated_logs_size_limit: 1024,
                  rotation_interval: "0"
               }
            },
            info: {
               collation_buffer_size: 0,
               enabled: true,
               rotation: {
                  localtime: false,
                  max_age: 6,
                  max_size: 100,
                  rotated_logs_size_limit: 1024,
                  rotation_interval: "0"
               }
            },
            log_file_path: "string",
            redaction_level: "partial",
            stats: {
               collation_buffer_size: 0,
               enabled: true,
               rotation: {
                  localtime: false,
                  max_age: 6,
                  max_size: 100,
                  rotated_logs_size_limit: 1024,
                  rotation_interval: "0"
               }
            },
            trace: {
               collation_buffer_size: 1000,
               enabled: false,
               rotation: {
                  localtime: false,
                  max_age: 2,
                  max_size: 100,
                  rotated_logs_size_limit: 1024,
                  rotation_interval: "0"
               }
            },
            warn: {
               collation_buffer_size: 0,
               enabled: true,
               rotation: {
                  localtime: false,
                  max_age: 180,
                  max_size: 100,
                  rotated_logs_size_limit: 1024,
                  rotation_interval: "0"
               }
            }
         },
         max_file_descriptors: 5000,
         replicator: {
            blip_compression: 0,
            max_concurrent_changes_batches: 2,
            max_concurrent_replications: 0,
            max_concurrent_revs: 5,
            max_heartbeat: "string"
         },
         unsupported: {
            allow_dbconfig_env_vars: true,
            http2: {
               enabled: false
            },
            serverless: {
               enabled: true,
               min_config_fetch_interval: "1s"
            },
            stats_log_frequency: "1m",
            use_stdlib_json: false,
            use_xattr_config: false
         }
      }
      

      api

      Type

      object (readOnly)

      Description

      Configuration settings for modifying how the REST API is interacted with.

      api.admin_interface

      Type

      string

      Description

      Network interface to bind admin API to.

      By default, this will only be accessible to the localhost.

      api.admin_interface_authentication

      Type

      boolean

      Description

      Whether the admin API requires authentication

      api.compress_responses

      Type

      boolean

      Description

      If false, disables compression of HTTP responses

      api.cors.headers

      Type

      array

      Description

      List of allowed headers

      api.cors.login_origin

      Type

      array

      Description

      List of allowed login origins

      api.cors.max_age

      Type

      integer

      Description

      Maximum age of the CORS Options request

      api.cors.origin

      Type

      array

      Description

      List of allowed origins, use ['*'] to allow access from everywhere

      api.enable_advanced_auth_dp

      Type

      boolean

      Description

      Whether to enable the DP permissions check feature of admin auth.

      Defaults to true if using enterprise-edition or false if using community-edition.

      api.hide_product_version

      Type

      boolean

      Description

      Whether product versions removed from Server headers and REST API responses

      api.https.tls_cert_path

      Type

      string

      Description

      The TLS cert file to use for the REST APIs

      api.https.tls_key_path

      Type

      string

      Description

      The TLS key file to use for the REST APIs

      api.https.tls_minimum_version

      Type

      string

      Description

      The minimum allowable TLS version for the REST APIs

      api.idle_timeout

      Type

      string

      Description

      The maximum amount of time to wait for the next request when keep-alives are enabled.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      api.max_connections

      Type

      number

      Description

      Max of incoming HTTP connections to accept

      api.metrics_interface

      Type

      string

      Description

      Network interface to bind metrics API to.

      By default, this will only be accessible to the localhost.

      api.metrics_interface_authentication

      Type

      boolean

      Description

      Whether the metrics API requires authentication

      api.profile_interface

      Type

      string

      Description

      Network interface to bind profiling API to

      api.public_interface

      Type

      string

      Description

      Network interface to bind public API to

      api.read_header_timeout

      Type

      string

      Description

      The amount of time allowed to read request headers.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      api.server_read_timeout

      Type

      string

      Description

      Maximum duration before timing out read of the HTTP(S) request.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      api.server_write_timeout

      Type

      string

      Description

      Maximum duration before timing out write of the HTTP(S) response.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      auth.bcrypt_cost

      Type

      integer

      Description

      Cost to use for bcrypt password hashes

      bootstrap

      Type

      object (readOnly)

      Description

      Configuration settings for interacting with Couchbase Server.

      bootstrap.ca_cert_path

      Type

      string

      Description

      Root CA cert path for TLS connection

      bootstrap.config_update_frequency

      Type

      string

      Description

      How often to poll Couchbase Server for new config changes.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      bootstrap.group_id

      Type

      string

      Description

      The config group ID to use when discovering databases. Allows for non-homogenous configuration.

      bootstrap.password

      Type

      string

      Description

      Password for authenticating to server

      bootstrap.server

      Type

      string

      Description

      Couchbase Server connection string/URL.

      bootstrap.server_tls_skip_verify

      Type

      boolean

      Description

      Allow empty server CA Cert Path without attempting to use system root pool

      bootstrap.use_tls_server

      Type

      boolean

      Description

      Enforces a secure or non-secure server scheme

      bootstrap.username

      Type

      string

      Description

      Username for authenticating to server.

      bootstrap.x509_cert_path

      Type

      string

      Description

      Cert path (public key) for X.509 bucket auth

      bootstrap.x509_key_path

      Type

      string

      Description

      Key path (private key) for X.509 bucket auth

      bucket_credentials

      Type

      object (readOnly)

      Description

      A map of bucket names to credentials, that can be used instead of the bootstrap ones.

      bucket_credentials.{bucketname…​}

      Type

      object

      Description

      The configuration for the credentials set.

      bucket_credentials.{bucketname…​}.password

      Type

      string

      Description

      Password for authenticating to the bucket. This value is always redacted.

      bucket_credentials.{bucketname…​}.username

      Type

      string

      Description

      Username for authenticating to the bucket

      bucket_credentials.{bucketname…​}.x509_cert_path

      Type

      string

      Description

      Cert path (public key) for X.509 bucket auth

      bucket_credentials.{bucketname…​}.x509_key_path

      Type

      string

      Description

      Key path (private key) for X.509 bucket auth

      database_credentials

      Type

      object (readOnly)

      Description

      A map of database name to credentials, that can be used instead of the bootstrap ones.

      database_credentials.{databasename…​}

      Type

      object

      Description

      The configuration for the credentials set.

      database_credentials.{databasename…​}.password

      Type

      string

      Description

      Password for authenticating to the bucket. This value is always redacted.

      database_credentials.{databasename…​}.username

      Type

      string

      Description

      Username for authenticating to the bucket

      database_credentials.{databasename…​}.x509_cert_path

      Type

      string

      Description

      Cert path (public key) for X.509 bucket auth

      database_credentials.{databasename…​}.x509_key_path

      Type

      string

      Description

      Key path (private key) for X.509 bucket auth

      heap_profile_collection_threshold

      Type

      integer (readOnly)

      Description

      Threshold in bytes for automatic collection of heap profiles. If not specified, defaults to 85% of the lesser of cgroup or system memory.

      heap_profile_disable_collection

      Type

      boolean (readOnly)

      Description

      Disables automatic heap profile collection.

      logging

      Type

      object

      Description

      The configuration settings for modifying Sync Gateway logging.

      logging.console.collation_buffer_size

      Type

      integer (readOnly)

      Description

      The size of the log collation buffer. The default is 10 if the output is stderr, or 1000 if to a file.

      logging.console.color_enabled

      Type

      boolean (readOnly)

      Description

      Log with color for the console output

      logging.console.enabled

      Type

      boolean (readOnly)

      Description

      Toggle for this log output

      logging.console.file_output

      Type

      string (readOnly)

      Description

      Override the default stderr output, and write to the file specified instead

      logging.console.log_keys

      Type

      array

      Description

      Log Keys for the console output

      logging.console.log_level

      Type

      string

      Description

      Log Level for the console output

      logging.console.rotation.localtime

      Type

      boolean

      Description

      If true, it uses the computer's local time to format the backup timestamp.

      logging.console.rotation.max_age

      Type

      integer

      Description

      The maximum number of days to retain old log files. By default, there is no rotation, max_age=0.

      logging.console.rotation.max_size

      Type

      integer

      Description

      The maximum size in MB of the log file before it gets rotated.

      logging.console.rotation.rotated_logs_size_limit

      Type

      integer

      Description

      Max Size (in mb) of log files before deletion

      logging.console.rotation.rotation_interval

      Type

      string

      Description

      If set, the interval at which log files are rotated, even if max_size is not reached.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      logging.debug

      Type

      object

      Description

      Debug logging configuration.

      logging.debug.collation_buffer_size

      Type

      integer (readOnly)

      Description

      The size of the log collation buffer

      logging.debug.enabled

      Type

      boolean

      Description

      Toggle for this log output

      logging.debug.rotation.localtime

      Type

      boolean

      Description

      If true, it uses the computer's local time to format the backup timestamp.

      logging.debug.rotation.max_age

      Type

      integer

      Description

      The maximum number of days to retain old log files.

      logging.debug.rotation.max_size

      Type

      integer

      Description

      The maximum size in MB of the log file before it gets rotated.

      logging.debug.rotation.rotated_logs_size_limit

      Type

      integer

      Description

      Max Size (in mb) of log files before deletion

      logging.debug.rotation.rotation_interval

      Type

      string

      Description

      If set, the interval at which log files are rotated, even if max_size is not reached.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      logging.error

      Type

      object

      Description

      Error logging configuration.

      logging.error.collation_buffer_size

      Type

      integer (readOnly)

      Description

      The size of the log collation buffer.

      logging.error.enabled

      Type

      boolean

      Description

      Toggle for this log output

      logging.error.rotation.localtime

      Type

      boolean

      Description

      If true, it uses the computer's local time to format the backup timestamp.

      logging.error.rotation.max_age

      Type

      integer

      Description

      The maximum number of days to retain old log files.

      logging.error.rotation.max_size

      Type

      integer

      Description

      The maximum size in MB of the log file before it gets rotated.

      logging.error.rotation.rotated_logs_size_limit

      Type

      integer

      Description

      Max Size (in mb) of log files before deletion

      logging.error.rotation.rotation_interval

      Type

      string

      Description

      If set, the interval at which log files are rotated, even if max_size is not reached.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      logging.info

      Type

      object

      Description

      Info logging configuration.

      logging.info.collation_buffer_size

      Type

      integer (readOnly)

      Description

      The size of the log collation buffer

      logging.info.enabled

      Type

      boolean

      Description

      Toggle for this log output

      logging.info.rotation.localtime

      Type

      boolean

      Description

      If true, it uses the computer's local time to format the backup timestamp.

      logging.info.rotation.max_age

      Type

      integer

      Description

      The maximum number of days to retain old log files.

      logging.info.rotation.max_size

      Type

      integer

      Description

      The maximum size in MB of the log file before it gets rotated.

      logging.info.rotation.rotated_logs_size_limit

      Type

      integer

      Description

      Max Size (in mb) of log files before deletion

      logging.info.rotation.rotation_interval

      Type

      string

      Description

      If set, the interval at which log files are rotated, even if max_size is not reached.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      logging.log_file_path

      Type

      string (readOnly)

      Description

      Absolute or relative path on the filesystem to the log file directory. A relative path is from the directory that contains the Sync Gateway executable file.

      logging.redaction_level

      Type

      string (readOnly)

      Description

      Redaction level to apply to log output.

      logging.stats

      Type

      object

      Description

      Trace logging configuration.

      logging.stats.collation_buffer_size

      Type

      integer (readOnly)

      Description

      The size of the log collation buffer

      logging.stats.enabled

      Type

      boolean

      Description

      Toggle for this log output

      logging.stats.rotation.localtime

      Type

      boolean

      Description

      If true, it uses the computer's local time to format the backup timestamp.

      logging.stats.rotation.max_age

      Type

      integer

      Description

      The maximum number of days to retain old log files.

      logging.stats.rotation.max_size

      Type

      integer

      Description

      The maximum size in MB of the log file before it gets rotated.

      logging.stats.rotation.rotated_logs_size_limit

      Type

      integer

      Description

      Max Size (in mb) of log files before deletion

      logging.stats.rotation.rotation_interval

      Type

      string

      Description

      If set, the interval at which log files are rotated, even if max_size is not reached.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      logging.trace

      Type

      object

      Description

      Trace logging configuration.

      logging.trace.collation_buffer_size

      Type

      integer (readOnly)

      Description

      The size of the log collation buffer

      logging.trace.enabled

      Type

      boolean

      Description

      Toggle for this log output

      logging.trace.rotation.localtime

      Type

      boolean

      Description

      If true, it uses the computer's local time to format the backup timestamp.

      logging.trace.rotation.max_age

      Type

      integer

      Description

      The maximum number of days to retain old log files.

      logging.trace.rotation.max_size

      Type

      integer

      Description

      The maximum size in MB of the log file before it gets rotated.

      logging.trace.rotation.rotated_logs_size_limit

      Type

      integer

      Description

      Max Size (in mb) of log files before deletion

      logging.trace.rotation.rotation_interval

      Type

      string

      Description

      If set, the interval at which log files are rotated, even if max_size is not reached.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      logging.warn

      Type

      object

      Description

      Warning logging configuration.

      logging.warn.collation_buffer_size

      Type

      integer (readOnly)

      Description

      The size of the log collation buffer

      logging.warn.enabled

      Type

      boolean

      Description

      Toggle for this log output

      logging.warn.rotation.localtime

      Type

      boolean

      Description

      If true, it uses the computer's local time to format the backup timestamp.

      logging.warn.rotation.max_age

      Type

      integer

      Description

      The maximum number of days to retain old log files.

      logging.warn.rotation.max_size

      Type

      integer

      Description

      The maximum size in MB of the log file before it gets rotated.

      logging.warn.rotation.rotated_logs_size_limit

      Type

      integer

      Description

      Max Size (in mb) of log files before deletion

      logging.warn.rotation.rotation_interval

      Type

      string

      Description

      If set, the interval at which log files are rotated, even if max_size is not reached.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      max_file_descriptors

      Type

      number (readOnly)

      Description

      Max of open file descriptors (RLIMIT_NOFILE)

      replicator.blip_compression

      Type

      integer

      Description

      BLIP data compression level (0-9)

      replicator.max_concurrent_changes_batches

      Type

      integer

      Description

      Maximum number of changes batches to process concurrently per replication (1-5)"

      replicator.max_concurrent_replications

      Type

      integer

      Description

      Maximum number of concurrent replication connections allowed. If set to 0 this limit will be ignored.

      replicator.max_concurrent_revs

      Type

      integer

      Description

      Maximum number of revs to process concurrently per replication (5-200)

      replicator.max_heartbeat

      Type

      string

      Description

      Max heartbeat value for _changes request.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      unsupported

      Type

      object (readOnly)

      Description

      Settings that are not officially supported. It is highly recommended these are not used.

      unsupported.allow_dbconfig_env_vars

      Type

      boolean

      Description

      Can be set to false to skip environment variable expansion in database configs

      unsupported.http2.enabled

      Type

      boolean

      Description

      Whether HTTP2 support is enabled

      unsupported.serverless

      Type

      object

      Description

      Configuration for when SG is running in serverless mode

      unsupported.serverless.enabled

      Type

      boolean (readOnly)

      Description

      Run SG in to serverless mode

      unsupported.serverless.min_config_fetch_interval

      Type

      string

      Description

      How long database configs should be kept for in Sync Gateway before refreshing. Set to 0 to fetch configs everytime. This is used for requested databases that SG does not know about.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      unsupported.stats_log_frequency

      Type

      string

      Description

      How often should stats be written to stats logs.

      This is a duration and therefore can be provided with units "h", "m", "s", "ms", "us", and "ns". For example, 5 hours, 20 minutes, and 30 seconds would be 5h20m30s.

      unsupported.use_stdlib_json

      Type

      boolean

      Description

      Bypass the jsoniter package and use Go's stdlib instead

      unsupported.use_xattr_config

      Type

      boolean

      Description

      Store database configurations in system xattrs