Bootstrap Configuration
Reference data on the contents of Sync Gateway’s bootstrap configuration, which determines its run time behavior.
Related topics: Overview | Bootstrap | Database | Database Security | Access Control | Import | Inter-Sync Gateway Replication
|
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
For reliable operation, all the nodes listed in the bootstrap.server connection string must be data (KV) nodes.
|
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",
node_heartbeat_expiry: "60s",
password: "string",
server: "string",
server_tls_skip_verify: false,
use_system_metadata_collection: 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: 0,
heap_profile_disable_collection: false,
logging: {
audit: {
audit_log_file_path: "string",
enabled: false,
enabled_events: [0...],
rotation: {
localtime: false,
max_age: 6,
max_size: 100,
rotated_logs_size_limit: 1024,
rotation_interval: ""
}
},
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: ""
}
},
debug: {
collation_buffer_size: 1000,
enabled: false,
rotation: {
localtime: false,
max_age: 2,
max_size: 100,
rotated_logs_size_limit: 1024,
rotation_interval: ""
}
},
error: {
collation_buffer_size: 0,
enabled: true,
rotation: {
localtime: false,
max_age: 360,
max_size: 100,
rotated_logs_size_limit: 1024,
rotation_interval: ""
}
},
info: {
collation_buffer_size: 0,
enabled: true,
rotation: {
localtime: false,
max_age: 6,
max_size: 100,
rotated_logs_size_limit: 1024,
rotation_interval: ""
}
},
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: ""
}
},
trace: {
collation_buffer_size: 1000,
enabled: false,
rotation: {
localtime: false,
max_age: 2,
max_size: 100,
rotated_logs_size_limit: 1024,
rotation_interval: ""
}
},
warn: {
collation_buffer_size: 0,
enabled: true,
rotation: {
localtime: false,
max_age: 180,
max_size: 100,
rotated_logs_size_limit: 1024,
rotation_interval: ""
}
}
},
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,
diagnostic_interface: "",
http2: {
enabled: false
},
serverless: {
enabled: true,
min_config_fetch_interval: "1s"
},
stats_log_frequency: "1m",
use_gocb_fast_fail_retry: false,
use_stdlib_json: false,
use_xattr_config: false
}
}
api
Type: object (readOnly)
Configuration settings for modifying how the REST API is interacted with.
api.admin_interface
Type: string (Default 127.0.0.1:4985)
Network interface to bind admin API to.
By default, this will only be accessible to the localhost.
api.admin_interface_authentication
Type: boolean (Default true)
Whether the admin API requires authentication
api.compress_responses
Type: boolean (Default true)
If false, disables compression of HTTP responses
api.cors.headers
Type: array
List of allowed headers. These headers will be added the Access-Control-Allow-Headers response to a valid CORS request.
A recommended minimum set of values should be ["Accept-Encoding", "Authorization", "Content-Type", "If-Match"].
api.cors.login_origin
Type: array
List of allowed origins to apply to public /{db}/_session API.
To use cors on /{db}/_session, the domain must be present in both login_origin and origin.
If configured, Authorization must be included in headers.
api.cors.max_age
Type: integer (Default 0)
Value for Access-Control-Maximum-Age. Uses 0 by default.
api.cors.origin
Type: array
List of allowed origins for the public API. The request Origin header is checked against these values. If successful the Origin header is returned in the HTTP response header as Access-Control-Allow-Origin.
api.enable_advanced_auth_dp
Type: boolean
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
Whether product versions removed from Server headers and REST API responses
api.https.tls_cert_path
Type: string
The TLS cert file to use for the REST APIs
api.https.tls_key_path
Type: string
The TLS key file to use for the REST APIs
api.https.tls_minimum_version
Type: string (Default tlsv1.2)
The minimum allowable TLS version for the REST APIs
api.idle_timeout
Type: string (Default 90s)
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 (Default 0)
Max of incoming HTTP connections to accept
api.metrics_interface
Type: string (Default 127.0.0.1:4986)
Network interface to bind metrics API to.
By default, this will only be accessible to the localhost.
api.metrics_interface_authentication
Type: boolean (Default true)
Whether the metrics API requires authentication
api.profile_interface
Type: string
Network interface to bind profiling API to
api.public_interface
Type: string (Default :4984)
Network interface to bind public API to
api.read_header_timeout
Type: string (Default 5s)
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
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
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 (Default 10)
Cost to use for bcrypt password hashes
bootstrap
Type: object (readOnly)
Configuration settings for interacting with Couchbase Server.
bootstrap.ca_cert_path
Type: string
Root CA cert path for TLS connection
bootstrap.config_update_frequency
Type: string (Default 10s)
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 (Default default)
The config group ID to use when discovering databases. Allows for non-homogenous configuration.
bootstrap.node_heartbeat_expiry
Type: string (Default 60s)
How long since a node's last heartbeat before its cluster compat registry entry is pruned. Minimum is 2x the configured config_update_frequency.
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.password
Type: string
Password for authenticating to server
bootstrap.server
Type: string
Couchbase Server connection string/URL for bootstrap configuration. The connection string should only reference Couchbase Server Data (KV) nodes. Using other node types (Query, Index, Analytics, or Search nodes) is not supported. Connection String Format Sync Gateway supports the ability to resolve DNS SRV records for alternate hostnames, or specifying multiple hostnames explicitly. See the Couchbase Go SDK documentation on DNS SRV records for more details. Sync Gateway supports both the couchbases:// for TLS and couchbase:// schemes for insecure connection. The supported schemes match that of the Couchbase Server SDKs. Examples of valid server values:
couchbases://nodeA.example.comcouchbase://nodeA.example.comcouchbases://nodeA.example.com,nodeB.example.comcouchbase://nodeA.example.com,nodeB.example.comcouchbases://nodeA.example.com:1234,nodeB.example.com:1234couchbase://nodeA.example.com:1234,nodeB.example.com:1234couchbases://127.0.0.1couchbase://127.0.0.1On startup, Sync Gateway will try all hostnames until it is able to connect successfully. Port Information When using the couchbase:// or couchbases:// schemes, the port is not required as Sync Gateway will use the default Couchbase Server client-to-node ports (11210 for couchbase:// and 11207 for couchbases://). See the Couchbase Server ports documentation for more details. Alternate Addresses If your Couchbase Server cluster is running in a containerized, port mapped, or otherwise NATd environment like Docker or Kubernetes, Sync Gateway might need more information to connect to the cluster. In many cases the client is able to automatically select the correct set of addresses. If the detection heuristic fails in your environment, it is possible to override this behavior by adding a network parameter to the connection string. The network parameter can be:external: Force the use alternate addresses of Couchbase Server. Used when Sync Gateway should not share network used by Couchbase Server internally.default: Do not allow use of alternate addresses of Couchbase Server. Used when Sync Gateway and Couchbase Server are on the same network. 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.
bootstrap.server_tls_skip_verify
Type: boolean
Allow empty server CA Cert Path without attempting to use system root pool
bootstrap.use_system_metadata_collection
Type: boolean
If true, Sync Gateway uses the _system._mobile metadata collection and triggers a one-time migration of any metadata in the default collection.
bootstrap.use_tls_server
Type: boolean (Default true)
Enforces a secure or non-secure server scheme
bootstrap.username
Type: string
Username for authenticating to server.
bootstrap.x509_cert_path
Type: string
Cert path (public key) for X.509 bucket auth
bootstrap.x509_key_path
Type: string
Key path (private key) for X.509 bucket auth
bucket_credentials
Type: object (readOnly)
A map of bucket names to credentials, that can be used instead of the bootstrap ones.
bucket_credentials.{bucketname…}
Type: object
The configuration for the credentials set.
bucket_credentials.{bucketname…}.password
Type: string
Password for authenticating to the bucket. This value is always redacted.
bucket_credentials.{bucketname…}.username
Type: string
Username for authenticating to the bucket
bucket_credentials.{bucketname…}.x509_cert_path
Type: string
Cert path (public key) for X.509 bucket auth
bucket_credentials.{bucketname…}.x509_key_path
Type: string
Key path (private key) for X.509 bucket auth
database_credentials
Type: object (readOnly)
A map of database name to credentials, that can be used instead of the bootstrap ones.
database_credentials.{databasename…}
Type: object
The configuration for the credentials set.
database_credentials.{databasename…}.password
Type: string
Password for authenticating to the bucket. This value is always redacted.
database_credentials.{databasename…}.username
Type: string
Username for authenticating to the bucket
database_credentials.{databasename…}.x509_cert_path
Type: string
Cert path (public key) for X.509 bucket auth
database_credentials.{databasename…}.x509_key_path
Type: string
Key path (private key) for X.509 bucket auth
heap_profile_collection_threshold
Type: integer (readOnly)
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)
Disables automatic heap profile collection.
logging
Type: object
The configuration settings for modifying Sync Gateway logging.
logging.audit.audit_log_file_path
Type: string (readOnly)
The path to write audit log files to
logging.audit.enabled
Type: boolean
Toggle for this log output
logging.audit.enabled_events
Type: array (readOnly)
List of enabled global audit events.
logging.audit.rotation.localtime
Type: boolean
If true, it uses the computer's local time to format the backup timestamp.
logging.audit.rotation.max_age
Type: integer (Default 6)
The maximum number of days to retain old log files.
logging.audit.rotation.max_size
Type: integer (Default 100)
The maximum size in MB of the log file before it gets rotated.
logging.audit.rotation.rotated_logs_size_limit
Type: integer (Default 1024)
Max Size (in mb) of log files before deletion
logging.audit.rotation.rotation_interval
Type: string
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.console.collation_buffer_size
Type: integer (readOnly) (Default 10)
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)
Log with color for the console output
logging.console.enabled
Type: boolean (readOnly)
Toggle for this log output
logging.console.file_output
Type: string (readOnly)
Override the default stderr output, and write to the file specified instead
logging.console.log_keys
Type: array
Log Keys for the console output
logging.console.log_level
Type: string (Default info)
Log Level for the console output
logging.console.rotation.localtime
Type: boolean
If true, it uses the computer's local time to format the backup timestamp.
logging.console.rotation.max_age
Type: integer (Default 0)
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 (Default 100)
The maximum size in MB of the log file before it gets rotated.
logging.console.rotation.rotated_logs_size_limit
Type: integer (Default 1024)
Max Size (in mb) of log files before deletion
logging.console.rotation.rotation_interval
Type: string
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
Debug logging configuration.
logging.debug.collation_buffer_size
Type: integer (readOnly) (Default 1000)
The size of the log collation buffer
logging.debug.enabled
Type: boolean
Toggle for this log output
logging.debug.rotation.localtime
Type: boolean
If true, it uses the computer's local time to format the backup timestamp.
logging.debug.rotation.max_age
Type: integer (Default 2)
The maximum number of days to retain old log files.
logging.debug.rotation.max_size
Type: integer (Default 100)
The maximum size in MB of the log file before it gets rotated.
logging.debug.rotation.rotated_logs_size_limit
Type: integer (Default 1024)
Max Size (in mb) of log files before deletion
logging.debug.rotation.rotation_interval
Type: string
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
Error logging configuration.
logging.error.collation_buffer_size
Type: integer (readOnly) (Default 0)
The size of the log collation buffer.
logging.error.enabled
Type: boolean (Default true)
Toggle for this log output
logging.error.rotation.localtime
Type: boolean
If true, it uses the computer's local time to format the backup timestamp.
logging.error.rotation.max_age
Type: integer (Default 360)
The maximum number of days to retain old log files.
logging.error.rotation.max_size
Type: integer (Default 100)
The maximum size in MB of the log file before it gets rotated.
logging.error.rotation.rotated_logs_size_limit
Type: integer (Default 1024)
Max Size (in mb) of log files before deletion
logging.error.rotation.rotation_interval
Type: string
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
Info logging configuration.
logging.info.collation_buffer_size
Type: integer (readOnly) (Default 0)
The size of the log collation buffer
logging.info.enabled
Type: boolean (Default true)
Toggle for this log output
logging.info.rotation.localtime
Type: boolean
If true, it uses the computer's local time to format the backup timestamp.
logging.info.rotation.max_age
Type: integer (Default 6)
The maximum number of days to retain old log files.
logging.info.rotation.max_size
Type: integer (Default 100)
The maximum size in MB of the log file before it gets rotated.
logging.info.rotation.rotated_logs_size_limit
Type: integer (Default 1024)
Max Size (in mb) of log files before deletion
logging.info.rotation.rotation_interval
Type: string
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)
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) (Default partial)
Redaction level to apply to log output.
logging.stats
Type: object
Trace logging configuration.
logging.stats.collation_buffer_size
Type: integer (readOnly) (Default 0)
The size of the log collation buffer
logging.stats.enabled
Type: boolean (Default true)
Toggle for this log output
logging.stats.rotation.localtime
Type: boolean
If true, it uses the computer's local time to format the backup timestamp.
logging.stats.rotation.max_age
Type: integer (Default 6)
The maximum number of days to retain old log files.
logging.stats.rotation.max_size
Type: integer (Default 100)
The maximum size in MB of the log file before it gets rotated.
logging.stats.rotation.rotated_logs_size_limit
Type: integer (Default 1024)
Max Size (in mb) of log files before deletion
logging.stats.rotation.rotation_interval
Type: string
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
Trace logging configuration.
logging.trace.collation_buffer_size
Type: integer (readOnly) (Default 1000)
The size of the log collation buffer
logging.trace.enabled
Type: boolean
Toggle for this log output
logging.trace.rotation.localtime
Type: boolean
If true, it uses the computer's local time to format the backup timestamp.
logging.trace.rotation.max_age
Type: integer (Default 2)
The maximum number of days to retain old log files.
logging.trace.rotation.max_size
Type: integer (Default 100)
The maximum size in MB of the log file before it gets rotated.
logging.trace.rotation.rotated_logs_size_limit
Type: integer (Default 1024)
Max Size (in mb) of log files before deletion
logging.trace.rotation.rotation_interval
Type: string
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
Warning logging configuration.
logging.warn.collation_buffer_size
Type: integer (readOnly) (Default 0)
The size of the log collation buffer
logging.warn.enabled
Type: boolean (Default true)
Toggle for this log output
logging.warn.rotation.localtime
Type: boolean
If true, it uses the computer's local time to format the backup timestamp.
logging.warn.rotation.max_age
Type: integer (Default 180)
The maximum number of days to retain old log files.
logging.warn.rotation.max_size
Type: integer (Default 100)
The maximum size in MB of the log file before it gets rotated.
logging.warn.rotation.rotated_logs_size_limit
Type: integer (Default 1024)
Max Size (in mb) of log files before deletion
logging.warn.rotation.rotation_interval
Type: string
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) (Default 5000)
Max of open file descriptors (RLIMIT_NOFILE)
replicator.blip_compression
Type: integer
BLIP data compression level (0-9)
replicator.max_concurrent_changes_batches
Type: integer (Default 2)
Maximum number of changes batches to process concurrently per replication (1-5)"
replicator.max_concurrent_replications
Type: integer
Maximum number of concurrent replication connections allowed. If set to 0 this limit will be ignored.
replicator.max_concurrent_revs
Type: integer (Default 5)
Maximum number of revs to process concurrently per replication (5-200)
replicator.max_heartbeat
Type: string
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)
Settings that are not officially supported. It is highly recommended these are not used.
unsupported.allow_dbconfig_env_vars
Type: boolean (Default true)
Can be set to false to skip environment variable expansion in database configs
unsupported.diagnostic_interface
Type: string
Network interface to bind diagnotic API to.
By default, this API will not be run unless this string is specified.
unsupported.http2.enabled
Type: boolean
Whether HTTP2 support is enabled
unsupported.serverless
Type: object
Configuration for when SG is running in serverless mode
unsupported.serverless.enabled
Type: boolean (readOnly)
Run SG in to serverless mode
unsupported.serverless.min_config_fetch_interval
Type: string (Default 1s)
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 (Default 1m)
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_gocb_fast_fail_retry
Type: boolean
When true, errors on initial connection to Couchbase Server will fail instantaneously. Enabling this will surface authentication errors quickly, but can cause some Sync Gateway operations to shut down databases with intermittent Couchbase Server connection errors.
unsupported.use_stdlib_json
Type: boolean
Bypass the jsoniter package and use Go's stdlib instead
unsupported.use_xattr_config
Type: boolean
Store database configurations in system xattrs