A newer version of this documentation is available.

View Latest

Using Hostnames

Each Couchbase Server’s instance can have its hostname.

When you first install Couchbase Server, you can access it using a default IP address. However, in some cases you might 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 failover 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 an online upgrade.

  • Using a REST API call.

Couchbase Server stores the hostnames in a configuration 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.

cluster setup host

Provide Hostname while Adding a Node

If a new node is being added to an existing 2.0.1 or earlier Couchbase Server 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.

upgrade online 02

Provide Hostname via REST API

Provide a hostname for a node a hostname with the REST request at the /node/controller/rename endpoint.

Provide the hostname before adding a node to a cluster. If the node is already part of a cluster, Couchbase Server rejects the request and returns an error:

error 400 reason: unknown ["Renaming is disallowed for nodes that are already part of a cluster"]
curl -v -X POST -u Administrator:asdasd \ -d hostname=shz.localdomain

Hostname Errors

Provide the hostname 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.