Upgrading your Client and Server

Introduction

These steps will help you upgrade to the latest version of Netmaker. Note that all instructions here assume you have installed using docker compose. You may need to modify these steps depending on your setup.

As of v0.20+, the server configuration is stable, meaning you should only need to:

1

Update image tags

Change the associated docker image tags for the Netmaker server and Netmaker UI.

2

Restart services

Restart the server and UI using the new image (for example: docker compose up -d).

For migrating from v0.17.1, you can use the migration steps listed below under Upgrade from v0.17.1 to Latest

For older versions of Netmaker (pre-v0.17.1), you must first manually upgrade to v0.17.1 before running the migration script.

Client Upgrades (General)

As of v0.20.5, the Netclient should automatically upgrade itself when it detects a change in the server version. For prior versions of the netclient (or if this fails), you will need to manually upgrade the client.

For Linux and Freebsd: Download the netclient for your target version, OS, and arch, from the fileserver. Then run ./netclient install from the downloaded executable in your terminal.

For Mac and Windows: Download and run the installer (.EXE for Windows, .PKG for Mac) for your target version, OS, and arch, from the fileserver. Then, run the installer.

Server Upgrades (v0.20.0+)

Unless otherwise noted, for newer versions of Netmaker:

1

Connect to the server

SSH to the server hosting Netmaker.

2

Edit environment file

Open the netmaker.env file using a text editor.

3

Update image tags

Change UI_IMAGE_TAG and SERVER_IMAGE_TAG to the latest version.

4

Restart

Run docker compose up -d.

1. For versions prior to v0.20.5, follow the Client Upgrades instructions to upgrade your netclients.

2. For v0.20.5 or later, check in the UI to confirm that all nodes have successfully upgraded to the new version.

test line

Upgrade to latest from v0.17.1

These steps assume you have already upgraded your server and netclients to v0.17.1.

General Notes

1. The server should be upgraded before any clients.

2. Relays will need to be recreated after the server and all clients are upgraded. Relays are now only available on Pro.

3. If upgrading to Pro, a new license key and tennet id must be obtained from https://app.netmaker.io

4. As each netclient is updated, a new nodes, nodes, and gateways (if applicable) will be visible in the netmaker UI.

5. Extclient config files may have to be regenerated after the upgrade.

Steps

1

Download upgrade script

Download the nm-upgrade.sh script from: https://fileserver.netmaker.io/upgrade/nm-upgrade.sh

2

Run upgrade script

Make the script executable and run it.

3

Verify server node

After the upgrade, you should see only one node in the Netmaker UI. It will have the same name as the hostname of your server, rather than netmaker-1.

4

Upgrade netclients

Do not use packages to upgrade on Windows/Darwin; use the netclient binary to update.

5

Client-specific install commands

Linux/Freebsd/Darwin:

• On each client download the latest version of netclient and run the netclient install command.

Windows:

• On each client download https://fileserver.netmaker.io/latest/netclient-windows-amd64.exe

• Open a PowerShell window as Administrator and run:

  • net stop netclient

  • C:\Users\User\Downloads\netclient-windows-amd64.exe install

6

Verify clients in UI

As each netclient is updated, check that a new node, nodes, and gateways (if applicable) are visible in the Netmaker UI.

7

Recreate relays for Pro

If upgrading to Pro, recreate any relay gateways.

8

Verify extclient configs

Verify extclient config files are correct. Delete and regenerate if incorrect. For each peer in config file:

• the peer’s public key should be the same as the peer’s public key in the Netmaker UI

• the peer’s endpoint should be the same as the peer’s endpoint in the Netmaker UI

• the peer’s allowed ips should be the same as the peer’s allowed ips in the Netmaker UI

Your Netmaker server and clients should all now be running the latest version of Netmaker.

Critical Notes for 0.13.X

If upgrading from 0.12 to 0.13, refer to this gist: https://gist.github.com/afeiszli/f53f34eb4c5654d4e16da2919540d0eb

Critical Notes for 0.10.0

At the time of this writing, an upgrade process has not been defined for 0.10.0. DO NOT follow this documentation to upgrade from a prior version to 0.10.0. An upgrade process will be defined shortly. For now, if you seek to upgrade to 0.10.0, you must clear your server entirely (docker compose down --volumes), uninstall your netclients, and re-install netmaker + netclients.

Upgrade the Server (prior to 0.10.0)

To upgrade the server, you only need to change the docker image versions:

1

SSH to the server:

ssh root@my-server-ip

2

Stop compose:

docker compose down

3

Edit docker-compose:

vi docker-compose.yml

Change gravitl/netmaker:<version> and gravitl/netmaker-ui:<version> to the new version.

4

Start compose:

docker compose up -d

Upgrade the server after v0.16.1

There have been changes to the MQ after v0.16.1. You will need to make changes to the docker-compose.yml and get the new mosquitto.conf files. We recommend upgrading your server first before any clients.

Start by shutting down your server with:

docker compose down

You then need to get the updated mosquitto.conf file. You will also need to get the wait.sh file and make sure it is executable.

wget -O /root/mosquitto.conf https://raw.githubusercontent.com/gravitl/netmaker/master/docker/mosquitto.conf
wget -q -O /root/wait.sh https://raw.githubusercontent.com/gravitl/netmaker/develop/docker/wait.sh
chmod +x wait.sh

Then make the following changes to the docker-compose.yml file.

• change image tags in netmaker and netmaker-ui service sections to gravitl/netmaker:v.0.16.1.

In your netmaker service section:

• In the volumes section, change - shared_certs:/etc/netmaker to - mosquitto_data:/etc/netmaker

• In the environment section, add MQ_ADMIN_PASSWORD: "<CHOOSE_A_PASSWORD_YOU_WOULD_LIKE_TO_USE>"

In the mq service section:

• Add command: ["/mosquitto/config/wait.sh"]

• Add an environment section and add NETMAKER_SERVER_HOST: "https://api.NETMAKER_BASE_DOMAIN"

• In the volumes, add - /root/wait.sh:/mosquitto/config/wait.sh

• You need to make some changes to the labels. A few of them just need mqtts to be mqtt. The labels should look like this:

- traefik.enable=true
- traefik.tcp.routers.mqtt.rule=HostSNI(`broker.NETMAKER_BASE_DOMAIN`)
- traefik.tcp.routers.mqtt.tls.certresolver=http
- traefik.tcp.services.mqtt.loadbalancer.server.port=8883
- traefik.tcp.routers.mqtt.entrypoints=websecure

Your MQ section should look like this after the changes.

mq:
container_name: mq
image: eclipse-mosquitto:2.0.11-openssl
depends_on:
  - netmaker
restart: unless-stopped
command: ["/mosquitto/config/wait.sh"]
environment:
  NETMAKER_SERVER_HOST: "https://api.NETMAKER_BASE_DOMAIN"
volumes:
  - /root/mosquitto.conf:/mosquitto/config/mosquitto.conf
  - /root/wait.sh:/mosquitto/config/wait.sh
  - mosquitto_data:/mosquitto/data
  - mosquitto_logs:/mosquitto/log
expose:
  - "8883"
labels:
  - traefik.enable=true
  - traefik.tcp.routers.mqtt.rule=HostSNI(`broker.NETMAKER_BASE_DOMAIN`)
  - traefik.tcp.routers.mqtt.tls.certresolver=http
  - traefik.tcp.services.mqtt.loadbalancer.server.port=8883
  - traefik.tcp.routers.mqtt.entrypoints=websecure

You should be all set to:

docker compose up -d

Note: Your clients will show in warning until they are also upgraded. The upgrade for clients is the regular upgrade, then do a netclient pull.

If your docker logs mq show repeated "Waiting for netmaker server to startup" after longer than usual, check if your Traefik certs are generated correctly. You can try to resolve with:

docker restart traefik

Example expected MQ logs:

Waiting for netmaker server to startup
...
Starting MQ...
1665067766: mosquitto version 2.0.11 starting
...
1665067769: New client connected from 172.21.0.2:34004 as L0vUDgN0IZFru9VaS6HoRL5 (p2, c1, k60, u'Netmaker-Admin').

Upgrade the server to use 0.17.0 after Upgrading for 0.16.3

Version 0.17.0 uses Caddy instead of Traefik.

To set up Caddy you’ll need to configure the Caddyfile as follows.

Community Edition:

wget -O /root/Caddyfile "https://raw.githubusercontent.com/gravitl/netmaker/master/docker/Caddyfile"

Professional Edition:

wget -O /root/Caddyfile "https://raw.githubusercontent.com/gravitl/netmaker/master/docker/Caddyfile-pro"

Once you have a Caddyfile you’ll need to run these two commands:

sed -i "s/NETMAKER_BASE_DOMAIN/$NETMAKER_BASE_DOMAIN/g" /root/Caddyfile
sed -i "s/YOUR_EMAIL/$EMAIL/g" /root/Caddyfile

Where $NETMAKER_BASE_DOMAIN is the base domain you used for your Netmaker setup and $YOUR_EMAIL is your email address.

If users still want to keep using Traefik as the reverse-proxy instead of Caddy for v0.17.0 and above, refer to this docker-compose file: https://gist.github.com/alphadose/1602e5dcba500f75ab0b873d4441236b

Edit the above docker-compose file:

sed -i 's/NETMAKER_BASE_DOMAIN/<your base domain>/g' docker-compose.yml
sed -i 's/SERVER_PUBLIC_IP/<your server ip>/g' docker-compose.yml
sed -i 's/REPLACE_MASTER_KEY/<your generated key>/g' docker-compose.yml
sed -i "s/REPLACE_MQ_ADMIN_PASSWORD/<your generated password>/g" docker-compose.yml

After that finally start the netmaker server:

sudo docker compose up -d

Upgrade the Clients (prior to 0.10.0)

To upgrade the client, you must get the new client binary and place it in /etc/netclient. Depending on the new vs. old version, there may be minor incompatibilities (discussed below).

1

Find release

Visit: https://github.com/gravitl/netmaker/releases/

2

Download binary

Find the appropriate binary for your machine and download, e.g.:

wget https://github.com/gravitl/netmaker/releases/download/vX.X.X/netclient-myversion

3

Install binary

Rename binary to netclient and move to folder, e.g.:

mv netclient-myversion /etc/netclient/netclient

4

Verify and pull

Check version:

netclient --version

Then run:

netclient pull

This helps ensure any newly added fields are now present.

You may run into a “panic” based on missing fields and your version mismatch. In such cases, you can either:

• Add the missing field to /etc/netclient/config/netconfig-yournetwork and then run netclient checkin

or

• Leave and rejoin the network