Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Configuration Overview

      +

      How to configure Sync Gateway for secure cloud-to-edge data sync

      Related topics: Overview | Bootstrap | Database | Database Security | Access Control | Import | Inter-Sync Gateway Replication

      Introduction

      Sync Gateway 3.0 introduces Centralized Persistent Modular Configuration, to better suit its use in increasingly prevalent multi-node, multi-cluster deployments. Centralized persistent modular configuration replaces the established, file-based configuration method [1], supporting the move away from a reliance on increasingly monolithic central configuration files. It enables simpler, more agile configuration updates and encompasses:

      • Bootstrap Startup
        A minimal configuration file is used to bootstrap a sync gateway node and attach it to its Couchbase Server cluster; these files and their settings are node-specific — see the Bootstrap Configuration

      • Dynamic Configuration
        The ability to make remote in-flight configuration changes to database settings, access-control policies and inter-sync gateway replications, enables simpler and more agile maintenance.

      • Cluster-aware Updates
        Configuration changes made to a node through the API endpoints are propagated to other sync gateway nodes belonging to the same cluster (or to a user-defined subset of nodes) — Configuration Groups

      • Persistent Updates
        Any database changes made using the API endpoints are persisted and survive sync gateway node restarts (this does not apply when running in file-based configuration mode).

      • Secure REST API
        by default the REST API requires authentication and authorization using Couchbase Server RBAC-user credentials — see Secure Sync Gateway Access. This can be disabled for test purposes only.

      • Automatic upgrade path
        Your existing legacy Pre-3.0 configuration files will (optionally) be automatically converted, on start-up, to the new format for centralized persistent modular configuration.

      Workflow

      In the Centralized Persistent Modular Configuration ecosphere you provide a minimal bootstrap configuration to get Sync Gateway started, then add users, roles, database and replications using the REST API.

      persistent config
      Figure 1. Configuration Workflow

      1. Set up a user for the Admin REST API on Couchbase Server
        Alternatively, you can disable authentication of REST API user(s) — for test purposes only

      2. Provide a bootstrap configuration file, in JSON format, which defines the sync gateway node’s run time behavior. This configuration is node-specific. Any changes require a sync gateway restart.

      3. Add or amend configuration items in-flight using the Admin Rest API.
        All changes are persisted across sync gateway restarts. Auto restarts will be initiated for ny change that requires one. You will need to configure and maintain:

        1. Databases
          Use the Admin REST API endpoint Database Configuration endpoints to add required databases.

        2. Database Security
          Use the Database Security endpoints to configure users and roles.

        3. Access Control
          Use the Access Control endpoints to configure your Sync Function.

        4. Inter-Sync Gateway replications
          Use the inter-sync gateway replication endpoints to configure required replications.

      Opt-out

      To continue using legacy Pre-3.0 configuration you should start sync gateway with disable-persistent-config set true either in the configuration file or in Command Line Options.

      This ensures you can use the Legacy Pre-3.0 Configuration. Note that no Admin REST API changes are persisted across sync gateway restarts.

      Key Terms

      Term Description

      Sync Gateway Cluster

      A collection of sync gateway nodes connected to a common Couchbase Server cluster

      Homogeneous Sync Gateway Cluster

      A sync gateway cluster where every node in cluster shares common configuration

      Sync Gateway Config Group

      A group of sync gateway nodes within a sync gateway cluster sharing common configuration. Each node in the group will continue to have node-specific config.

      Configuration Levels

      All the configuration properties, whether defined in the bootstrap configuration file or by the Admin REST API endpoint belong to one of two core 'levels': node or database — see Table 1

      Table 1. Configuration levels in centralized persistent modular configuration
      Level Use Scope Changeable?

      Node

      Couchbase Server connection

      Minimal set of configuration properties required for connection to Couchbase Server bucket, for example server credentials, and group id

      Node-specific; unshared

      Yes, file-edit
      Restart required

      System properties

      Node level system properties including, for example, api.tls.cert_path and max_file_descriptors

      Node-specific; unshared

      Yes, file-edit
      Restart required

      Logging properties

      Logging-related properties

      Node-specific; unshared

      Yes by the Admin REST API
      No restart, but not persisted

      Database

      DB properties

      Database configuration properties including, for example, bucket, or access control policies such as users and sync

      May be node-specific, but typically shared across nodes in same group

      Yes, by Admin REST API
      Restart initiated as needed

      Replication properties

      inter-sync gateway replication properties

      Shared across all participating replication nodes

      Yes, by Admin REST API
      Restart initiated as needed

      Secure Administration

      Secure Administration is on by default.

      In order to submit Admin or Metrics REST API requests you should create specific Couchbase Server users for that purpose. You will then provide a valid set of Couchbase Server credentials for these RBAC-users in each API request.

      Authenticated users will have access to Admin and-or Metrics API functionality, application data and configuration settings.

      For more see: REST API Access

      Configuration Groups

      You can group sync gateway nodes into homogenous clusters using the Config-Group-ID property (bootstrap.group_id). This defines the database configuration group to which a node belongs.

      All nodes in a group share the same database configuration. Changes made from one node are propagated to other nodes in the group automatically.

      All nodes in a cluster belong, by default, to a common shared group default.

      If you move a sync gateway node to a new group, it will inherit the configuration associated with that group. This applies also if you move a group (back) into the default group.

      Related Content

      API Topics
      Reference
      Community

      Mobile Forum | Blog | Blog (Mobile) | Tutorials

      1. You can continue using file-based configuration by using the CLI option -disable_persistent_config when starting Sync Gateway