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 used. For IPv6 to be used instead, configuration changes must be made. An established cluster must use, both prior to and subsequent to the address-family changeover-process, either IPv4 or IPv6, for all its nodes.

    A Couchbase Server-cluster can be configured to use 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 below.

    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 Couchbase Enterprise Server Version 6.5.

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

      • Cluster using IPv6: Every node in the cluster is using IPv6.

      • 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 changing the address family for the whole cluster to either IPv4 or IPv6.

      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 use the IPv6 family.

      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.