Using hostnames

Each Couchbase Server's instance can have its own hostname.

When you first install Couchbase Server, you can access it using a default IP address. There are cases, however, when you want to provide a hostname for each instance of a server. Each hostname you provide must be a valid one and will ultimately resolve to a valid IP Address. If you restart a node, it will use the hostname once again. If you fail over or remove a node from a cluster, the node needs to be configured with the hostname once again.

There are several ways you can provide hostnames: when installing a Couchbase Server on a machine, when adding a node to an existing cluster for online upgrade, or via a REST API call. Couchbase Server stores the hostnames in a config file on the disk.

Provide hostname on initial setup

In the first screen, provide either a hostname or IP address under Configure Server Hostname. The provided hostname survives node restart.

Provide hostname while adding a node

If a new node is being added to an existing 2.0.1 or earlier Couchbase cluster, first set up the hostname for the new node in the setup wizard. Add a new node to a cluster by providing either a hostname or IP address under Add Server > Server IP Address .

Provide hostname via REST API

Provide a host name for a node a host name with the REST request at the /node/controller/rename endpoint.
If this method is used, provide the hostname before adding a node to a cluster. If a hostname is provided for a node that is already part of a Couchbase cluster, the server rejects the request and returns 
error 400 reason: unknown ["Renaming is disallowed for nodes that are already part of a cluster"]
curl -v -X POST -u Administrator:asdasd \
http://127.0.0.1:8091/node/controller/rename -d hostname=shz.localdomain

Hostname errors

Provide the IP address and port for the node and administrative credentials for the cluster. The value you provide for hostname must be a valid hostname for the node. Possible errors that can occur:

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