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

Manage Address Families

      +
      Couchbase Server Enterprise Edition supports the IPv4 and IPv6 address families.

      Understanding Address Families

      Couchbase Server Enterprise Edition supports the IPv4 and IPv6 address families. By default, IPv4 is the address family established for the cluster: this means that IPv4 must be available on all Couchbase-Server ports — if it is not available, the service that is attempting to bind will fail. Provided that IPv4 is available, Couchbase Server and its services may also bind using IPv6.

      To establish IPv6 as the address family for the cluster, instead of IPv4, configuration changes must be made. An established cluster must be established, both prior to and subsequent to the address-family changeover-process, with either IPv4 or IPv6, for all its nodes.

      A Couchbase Server-cluster can be established with IPv4 or IPv6 either:

      • When the cluster is being created. For information on using the UI, see Create a Cluster. For information on using the CLI, see Initialize a Node with the CLI.

      • After the cluster has been created. This procedure, which uses the CLI, is explained on this page, below. Note that the procedure requires the address family to be established with one of the following results specified:

        • The selected address family is required, but the other supported address family can also be used. This is the default setting, with the IPv4 address family being the one required.

        • Only the selected address family can be used. This option is available only with Couchbase Server Version 7.0.2 and later.

      Changing Address Family

      Before attempting to change an existing cluster’s address family, note the following:

      • The address family can only be changed if each cluster-node is named with a fully qualified domain-name (such as nodename.clustername.com). Raw IP addresses can be used to name cluster-nodes, but the cluster must be created with them, and the address family cannot subsequently be changed.

      • Each cluster-node must be operating in dual stack mode, thereby supporting both IPv4 and IPv6 addressing.

      • DNS records must be managed, to ensure address-resolution to both IPv4 and IPv6 during the changeover, and to either IPv4 or IPv6 following the changeover (at which point, address-resolution can be disabled for the address family no longer used).

      • Auto-failover must be disabled prior to the changeover (and can be re-enabled after the changeover).

      • Node-to-node encryption must be disabled prior to the changeover (and can be re-enabled after the changeover).

      • On each node, when the address-family change occurs, all Couchbase Services hosted on that node other than the Data Service are restarted.

      The following sequence demonstrates how to change the address family for a cluster, using the Couchbase CLI. The sequence assumes:

      • Familiarity with the instructions provided in Manage Node-to-Node Encryption (since node-to-node encryption-settings are modified during the sequence).

      • A pre-existing cluster of two nodes, node1-devcluster.com and node2-devcluster.com, both running the latest version of Couchbase Server Enterprise Edition.

      • Node-to-node encryption initially enabled.

      • Auto-failover initially enabled.

      Proceed as follows:

      1. Retrieve the current address-family setting.

        This can be accomplished by means of the ip-family CLI command, using the --get flag:

        /opt/couchbase/bin/couchbase-cli ip-family \
-c http://node1-devcluster.com:8091 \
-u Administrator \
-p password \
--get

        The output from this command consists of one of the following three messages:

        • Cluster using ipv4: Every node in the cluster is using IPv4, and may use IPv6.

        • Cluster using ipv6: Every node in the cluster is using IPv6, and may use IPv4.

        • Cluster using ipv4only: Every node in the cluster is using IPv4, and may not use IPv6. (This message is generated only by Couchbase Server Version 7.0.2 and later.)

        • Cluster using ipv6only: Every node in the cluster is using IPv6, and may not use IPv4. (This message is generated only by Couchbase Server Version 7.0.2 and later.)

        • Cluster is in mixed mode: The cluster contains some nodes that are using IPv4, and others that are using IPv6: this situation is indicative of an error, likely incurred during a previous, attempted reconfiguration of the address family for the cluster. The error should be fixed, by re-establishing the address family for the whole cluster.

          The remaining steps below assume that the address family of the cluster is to be changed to IPv6.

      2. Switch off auto-failover.

        Auto-failover must be disabled, for the address family to be modified. Use the setting-autofailover CLI command, as follows:

        /opt/couchbase/bin/couchbase-cli setting-autofailover \
-c http://node1-devcluster.com:8091 \
-u Administrator \
-p password \
--enable-auto-failover 0

        If successful, this provides the following output:

        SUCCESS: Auto-failover settings modified

      3. Switch off node-to-node encryption, if appropriate.

        Node-to-node encryption must be disabled, before the address family can be changed. To check the status of node-to-node encryption, use the node-to-node-encryption CLI command, specifying the --get flag:

        /opt/couchbase/bin/couchbase-cli node-to-node-encryption \
-c http://node1-devcluster.com:8091 \
-u Administrator \
-p password \
--get

        The output from this command is one of two messages: either Node-to-node encryption is disabled, indicating that it does not need to be disabled; or Node-to-node encryption is enabled. which indicates that it does.

        If node-to-node encryption needs to be disabled, ensure that the clusterEncryptionLevel for the cluster is set to control, rather than all — otherwise node-to-node encryption cannot be disabled. See the instructions provided in Manage Node-to-Node Encryption.

        When the clusterEncryptionLevel for the cluster has been set to control, disable node-to-node encryption using the node-to-node-encryption command with the --disable flag:

        /opt/couchbase/bin/couchbase-cli node-to-node-encryption \
-c http://node1-devcluster.com:8091 \
-u Administrator \
-p password \
--disable

        If this command is successful, the output is as follows:

        Turned off encryption for node: http://node1-devcluster.com:8091
Turned off encryption for node: http://node2-devcluster.com:8091
SUCCESS: Switched node-to-node encryption off

      4. Change the address family for the cluster to IPv6.

        Use the ip-family CLI command, using the --set and --ipv6 flags, as follows:

        /opt/couchbase/bin/couchbase-cli ip-family \
-c http://node1-devcluster.com:8091 \
-u Administrator \
-p password \
--set \
--ipv6

        The --set flag indicates that an address-family setting is to be made. The --ipv6 flag specifies that the cluster will from this point require that the IPv6 family be available for communications — communication with the IPv4 family is still supported. (Note that if communication with the IPv4 family should be absolutely prohibited, the --ipv6only flag should be used, instead of the --ipv6 flag.)

        If successful, the command provides the following output:

        Switched ip family for node: http://node1-devcluster.com:8091
Switched ip family for node: http://node2-devcluster.com:8091
SUCCESS: Switched ip family of the cluster

        The output indicates that the IP family has been successfully established, and thus changed for each cluster in the node.

      5. If appropriate, switch node-to-node encryption back on. Use the node-to-node-encryption CLI command, specifying the --enable flag:

        /opt/couchbase/bin/couchbase-cli node-to-node-encryption \
-c http://node1-devcluster.com:8091 \
-u Administrator \
-p password \
--enable

        If the command succeeds, the following output is displayed:

        Turned on encryption for node: http://node1-devcluster.com:8091
Turned on encryption for node: http://node2-devcluster.com:8091
SUCCESS: Switched node-to-node encryption on

      6. If appropriate, switch auto-failover back on.

        /opt/couchbase/bin/couchbase-cli setting-autofailover \
-c http://node1-devcluster.com:8091 \
-u Administrator \
-p password \
--enable-auto-failover 1 \
--auto-failover-timeout 120 \
--enable-failover-of-server-groups 1 \
--max-failovers 2 \
--can-abort-rebalance 1

        The parameter values specify that auto-failover be enabled with a timeout of 120 seconds; with a maximum of two, sequential automated failovers able to occur, prior to administrator intervention being required. Automated failover of server groups is enabled, as is the aborting of rebalance.

        If the command succeeds, and the settings are successfully modified, the following output is displayed:

        SUCCESS: Auto-failover settings modified

      This concludes the sequence of commands: the cluster is now running with the IPv6 address family.