A newer version of this documentation is available.

Bootstrap Configuration

March 23, 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.

 {
  bootstrap: {
    group_id: "string",
    config_update_frequency: "string",
    server: "string",
    username: "string",
    password: "string",
    ca_cert_path: "string",
    server_tls_skip_verify: false,
    x509_cert_path: "string",
    x509_key_path: "string",
    use_tls_server: false,
    kv_tls_port: 0,
    max_concurrent_query_ops: 0
  },
  api: {
    admin_interface: "string",
    admin_interface_authentication: false,
    metrics_interface: "string",
    metrics_interface_authentication: false,
    profile_interface: "string",
    public_interface: "string",
    compress_responses: false,
    cors: {
      headers: [
        "string"
      ],
      login_origin: [
        "string"
      ],
      max_age: 0,
      origin: [
        "string"
      ]
    },
    hide_product_version: false,
    https: {
      tls_minimum_version: "string",
      tls_cert_path: "string",
      tls_key_path: "string"
    },
    idle_timeout: 0,
    max_connections: 0,
    pretty: false,
    read_header_timeout: 0,
    server_read_timeout: 0,
    server_write_timeout: 0
  },
  logging: {
    log_file_path: "string",
    redaction_level: "string",
    console: {
      enabled: false,
      rotation: {
        max_size: 0,
        max_age: 0,
        localtime: false,
        rotated_logs_size_limit: 0
      },
      collation_buffer_size: 0,
      log_level: "string",
      log_keys: [
        "string"
      ],
      color_enabled: false,
      file_output: "string"
    },
    error: {
      enabled: false,
      rotation: {
        max_size: 0,
        max_age: 0,
        localtime: false,
        rotated_logs_size_limit: 0
      },
      collation_buffer_size: 0
    },
    warn: {
      enabled: false,
      rotation: {
        max_size: 0,
        max_age: 0,
        localtime: false,
        rotated_logs_size_limit: 0
      },
      collation_buffer_size: 0
    },
    info: {
      enabled: false,
      rotation: {
        max_size: 0,
        max_age: 0,
        localtime: false,
        rotated_logs_size_limit: 0
      },
      collation_buffer_size: 0
    },
    debug: {
      enabled: false,
      rotation: {
        max_size: 0,
        max_age: 0,
        localtime: false,
        rotated_logs_size_limit: 0
      },
      collation_buffer_size: 0
    },
    trace: {
      enabled: false,
      rotation: {
        max_size: 0,
        max_age: 0,
        localtime: false,
        rotated_logs_size_limit: 0
      },
      collation_buffer_size: 0
    },
    stats: {
      enabled: false,
      rotation: {
        max_size: 0,
        max_age: 0,
        localtime: false,
        rotated_logs_size_limit: 0
      },
      collation_buffer_size: 0
    }
  },
  auth: {
    bcrypt_cost: 0
  },
  unsupported: {
    stats_log_freq: "string",
    http2.enabled: false,
    use_stdlib_json: false
  },
  max_file_descriptors: 0
}

`bootstrap`

object

Define fundamental bootstrap related configuration properties

`bootstrap.group_id`

string

(Default: default)

The ID of the configuration group to which this node belongs.

`bootstrap.config_update_frequency`

string

(Default: 10s)

Sets the interval between checks for new or updated configurations made by other nodes in Couchbase Server

It is provided as string, which uses Go's duration format (e.g: 1s = 1 second, 5m = 5 minutes , 1h32m15s = 1 hour, 32 mins, 15 seconds) see: https://pkg.go.dev/time#ParseDuration

`bootstrap.server`

string

(Default: none)

Sets the endpoint for the Couchbase Server holding (database) configuration details.

The value of the server property specifies the Hostname(s) to the Couchbase Server node(s) in the cluster.

Sync Gateway supports the ability to specify multiple hosts in the configuration. Sync Gateway supports both the couchbase:// and http:// schemes for specifying connection endpoints.

Sync Gateway also supports SSL in the connection to Couchbase Server; use the couchbases:// scheme for this. As with the Couchbase Server SDKs, the https:// scheme is not supported.

Examples of valid server values for IPv4 include:

couchbase://host1
couchbases://host1
couchbase://host1,host2
couchbase://host1:11210,host2,
couchbases://host1:11207,host2
http://host1:8091
http://host1,host2:8091
http://foo:bar@host1:8091

Examples of valid server values for IPv6 include:

http://[2001:db8::8811]:8091 // single node IPv6 - http scheme with default server port
couchbases://[2001:db8::8811] // single node SSL IPv6 - default port (omitted)
couchbase://[2001:db8::8811],[2001:db8::8822]:888 // node1 default port, node2 port 888

As with the SDK, when using the couchbase:// or couchbases:// schemes, the port is not required, but if specified should be the external/internal bucket ports (defaults are 11210 or 11207 respectively). Attempting to use the admin ports (8091/18091) will result in a startup error.

Alternate Addresses

On startup, Sync Gateway will try each hostname that is provided until it is able to connect successfully.

By default, if a remote cluster has an external address set, then when SG connects it will apply a heuristic to determine whether to choose between external or default (internal) addresses.

The choice is based on the host names supplied in the connection string.

SG uses external networking only when none of the supplied host names match any of Couchbase Server's internal node addresses, and an external address is defined.
In all other cases Sync Gateway uses the default (internal) networking.

However, it is possible to override this behavior by adding a network parameter to the connection string.

The network parameter can be --

auto - this is the default value if no parameter is provided. In this case the heuristic described above is applied to determine the address used; so effectively there is no override.
external - to always force use of the external address
default - to always force use of the internal address

For example: "server": "couchbases://my-cbs-server?network=default"

Will force the connection to ignore any alternative external addresses configured on the Couchbase Server node.

Lost Connections

If the connection to Couchbase Server is lost during normal operations, Sync Gateway will automatically re-connect to another node in the cluster. During that re-connection period, the Sync Gateway will appear offline - see Taking Databases Offline - and documents will not be replicated to mobile clients.

`bootstrap.username`

string

(Default: none)

The username to be used when authenticating to the server.

`bootstrap.password`

string

(Default: none)

The password to be used when authenticating to the server.

`bootstrap.ca_cert_path`

string

Absolute or relative path on the filesystem to the root CA certificate to verify the certificate chain and hostname of the Couchbase Server cluster.

Works in conjunction with server_tls_skip_verify to control whether system root pool is used or not. Set this empty and server_tls_skip_verify true to avoid using system root pool

`bootstrap.server_tls_skip_verify`

boolean

Defaults to false, which requires a valid CA Cert Path. Works in conjunction with ca_cert_path to control whether system root pool is used or not. Set this true and ca_cert_path empty to allow, for example, self-signed or un-trusted certificates. This will be the default of-of-the-box setting.

`bootstrap.x509_cert_path`

string

Use x509_cert_path to define the absolute or relative path on the filesystem to the x509 certificate.

Relative paths are relative to the directory containing the Sync Gateway executable.

`bootstrap.x509_key_path`

string

Absolute or relative path on the filesystem to the X509 key.

Relative paths are relative to the directory containing the Sync Gateway executable.

`bootstrap.use_tls_server`

boolean

(Default: )

Default to true, which forces the connection to Couchbase Server to use TLS.

Use use_tls_server to enforce use of a secure scheme (for example, couchbases://) to connect to Couchbase Server.

Set this false to use a non-secure scheme (for example with couchbase://).

If the scheme used does not match that indicated by the use_tls_server value (for example, couchbases:// with use_tls_server = false) then Sync Gateway will error and refuse to start.

`bootstrap.kv_tls_port`

integer

(Default: 11207)

Optional value for the Memcached TLS port, if not using the default (11207)

`bootstrap.max_concurrent_query_ops`

integer

(Default: 1000)

Sets the maximum number of concurrent query operations allowed

`api`

object

Define API related configuration properties

`api.admin_interface`

string

(Default: 127.0.0.1:4985)

Port or TCP network address (IP address and the port) that the Admin REST API listens on.

The loopback address prefix before the port (127.0.0.1) means the interface will not be reachable from other hosts. To make it reachable, change it to ":4985".

Change requires restart of Admin API

`api.admin_interface_authentication`

boolean

(Default: )

Use the admin_interface_authentication property to disable authentication for the metrics API. This option should be used with discretion and only in test environments.

By default the Admin API requires Couchbase Server RBAC authentication. The user must provide credentials to an existing user with an appropriate Sync Gateway role.

`api.metrics_interface`

string

(Default: 127.0.0.1:4986)

This defines the Port or TCP network address (IP address and the port) that the Metrics REST API will listen on.

Using the loopback address prefix before the port (127.0.0.1) means the interface will not be reachable from other hosts.

For example "metricsInterface": "127.0.0.1:4986"

`api.metrics_interface_authentication`

boolean

(Default: )

Use the metrics_interface_authentication property to disable authentication for the metrics API. This option should be used with discretion and only in test environments.

By default the Metrics API requires Couchbase Server RBAC authentication. The user must provide credentials to an existing user with an appropriate Sync Gateway role.

`api.profile_interface`

string

TCP network address (IP address and the port) that the Go profile API listens on. You can obtain Go profiling information from the interface. You can omit the IP address.

`api.public_interface`

string

(Default: :4984)

Public REST API port

Change requires restart of Public API

`api.compress_responses`

boolean

(Default: )

Whether to compress HTTP responses. Set to false to disable compression of HTTP responses.

`api.cors`

object

Configuration object for allowing cross-origin resource sharing (CORS). This is useful to interact directly with Sync Gateway from HTML 5 applications via XHR.

Change requires HTTP server restart

`api.cors.headers`

array

List of HTTP headers that can be used by domains specified in the origin and login_origin properties.

A common value is ["Content-Type"] as clients use the Content-Type: application/json header when sending data as JSON in the body of POST/PUT requests.

Change requires HTTP server restart

`api.cors.login_origin`

array

List of allowed login origins.

Change requires HTTP server restart

`api.cors.max_age`

integer

Value for the Access-Control-Max-Age header. This is the period of time, in seconds, that the response to a CORS preflight request is cached before sending another preflight request.

Change requires HTTP server restart

`api.cors.origin`

array

List of allowed origins; use a wildcard character (*) to allow access from everywhere.

Note that the wildcard (*) cannot be used if you plan to authenticate users as well (by using the withCredentials flag on the client side). Instead specify the explicit domain(s) in the origin and login_origin properties of the configuration file.

Change requires HTTP server restart

`api.hide_product_version`

boolean

Determines whether product versions are removed from Server headers and REST API responses. This setting does not apply to the Admin REST API.

This customization of the Sync Gateway response avoids revealing the version of the Sync Gateway to HTTP requests to the root path.

`api.https`

object

Group in which to specify any API HTTPS configuration properties

`api.https.tls_minimum_version`

string

(Default: tlsv1.2)

Enforce a minimum TLS version to be used in replications with Couchbase Lite.

Possible values are:

"tlsv1"
"tlsv1.1"
"tlsv1.2"
"tlsv1.3"

Change requires HTTP server restart

`api.https.tls_cert_path`

string

Absolute or relative path on the filesystem to the TLS certificate file, if TLS is used to secure Sync Gateway connections

To use plaintext, omit both this property and the tls_key_path property.

A relative path is from the directory that contains the Sync Gateway executable file.

Change requires HTTP server restart

`api.https.tls_key_path`

string

Absolute or relative path on the filesystem to the TLS private key files.

To use plaintext, omit both this property and the tls_cert_path property.

A relative path is from the directory that contains the Sync Gateway executable file.

Change requires HTTP server restart

`api.idle_timeout`

integer

(Default: 90)

Maximum duration (in seconds) to wait for the next request when keep-alives are enabled

Change requires HTTP server restart

`api.max_connections`

integer

Maximum number of incoming HTTP connections to accept.

Change requires HTTP server restart

`api.pretty`

boolean

(Deprecated) Whether to pretty-print JSON responses.

`api.read_header_timeout`

integer

(Default: 5)

Maximum duration (in seconds) allowed to read request headers

Change requires HTTP server restart

`api.server_read_timeout`

integer

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

This property only effects the HTTP connections on the Sync Gateway public and admin ports.

Sync Gateway is written in the Go programming language, therefore the value set in the configuration file is passed to Go's server instance https://golang.org/pkg/net/http/#Server.

Change requires HTTP server restart

`api.server_write_timeout`

integer

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

This property only effects the HTTP connections on the Sync Gateway public and admin ports.

Sync Gateway is written in the Go programming language, therefore the value set in the configuration file is passed to Go's server instance https://golang.org/pkg/net/http/#Server.

Change requires HTTP server restart

`logging`

object

Holding object for all logging-related settings.

Note that in addition to setting these logging values in the bootstrap configuration file, you can also use the ADMIN Rest API to set or change the values without requiring a full reload. See: Rest Admin API

A full logging initialization is required.

See the Logging page for a fuller explanation on logging settings.

`logging.log_file_path`

string

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

Changes require full logging re-initialization

`logging.redaction_level`

string

(Default: none)

Optionally, log files can be redacted. This means that user-data, considered to be private, is removed. Such data includes:

Key/value pairs in JSON documents
Usernames
Query-fields that reference key/value pairs and/or usernames
Names and email addresses retrieved during product registration
Extended attributes

This redaction of user-data is referred to as partial redaction.

To enable it, set this property to "redaction_level" : "partial" in the configuration file:

`logging.console`

object

Settings for the console output logging.

`logging.console.enabled`

boolean

Indicates whether console logging is enabled

`logging.console.rotation`

object

The log file may be rotated by defining a "rotation" sub document. See details in log rotation.

`logging.console.rotation.max_size`

integer

(Default: 100)

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

`logging.console.rotation.max_age`

integer

The maximum number of days to retain old log files. This can't be set below the minimum allowed value for the given level.

`logging.console.rotation.localtime`

boolean

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

`logging.console.rotation.rotated_logs_size_limit`

integer

(Default: 1024)

Controls how much disk space the rotated (and compressed) log files for this level can take up.

The value is expressed in megabytes. The minimum value is 10 and there is no maximum value.

`logging.console.collation_buffer_size`

integer

Size of the collation buffer

`logging.console.log_level`

string

(Default: info)

The level of logging.

Log levels are cumulative (that is, log entries at WARN will also be included in the INFO and DEBUG logs).

See: Log Levels page

`logging.console.log_keys`

array

(Default: ["HTTP"])

List of log keys to enable for diagnostic logging.

Available log key values are described in the Log Keys page

`logging.console.color_enabled`

boolean

Use ANSI color codes in the console output (Linux/MacOS only).

`logging.console.file_output`

string

Changes require full logging re-initialization

`logging.error`

object

Activate the error logging level - see Logging page for more on log levels.

`logging.error.enabled`

boolean

Enable this error log level.

The error, warn and info log levels are enabled by default.
The debug log level is disabled by default.

Note: You are advised to keep this log level enabled to troubleshoot issues.

Enabling this log level is a requirement to receive Enterprise Support.

`logging.error.rotation`

object

The log file may be rotated by defining a "rotation" sub document.

See details in log rotation.

`logging.error.rotation.max_size`

integer

(Default: 100)

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

`logging.error.rotation.max_age`

integer

The maximum number of days to retain old log files. This can't be set below the minimum allowed value for the given level.

`logging.error.rotation.localtime`

boolean

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

`logging.error.rotation.rotated_logs_size_limit`

integer

(Default: 1024)

Controls how much disk space the rotated (and compressed) log files for this level can take up.

The value is expressed in megabytes. The minimum value is 10 and there is no maximum value.

`logging.error.collation_buffer_size`

integer

Size of the collation buffer

`logging.warn`

object

The warning logging-level is triggered when Sync Gateway detects something is wrong but it can still service requests

Minimum max_age is 90 days
Log File Name is sg_warn.log

`logging.warn.enabled`

boolean

Whether to enable this log level. The error, warn and info log levels are enabled by default. The debug log level is disabled by default.

Note, however, that you are advised to keep this log level enabled to troubleshoot issues. Enabling this log level is a requirement to receive Enterprise Support.

`logging.warn.rotation`

object

The log file may be rotated by defining a "rotation" sub document. See details in log rotation.

`logging.warn.rotation.max_size`

integer

(Default: 100)

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

`logging.warn.rotation.max_age`

integer

The maximum number of days to retain old log files. This can't be set below the minimum allowed value for the given level.

`logging.warn.rotation.localtime`

boolean

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

`logging.warn.rotation.rotated_logs_size_limit`

integer

(Default: 1024)

Controls how much disk space the rotated (and compressed) log files for this level can take up.

The value is expressed in megabytes. The minimum value is 10 and there is no maximum value.

`logging.warn.collation_buffer_size`

integer

Size of the collation buffer

`logging.info`

object

The information logging-level provides important diagnostics for support and customers

`logging.info.enabled`

boolean

(Default: )

Whether to enable this log level.

`logging.info.rotation`

object

The log file may be rotated by defining a "rotation" sub document

`logging.info.rotation.max_size`

integer

(Default: 100)

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

`logging.info.rotation.max_age`

integer

The maximum number of days to retain old log files. This can't be set below the minimum allowed value for the given level.

`logging.info.rotation.localtime`

boolean

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

`logging.info.rotation.rotated_logs_size_limit`

integer

(Default: 1024)

Controls how much disk space the rotated (and compressed) log files for this level can take up.

The value is expressed in megabytes. The minimum value is 10 and there is no maximum value.

`logging.info.collation_buffer_size`

integer

Size of the collation buffer

`logging.debug`

object

The debug logging-level provides lower level development analysis

Minimum maxage is 1 day Log File Name is sg_debug.log

`logging.debug.enabled`

boolean

Sets this logging-level on or off.

Note, you are advised to keep this log level enabled when troubleshooting issues. Enabling this log level is a requirement to receive Enterprise Support.

`logging.debug.rotation`

object

The log file may be rotated by defining a "rotation" sub document. See details in log rotation.

`logging.debug.rotation.max_size`

integer

(Default: 100)

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

`logging.debug.rotation.max_age`

integer

The maximum number of days to retain old log files. This can't be set below the minimum allowed value for the given level.

`logging.debug.rotation.localtime`

boolean

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

`logging.debug.rotation.rotated_logs_size_limit`

integer

(Default: 1024)

Controls how much disk space the rotated (and compressed) log files for this level can take up.

The value is expressed in megabytes. The minimum value is 10 and there is no maximum value.

`logging.debug.collation_buffer_size`

integer

Size of the collation buffer

`logging.trace`

object

The trace logging-level.

`logging.trace.enabled`

boolean

Whether to enable this log level.

`logging.trace.rotation`

object

The log file may be rotated by defining a "rotation" sub document. See details in log rotation.

`logging.trace.rotation.max_size`

integer

(Default: 100)

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

Controls how much disk space the rotated (and compressed) log files for this level can take up.

The value is expressed in megabytes. The minimum value is 10 and there is no maximum value.

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

Controls how much disk space the rotated (and compressed) log files for this level can take up.

The value is expressed in megabytes. The minimum value is 10 and there is no maximum value.

Cost to use for bcrypt password hashes

`unsupported`

object

Collection of unsupported properties

`unsupported.stats_log_freq`

string

(Default: 1m)

It is provided as string, which uses Go's duration format (e.g: 1s = 1 second, 5m = 5 minutes , 1h32m15s = 1 hour, 32 mins, 15 seconds) see: https://pkg.go.dev/time#ParseDuration

Maximum number of open file descriptors.

API Topics

Reference

Community

Mobile Forum | Blog | Blog (Mobile) | Tutorials

Bootstrap Configuration

Introduction

Bootstrap Configuration Schema

Related Content