A newer version of this documentation is available.

View Latest

Using Hostnames

    Each individual Couchbase Server-node can be referenced by a hostname, as well as by an IP address. You can specify a node’s hostname by using either the Couchbase Web Console or the REST API, during the process of node-configuration and cluster-definition.

    Specifying a Hostname

    Initial configuration of Couchbase Server allows the node to be referenced by means of a default IP address: You may choose to specify a different IP address, or a hostname. The hostname must be valid, and must ultimately resolve to a valid IP Address.

    If you restart a node, Couchbase Server continues to use the specified hostname. Note, however, that if you fail over, or remove the node from a cluster, Couchbase Server will no longer use the specified hostname: therefore, in such circumstances, you must reconfigure the node, in order to re-specify the hostname.

    You can specify a hostname when performing initial configuration of Couchbase Server; when adding a node to an existing cluster; or before adding a node to a cluster, by means of a REST API call. Each of these options is described below.

    Provide a Hostname on Initial Configuration

    In the Cluster Name panel, on the Couchbase > New Cluster dialog, you can enter either a hostname or a specific IP address into the interactive text-field.

    cluster setup host

    Provide a Hostname while Adding a Node

    Nodes can be added to a cluster by means of the Server tab, visible on the vertical navigation-bar at the left-hand side of the Couchbase Web Console. This displays the Servers screen, on which the Add Server button is located, at the upper-right. Left-click on this button to display the Add Server Node dialog:


    Enter either a hostname or IP address into the interactive Server IP Address text-field.

    Provide a Hostname using the REST API

    The REST API provides the endpoint /node/controller/rename, which can be used to specify a hostname before the node has been added to a cluster. For example:

    curl -v -X POST -u Administrator:adm1npwd \ -d hostname=shz.localdomain

    Note that if the node is already part of a cluster, Couchbase Server rejects the request; returning the following error:

    error 400 reason: unknown ["Renaming is disallowed for nodes that are
    already part of a cluster"]

    Hostname Errors

    If the hostname you specify is invalid, or has been specified at an inappropriate point in the configuration or node-addition sequence, an error is returned. The following are examples of errors that you might encounter:

    Could not resolve the host name. The host name you provide as a parameter
    does not resolve to a IP address.
    Could not listen. The host name resolves to an IP address, but no network
    connection exists for the address.
    Could not rename the node because name was fixed at server start-up.
    Could not save address after rename.
    Requested name host name is not allowed. Invalid host name provided.
    Renaming is disallowed for nodes that are already part of a cluster.