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

cluster-init

      +

      Initializes a Couchbase Server cluster

      SYNOPSIS

      couchbase-cli cluster-init [--cluster <url>] [--cluster-username <username>] [--cluster-password <password>]
    [--client-cert <path>] [--client-cert-password <password>] [--client-key <path>]
    [--client-key-password <password>] [--cluster-port <port>]
    [--cluster-ramsize <mebibytes>] [--cluster-name <name>]
    [--cluster-index-ramsize <mebibytes>] [--cluster-fts-ramsize <mebibytes>]
    [--cluster-eventing-ramsize <mebibytes>]
    [--cluster-analytics-ramsize <mebibytes>]
    [--index-storage-setting <setting>] [--services <services>]
    [--update-notifications <1|0>]
    [--ip-family <ipv4|ipv6|ipv4-only|ipv6-only>] [--node-to-node-encryption <on|off>]

      DESCRIPTION

      Initializes the first node in a Couchbase Server cluster. Before initializing a cluster you need to decide which services you will be running on this node as well as the memory quota for each service you are starting. Services started with cluster-init will be running on this server only. Future servers that are added to this cluster may be configured with different services running on them. Note that the data service is always required on the first node. Memory quotas for each service are global settings and will apply to each node added to the cluster. The memory quota for a service only applies if that service is running on a given server. You may also define the index storage mode which will determine how the global secondary indexes (GSI) are stored.

      OPTIONS

      -c
      --cluster

      Specifies the hostname of the cluster to initialize. By default, this parameter is set to localhost:8091 for this command. See the HOST FORMATS section for more information on specifying a hostname.

      --cluster-username

      When starting a new cluster you need to create the Couchbase Server built-in administrator user for the cluster. This user will be able to access the Couchbase Server Administration Console as well as be used for data access and future configuration. This option specifies the username for the administrator user.

      --cluster-password

      When starting a new cluster you need to create the Couchbase Server built-in administrator user for the cluster. This user will be able to access the Couchbase Server Administration Console as well as be used for data access and future configuration. This option specifies the password for the administrator user.

      --cluster-ramsize

      Specifies the data services memory quota (in MiB). This quota will be assigned to all future nodes added to the cluster with the data service.

      --cluster-fts-ramsize

      Sets the full-text service memory quota (in MiB). This parameter is required if the full-text service is specified in the --services option. This quota will be assigned to all future nodes added to the cluster with the full-text service.

      --cluster-index-ramsize

      Sets the index service memory quota (in MiB). This parameter is required if the index service is specified in the --services option. This quota will be assigned to all future nodes added to the cluster with the index service.

      --cluster-eventing-ramsize

      Sets the Eventing service memory quota (in MiB). This parameter is required if the Eventing service is specified in the --services option. This quota will be assigned to all future nodes added to the cluster with the eventing service.

      --cluster-analytics-ramsize

      Sets the Analytics service memory quota (in MiB). This parameter is required if the Analytics service is specified in the --services option. This quota will be assigned to all future nodes added to the cluster with the analytics service.

      --cluster-name

      Sets the name for this cluster. Naming clusters is useful when you have multiple Couchbase Server clusters in your deployment.

      --cluster-port

      Specifies the port for the Couchbase Administration Console. Defaults to port 8091.

      --index-storage-setting

      Specifies the index storage mode for the index service. Accepted storage modes are "default" for the standard index backend or memopt for memory optimized indexes. If the index service is specified to be started with the --services command then this parameter defaults to "default". If the index service is not specified to be started then the index storage mode will not be set. You will then be required to set the index storage mode when the first index service is started on a server in the cluster. You may also define the index storage mode even if an index service is not started on the first node and it will be remembered when the first index service is added in the future. You may not change this parameter while there are index nodes in the cluster.

      --services

      Specifies the services to start on this cluster. You may not change the services running on this node once the cluster has been initialized. This options takes a comma separated list of services. Accepted services are "data", "index", "query", "fts", "eventing", "analytics" and "backup" specified as a comma-separated list. This parameter defaults to "data".

      --update-notifications

      Specifies whether or not software update notifications and sharing of system performance information should be enabled. To enable notifications set this flag to "1". To disable notifications set this flag to "0". By default it’s enabled and notifications will be displayed in the Couchbase web console when a new version of Couchbase Server is available. This system also collects information about use and experience with the product every time an administrator interacts with the administrator user interface. It collects configuration, usage and performance data, including cluster information (such as settings and configuration, software version, cluster ID, load levels, and resource quotas), and browser and network information (such as IP address, inferred geolocation only at the city level, and browser type). This does not allow Couchbase to track your specific interactions or usage of Couchbase Server. Couchbase, Inc never accesses or collects any data stored within Couchbase Server. This feature can be disabled at any time by using 'couchbase-cli-setting-notification.' For more information on this feature, please see the “Couchbase Server Privacy FAQ” in the product documentation, which supplements the Couchbase Privacy Policy available online. This feature is only available in Couchbase Enterprise Edition.

      --ip-family

      Specifies what IP family the cluster should used. The default option is 'ipv4'. When 'ipv4-only' or 'ipv6-only' is used the cluster will only listen on that address.

      --node-to-node-encryption

      Specifies if node to node encryption should be used. The default option is 'off'. When set to 'on' all communications between nodes will be over a encrypted connection.

      HOST FORMATS

      When specifying a host for the couchbase-cli command the following formats are expected:

      • couchbase://<addr> or couchbases://<addr>

      • http://<addr>:<port> or https://<addr>:<port>

      • <addr>:<port>

      It is recommended to use the couchbase://<addr> or couchbases://<addr> format for standard installations. The other formats allow an option to take a port number which is needed for non-default installations where the admin port has been set up on a port other that 8091 (or 18091 for https).

      CERTIFICATE AUTHENTICATION (MTLS AUTHENTICATION)

      This tool supports authenticating against a Couchbase Cluster by using certificate based authentication (mTLS authentication). To use certificate based authentication a certificate/key must be supplied, there a currently multiple ways this may be done.

      PEM ENCODED CERTIFICATE/KEY

      An unencrypted PEM encoded certificate/key may be supplied by using: - --client-cert <path> - --client-key <path>

      The file passed to --client-cert must contain the client certificate, and an optional chain required to authenticate the client certificate.

      The file passed to --client-key must contain at most one private key, the key can be in one of the following formats: - PKCS#1 - PKCS#8

      Currently, only the following key types are supported: - RSA - DSA

      PEM ENCODED CERTIFICATE/PEM OR DER ENCRYPTED PKCS#8 KEY

      An encrypted PKCS#8 formatted key may be provided using: - --client-cert <path> - --client-key <path> - --client-key-password <password>

      The file passed to --client-cert must contain the client certificate, and an optional chain required to authenticate the client certificate.

      Currently, only the following key types are supported: - RSA - DSA

      ENCRYPTED PKCS#12 CERTIFICATE/KEY

      An encrypted PKCS#12 certificate/key may be provided using: - --client-cert <path> - --client-cert-password <password>

      The file passed to --client-cert must contain the client certificate and exactly one private key. It may also contain the chain required to authenticate the client certificate.

      Currently, only the following key types are supported: - RSA - DSA

      EXAMPLES

      To create a Couchbase Server cluster with only the data service on the first node and a memory quota of 4096MiB run the following command.

      $ couchbase-cli cluster-init -c 127.0.0.1 --cluster-username Administrator \
 --cluster-password password --services data --cluster-ramsize 4096

      To create a Couchbase Server cluster with the data and index service then you also need to set the memory quotas for each service as well as the index storage mode since you are starting the index service.

      To create a cluster with an index memory quota of 1024MiB, a data service memory quota of 2048MiB and a memory optimized index storage mode run the following command.

      $ couchbase-cli cluster-init -c 127.0.0.1 --cluster-username Administrator \
 --cluster-password password --services data,index --cluster-ramsize 2048 \
 --cluster-index-ramsize 1024 --index-storage-setting memopt

      To create a Couchbase Server cluster with all services then you need to set the memory quotas for the Data, Index, Full-Text, Eventing and Analytics service. The quotas are set to 2048MiB, 1024MiB, 1024MiB, 1024MiB and 1024MiB respectively. A quota is not set for the query service since it does not have a memory quota. You also need to set the index storage mode for the index service, which will be set to "default" since the service is started on the first node.

      $ couchbase-cli cluster-init -c 127.0.0.1 --cluster-username Administrator \
 --cluster-password password --services data,index,query,fts,analytics \
 --cluster-ramsize 2048 --cluster-index-ramsize 1024 \
 --cluster-eventing-ramsize 1024 --cluster-fts-ramsize 1024 \
 --cluster-analytics-ramsize 1024 --cluster-fts-ramsize 1024 \
 --index-storage-setting default

      If you want to set the port number you can do so with the --cluster-port option. In the example below, a cluster is setup on port 5000 and starts only the data service. The memory quota of the data service is set to 2048MiB.

      $ couchbase-cli cluster-init -c 127.0.0.1 --cluster-username Administrator \
 --cluster-password password --services data --cluster-ramsize 2048 \
 --cluster-port 5000

      DISCUSSION

      The cluster-init subcommand sets up the first node on a Couchbase cluster. To set per node settings such as the data storage directory, index storage directory, or hostname see the node-init command. To add nodes to a currently initialized cluster use the server-add command. Some cluster settings may be changed after a cluster is initialized. Use the setting-cluster command to edit these settings.

      ENVIRONMENT AND CONFIGURATION VARIABLES

      CB_REST_USERNAME

      Specifies the username to use when executing the command. This environment variable allows you to specify a default argument for the -u/--username argument on the command line.

      CB_REST_PASSWORD

      Specifies the password of the user executing the command. This environment variable allows you to specify a default argument for the -p/--password argument on the command line. It also allows the user to ensure that their password are not cached in their command line history.

      CB_CLIENT_CERT

      The path to a client certificate used to authenticate when connecting to a cluster. May be supplied with CB_CLIENT_KEY as an alternative to the CB_USERNAME and CB_PASSWORD variables. See the CERTIFICATE AUTHENTICATION section for more information.

      CB_CLIENT_CERT_PASSWORD

      The password for the certificate provided to the CB_CLIENT_CERT variable, when using this variable, the certificate/key pair is expected to be in the PKCS#12 format. See the CERTIFICATE AUTHENTICATION section for more information.

      CB_CLIENT_KEY

      The path to the client private key whose public key is contained in the certificate provided to the CB_CLIENT_CERT variable. May be supplied with CB_CLIENT_CERT as an alternative to the CB_USERNAME and CB_PASSWORD variables. See the CERTIFICATE AUTHENTICATION section for more information.

      CB_CLIENT_KEY_PASSWORD

      The password for the key provided to the CB_CLIENT_KEY variable, when using this variable, the key is expected to be in the PKCS#8 format. See the CERTIFICATE AUTHENTICATION section for more information.

      SEE ALSO

      cluster-edit, node-init, server-add

      COUCHBASE-CLI

      Part of the couchbase-cli suite