> For the complete documentation index, see [llms.txt](https://learn.netmaker.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.netmaker.io/getting-started/server-and-client-management/upgrading-your-client-and-server.md).

# Upgrading your Client and Server

## General upgrade instructions

These instructions assume a Docker Compose installation. Adapt them for other deployment methods.

Upgrade the server before upgrading any clients. Confirm it is healthy before continuing.

For v0.20 and later, the server configuration is stable:

{% 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 v0.20.5 and later, verify client upgrades in the UI. Upgrade earlier clients manually.

{% hint style="warning" %}
Review the version-specific paths before upgrading older releases.
{% endhint %}

### Upgrade notices

{% tabs %}
{% tab title="Server" %}

#### Server upgrades

**v1.7.0+**

Version v1.7.0 completes the SQL migration and introduces multi-tenancy bootstrap.

{% hint style="warning" %}
Run v1.6.0 successfully before upgrading an existing deployment to v1.7.0. Version v1.7.0 does not start until the v1.6.0 migration has completed.
{% endhint %}

1. Deploy v1.6.0 and confirm the server starts cleanly.
2. Upgrade to v1.7.0.
3. Confirm the migration completes and validate core functionality.

The schema and data update after a successful startup. Downgrades may not be supported afterwards.

**v1.5.1+**

{% hint style="warning" %}
Upgrade to v1.0.0 or later before upgrading to v1.5.1. Direct upgrades from earlier versions are unsupported.
{% endhint %}

Version v1.5.1 starts the migration from the key-value store to SQL. It migrates these tables:

* Users
* Roles
* Groups
* Networks
* Hosts

Later releases migrate the remaining tables.

**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 upgrade instructions above.
2. For v0.20.5 or later, check in the UI to confirm that all nodes have successfully upgraded to the new version.
   {% endtab %}

{% tab title="Client" %}

#### Client upgrades

As of v0.20.5, the Netclient should automatically upgrade itself if auto update is enabled on the device 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 target binary from [the fileserver](https://fileserver.netmaker.io/releases/download). Then run `./netclient install`.

For macOS and Windows, download and run the matching installer from [the fileserver](https://fileserver.netmaker.io/releases/download).
{% endtab %}
{% endtabs %}

### Version-specific upgrade paths

#### Upgrade to v1.0.0 from v0.17.1

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

**Before you begin**

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.

**Migration 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 v0.13.x

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

#### Critical notes for v0.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 before v0.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 v0.17.0 after v0.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 clients before v0.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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.