Configuration File

adminInterface

string

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".

adminUI

string

(Deprecated) URL of the Sync Gateway Admin Console HTML page.

metricsInterface

string

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"

compressResponses

boolean

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

configServer

string

(Deprecated) URL of a Couchbase database-configuration server (for dynamic database discovery). A database-configuration server allows Sync Gateway to load a database configuration dynamically from a remote endpoint. If a database configuration server is defined, when Sync Gateway gets a request for a database that it doesn't know about, then Sync Gateway will attempt to retrieve the database configuration properties from the URL ConfigServer/DBname, where DBname is the database name.

CORS

object

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

CORS.Origin

array

List of allowed origins; use an asterisk () to allow access from everywhere. Note that the asterisk () cannot be used if you plan to authenticate users as well (by using the withCredentials flag on the client side). In this case, the explicit domain(s) must be specified in the Origin and LoginOrigin properties of the configuration file.

CORS.LoginOrigin

array

List of allowed login origins.

CORS.Headers

array

List of HTTP headers that can be used by domains specified in the Origin and LoginOrigin 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.

CORS.MaxAge

integer

Value for the Access-Control-Max-Age header. This is the the number of seconds that the response to a CORS preflight request can be cached before sending another preflight request.

couchbaseKeepaliveInterval

integer

TCP keep-alive interval in seconds between Sync Gateway and Couchbase Server.

databases

object

Database settings.

databases.this_db

object

The database name is stored as a key.

databases.this_db.allow_conflicts

boolean

Introduced in Sync Gateway 2.0, this property can be used to disable Sync Gateway's handling of conflicts.

Setting to false will cause Sync Gateway to reject any attempt to write conflicting revisions (returning a 409 HTTP status code). It will be up to the client to resolve the conflict. Restarting Sync Gateway with this property enabled will not automatically result in disk space savings (compaction on a document won't occur until a document is updated).

Constraints:

• Push replications to pre-2.8 targets do not support the "allow_conflicts": false setting; the target must use "allow_conflicts": true.

databases.this_db.allow_empty_password

boolean

Whether Sync Gateway users can be created with empty passwords.

databases.this_db.bucket

string

Bucket name on Couchbase Server. The value walrus is deprecated.

The default is the database name.

databases.this_db.bucket_op_timeout_ms

integer

The bucket_op_timeout_ms value defines the period (in milliseconds) that Sync Gateway should wait for a bucket operation to complete before timing-out and trying again.

You can increase the period when there is a heavy load on Couchbase Server and operations are likely to take more than 2.5 seconds to complete.

The default value is 2500 milliseconds.

databases.this_db.compact_interval_days

number

The compact_interval_days value defines the interval (in days) between scheduled compaction runs. It is a decimal number -- float32

• A Zero value means do not run compaction
• Minimum non-zero value -- 0.04 (approximately 1 hour)
• Maximum value -- 60 days
• Default -- 1 day

databases.this_db.delta_sync

object

NOTE: Delta Sync is an Enterprise Edition feature on Sync Gateway and Couchbase Lite.

Delta Sync is the ability to replicate only parts of the Couchbase mobile document that have changed. This can result in significant savings in bandwidth consumption as well as throughput improvements, especially when network bandwidth is typically constrained.

Delta Sync incurs additional bucket storage requirements which can be tuned with the rev_max_age_seconds property.

Delta Sync does not apply to attachment contents.

Delta Sync is disabled by default on the Sync Gateway. You can enable it through the enabled property.

If delta sync is enabled on Sync Gateway, then Couchbase Lite clients will switch to using delta sync automatically. Similarly, if delta sync is disabled on Sync Gateway, clients will switch to normal mode.

Note: Push replications do not use Delta Sync when pushing to a pre-2.8 target.

The following configuration example enables delta sync.

{
  "logging": {
    "console": {
      "log_keys": ["*"]
    }
  },
  "databases": {
    "db": {
      "server": "http://localhost:8091",
      "bucket": "default",
      "users": { "GUEST": { "disabled": false, "admin_channels": ["*"] } },
      "allow_conflicts": false,
      "revs_limit": 20,
      "delta_sync": {
        "enabled": true,
        "rev_max_age_seconds": 86400
      }
    }
  }
}

Footnotes:

• Delta Sync is automatically enabled for peer-to-peer sync between Couchbase Lite clients.
• Delta sync is disabled for Couchbase Lite database replicas.

databases.this_db.delta_sync.enabled

boolean

Set this property to "true" to enable delta sync.

databases.this_db.delta_sync.rev_max_age_seconds

integer

On a write operation, the revision body is backed up in the bucket and retained for rev_max_age_seconds to calculate future revision deltas. As a result, new deltas can only be generated for read requests that come in within the rev_max_age_seconds time window. The storage of backed up revision bodies for delta sync incurs additional bucket storage requirements.

The additional storage can be calculated with the following formula: (doc_size * updates_per_day * 86400) / rev_max_age_seconds.

For example, with rev_max_age_seconds's default value, an average document size of 4 KB and 100 writes/day, enabling delta sync would take up an additional 400 KB of storage on Couchbase Server ((4 * 100 * 86400)/86400).

Setting this value to 0 will generate deltas opportunistically on pull replications, with no additional storage requirements.

databases.this_db.import_docs

boolean

Introduced in Sync Gateway 1.5, this property specifies whether this Sync Gateway node should perform import processing.

This property works in conjunction with the enable_shared_bucket_access property.

Starting in Sync Gateway 2.7, all Sync Gateway nodes can be configured as import nodes. This results in performance benefits as the import process is shared across all Sync Gateway nodes.

Prior to version 2.7, import_docs can only be set to true on a single node.

Workload Isolation

Starting in version 2.7, if enable_shared_bucket_access is set to true and import_docs is set to false, the node will not be participating in the import process.

This configuration is specifically recommended for workload isolation: to isolate import nodes from the client-facing nodes. Workload isolation is preferable in deployments with a large write throughput.

Prior to Release 2.1 a value of 'continuous' was also allowed. This was deprecated at Release 2.1 and replaced with the boolean value True. There is no change to the behavior or functionality (that is, a value of 'continuous' was interpreted as True and had the same effect).

databases.this_db.import_partitions

integer

Allows users to tune the number of partitions used for import processing. Partitions are distributed among all Sync Gateway nodes participating in import processing (import_docs:true), and each process a subset of the server's vbuckets.

Each partition is processed by a separate goroutine, so import_partitions can be used to tune concurrency based on the number of Sync Gateway nodes, and the number of cores per node.

databases.this_db.cacertpath

string

Relative or absolute path to the root CA certificate to verify the certificate chain and hostname of the Couchbase Server cluster.

This property is optional for X.509 authentication. If it isn't provided, Sync Gateway will accept any certificate provided by Couchbase Server.

databases.this_db.cache

object

Database cache configuration.

databases.this_db.cache.max_wait_pending

integer

(Deprecated) Moved to channel_cache.max_wait_pending. Maximum wait time in milliseconds for a pending sequence before skipping sequences.

databases.this_db.cache.max_num_pending

integer

(Deprecated) Moved to channel_cache.max_num_pending. Maximum number of pending sequences before skipping the sequence.

databases.this_db.cache.max_wait_skipped

integer

(Deprecated) Moved to channel_cache.max_wait_skipped. Maximum wait time in milliseconds for a skipped sequence before abandoning the sequence.

databases.this_db.cache.enable_star_channel

boolean

(Deprecated) Moved to channel_cache.enable_star_channel. Enable the star (*) channel.

databases.this_db.cache.channel_cache_max_length

integer

(Deprecated) Moved to channel_cache.max_length. Maximum number of entries maintained in cache per channel.

databases.this_db.cache.channel_cache_min_length

integer

(Deprecated) Moved to channel_cache.min_length. Minimum number of entries maintained in cache per channel.

databases.this_db.cache.channel_cache_expiry

integer

(Deprecated) Moved to channel_cache.expiry_seconds. Time (seconds) to keep entries in cache beyond the minimum retained.

databases.this_db.cache.channel_cache

object

Channel cache configuration

databases.this_db.cache.channel_cache.compact_high_watermark_pct

integer

High watermark for channel cache eviction (percent).

When the cache size, determined by max_number, reaches the high watermark, the eviction process iterates through the cache to remove inactive channels.

databases.this_db.cache.channel_cache.compact_low_watermark_pct

integer

Low watermark for channel cache eviction (percent).

When the cache size, determined by max_number returns to a value lower than compact_low_watermark_pct, the cache eviction process is stopped.

databases.this_db.cache.channel_cache.max_number

integer

Tuning this property is an Enterprise Edition feature. The Community Edition is configured with the default value, and will ignore any value in the configuration file.

Maximum number of channel caches which will exist at any one point. This property is used to determine the cache size (and the associated eviction watermarks compact_low_watermark_pct/compact_high_watermark_pct).

The default value for this property is 50000. Along with the default channel min_length and max_length values, this would result in a memory usage under 1GB.

The max_number value can be tuned to optimize for cache hits (requests that are handled using the cache), as opposed to cache misses (requests that require a round-trip to Couchbase Server to fetch data). The cache hit/miss ratio can be obtained with the following:

cache hit/miss ratio = cache.chan_cache_hits / cache.chan_cache_misses

Increasing the max_number value can increase the cache hit/miss ratio, resulting in better cache utilization.

If the cache size grows to reach the high watermark (compact_high_watermark_pct), channels with no connected replications will be evicted before channels which are associated with an active pull replication (i.e a blip-based pull replication in Couchbase Lite 2.x, or an active /{db}/_changes request in Couchbase Lite 1.x).

The minimum allowed value is 100.

It isn't possible to remove the limit altogether, users who wish to remove the limit would need to set max_number to an arbitrarily high value.

databases.this_db.cache.channel_cache.max_wait_pending

integer

Maximum wait time in milliseconds for a pending sequence before skipping sequences.

databases.this_db.cache.channel_cache.max_num_pending

integer

Maximum number of pending sequences before skipping the sequence.

databases.this_db.cache.channel_cache.max_wait_skipped

integer

Maximum wait time in milliseconds for a skipped sequence before abandoning the sequence.

databases.this_db.cache.channel_cache.enable_star_channel

boolean

Enable the all documents (*) channel -- sometimes referred to as the 'star' channel.

databases.this_db.cache.channel_cache.max_length

integer

Maximum number of entries maintained in cache per channel.

databases.this_db.cache.channel_cache.min_length

integer

Minimum number of entries maintained in cache per channel.

databases.this_db.cache.channel_cache.expiry_seconds

integer

Time (seconds) to keep entries in cache beyond the minimum retained.

databases.this_db.cache.channel_cache.query_limit

integer

Limit used for channel queries

databases.this_db.cache.rev_cache

object

Revision cache configuration

databases.this_db.cache.rev_cache.size

integer

Size of the revision cache, specified as the total number of document revisions to cache in memory for all recently accessed documents. When the revision cache is full, Sync Gateway removes less recent document revisions to make room for new document revisions. Adjust this property to tune memory consumption by Sync Gateway, for example on servers with less memory and in cases when Sync Gateway creates many new documents and/or updates many documents relative to the number of read operations.

Disabling the revision cache

Disabling the revision cache is an Enterprise Edition feature.

To disable the revision entirely, set this property to 0. Setting this property to 0 on the Community Edition is ignored.

Disabling the revision cache would be useful when there are very large documents or if you expect a very low cache hit rate. Otherwise it could negatively impact the latency of replications. It is generally not recommended to disable the revision cache, unless advised by Couchbase Enterprise Support.

databases.this_db.cache.rev_cache.shard_count

integer

Tuning this property is an Enterprise Edition feature. The Community Edition is configured with the default value, and will ignore any value in the configuration file.

Number of shards the rev cache should be split into. More shards allows for lower cache contention when accessing distinct revisions, at the cost of some memory overhead per-shard. This generally should not greatly exceed the number of CPU threads available to Sync Gateway.

It is generally not recommended to set this property, unless advised by Couchbase Enterprise Support.

databases.this_db.certpath

string

Relative or absolute path to the client's certificate to authenticate against Couchbase Server 5.5 or higher. The private key must be specified with the databases.$db.keypath property.

databases.this_db.enable_shared_bucket_access

boolean

Introduced in Sync Gateway 1.5, this property specifies whether to enable Mobile-Server Data Sync (a.k.a mobile convergence). You can learn more about this functionality in Syncing Mobile and Server

This property works in conjunction with the import_docs property, which determines whether a node participates in import processing.

Set enable_shared_bucket_access to true on all nodes participating in such a configuration.

On start-up, Sync Gateway will generate the mobile-specific metadata for all the pre-existing documents in the Couchbase Server bucket. From then on, documents can be inserted on the Server directly (with N1QL or SDKs) or through the Sync Gateway REST API.

Tombstones

When enable_shared_bucket_access is enabled, mobile tombstones are now also server tombstones. The document body is deleted, and only the mobile sync metadata required to replicate the tombstone is retained in the mobile extended attribute.

The server's metadata purge interval becomes an important consideration for mobile deployments under convergence. When the server purges a tombstone (based on the metadata purge interval), that tombstone will no longer be replicated to mobile clients.

Users should set the server's metadata purge interval based on their expected client replication frequency, to ensure that clients are notified of the tombstone prior to that tombstone being purged.

NOTE: The default Metadata Purge Interval is set to 3 days which can potentially result in tombstones being purged before all clients have had a chance to get notified of it.

Ways to tune the Metadata Purge Interval on Couchbase Server:

• Bucket settings on UI
• Bucket endpoint on the REST API

Implementation notes for XATTRs:

Mobile applications require additional metadata in order to manage security and replication. In previous versions of Sync Gateway, this information has always been stored in the document body. Sync Gateway 1.5 utilizes a new feature of Couchbase Server 5.0 called XATTRs (x-attributes) to store that metadata into an external document fragment.

Extended attributes (xattrs) are JSON objects that can be associated with Couchbase documents. Each document can be associated with zero or more extended attributes. There are currently three types (user, system, virtual). Mobile Convergence uses a system extended attribute, which has the following characteristics central to convergence:

• Shares lifetime with the document metadata - when a document is deleted, system xattrs are preserved with the tombstone.
• Allocated 1MB of storage, independent of the 20MB available for the document

Extended attributes are stored as part of the document, and are replicated with the document (both intra-cluster replication and XDCR).

Extended attributes can be accessed via the SDKs using the sub-document API, via command-line tools, and via views.

They are also accessible from N1QL in Couchbase Server 5.5 or above with the ().xattrs property. For example, SELECT meta().xattrs._sync from travel-sample where Meta().id = "user::demo";.

WARNING: The sync metadata is maintained internally by Sync Gateway and its structure can change at any time. It should not be used to drive business logic of applications. The direct use of the N1QL query is unsupported and must not be used in production environments. The raw endpoint (/db/_raw/{docid}) on Sync Gateway's Admin REST API returns both the document and it's associated mobile metadata.

databases.this_db.event_handlers

object

Webhooks in Sync Gateway are designed to minimize performance impacts on Sync Gateway's regular processing. Sync Gateway manages the number of processes that are spawned for webhook event handling, so that slow response times from the HTTP POST operations don't consume available CPU resources on Sync Gateway nodes. When a webhook event handler is defined, after Sync Gateway has updated a document, Sync Gateway adds a document_changed event to an asynchronous event-processing queue (the event queue). New processes are then spawned to apply the filter function to the documents and to perform the HTTP POST operations. When an event is not added to the event queue, but is instead discarded, a warning message is written to the the Sync Gateway log. You can configure Sync Gateway to log information about event handling, by including either the log key Event or Events+ in the Log property in your Sync Gateway configuration file. Events+ is more verbose.

databases.this_db.event_handlers.document_changed

array

The configuration for the action to perform when a document change is detected.

databases.this_db.event_handlers.document_changed.filter

string

A JavaScript function used to determine which documents to post. The filter function accepts the document body as input and returns a boolean value. If the filter function returns true, then Sync Gateway posts the document. If the filter function returns false, then Sync Gateway does not post the document. If no filter function is defined, then Sync Gateway posts all changed documents. Filtering only determines which documents to post. It does not extract specific content from documents and post only that.

databases.this_db.event_handlers.document_changed.handler

string

Type of the event handler. This must be "webhook" (only 1 possible value currently).

databases.this_db.event_handlers.document_changed.timeout

integer

Time in seconds to wait for a response to the POST operation. Using a timeout ensures that slow-running POST operations don't cause the webhook event queue to back up. Slow-running POST operations are discarded (if they time out), so that new events can be processed. When the timeout is reached, Sync Gateway stops listening for a response. A value of 0 (zero) means no timeout. The default value should work well in the majority of cases. You should not need to adjust it to tune performance.

databases.this_db.event_handlers.document_changed.url

string

URL to which to post documents (for a webhook event handler).

databases.this_db.event_handlers.max_processes

integer

Maximum number of events that can be processed concurrently, that is, no more than max_processes concurrent processes will be spawned for event handling. The default value should work well in the majority of cases. You should not need to adjust it to tune performance. However, if you wish to ensure that most webhook posts are sent, you can set it to sufficiently high value.

databases.this_db.event_handlers.wait_for_process

string

Maximum wait time in milliseconds before canceling event processing for an event that is detected when the event queue is full. If you set the value to 0 (zero), then incoming events are discarded immediately if the event queue is full. If you wish to avoid any blocking of standard Sync Gateway processing this may be a desirable value to use. The default value should work well in the majority of cases. You should not need to adjust it to tune performance.

databases.this_db.feed_type

string

(Deprecated) Feed type DCP or TAP.

databases.this_db.import_filter

string

JavaScript filter function to determine if a document written to the Couchbase Server bucket should be made available to Couchbase Mobile clients (i.e imported).

If an import filter function is provided it is expected to take the document body as parameter and to return a boolean indicating whether the document should be imported (true) or not. If no filter is provided (the default), then all documents are imported.

{
  "databases": {
    "db": {
      "server": "http://localhost:8091",
      "bucket": "default",
      "password": "password",
      "import_docs": true,
      "enable_shared_bucket_access": true,
      "import_filter": `
        function(doc) {
          if (doc.type != "mobile") {
            return false
          }
          return true
        }
        `,
    }
  }
}

databases.this_db.keypath

string

Relative or absolute path to the client's private key to authenticate against Couchbase Server 5.5 or higher. The client certificate must be specified with the databases.$db.certpath property.

databases.this_db.local_doc_expiry_secs

integer

Starting in Sync Gateway 2.0, it is possible to set an expiry value for local documents managed on Sync Gateway. This property defaults to 7776000 (90 days) if not specified. Local documents are used by the Couchbase Lite replicator to track up to which sequence number a given client has synchronized and where it should resume the next time it connects to Sync Gateway. Clients that don't replicate within the expiry window will be forced to restart their replication from the beginning (sequence zero). This property is being introduced to prevent the accumulation of obsolete replication checkpoint documents in the Couchbase Server bucket.

databases.this_db.num_index_replicas

integer

Determines the number of index replicas used when creating the core Sync Gateway indexes. This property is only applicable if databases.$db.use_views is set to false (default value).

databases.this_db.oidc

object

OIDC providers.

databases.this_db.oidc.default_provider

string

Provider to use for OIDC requests that don't specify a provider. If only one provider is specified in the providers map, it is used as the default provider. If multiple providers are defined and default_provider is not specified, requests to /db/_oidc must specify the provider parameter.

databases.this_db.oidc.providers

object

databases.this_db.oidc.providers.this_provider

object

databases.this_db.oidc.providers.this_provider.issuer

string

The OpenID Connect Provider issuer.

databases.this_db.oidc.providers.this_provider.client_id

string

The client ID defined in the provider for Sync Gateway.

databases.this_db.oidc.providers.this_provider.validation_key

string

Client secret associated with the client. Required for auth code flow.

databases.this_db.oidc.providers.this_provider.signing_method

string

Optional. Signing method used for validation key (provides additional security).

databases.this_db.oidc.providers.this_provider.callback_url

string

Optional. The callback URL to be invoked after the end-user obtains a client token. When not provided, Sync Gateway will generate it based on the incoming request.

databases.this_db.oidc.providers.this_provider.register

string

Optional. Whether Sync Gateway should automatically create users for successfully authenticated users that don't have an already existing user in Sync Gateway.

databases.this_db.oidc.providers.this_provider.disable_session

string

Optional. By default, Sync Gateway will create a new session for the user upon successful OIDC authentication, and set that session in the usual way on the _oidc_callback and _oidc_refresh responses. If disable_session is set to true, the session is not created (clients must use the ID token for subsequent authentications).

databases.this_db.oidc.providers.this_provider.scope

array

Optional. By default, Sync Gateway uses the scope "openid email" when calling the OP's authorize endpoint. If the scope property is defined in the config (as an array of string values), it will override this scope.

databases.this_db.oidc.providers.this_provider.include_access

string

Optional. When true, the oidccallback response will include the access_token, expires_at and token_type properties returned by the OP.

databases.this_db.oidc.providers.this_provider.user_prefix

string

Optional. Specifies the prefix for Sync Gateway usernames for the provider. When not specified, defaults to issuer.

databases.this_db.oidc.providers.this_provider.discovery_url

string

Optional. Discovery URL used to obtain the OpenID Connect provider configuration. If not specified, the default discovery endpoint of [issuer]/.well-known/openid-configuration will be used.

databases.this_db.oidc.providers.this_provider.disable_cfg_validation

boolean

Couchbase Sync Gateway, by default, applies strict validation of the OpenID Connect configuration based on the OIDC specification.

Set "disable_cfg_validation": true when you do not want strict validation of the OIDC configuration.

databases.this_db.oidc.providers.this_provider.disable_callback_state

boolean

DisableCallbackState determines whether or not to maintain state between the /_oidc and /_oidc_callback endpoints.

Disabling this action is NOT recommended as it will increase vulnerability to Cross-Site Request Forgery (CSRF, XSRF).

Set "disable_callback_state": true to switch-off callback state.

databases.this_db.oidc.providers.this_provider.username_claim

string

You can use `username_claim` to specify a claim other than subject to use as the Sync Gateway username.

The specified claim must be a string, as numeric claims may be un-marshalled inconsistently between Sync Gateway and the underlying OIDC library.

When authenticating incoming OIDC tokens, Sync Gateway currently treats the username as [userprefix][subject]. By default user_prefix is the issuer, but can be customized in the Sync Gateway provider config. Subject is always the sub claim in the token.

Behaviour:

• If username_claim is set but user_prefix is not set, use that claim as the Sync Gateway username.
• If username_claim is set and user_prefix is also set, use [userprefix][username_claim] as the Sync Gateway username.
• If username_claim is not set and user_prefix is set, use [userprefix][subject] as the Sync Gateway username (existing behavior).
• If neither username_claim nor userprefix are set, use [issuer][subject] as the Sync Gateway username (existing behavior).

databases.this_db.oidc.providers.this_provider.allow_unsigned_provider_tokens

boolean

Unsigned provider tokens are not accepted.

Set "allow_unsigned_provider_tokens": true to opt-in to accepting unsigned tokens from providers.

databases.this_db.offline

string

Whether the database if kept offline when Sync Gateway starts. Specifying the value true results in the database being kept offline. The default (if the property is omitted) is to bring the database online when Sync Gateway starts. For more information, see Taking databases offline and bringing them online.

databases.this_db.password

string

The RBAC user's password for authenticating to Couchbase Server. There is no default.

databases.this_db.pool

string

Couchbase pool name. The default is the string default.

databases.this_db.rev_cache_size

integer

(Deprecated) Moved to rev_cache.size. Size of the revision cache, specified as the total number of document revisions to cache in memory for all recently accessed documents. When the revision cache is full, Sync Gateway removes less recent document revisions to make room for new document revisions. Adjust this property to tune memory consumption by Sync Gateway, for example on servers with less memory and in cases when Sync Gateway creates many new documents and/or updates many documents relative to the number of read operations.

databases.this_db.revs_limit

integer

This property defines the maximum depth to which a document's revision tree can grow; its value governs the point at which to prune a document's revision tree.

The default and minimum values of revs_limit are dependent on whether allow_conflicts is set True or False -- see the Default and Minimum Values table below.

The process to remove obsolete revisions is called pruning and runs automatically every time a revision is added. Although fundamentally the same, the pruning algorithm works slightly differently between Sync Gateway and Couchbase Lite. On Sync Gateway, the pruning algorithm is applied to the shortest, non-tombstoned branch in the revision tree.

If there are conflicting revisions, the document may end up with disconnected branches after the pruning process. In the animation below, the document has a conflicting branch (revisions 4' - 1001'). When the shortest branch (in this case the conflicting branch) reaches the 1003rd update, it gets is cut off. The revision tree is not in a corrupted state and the logic that chooses the winning revision still applies. But it may make it impossible to do certain merges (n-way merge) to resolve conflicts and will occupy disk space that could have been freed if the conflict was resolved early on.

If the revision tree gets into this state then the only option to resolve the conflict is to pick a winning branch and tombstone all the non-winning conflicting branches.

NOTE: Setting the revs_limit to a value below 100 when allow_conflicts = true may adversely affect the conflict resolution process, as there may be insufficient revision history to resolve a given conflict.

Default and Minimum Values

For Releases 2.6+

allow_conflicts =|+ True |+ False :--- |+ :-------: |+ :-------: revs_limit default |+ 100 |+ 50 |+ revs_limit minimum |+ 20 |+ 1 |+

For Releases 2.0 - 2.5

allow_conflicts = |+ <-- True --> |+<-- False --> :--- |+ :-------: |+ :-------: revs_limit default |+ 100 |+ 1000 revs_limit minimum |+ 50 |+ 1

For Release 1.x

• revs_limit default = 1000
• revs_limit minimum = 20

See also:

• Sync Gateway purge endpoint /{db}/_purge.
• Sync Gateway document TTLs.

databases.this_db.roles

object

Initial roles.

databases.this_db.roles.this_role

object

The role name.

databases.this_db.roles.this_role.admin_channels

array

The list of channels this role is automatically granted access to when Sync Gateway starts.

If you use the all channels wildcard ("*") the role is granted access to all channels and to all documents within all channels. This will be inherited by any user assigned this role.

databases.this_db.send_www_authenticate_header

boolean

Whether to send WWW-Authenticate header in 401 responses.

databases.this_db.server

string

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.

The default value is an in-memory bucket called walrus that is only used during development and prototyping. Note that the walrus mode is being deprecated in Sync Gateway 2.5 and will be removed in a future release.

databases.this_db.session_cookie_name

string

Starting in Sync Gateway 2.0, it is possible to customize the session cookie name that is used for this database. This configuration property is primarly used for web applications interacting with multiple Sync Gateway databases. Browsers typically have two methods of determining which cookie to use for a given request: the URL path or cookie name. With this property, you can use different cookie names for each database specified in the configuration file. Let's consider the following configuration file:

{
   "interface":":4984",
   "log":["*"],
   "databases": {
      "db1": {
        "session_cookie_name": "CustomName1",
        "server": "http://localhost:8091",
        "bucket": "bucket-1",
        "users": {
            "user_1": {"password":"1234"}
        },
        "db2": {
          "session_cookie_name": "CustomName2",
          "server": "http://localhost:8091",
          "bucket": "bucket-2",
          "users": {
              "adam_2": {"password":"5678"}
          }
        }
      }
   }
}

With this configuration, the Set-Cookie response header of the POST :4984/{db}/_session endpoint (Public REST API) would then have the form "CustomName1=3cad4b95524179bf144fe0d92b8f09877bb86bf5;path=/db1/".

When using POST :4985/{db}/_session (Admin REST API) to create a session, the cookie value is returned in the response body instead of the Set-Cookie header. In this case, it could also be set by the client, for web applications it would be the following in JavaScript:

cookie1String = "CustomName1=3cad4b95524179bf144fe0d92b8f09877bb86bf5;path=/db1/";
document.cookie = cookie1String;

databases.this_db.sgreplicate_enabled

boolean

By default, this Sync Gateway node can be assigned sg-replicate replications for this database If set to false, this Sync Gateway node will not participate in sg-replicate distribution.

databases.this_db.sgreplicate_websocket_heartbeat_secs

integer

If set, this duration (in seconds) is used as a custom heartbeat interval for websocket ping frames

databases.this_db.serve_insecure_attachment_types

boolean

If an attachment has headers such as "text/html" where it would attempt to render in a browser Sync Gateway will force a download by sending content-disposition header. Setting this option to false will instead not set the content-disposition and allow a browser to render the attachment.

databases.this_db.session_cookie_secure

boolean

Override secure cookie flag (that is, disable secure cookies).

If SSLCert is set, then secure cookies are also used by default. However, this flag can be set false to override this behavior and allow insecure cookies to be used alongside SSL.

If SSLCert is not set then this flag defaults to false.

databases.this_db.session_cookie_http_only

boolean

This flag disallows cookies from being used by Javascript; by default javascript CAN use them

databases.this_db.sync

string

The sync function is a JavaScript function whose source code is stored in the Sync Gateway's database configuration file. Every time a new document, revision or deletion is added to a database, the sync function is called and given a chance to examine the document (see the Sync Function API guide).

If a document is in conflict there will be multiple current revisions. The default, the "winning" one is the one whose channel assignments and access grants take effect.

As with all embedded functions in this configuration file, the Sync Function must be enclosed in a pair of backticks.

If you don't supply a sync function, Sync Gateway uses the following default sync function:

`function (doc, oldDoc) {
   channel(doc.channels);
}`

In plain English: by default, a document will be assigned to the channels listed in its channels property (whose value must be a string or an array of strings.) More subtly, since there is no validation, any user can change any document. For this reason, the default sync function is really only useful for experimentation and development.

The channels property is an array of strings that contains the names of the channels to which the document belongs. If you do not include a channels property in a document, the document does not appear in any channels. Adding a channels property to each document is the easiest way to map documents to channels but if you need more advanced behavior such as read and write access, you'll probably need to write your own Sync Function.

databases.this_db.unsupported

object

databases.this_db.unsupported.oidc_tls_skip_verify

boolean

Unsupported option for use in development and testing environment ONLY

oidc_tls_skip_verify can be used to skip validation of TLS certs used for OpenID Connection testing.

NOTE: Due to the unsupported nature of this option, there is no guarantee on its continued availability.

databases.this_db.unsupported.sgr_tls_skip_verify

boolean

Unsupported option for use in development and testing environment ONLY

sgr_tls_skip_verify can be used to skip validation of TLS certs used for Inter-Sync Gateway Replication.

NOTE: Due to the unsupported nature of this option, there is no guarantee on its continued availability.

databases.this_db.username

string

The RBAC user's username for authenticating to Couchbase Server. There is no default.

databases.this_db.users

object

Initial user accounts.

databases.this_db.users.this_user

object

The user's name.

databases.this_db.users.this_user.password

string

The user's password.

databases.this_db.users.this_user.admin_channels

array

The list of channels this user is automatically granted access to when Sync Gateway starts.

If you use the all channels wildcard ("*") the user is granted access to all channels and to all documents within all channels -- see: all channels wildcard.

databases.this_db.users.this_user.admin_roles

array

The list of roles this user is automatically assigned to when Sync Gateway starts.

databases.this_db.users.this_user.disabled

boolean

Whether this user account is disabled.

databases.this_db.use_views

boolean

If set to true, Sync Gateway will use views instead of GSI for system functions like authentication and replication.

databases.this_db.view_query_timeout_secs

integer

The view query timeout in seconds. This property allows you to specify the time Sync Gateway should wait for a view query response from Couchbase Server before it times out. The timeout is used for both view and N1QL queries issued by Sync Gateway.

databases.this_db.replications

object

About

This replications property is where you configure all SG-Replicate 2.0 replications associated with this database. It comprises one or more named replication definitions.

Add a replication definition object for each replication to be associated with this database.

Options

Your replications can be one of two available types -- see replication types (not available in beta)

• Persistent -- the replication survives node restarts. These replications can also be launched dynamically using the Rest API _replication endpoint (see -- Admin Rest API)

• Ad-hoc -- the replication runs once and then the replication definition is removed when the replication is stopped. This includes when a one-shot replication completes, or a continuous replication is stopped via the _replicationStatus endpoint.

  Transient replications are initiated using the REST API's _replication endpoint. These replications are not guaranteed to run on the initiating node and will instead be distributed across available nodes.

Using

To configure SG-Replicate 1.0 replications -- see SG-Replicate 1.0 Replications.

For more on upgrading from SG-Replicate 1.0 -- see Moving to SG-Replicate 2..

Constraints

• Replications are defined in the context of a local database, with the replication pulling-to or pushing-from this database. This change means that you cannot to set-up replication between two remote databases, as -- by definition -- at least one database must be local.

• The following REST API only parameters are omitted from this configuration schema -- refer to Admin Rest API for details:

  • adhoc=true for transient replications
  • cancel=true to cancel a replication

databases.this_db.replications.this_rep

object

About

Use this replication definition object's name to specify this replication's replication_id.

Behavior

In use, this replication definition object will comprise all, or a subset, of its properties (defined below). It defines a single replication.

The database under which it is defined may be associated with more than one replication. You should add a replication definition object for each replication.

Give each a unique name, which will serve as the replication_id. This is the ID by which Sync Gateway recognizes and utilizes a replication.

Constraints

• For new replications -- if no replication_id is specified, Sync Gateway will assign a random UUID

• For _replicate REST API calls only -- If the 'cancel' property is true, this replication_id identifies which active replication task to cancel.

databases.this_db.replications.this_rep.adhoc

boolean

About

Use the Admin REST API's adhoc parameter to specify that a replication is ad hoc rather than persistent.

Behavior

Ad hoc replications behave the same as normal replications, but they are automatically removed when their status changes to stopped. This will usually be on completion, but may also be as a result of user action.

Constraints

This parameter is NOT available in configured replications; only those initialized using the Admin REST API.

databases.this_db.replications.this_rep.batch_size

integer

About

Use batch_size to specify the number of changes to be included in a single batch during replication.

Behavior

Increasing this value above the default may reduce processing time, whilst also consuming more memory resource.

databases.this_db.replications.this_rep.cancel

boolean

About

Use this parameter on,y when you want to want to cancel an existing active replication.

Constraints

• This parameter is NOT available in configured replications; only those initialized using the Admin REST API.

• NOTE that the body of the request must be the same as the replication's replication definition for the cancellation request to be honoured.

For example, if you requested continuous replication, the cancellation request must also contain the continuous field.

databases.this_db.replications.this_rep.conflict_resolution_type

string

About

Use conflict_resolution_type to specify how Sync Gateway should resolve conflicts. By default the automatic conflict resolution policy is applied.

Valid options

• default
• localWins
• remoteWins
• custom

For Example

  "conflict_resolution_type":"custom"

Behavior

The conflict_resolution_type defines the conflict resolution policy Sync Gateway applies to resolve conflicting revisions.

• default -- the automatic conflict resolution policy is applied, that is --

  • Deletes always win (the delete with longest revision history wins if both revisions are deletes)
  • The revision with the longest revision history wins (so, the one with most changes and consequently the highest revision Id).

• localWins -- Selecting localWins will result in local revisions always being the winner in any conflict.

• remoteWins -- Selecting remoteWins will result in remote revisions always being the winner in any conflict.

• custom -- Selecting custom specifies that you want to handle resolution with your own application logic. You must provide this logic as a Javascript function by specifying it using the a custom-conflict-resolver.

Constraints

• replications created prior to version 2.8 will default to default.

databases.this_db.replications.this_rep.continuous

boolean

About

Use continuous to specify whether this replication will run continuously, or be one-shot.

Behavior

• continuous=true-- In continuous mode, changes are immediately synced in accordance with the replication definition.
• continuous=false-- In one-shot mode, detected changes are synced in accordance with the replication definition. The replication ceases once all revisions are processed.

If omitted the replication defaults to one-shot mode.

Constraints

• Optional for stops and removes

databases.this_db.replications.this_rep.custom_conflict_resolver

string

About

Use custom_conflict_resolver to provide the Javascript function used to resolve conflicts if "conflict_resolution_type": "custom".

Valid Options

The property is mandatory when "conflict_resolution_type": "custom" and is ignored in all other cases.

Behavior

The optional custom_conflict_resolver property specifies the Javascript function that will be used to resolve conflicts. It is used only when custom is specified as theconflict_resolution_type.

Provide the required logic in a Javascript function, as a string within backticks (see also the description for the sync function).

The function takes one parameter struct representing the conflict and comprising

• the document id
• the local document
• the remote document

The function returns a document struct representing the winning revision.

Example

"custom_conflict_resolver":`
  function(conflict) {
    console.log("full remoteDoc doc: "+JSON.stringify(conflict.RemoteDocument));
  return conflict.RemoteDocument;
}`

Constraints

Using complex custom_conflict_resolver functions can noticeably degrade performance. Use a built-in resolver whenever possible.

databases.this_db.replications.this_rep.direction

string

About

Use direction to specify the replication is push, pull or pushAndPull relative to this node.

Behavior

The property value is referenced by the remote property.

• pull -- changes are pulled from the remote database
• push -- changes are pushed to the remote database
• pushAndPull -- changes are both pushed-to and pulled-from the remote database

Constraints

Replications created prior to version 2.8 derive their direction from the source and target url of the replication.

databases.this_db.replications.this_rep.enable_delta_sync

boolean

About

Use enable_delta_sync to specify use of delta sync for this replication.

It works in conjunction with database.this_db.delta_sync.enabled, which specifies whether the database can use delta sync or not.

Options

To use delta sync or not.

• "enable_delta_sync": true, the replication can use delta sync (depending on delta_sync.enabled setting
• "enable_delta_sync": false -- the replication cannot use delta sync

Behavior

The optional enable_delta_sync property works in conjunction with the database level database.this_db.delta_sync.enabled setting, to determine whether this replication uses delta sync.

• If "delta_sync.enabled": true for both databases involved in the replication, then this parameter enables or disables its use for this specific replication.

• In all other cases it has no effect and the replication runs without delta-sync.

Constraints

• Requires Enterprise Edition
• Depends upon setting of database.this_db.delta_sync.enabled
• Replications created prior to version 2.8 must run with "enable_delta_sync": false
• Push replications will not use Delta Sync when pushing to a pre-2.8 target

databases.this_db.replications.this_rep.filter

string

About

Use filter to specify the name of the function to be used to filter documents.

Options

A common value used when replicating from Sync Gateway is sync_gateway/bychannel. This option limits the pull replication to a specific set of channels. You can specify the required channels using query_params.

Behavior

Works in conjunction with.query_params to control the documents processed by the replication.

Example

"filter":"sync_gateway/bychannel"

Constraints

OPTIONAL for stops and removes (even if defined during creation)

databases.this_db.replications.this_rep.max_backoff_time

integer

About

Use max_backoff_time to specify the number of minutes Sync Gateway will spend trying to reconnect lost or unreachable remote targets.

Behavior

On disconnection Sync Gateway performs an exponential backoff up to max_backoff_time minutes. Thereafter, it will try to reconnect indefinitely every max_backoff_time minutes.

If a zero value is specified, Sync Gateway does an exponential backoff for up to five minutes before stopping the replication.

Constraints

The value defaults to five minutes for replications created prior to version 2.8.

databases.this_db.replications.this_rep.password

string

About

Use password to provide the login password value for the accredited user running this replication.

Behavior

These details are used to authenticate credentials and approve access to data.

Once provided and recorded, the password data is redacted and will not be displayed in either the configuration file or Admin REST API. A string of **** will be displayed in its place.

databases.this_db.replications.this_rep.perf_tuning_params

array

The perf_tuning_params are not available in this release.

databases.this_db.replications.this_rep.purge_on_removal

boolean

About

Use purge_on_removal to specify (per replication) whether removing a channel should trigger a purge.

Options

• true or false
• Default = false -- document removals are ignored

Behavior

If purge_on_removal=false, then the removal of channels is ignored (not purged) by the receiving end.

Constraints

Replications created prior to version 2.8 must be run with purge_on_removal=false.

databases.this_db.replications.this_rep.query_params

array

About

Use query_params to specify the key/value pairs to be passed to the filter named in filter.

Behavior

This property works in conjunction with filters and channels to provide routing.

Using

You can use query_params' channels function to allow only a specific set of channels to pass. To do so, you would also need to set the filter to sync_gateway/bychannels.

For example :

  "filter":"sync_gateway/bychannel",
  "query_params": {
    "channels":["thisChannel"]
  },

Constraints

OPTIONAL for stops and removes (even if defined during creation)

databases.this_db.replications.this_rep.remote

string

About

Use remote to specify the database endpoint on the remote Sync Gateway custer.

Options

The format can be one of --

• a string containing a valid URL for a (remote) Sync Gateway database.
• an object whose url property contains the Sync Gateway database URL.

Behavior

The remote property represents a database endpoint for the remote Sync Gateway cluster. That is, it identifies the remote cluster that is the subject of this replication's push, pull or pushAndPull action.

The effect of this setting is dependent upon the setting of the direction configuration property.

If direction is :

• direction=pull, then remote defines the remote cluster from which data is pulled
• direction=push, then remote defines the remote cluster to which data is pushed
• direction=pushAndPull, then remote defines the remote cluster to which data is pushed.

Example

 "remote": "http://www.example.com:4984/db2name",

Constraints

• You must specify the 'remote' database's url even if it is located on the same cluster as the replication's database.
• OPTIONAL for stops and removes

databases.this_db.replications.this_rep.replication_id

string

About

Use replication_id to specify an identifying name for the replication.

Behavior

The replication_id property specifies either:

• For NEW replications, the ID to be assigned to the the replication. If no replication_id is specified, Sync Gateway will assign a random UUID to new replications.
• For existing replications, this is the ID of the required replication.
• If cancel=true, this is the id of the active replication task to be cancelled.

Constraints

• If specified in configuration, it must match the name of the replication definition object.
• If specified in the body of an Admin REST API request, it must match the replication_id specified in the request URL.

databases.this_db.replications.this_rep.initial_state

string

About

Use initial_state to specify the initial state of the replication on launch.

Behavior

All replications are configured to auto-start on Sync Gateway launch. So, if omitted, the initial_state defaults to running.

To prevent the auto-start behavior, include initial_state with a value of stopped ("initial_state" "stopped")

Constraints

Replications created prior to version 2.8 will all default to a initial_state of running.

databases.this_db.replications.this_rep.username

string

About

Use username to provide the name of the accredited user running this replication.

Behavior

These details are used to authenticate credentials and approve access to data

Once provided and recorded, the username data is redacted and will not be displayed in either the configuration file or Admin REST API. A string of **** will be displayed in its place.

Replications initiated by this user will pull all documents in all channels the user has access grants for. If the all channels wildcard was used to grant access then the sync will pull ALL documents. Use a filter to avoid syncing excessive amounts of data to mobile devices.

facebook

object

Configuration for Facebook Login authentication.

facebook.register

boolean

Whether the POST /{db}/_facebook endpoint should register a user if one doesn't already exist. The email returned by Facebook is used to determine if that user already exists in Sync Gateway.

google

object

Configuration for Google Login authentication.

google.register

boolean

Whether the POST /{db}/_google endpoint should register a user if one doesn't already exist. The username and email returned by Google are used to determine if that user already exists in Sync Gateway.

google.app_client_id

string

The Google App Client ID.

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.

interface

string

Public REST API port.

log

string

NOTE: This property is being deprecated in Sync Gateway 2.1 and replaced by the new logging property.

Comma-separated list of log keys to enable for diagnostic logging. Use ["*"] to enable logging for all log keys.

• Access: Anytime an access() call is made in the sync function.
• Attach: Attachment processing.
• Auth: Authentication.
• Bucket: Sync Gateway interactions with the bucket (verbose logging).
• Cache: Interactions with Sync Gateway's in-memory channel cache.
• Changes: Processing of _changes requests.
• CRUD: Updates made by Sync Gateway to documents.
• DCP: DCP-feed processing (verbose logging).
• Events: Event processing (webhooks).
• Feed: Server-feed processing.
• HTTP: All requests made to the Sync Gateway REST APIs (Sync and Admin). Note that the log keyword HTTP is always enabled, which means that HTTP requests and error responses are always logged (in a non-verbose manner). HTTP+ provides more verbose HTTP logging.
• Replicate: Log messages related to replications between Sync Gateways (using sg-replicate). This tag cannot be used for replications initiated by Couchbase Lite.
• Import+: This logging key was introduced in Sync Gateway 1.5 to help troubleshoot the import process of a document (this is the Sync Gateway process to make a document that was added through N1QL or the Server SDKs mobile-aware). This log key can be useful to troubleshoot why a given document was not successfully imported.
• Sync: Activity which relates to synchronization between Couchbase Lite and Sync Gateway (Sync+ and Sync++ can be used for additional logging output).

logFilePath

string

NOTE: This property is being deprecated in Sync Gateway 2.1 and replaced by the new logging property.

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.

logging

object

The logging object.

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.

logging.redaction_level

string

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, the value must be "partial" in the configuration file:

{
  "logging": {
    "redaction_level": "partial"
  }
}

logging.console

object

Settings for the console output logging.

logging.console.log_level

string

The level of logging. Log levels accumulate as you read down the table (i.e log entries at WARN will also be included in the INFO and DEBUG logs).

logging.console.log_keys

array

List of log keys to enable for diagnostic logging. Example:

{
  "logging": {
    "console": {
      "log_keys": ["HTTP", "CRUD", "Import"]
    }
  }
}

Available log key values include:

• *: Wildcard log key. Enables all log keys
• none:Disables all log keys
• Admin: Admin processes in Sync Gateway.
• Access: Anytime an access() call is made in the sync function.
• Auth: Authentication.
• Bucket: Sync Gateway interactions with the bucket (trace level only).
• Cache: Interactions with Sync Gateway's in-memory channel cache.
• Changes: Processing of /{db}/_changes requests.
• CRUD: Updates made by Sync Gateway to documents.
• DCP: DCP-feed processing.
• Events: Event processing (webhooks).
• gocb: All logging emitted by the GoCB SDK
• HTTP: All requests made to the Sync Gateway REST APIs. This is the default setting.
• HTTP+: Additional information about HTTP requests (response times, status codes).
• Import: Introduced in Sync Gateway 1.5 to help troubleshoot the import process of a document (this is the Sync Gateway process to make a document that was added through N1QL or the Server SDKs mobile-aware). This log key can be useful to troubleshoot why a given document was not successfully imported.
• Javascript: All logging from Javascript. This includes: sync function, import filters, webhook filter function, and the custom ISGR conflict resolvers
• Migrate: Logs messages that show when old inline document metadata is upgraded to xattrs
• Query: Query is used for Sync Gateway code related to N1QL queries
• Replicate: Log messages related to replications between Sync Gateways (using sg-replicate). This tag cannot be used for replications initiated by Couchbase Lite.
• SGCluster: Log messages related to the sharded import and HA sg-replicate
• Sync: Activity which relates to synchronization between Couchbase Lite and Sync Gateway
• SyncMsg: Can be used for additional Sync logging output
• WS: Websocket replication log messages
• WSFrame: Can be used for additional WS logging output

logging.console.color_enabled

boolean

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

logging.default

string

Logging configuration. This property is being deprecated in Sync Gateway 2.1 and replaced with 4 different log levels.

See the logging.$level property for more detail.

logging.$level

object

The level of logging as a key. Log levels accumulate as you read down the table (i.e log entries at WARN will also be included in the INFO and DEBUG logs).

Each log level takes a dictionary as value and various properties can set for each log level. For example:

"logging": {
    "log_file_path": "/home/sync_gateway/logs", // Where to put log files
    "console": {
        "log_level": "info",  // What level to output to console - [error|+warn|+info|+debug|+none]
        "log_keys": ["HTTP"], // What log keys to output to console (comma separated)
        "color_enabled": true
    },
    "error": {
        "enabled": true,
        "rotation": {
            "max_size": 100,    // Threshold in megabytes to rotate logs
            "max_age": 360,     // Maximum days to retain log files (Min: 180)
            "localtime": false // Use local computer's time on backup timestamps (false=UTC)
        }
    },
    "warn": {
        "enabled": true,
        "rotation": {
            "max_size": 100,
            "max_age": 180,     // (Minimum: 90)
            "localtime": false
        }
    },
    "info": {
        "enabled": true,
        "rotation": {
            "max_size": 100,
            "max_age": 6,     // (Minimum: 3)
            "localtime": false
        }
    },
    "debug": {
        "enabled": false,
        "rotation": {
            "max_size": 100,
            "max_age": 2,     // (Minimum: 1)
            "localtime": false
        }
    }
}

logging.$level.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.$level.rotation

object

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

logging.$level.rotation.max_size

integer

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

logging.$level.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.$level.rotation.localtime

boolean

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

logging.$level.rotation.rotated_logs_size_limit

integer

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.

maxFileDescriptors

integer

Maximum number of open file descriptors.

maxHeartbeat

integer

This specifies the Maximum Heartbeat value for the _changes feed requests; the time in second between heartbeats.

• The default value of maxHeartbeat is 0 (zero)
• The minimum value of maxHeartbeat is 25 (25,000 ms)

maxIncomingConnections

integer

Maximum number of incoming HTTP connections to accept.

pretty

boolean

(Deprecated) Whether to pretty-print JSON responses.

profileInterface

string

(Deprecated) 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.

replications

array

Support Notice (Deprecated) This SG-Replicate 1.0 method of configuring replication is deprecated at version 2.8. For replication using the SG-Replicate 2.0 protocol configure the replication properties under database.replications instead -- see SG-Replicate 2.0 Replications.

NOTE: Sync Gateway will fail to start if any replications defined at this level do involve at least one local database (source and-or target); an error is recorder in the log.

About SG-Replicate 1.0 replications :

• default to a 'Running' state
• do not support built-in, or custom, conflict resolution -- see Resolving Conflicts and SG-Replicate 2.0 Conflict Resolution
• use source and target to derive replication direction

replications.replication_id

string

(Deprecated) This is the ID to assign this replication with. If no replication_id is given for a new replication it is assigned a random UUID.

replications.source

string

(Deprecated) Identifies the database to copy revisions from.

Valid options:

• a string containing a local database name
• a remote database URL
• an object whose url property contains the database name or URL. Also an object can contain a headers property that contains custom header values such as a cookie.

replications.target

string

(Deprecated) Identifies the database to copy revisions to. Same format and interpretation as source.

replications.continuous

boolean

(Deprecated) Specifies whether the replication should be in continuous mode.

replications.changes_feed_limit

integer

(Deprecated) The maximum number of change entries to pull in each loop of a continuos changes feed.

replications.filter

string

(Deprecated) Indicates that the documents should be filtered using the specified filter function name. A common value used when replicating from Sync Gateway is sync_gateway/bychannel to limit the pull replication to a set of channels.

replications.query_params

array

(Deprecated) A set of key/value pairs to use in the querystring of the replication. For example, the channels field can be used to pull from a set of channels (in this particular case, the filter key must be set for the channels field to work as expected).

replicator_compression

integer

This sets the 'deflate' compression level to use when compressing messages sent via the WebSocket protocol, where 0 means no compression, 1 means fastest (least) compression, and 9 means slowest (most) compression.

readHeaderTimeout

integer

Maximum duration (in seconds) allowed to read request Headers

idleHeaderTimeout

integer

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

serverReadTimeout

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, therefor the value set in the configuration file is passed to Go's server instance https://golang.org/pkg/net/http/#Server.

serverWriteTimeout

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, therefor the value set in the configuration file is passed to Go's server instance https://golang.org/pkg/net/http/#Server.

slowQueryWarningThreshold

integer

Log warnings if N1QL or View queries made by Sync Gateway take this many milliseconds or longer.

SSLCert

string

Absolute or relative path on the filesystem to the TLS certificate file, if TLS is used to secure Sync Gateway connections, or "nil" for plaintext. A relative path is from the directory that contains the Sync Gateway executable file.

SSLKey

string

Absolute or relative path on the filesystem to the TLS private key file, if TLS is used to secure Sync Gateway connections, or "nil" for plaintext. A relative path is from the directory that contains the Sync Gateway executable file.

tls_minimum_version

string

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

Possible values are:

• "tlsv1"
• "tlsv1.1"
• "tlsv1.2"