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:
Change the associated docker image tags for the Netmaker server and Netmaker UI
Restart the server and UI using the new image (e.g. “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 (.MSI 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:
SSH to the server hosting Netmaker
Open the “netmaker.env” file using a text editor
Change UI_IMAGE_TAG and SERVER_IMAGE_TAG to the latest version
Run “docker-compose up -d”
For versions prior to v0.20.5, follow the Client Upgrades instructions to upgrade your netclients.
For v0.20.5 or later, check in the UI to confirm that all hosts have successfully upgraded to the new version.
Upgrade to latest from v0.17.1¶
These steps assume you have already upgraded your server and netclients to v0.17.1.
The server should be upgraded before any clients.
Relays will need to be recreated after the server and all clients are upgraded. Relays are now only available on Pro.
If upgrading to Pro, a new license key and tennet id must be obtained from https://app.netmaker.io
As each netclient is updated, a new host, nodes, and gateways (if applicable) will be visible in the netmaker UI.
Extclient config files may have to be regenerated after the upgrade.
Download the nm-upgrade.sh script from https://fileserver.netmaker.io/upgrade/nm-upgrade.sh
Make the script executable and run it.
After the upgrade, you should see only one host in the Netmaker UI. It will have the same name as the hostname of your server, rather than netmaker-1.
Upgrade your netclients do not use packages to upgrade on window/darwin, use the netclient binary to update
Linux/Freebsd/Darwin: On each client download the latest version of netclient and run the netclient install command
- Windows: On each client download the latest version of netclient-windows-amd64.exe and netclient-gui-windows-amd64.exe
open Powershell window as Administrator and run the following commands:
cp c:\\Users\User\Downloads\netclient-gui-windows-amd64.exe c:\\Windows\System32\netclient-gui-windows-amd64.exe C:\\Program Files (x86)\gui.exe
net stop netclient
As each netclient is updated, check that a new host, nodes, and gateways (if applicable) are visible in the Netmaker UI.
If upgrading to Pro, recreate any relay gateways
Verify extcient 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:
Change gravitl/netmaker:<version> and gravitl/netmaker-ui:<version> to the new version.
Save and close the file
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
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
- In your netmaker service section:
In the volumes section, change
In the environment section, add
- In the mq service section:
Add an environment section and add
In the volumes, add
You need to make some changes to the labels. a few of them just need
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
docker logs mq should be showing logs like this:
Waiting for netmaker server to startup Waiting for netmaker server to startup Waiting for netmaker server to startup Waiting for netmaker server to startup Waiting for netmaker server to startup Waiting for netmaker server to startup Waiting for netmaker server to startup Starting MQ... 1665067766: mosquitto version 2.0.11 starting 1665067766: Config loaded from /mosquitto/config/mosquitto.conf. 1665067766: Loading plugin: /usr/lib/mosquitto_dynamic_security.so 1665067766: Opening ipv4 listen socket on port 8883. 1665067766: Opening ipv6 listen socket on port 8883. 1665067766: Opening ipv4 listen socket on port 1883. 1665067766: Opening ipv6 listen socket on port 1883. 1665067766: mosquitto version 2.0.11 running 1665067769: New connection from 172.21.0.2:34004 on port 1883. 1665067769: New client connected from 172.21.0.2:34004 as L0vUDgN0IZFru9VaS6HoRL5 (p2, c1, k60, u'Netmaker-Admin'). 1665067769: New connection from 172.21.0.2:34006 on port 1883. 1665067769: New client connected from 172.21.0.2:34006 as ydmOjmIcw9nNaT1GB1q97Se (p2, c1, k60, u'Netmaker-Server').
If you see mq logs about waiting for netmaker server to startup after longer period than usual, check if your traefik certs are generated correctly. You can try to resolve with
docker restart traefik
Upgrade the server to use 0.17.0 after Upgrading for 0.16.3¶
Version 0.17.0 uses Caddy instead of traefik.
Open a Terminal window (shell prompt). To set up Caddy you’ll need to configure the Caddyfile as follows.
If you are using the Community Edition of Netmaker use this command:
wget -O /root/Caddyfile "https://raw.githubusercontent.com/gravitl/netmaker/master/docker/Caddyfile"
If you are using the Professional Edition of Netmaker use this command:
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 (the part after “dashboard.” in your Dockerfile) 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).
Find the appropriate binary for your machine.
Download. E.x.: wget https://github.com/gravitl/netmaker/releases/download/vX.X.X/netclient-myversion
Rename binary to netclient and move to folder. E.x.: mv netclient-myversion /etc/netclient/netclient
netclient –version (confirm it’s the correct version)
This last step 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”
Leave and rejoin the network