Upgrade a quickstart network

Back up and upgrade your controller and routers with these steps.

Non-Docker Quickstart

Back up existing network

While you can certainly back up every file relating to your network, there are only a few that would be necessary. To back up the necessary files follow these steps:

1. Back up the database:
   1. Run the following:

   ziti edge db snapshot

   1. This will create a backup file in the same directory as your controller's DB file. It will have the same name as the controller DB file (usually ctrl.db) with a date and timestamp appended to it in the following format ctrl.db-YYYYMMDD-HHMMSS. If you're not sure where your DB file is located, you can find the location in the db section of your controller config.
2. Back up the controller PKI.
   1. Copy the PKI directory to a safe backup location (default path: $ZITI_HOME/quickstart/$(hostname -s)/pki/).
3. Back up the controller config file (default path: $ZITI_HOME/$(hostname -s).yaml).
4. Back up the environment file (default path: $ZITI_HOME/$(hostname -s).env).
5. Back up any router config files.
   1. If you used one of our quickstarts, the single edge router created defaults to $ZITI_HOME/$(hostname -s)-edge-router.yaml.

Stop existing services

If your network is using services to run your controller and/or router(s), stop those services.

Obtain the desired binary

Releases are available on the OpenZiti releases page. There is a helpful script function called getZiti that will obtain the binary and determine the correct architecture and OS for you.

Here is the process for using getZiti to obtain the latest binary. You may optionally add yes as an argument to the getZiti function to have the new ziti binary automatically added to your $PATH.

source /dev/stdin <<< "$(wget -qO- https://get.openziti.io/quick/ziti-cli-functions.sh)"
getZiti

note

After upgrading the binary, be sure to check your $PATH to ensure it is pointing to the new binary.

Update services

If you have services to start up the network, update them to use the new binary file.

v0.28.2 or Later

The ExecStart section on a systemd service will point to the full path to the old binary. Update this line to point to the path of the newly downloaded binary. Any path in the service file needs to be updated similarly.

For example, the following portion of the ExecStart:

.../ziti-v0.28.0/ziti" controller run 

will be updated to the following for v0.28.2 and later:

.../ziti-v0.30.4/ziti" controller run

v0.28.1 or Earlier

In version v0.28.2, ziti-controller, ziti-router, and ziti-tunnel were bundled into the ziti binary. Therefore, in these earlier versions, the path to the binary will not only point to the older version of the binary but the executable used will be ziti-router and ziti-controller. When upgrading, it is important to update the path(s) to use the new binary along with the command (ex. ziti controller rather than ziti-controller).

For example, the following portion of the ExecStart on a systemd file:

.../ziti-v0.27.0/ziti-controller" run 

will be updated to the following when upgrading v0.28.1 or earlier. Notice the version and executable change:

.../ziti-v0.30.4/ziti" controller run

Reload and start services

To reflect changes made to the services, reload the service daemon and start your services.

Docker Quickstart

Back up existing network

All the files used for the network are stored in the /persistent directory of the Docker containers. You may back up the files if desired.

1. Exec into the controller container.
2. Back up the database:
   1. Create a database snapshot by running ziti edge db snapshot. Here's one example of how you can do that:

   docker exec <ziti-controller-container> /var/openziti/ziti-bin/ziti edge db snapshot
   # List the files to find the snapshot filename
   docker exec <ziti-controller-container> ls -la /persistent/db

   1. This will create a backup file in the same directory as your controller's DB file. It will have the same name as the controller DB file (usually ctrl.db) with a date and timestamp appended to it in the following format ctrl.db-YYYYMMDD-HHMMSS. If you're not sure where your DB file is located, you can find the location in the db section of your controller config.
   2. Copy the backup file to a safe location outside the Docker container, here's an example:

   docker cp <ziti-controller-container>:/persistent/db/ctrl.db-YYYYMMDD-HHMMSS <local-backup-location>

3. Back up the controller PKI.
   1. Copy the PKI as was done with the database file (default path: /persistent/pki/).
4. Back up the controller config file (default path: /persistent/ziti-controller.yaml).
5. Back up the environment file (default path: /persistent/ziti.env).
6. Back up the router config files — depending on which quickstart you performed, you may have more than one (default path: /persistent/*-router*.yaml). Unfortunately, Docker does not support wildcard characters when using docker cp. This command will list the files in /persistent, from which you can craft your docker cp commands for each router config:

   docker exec -it ziti-controller ls -la

Stop the containers

1. Stop and remove the Docker containers but do not remove the volume.
   1. For docker-compose users, use docker compose down (do not use the -v option).
   2. For standalone Docker users, use docker stop <container1>, <container2>, ...

Obtain the desired version

1. If you used a .env file, update it to use the desired OpenZiti version. Otherwise, the OpenZiti version is likely specified in your run command. The line containing the OpenZiti version will look like this: openziti/quickstart:<version>. If the :<version> portion is not present in your command, it will pull the latest version.
2. Pull the desired image:
   1. For docker compose: docker compose pull
   2. For standalone Docker: docker pull openziti/quickstart:<version>

Start the OpenZiti containers

1. Start the network back up:
   1. Compose: docker compose up
   2. Standalone: modify the docker run command replacing openziti/quickstart:latest with your desired version.

Verify the upgrade

1. Run the following to confirm the version:

   docker exec <ziti-controller-container> /var/openziti/ziti-bin/ziti version

Upgrade versions <=v0.28.2

If your OpenZiti network was v0.28.3 or later, you can ignore this section.

A major change to environment variable names was performed in v0.28.3. If your network was v0.28.2 or earlier, you may optionally run the following commands to update your env file to use the updated environment variable names:

source /dev/stdin <<< "$(wget -qO- https://get.openziti.io/quick/ziti-cli-functions.sh)"
performMigration