Full Guide: Migrating ZeroTier Controller, ztncui and Data to a New Host

Introduction

ZeroTier-One is an innovative open-source networking software. Its advanced capabilities allow seamless connectivity across devices, irrespective of physical location, providing organizations with scalable and fortified network solutions. Complementing this software, ztncui serves as the web-based user interface, simplifying network management and offering comprehensive insights into ZeroTier networks.

Within this guide, I explain the precise procedure for migrating the ZeroTier-One controller and ztncui data from a "Donor Host" to a "Recipient Host." The term "Donor Host" refers to the original system hosting the current ZeroTier-One controller and ztncui. The term "Recipient Host" designates the destination system where we aim to transfer the controller and ztncui data, guaranteeing an uninterrupted continuation of network operations.

I created this step-by-step manual in response to a noticeable lack of decent resources online, which frequently provide inaccurate or misleading information. Its main goal is to equip system administrators with the knowledge and assurance needed to carry out successful migrations.

Please bear in mind that this guide is specifically designed for sysadmins using Debian or Debian-based distributions. It's important to note that the ztncui is installed from a DEB package, not as a Docker container. For RPM-based systems, the process will be nearly identical. I will assume you are familiar with the necessary procedures.

I hope that this guide will be very helpful to anyone who wants clear and reliable documentation of a process.

Donor Host

Step 1 : Stop the services:

• SSH into the Donor host.
• Run the following commands to stop the ztncui and zerotier-one services:

sudo systemctl stop ztncui
sudo systemctl stop zerotier-one        

Step 2 : Copy the Data:

• While still on the Donor host, copy the ztncui data directory to a safe location (e.g., an external drive or another directory):

sudo cp -a /opt/key-networks/ztncui/etc /path/to/backup_location        

• Copy the zerotier-one data directory to the same backup location:

sudo cp -a /var/lib/zerotier-one /path/to/backup_location        

Recipient Host

Step 1 : Install ZeroTier-One Controller and ztncui:

• SSH into the Recipient host.
• Make sure ZeroTier-One and ztncui are installed on the Recipient host. If not, install them using your package manager or follow the official installation instructions for ZeroTier.

Step 2 : Stop ZeroTier Controller and zerotier-one on the Recipient Host:

• Run the following commands to stop the ztncui and zerotier-one services on the Recipient host:

sudo systemctl stop ztncui
sudo systemctl stop zerotier-one        

Step 3 : Copy the Data from the Donor to the Recipient:

• Transfer the backed-up ztncui/etc directory from the Donor host to the Recipient host using a secure method like SCP or Rsync. Replace /path/to/backup_location with the actual path to the backup directory on the Donor host:

rsync -rva user@donor_host:/path/to/backup_location/etc /opt/key-networks/ztncui/        

• Transfer the backed-up zerotier-one directory from the Donor host to the Recipient host. Replace /path/to/backup_location with the actual path to the backup directory on the Donor host:

rsync -rva user@donor_host:/path/to/backup_location/zerotier-one /var/lib/        

Step 4 : Set Proper Ownership:

• On the Recipient host, ensure the ownership of the copied ztncui directory is correct:

ls -l /opt/key-networks/ztncui/etc        

• The files and directories should be owned by the appropriate user and group (e.g., ztncui user and ztncui group).

-rw------- 1 ztncui ztncui 148 Jul 26 09:48 default.passw
-rw------- 1 ztncui ztncui 435 Jul 26 09:48 passwd
drwxr-xr-x 2 ztncui ztncui 4096 Jul 26 09:48 storage
drwxr-x--- 2 ztncui ztncui 4096 Jul 26 09:48 tlsd        

• On the Recipient host, ensure the ownership of the copied zerotier-one directory is correct:

ls -l /var/lib/zerotier-one        

• The files and directories should be owned by the appropriate user and group (e.g., zerotier-one user and zerotier-one group).

-rw------- 1 zerotier-one zerotier-one       24 Jul 26 09:54 authtoken.secre
drwx------ 4 zerotier-one zerotier-one     4096 Jul 26 09:54 controller.d
-rw-r--r-- 1 zerotier-one zerotier-one      141 Jul 26 09:54 identity.public
-rw------- 1 zerotier-one zerotier-one      270 Jul 26 09:54 identity.secret
drwxr-xr-x 2 zerotier-one zerotier-one     4096 Jul 26 09:54 networks.d
drwxr-xr-x 2 zerotier-one zerotier-one     4096 Jul 27 12:22 peers.d
-rw-r--r-- 1 zerotier-one zerotier-one      570 Jul 26 09:54 planet
-rwxr-xr-x 1 zerotier-one zerotier-one 10892304 Jul 26 09:54 zerotier-cli
-rwxr-xr-x 1 zerotier-one zerotier-one 10892304 Jul 26 09:54 zerotier-idtool
-rwxr-xr-x 1 zerotier-one zerotier-one 10892304 Jul 26 09:54 zerotier-one
-rw-r--r-- 1 zerotier-one zerotier-one        4 Jul 26 09:58 zerotier-one.pid
-rw-r--r-- 1 zerotier-one zerotier-one        4 Jul 26 09:58 zerotier-one.port
-rw-r--r-- 1 zerotier-one zerotier-one      276 Jul 26 09:54 zerotier-one.te        

• If for some reason permissions are changed, fix the ownership of directories:

sudo chown -R ztncui:ztncui /opt/key-networks/ztncui/etc
sudo chown -R zerotier-one:zerotier-one /var/lib/zerotier-one        

Step 5 : Generate New Secret and Set Access Privileges:

• After ztncui upgrade, migration, or system kernel upgrade (effective after reboot), you need to generate a new secret for the controller and set correct access privileges.
• Run the following commands to create the .env file and set the necessary environment variables:

sudo sh -c "echo ZT_TOKEN=$(sudo cat /var/lib/zerotier-one/authtoken.secret) > /opt/key-networks/ztncui/.env"
sudo sh -c "echo HTTPS_PORT=3443 >> /opt/key-networks/ztncui/.env"
sudo sh -c "echo NODE_ENV=production >> /opt/key-networks/ztncui/.env"
sudo chmod 400 /opt/key-networks/ztncui/.env
sudo chown ztncui:ztncui /opt/key-networks/ztncui/.env        

Step 6 : Add Host IP to Access Web UI:

• Open the .env file using a text editor:

sudo nano /opt/key-networks/ztncui/.env        

• Add the following line to specify the Recipient host's IP address (replace <your-receipment-ip-address> with the actual IP address):

HTTPS_HOST=<your-receipment-ip-address>        

• Save the changes and exit the text editor.

Step 7 : Restart Controller UI (ztncui) and zerotier-one:

• Start the ZeroTier-One controller and ztncui services on the Recipient host:

sudo systemctl start ztncui
sudo systemctl start zerotier-one        

Step 8 : Verify the Migration:

• Check the status of the services to ensure they are running without errors:

sudo systemctl status ztncui
sudo systemctl status zerotier-one        

• Check the logs of the services for any potential issues:

sudo journalctl -u ztncui -u zerotier-one -f        

• Access the ZeroTier-One controller web interface (ztncui) from a web browser on the Recipient host using the IP address specified in the .env file, followed by the configured ztncui port (default is 3443).

After Successful Migration

Step 1 : Verify the Recipient Host:

• On the Recipient host, check that the ZeroTier controller (zerotier-one) and the network interface data (ztncui) are running correctly. Confirm that you can access the web interface and manage your ZeroTier networks.

Step 2 : Disable ZeroTier Processes on the Donor Host:

• As a best practice, after successfully migrating ZeroTier-One to the Recipient host, it's crucial to disable the ZeroTier processes on the donor host, especially to avoid conflicts with the migrated controller.
• To disable ZeroTier-One processes on the donor host, run the following commands:

sudo systemctl stop ztncui
sudo systemctl stop zerotier-one
sudo systemctl disable ztncui
sudo systemctl disable zerotier-one        

Step 3 : Optionally, Remove Old ZeroTier-One Data on the Donor Host:

• If you still intend to use ZeroTier-One on the donor host with a fresh identity, it's necessary to remove the /var/lib/zerotier-one directory so that the process can create a new one. Keep in mind that this will reset the identity of the donor host.
• To remove the old ZeroTier-One data directory on the donor host, run the following command:

sudo rm -rf /var/lib/zerotier-one        

• After removing the data directory, you can start ZeroTier-One on the donor host, and it will create a new identity:

sudo systemctl enable --now zerotier-one        

If you start a new identity of ZeroTier-One on the donor host, it will function as a separate and isolated controller from the one on the recipient host.

Congratulations! You have successfully migrated the ZeroTier-One controller identity and the ztncui data to the Recipient host. The services should now be accessible through the web interface, and your ZeroTier networks should be fully operational on the new host. Remember to double-check and verify all steps in the migration process before making any changes. Regularly back up critical data and configurations to ensure smooth transitions and avoid data loss during the migration process.

This guide is published under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).