Change the Carbonio CE Hostname

This guide helps you in changing the hostnames of a Carbonio CE infrastructure, whether a Single-Server or Multi Node. The procedure may become quite long in the case of a Multi-Node, please go through the whole section before proceeding with the actual procedures. Indeed, depending on the number and type of Nodes that you need to rename, different procedure should be applied to each Node.

Requirements & Limitations

You need to take into account the following requirements during the procedure.

1. Ensure you have administrative access to each Node.

2. Update the A, MX, and PTR DNS records to reflect the new hostname before starting.

3. Verify the new hostname is resolvable using nslookup or dig

4. During the hostname change, every node must be resolvable by both the old and the new hostname

5. All commands in the procedures must be executed as the root user unless stated differently

6. Always start the procedure from the Node which installs the Mesh & Directory Component

7. The procedures are valid only for a change of hostname, not for a change in the domain name (i.e., of the FQDN)

Infrastructure Examples

To cover most use cases, we take into account the following scenarios on which we apply the procedure. All other cases can be traced back to either of them. In the Multi-Node setups, except for the Node featuring the Mesh & Directory Component (and the Directory Replica, if present), it is not relevant which Components are installed on each Node.

Example A, Single-Server

This is a Single-Server, Single Node setup. Simply refer to Section Change Hostname to Mesh & Directory Node below.

Example B, 3 Nodes setup.

1. Node 1 is the Directory Server with hostname srv1.example.com

2. Nodes 2 and 3 have hostnames srv2.example.com and srv3.example.com, respectively.

In this setup, we change name to Node 1 only, which will be called node1.example.com. You need to execute procedure Change Hostname to Mesh & Directory Node on Node 1 and procedure Nodes Keeping Their Hostname on Nodes 2 and 3.

Example C, 5 Nodes setup.

1. Node 1 is the Directory Server with hostname srv1.example.com

2. Nodes 2, 3, 4, and 5 have hostnames srv2.example.com, srv3.example.com, srv4.example.com, and srv5.example.com, respectively.

In this setup, we change name to Node 1, Node 2, and Node 5, which will be called node1.example.com, node2.example.com, and node5.example.com, respectively. You need to execute procedure Change Hostname to Mesh & Directory Node on Node 1, procedure Nodes Keeping Their Hostname on Nodes 3 and 4, and procedure Change Hostname of Other Nodes on Nodes 2 and 5.

Change Hostname to Mesh & Directory Node

Warning

Remember to start the procedure if and only if you have satisfied the Requirements & Limitations.

This procedure must be used on the Node featuring the Mesh & Directory Component only.

Stop Carbonio CE Services

To stop all Carbonio CE services, execute command

Ubuntu 22.04

As the zextras user user, execute

zextras$ zmcontrol status

Ubuntu 24.04

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

RHEL 8

As the zextras user user, execute

zextras$ zmcontrol status

RHEL 9

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

Change the Hostname

Update the system hostname:

# hostnamectl set-hostname node1.example.com

Verify that file /etc/hostname is up to date:

# cat /etc/hostname
node1.example.com

Update file /etc/hosts to map the new hostname to the Node IP:

# nano /etc/hosts
127.0.0.1 localhost
192.168.1.10 node1.example.com node1

Update Carbonio CE Configuration

Run the following command to update Carbonio CE interanal setting with the new hostname

# su - zextras -c "/opt/zextras/libexec/zmsetservername -n node1.example.com"

The output will be similar to:

Getting local config zimbra_server_hostname=srv1.example.com
Getting local config zimbra_ldap_userdn=uid=zimbra,cn=admins,cn=zimbra
Getting local config zimbra_ldap_password=jZl2hcK3
Getting local config ldap_is_master=true
Getting local config ldap_url=ldap://srv1.example.com:389
Getting local config ldap_master_url=ldap://srv1.example.com:389
Getting local config ldap_starttls_supported=0
Starting ldap...done.
Renaming srv1.example.com to node1.example.com
Shutting down zimbra...done.
Setting local config ldap_master_url=ldap://node1.example.com:389
Setting local config ldap_url=ldap://node1.example.com:389
Getting local config ldap_host=srv1.example.com
Setting local config ldap_host=node1.example.com
Getting local config av_notify_user=zextras@example.com
Getting local config av_notify_domain=example.com
Getting local config smtp_source=
Getting local config smtp_destination=
Setting local config zimbra_server_hostname=node1.example.com
Starting ldap...done.

Searching for ldap server entry...done.
Renaming cn=srv1.example.com,cn=servers,cn=zimbra...done.
Updating zimbraServiceHostname for cn=node1.example.com,cn=servers,cn=zimbra...done.
Updating zimbraPublicServiceHostname for cn=config,cn=zimbra...done.
Updating zimbraMailHost for uid=zextras,ou=people,dc=example,dc=com...done.
Updating zimbraMailHost for uid=spam.sdt2ak3pl,ou=people,dc=example,dc=com...done.
Updating zimbraMailHost for uid=ham.q_otnlxbi,ou=people,dc=example,dc=com...done.
Updating zimbraMailHost for uid=virus-quarantine.doj_qdcw,ou=people,dc=example,dc=com...done.
Updating zimbraMailHost for uid=galsync.eresranlan,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=zextras,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=spam.sdt2ak3pl,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=ham.q_otnlxbi,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=virus-quarantine.doj_qdcw,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=galsync.eresranlan,ou=people,dc=example,dc=com...done.
Services:
Getting local config ldap_port=389
Reinitializing the mta config...done.

Update Carbonio Mesh

After the hostname has been changed in Carbonio CE configuration, we need to notify Carbonio Mesh of the hostname change.

# sed -i 's/srv1.example.com/node1.example.com/g' /etc/zextras/service-discover/main.json
# systemctl restart service-discover

Verify SSL Certificates

If your SSL certificates are hostname-specific, you need to

• Reissue SSL certificates for the new hostname

• Deploy the new certificates

Start Carbonio CE Services

To start all Carbonio CE services, execute command

Ubuntu 22.04

As the zextras user user, execute

zextras$ zmcontrol start

Ubuntu 24.04

Hint

On Ubuntu 24.04, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

RHEL 8

As the zextras user user, execute

zextras$ zmcontrol start

RHEL 9

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

Verify the new configuration

At this point the Node configurations have all been modified with the new hostname. These tasks help you understand if everything operated correctly.

1. Check Carbonio status:

   Ubuntu 22.04

   As the zextras user user, execute

   zextras$ zmcontrol status
   

   Ubuntu 24.04

   Hint

   On Ubuntu 24.04, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

   RHEL 8

   As the zextras user user, execute

   zextras$ zmcontrol status
   

   RHEL 9

   Hint

   On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

2. Verify the e-mail flow by sending test emails

3. If the Node features also the Proxy Component, check on the Carbonio Admin Panel on port 6071 (see Access to the Web Interface) that the new hostname is reported correctly

Change Hostname of Other Nodes

This procedure applies to all nodes that do not feature the Mesh & Directory Component, that is, Node 1 in Scenario B and Nodes 1, 2, and 5 in Scenario C.

Configure new Directory Server hostname

Make sure all Carbonio CE services are running

Ubuntu 22.04

As the zextras user user, execute

zextras$ zmcontrol status

Ubuntu 24.04

Hint

On Ubuntu 24.04, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

RHEL 8

As the zextras user user, execute

zextras$ zmcontrol status

RHEL 9

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

Verify how many references to the old Mesh & Directory Node are in the configuration.

zextras$ zmlocalconfig -s|grep srv1.example.com

Configure the Node to point to the new Mesh & Directory Node.

zextras$ zmlocalconfig -e ldap_host=srv2.example.com ldap_master_url=node1.example.com ldap_url=ldap://node1.example.com

Restart the services

Ubuntu 22.04

As the zextras user user, execute

zextras$ zmcontrol restart

Ubuntu 24.04

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

RHEL 8

As the zextras user user, execute

zextras$ zmcontrol restart

RHEL 9

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

Stop Carbonio CE Services

To stop all Carbonio CE services, execute command

Ubuntu 22.04

As the zextras user user, execute

zextras$ zmcontrol status

Ubuntu 24.04

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

RHEL 8

As the zextras user user, execute

zextras$ zmcontrol status

RHEL 9

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

Change the Hostname

Update the system hostname:

# hostnamectl set-hostname node1.example.com

Verify that file /etc/hostname is up to date:

# cat /etc/hostname
node1.example.com

Update file /etc/hosts to map the new hostname to the Node IP:

# nano /etc/hosts
127.0.0.1 localhost
192.168.1.10 node1.example.com node1

Update Carbonio CE Configuration

Run the following command to update Carbonio CE interanal setting with the new hostname

# su - zextras -c "/opt/zextras/libexec/zmsetservername -n node1.example.com"

The output will be similar to:

Getting local config zimbra_server_hostname=srv1.example.com
Getting local config zimbra_ldap_userdn=uid=zimbra,cn=admins,cn=zimbra
Getting local config zimbra_ldap_password=jZl2hcK3
Getting local config ldap_is_master=true
Getting local config ldap_url=ldap://srv1.example.com:389
Getting local config ldap_master_url=ldap://srv1.example.com:389
Getting local config ldap_starttls_supported=0
Starting ldap...done.
Renaming srv1.example.com to node1.example.com
Shutting down zimbra...done.
Setting local config ldap_master_url=ldap://node1.example.com:389
Setting local config ldap_url=ldap://node1.example.com:389
Getting local config ldap_host=srv1.example.com
Setting local config ldap_host=node1.example.com
Getting local config av_notify_user=zextras@example.com
Getting local config av_notify_domain=example.com
Getting local config smtp_source=
Getting local config smtp_destination=
Setting local config zimbra_server_hostname=node1.example.com
Starting ldap...done.

Searching for ldap server entry...done.
Renaming cn=srv1.example.com,cn=servers,cn=zimbra...done.
Updating zimbraServiceHostname for cn=node1.example.com,cn=servers,cn=zimbra...done.
Updating zimbraPublicServiceHostname for cn=config,cn=zimbra...done.
Updating zimbraMailHost for uid=zextras,ou=people,dc=example,dc=com...done.
Updating zimbraMailHost for uid=spam.sdt2ak3pl,ou=people,dc=example,dc=com...done.
Updating zimbraMailHost for uid=ham.q_otnlxbi,ou=people,dc=example,dc=com...done.
Updating zimbraMailHost for uid=virus-quarantine.doj_qdcw,ou=people,dc=example,dc=com...done.
Updating zimbraMailHost for uid=galsync.eresranlan,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=zextras,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=spam.sdt2ak3pl,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=ham.q_otnlxbi,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=virus-quarantine.doj_qdcw,ou=people,dc=example,dc=com...done.
Updating zimbraMailTransport for uid=galsync.eresranlan,ou=people,dc=example,dc=com...done.
Services:
Getting local config ldap_port=389
Reinitializing the mta config...done.

Update Carbonio Mesh

After the hostname has been changed in Carbonio CE configuration, we need to notify Carbonio Mesh of the hostname change.

# sed -i 's/srv1.example.com/node1.example.com/g' /etc/zextras/service-discover/main.json
# systemctl restart service-discover

Verify SSL Certificates

If your SSL certificates are hostname-specific, you need to

• Reissue SSL certificates for the new hostname

• Deploy the new certificates

Start Carbonio CE Services

To start all Carbonio CE services, execute command

Ubuntu 22.04

As the zextras user user, execute

zextras$ zmcontrol start

Ubuntu 24.04

Hint

On Ubuntu 24.04, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

RHEL 8

As the zextras user user, execute

zextras$ zmcontrol start

RHEL 9

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

Verify the new configuration

At this point the Node configurations have all been modified with the new hostname. These tasks help you understand if everything operated correctly.

1. Check Carbonio status:

   Ubuntu 22.04

   As the zextras user user, execute

   zextras$ zmcontrol status
   

   Ubuntu 24.04

   Hint

   On Ubuntu 24.04, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

   RHEL 8

   As the zextras user user, execute

   zextras$ zmcontrol status
   

   RHEL 9

   Hint

   On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

2. Verify the e-mail flow by sending test emails

3. If the Node features also the Proxy Component, check on the Carbonio Admin Panel on port 6071 (see Access to the Web Interface) that the new hostname is reported correctly

Nodes Keeping Their Hostname

Even if a Node keeps its hostname (this is the case for Nodes 2 and 3 in scenarios B and Nodes 3 and 4 in C), nonetheless you need to let the Node know that the Master LDAP server (i.e., the Mesh & Directory Node) has changed hostname. This can be achieved by executing the following commands, as the zextras user.

Configure new Directory Server hostname

Make sure all Carbonio CE services are running

Ubuntu 22.04

As the zextras user user, execute

zextras$ zmcontrol status

Ubuntu 24.04

Hint

On Ubuntu 24.04, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

RHEL 8

As the zextras user user, execute

zextras$ zmcontrol status

RHEL 9

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

Verify how many references to the old Mesh & Directory Node are in the configuration.

zextras$ zmlocalconfig -s|grep srv1.example.com

Configure the Node to point to the new Mesh & Directory Node.

zextras$ zmlocalconfig -e ldap_host=srv2.example.com ldap_master_url=node1.example.com ldap_url=ldap://node1.example.com

Restart the services

Ubuntu 22.04

As the zextras user user, execute

zextras$ zmcontrol restart

Ubuntu 24.04

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).

RHEL 8

As the zextras user user, execute

zextras$ zmcontrol restart

RHEL 9

Hint

On RHEL 9, as the root user execute the new systemd commands that replace the zmcontrol command (see the dedicated box).