Change the Carbonio Hostname

Change the Carbonio Hostname#

This guide helps you in changing the hostnames of a Carbonio 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 Role

  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 Role (and the Directory Replica, if present), it is not relevant which Roles 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.

Example D, setup with Directory Replica Role

If one or more Directory Replica Roles are installed within your infrastructure, there are slight changes to the procedures described below. Please refer to Section Tasks for the Directory Replica Role for more information.

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 Role only.

Stop Carbonio Services

To stop all Carbonio services, execute command

As the zextras user user, execute

zextras$ zmcontrol status

As the zextras user user, execute

zextras$ zmcontrol status

As the zextras user user, execute

zextras$ zmcontrol status

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 Configuration

Run the following command to update Carbonio 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 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 Services

To start all Carbonio services, execute command

As the zextras user user, execute

zextras$ zmcontrol start

As the zextras user user, execute

zextras$ zmcontrol start

As the zextras user user, execute

zextras$ zmcontrol start

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:

    As the zextras user user, execute

    zextras$ zmcontrol status

    As the zextras user user, execute

    zextras$ zmcontrol status

    As the zextras user user, execute

    zextras$ zmcontrol status

    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 Role, 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 Role, 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 services are running

As the zextras user user, execute

zextras$ zmcontrol status

As the zextras user user, execute

zextras$ zmcontrol status

As the zextras user user, execute

zextras$ zmcontrol status

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

As the zextras user user, execute

zextras$ zmcontrol restart

As the zextras user user, execute

zextras$ zmcontrol restart

As the zextras user user, execute

zextras$ zmcontrol restart

Hint

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

Stop Carbonio Services

To stop all Carbonio services, execute command

As the zextras user user, execute

zextras$ zmcontrol status

As the zextras user user, execute

zextras$ zmcontrol status

As the zextras user user, execute

zextras$ zmcontrol status

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 Configuration

Run the following command to update Carbonio 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 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 Services

To start all Carbonio services, execute command

As the zextras user user, execute

zextras$ zmcontrol start

As the zextras user user, execute

zextras$ zmcontrol start

As the zextras user user, execute

zextras$ zmcontrol start

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:

    As the zextras user user, execute

    zextras$ zmcontrol status

    As the zextras user user, execute

    zextras$ zmcontrol status

    As the zextras user user, execute

    zextras$ zmcontrol status

    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 Role, 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 services are running

As the zextras user user, execute

zextras$ zmcontrol status

As the zextras user user, execute

zextras$ zmcontrol status

As the zextras user user, execute

zextras$ zmcontrol status

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

As the zextras user user, execute

zextras$ zmcontrol restart

As the zextras user user, execute

zextras$ zmcontrol restart

As the zextras user user, execute

zextras$ zmcontrol restart

Hint

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

Tasks for the Directory Replica Role#

If your infrastructure features a Directory Replica, you need to carry out these tasks on all Nodes. Depending if you change hostname on the Mesh & Directory Node only or also on the Replica, the commands to execute slightly differ.

  1. If you change hostname only the Mesh & Directory, execute

    zextras$ carbonio prov ms <hostname> zimbraLdapMasterURL ldap://node1.example.com:389

    Replace <hostname> with the actual hostname of the Node on which you are executing the command.

  2. If you change also the hostname of the Directory Replica, assuming its new hostname is replica1.example.com execute also

    zextras$ carbonio prov ms <hostname> zimbraLdapURL ldap://replica1.example.com:389

    Replace <hostname> with the actual hostname of the Node on which you are executing the command.

In both cases, when you executed the commands, restart all services

Attributes zimbraLdapMasterURL and zimbraLdapURL

  • zimbraLdapMasterURL ensures that write operations are consistently directed to the correct Directory Server, preserving data integrity

  • zimbraLdapURL ensures that the system can still authenticate users and access LDAP data even if one of the replicas is down.

In a Single-Server Carbonio setup, these values are typically the same. In a Multi-Server setup with LDAP replication, they will differ, with zimbraLdapURL listing all replicas and zimbraLdapMasterURL pointing only to the master.

Contents