# Linux Distribution Upgrade

Need to bump your server’s host OS to a new major version? We can handle the whole upgrade for you for a one-time fee, start to finish. Or, if you’d rather do it yourself at no extra cost, here’s how.

## Ubuntu

Please use **LTS** (Long Term Support) versions of Ubuntu only. We recommend using the [latest LTS version](https://wiki.ubuntu.com/Releases#List_of_releases) available at the time of installation.

### 1. Take a backup

**Hosting customers**: Daily backup (snapshot) is taken automatically every day, the backups are retained for 7 days, you don’t need to do anything.

**On-premises customers**: Make sure to back up your server before proceeding. All cloud providers have some kind of backup functionality and make snapshots either automatically or on-demand (manually).

### 2. Set up a fallback port

During the upgrade process, the SSH process on your host may be restarted and you may lose connectivity.

The upgrade process usually opens another fallback SSH port (`1022`) that may be used to get back to the upgrade process. Though the port will be opened automatically, you need to update your firewalls to allow incoming connections to this port.

Also, ensure the `screen` utility is installed on your system, and **start a screen session before proceeding**:

```bash
screen -S upgrade
```

If you lose connectivity during the upgrade, reconnect with `screen -r upgrade`. See [resuming a screen session](https://serverfault.com/a/427004) for details.

**Hosting customers**: the `1022` port is already open on the provider-level firewall, so you only need to update the on-server firewall:

```bash
ufw allow 1022/tcp
```

**On-premises customers**:

1. Update your provider-level firewall rules to allow connectivity to the `1022` (TCP) port, if you have one
2. Update the on-server firewall to allow incoming connections to the fallback port:
   
   ```bash
   ufw allow 1022/tcp
   ```

### 3. Update the system

Before performing the actual distribution upgrade, make sure your system is up-to-date:

```bash
# Update the package list
apt-get update
# Upgrade the system packages
apt-get dist-upgrade
```

You *may* reboot your server after this step, if prompted to do so.

### 4. Unpin Docker

We pin Docker to a specific version on your server to prevent accidental upgrades to a newer release that may not yet be compatible. Before performing the distribution upgrade, you must remove those pins, otherwise the upgrade process may fail to resolve package dependencies.

```bash
# Remove the apt-mark holds
apt-mark unhold docker-ce docker-ce-cli containerd.io docker-buildx-plugin
# Remove the apt-preferences block
rm -f /etc/apt/preferences.d/docker-ce-block
```

After the distribution upgrade is complete and you have run maintenance via [Ketesa Server Actions](https://etke.cc/help/extras/ketesa/#server-actions), the pins will be re-applied automatically.

### 5. Upgrade to the new release

Finally, run the upgrade command:

```bash
do-release-upgrade
```

Follow the on-screen instructions. They are quite straightforward.

> **Note**: if you are upgrading from an older LTS release (e.g., Ubuntu 20.04 while the currently supported LTS release is Ubuntu 24.04), you may need to repeat the process multiple times, as Ubuntu only supports direct upgrades between consecutive LTS releases. We recommend always upgrading to the **latest LTS** version available.
> 
> When doing a multi-hop upgrade, run maintenance after each intermediate release before continuing to the next one. Maintenance will re-pin Docker, so you will need to **repeat step 4 (Unpin Docker)** before each subsequent `do-release-upgrade`.

## Post-upgrade steps

After the upgrade is complete:

1. **Close the fallback port** you opened in step 2:
   
   ```bash
   ufw delete allow 1022/tcp
   ```
2. **Run maintenance** via [Ketesa Server Actions](https://etke.cc/help/extras/ketesa/#server-actions). This will:
   
   - Re-apply the Docker version pin
   - Update the Docker apt repository to reference the new distro codename (without this, apt may show errors or install unexpected Docker versions)
   - Ensure your server is fully reconfigured for the new OS release

If your Matrix server happens to be down after the upgrade, [contact us](https://etke.cc/contacts/) and we will help you bring it back online.


---
* [llms.txt](https://etke.cc/llms.txt): full site index in markdown