# 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:

{% stepper %}
{% step %}

### Update image tags

Change the associated docker image tags for the Netmaker server and Netmaker UI.
{% endstep %}

{% step %}

### Restart services

Restart the server and UI using the new image (for example: `docker compose up -d`).
{% endstep %}
{% endstepper %}

For migrating from v0.17.1, you can use the migration steps listed below under [Upgrade from v0.17.1 to Latest](#upgrade-to-latest-from-v0171)

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](https://fileserver.netmaker.io/releases/download). 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](https://fileserver.netmaker.io/releases/download). Then, run the installer.

## Server Upgrades (v1.5.1+)

**Upgrade Notice for v1.5.1+**

* **Prerequisites**: To upgrade to v1.5.1 or later successfully, you must be running at least version v1.0.0. Direct upgrades from versions earlier than v1.0.0 to v1.5.1 are not supported.
* **Schema Migration**: v1.5.1 begins a schema migration process, moving all tables from a key-value store to SQL. The following tables are migrated in this version:
  * Users
  * Roles
  * Groups
  * Networks
  * Hosts
* **Note**: Additional tables will be migrated in future releases.

## Server Upgrades (v0.20.0+)

Unless otherwise noted, for newer versions of Netmaker:

{% stepper %}
{% step %}

### Connect to the server

SSH to the server hosting Netmaker.
{% endstep %}

{% step %}

### Edit environment file

Open the `netmaker.env` file using a text editor.
{% endstep %}

{% step %}

### Update image tags

Change `UI_IMAGE_TAG` and `SERVER_IMAGE_TAG` to the latest version.
{% endstep %}

{% step %}

### Restart

Run `docker compose up -d`.
{% endstep %}
{% endstepper %}

1. For versions prior to v0.20.5, follow the [Client Upgrades](#client-upgrades-general) 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](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

{% stepper %}
{% step %}

### Download upgrade script

Download the `nm-upgrade.sh` script from: <https://fileserver.netmaker.io/upgrade/nm-upgrade.sh>
{% endstep %}

{% step %}

### Run upgrade script

Make the script executable and run it.
{% endstep %}

{% step %}

### 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`.
{% endstep %}

{% step %}

### Upgrade netclients

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

{% step %}

### Client-specific install commands

Linux/Freebsd/Darwin:

* On each client download [the latest version](https://fileserver.netmaker.io/latest) 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`
    {% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### Recreate relays for Pro

If upgrading to Pro, recreate any relay gateways.
{% endstep %}

{% step %}

### 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
  {% endstep %}
  {% endstepper %}

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:

{% stepper %}
{% step %}
SSH to the server:

```bash
ssh root@my-server-ip
```

{% endstep %}

{% step %}
Stop compose:

```bash
docker compose down
```

{% endstep %}

{% step %}
Edit docker-compose:

```bash
vi docker-compose.yml
```

Change `gravitl/netmaker:<version>` and `gravitl/netmaker-ui:<version>` to the new version.
{% endstep %}

{% step %}
Start compose:

```bash
docker compose up -d
```

{% endstep %}
{% endstepper %}

## 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:

```bash
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.

```bash
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:

```plaintext
- 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.

```plaintext
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:

```bash
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:

```bash
docker restart traefik
```

Example expected MQ logs:

```plaintext
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:

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

Professional Edition:

```bash
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:

```bash
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:

```bash
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:

```bash
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).

{% stepper %}
{% step %}

### Find release

Visit: <https://github.com/gravitl/netmaker/releases/>
{% endstep %}

{% step %}

### Download binary

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

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

{% endstep %}

{% step %}

### Install binary

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

```bash
mv netclient-myversion /etc/netclient/netclient
```

{% endstep %}

{% step %}

### Verify and pull

Check version:

```bash
netclient --version
```

Then run:

```bash
netclient pull
```

This helps ensure any newly added fields are now present.
{% endstep %}
{% endstepper %}

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.netmaker.io/getting-started/server-and-client-management/upgrading-your-client-and-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.