A newer version of this documentation is available.

Bootstrap Configuration

March 16, 2025

+ 12

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:

bashrc
Copy
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: ["string"...],
         login_origin: ["string"...],
         max_age: 0,
         origin: ["string"...]
      },
      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: ["string"...],
         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

API Topics

Reference

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials

Bootstrap Configuration

Introduction

Bootstrap Configuration Schema

api

api.admin_interface

api.admin_interface_authentication

api.compress_responses

api.cors.headers

api.cors.login_origin

api.cors.max_age

api.cors.origin

api.enable_advanced_auth_dp

api.hide_product_version

api.https.tls_cert_path

api.https.tls_key_path

api.https.tls_minimum_version

api.idle_timeout

api.max_connections

api.metrics_interface

api.metrics_interface_authentication

api.profile_interface

api.public_interface

api.read_header_timeout

api.server_read_timeout

api.server_write_timeout

auth.bcrypt_cost

bootstrap

bootstrap.ca_cert_path

bootstrap.config_update_frequency

bootstrap.group_id

bootstrap.password

bootstrap.server

bootstrap.server_tls_skip_verify

bootstrap.use_tls_server

bootstrap.username

bootstrap.x509_cert_path

bootstrap.x509_key_path

bucket_credentials

bucket_credentials.{bucketname…​}

bucket_credentials.{bucketname…​}.password

bucket_credentials.{bucketname…​}.username

bucket_credentials.{bucketname…​}.x509_cert_path

bucket_credentials.{bucketname…​}.x509_key_path

database_credentials

database_credentials.{databasename…​}

database_credentials.{databasename…​}.password

database_credentials.{databasename…​}.username

database_credentials.{databasename…​}.x509_cert_path

database_credentials.{databasename…​}.x509_key_path

heap_profile_collection_threshold

heap_profile_disable_collection

logging

logging.console.collation_buffer_size

logging.console.color_enabled

logging.console.enabled

logging.console.file_output

logging.console.log_keys

logging.console.log_level

logging.console.rotation.localtime

logging.console.rotation.max_age

logging.console.rotation.max_size

logging.console.rotation.rotated_logs_size_limit

logging.console.rotation.rotation_interval

logging.debug

logging.debug.collation_buffer_size

logging.debug.enabled

logging.debug.rotation.localtime

logging.debug.rotation.max_age

logging.debug.rotation.max_size

logging.debug.rotation.rotated_logs_size_limit

logging.debug.rotation.rotation_interval

logging.error

logging.error.collation_buffer_size

logging.error.enabled

logging.error.rotation.localtime

logging.error.rotation.max_age

logging.error.rotation.max_size

logging.error.rotation.rotated_logs_size_limit

logging.error.rotation.rotation_interval

logging.info