---
title: "Upgrading"
canonical_url: https://www.superlogical.com/rex/docs/linux/upgrading
---

# Upgrading

You can upgrade Rex using your standard package manager that you installed
with. If you used the `install.sh` script, running that again is also safe;
it merely detects and invokes your package manager.

**Upgrading ends every session on a running shared server.** The login
server and personal servers keep their sessions. See
[What Restarts](#what-restarts).

## Upgrading the Package

| Installed with   | Upgrade                                                            |
| ---------------- | ------------------------------------------------------------------ |
| Debian, Ubuntu   | `sudo apt-get update && sudo apt-get install --only-upgrade rex`   |
| Fedora, RHEL     | `sudo dnf upgrade --refresh rex`                                   |
| openSUSE         | `sudo zypper update rex`                                           |
| Alpine           | `apk update && apk add -u rex`                                     |
| Nix profile      | `nix profile upgrade --regex '.*superlogical.*'`                   |
| Install script   | Run the same command you installed with.                           |
| `--tarball`      | Run the install script again with `--tarball`.                     |

When you run the install script again, pass the same `--channel` you
installed with. Without it, the script switches the repository to the
default channel.

## What Restarts

The package restarts the Rex services that are running, and leaves stopped
ones stopped. In containers without a running init system, it restarts
nothing.

| Server          | On upgrade        | Sessions | Runs the new version    |
| --------------- | ----------------- | -------- | ----------------------- |
| Shared server   | Restarts          | End      | Right away              |
| Login server    | Restarts          | Survive  | Right away              |
| Account servers | Keep running      | Survive  | When their sessions end |
| Personal server | Keeps running     | Survive  | When it stops           |

**Restarting the shared server ends every session and every program in
them.** Upgrade when nobody has work running, or
[hold the package](#holding-an-upgrade) until then.

The servers the login server starts for each account keep running the
version they started with. Each one stops around 10 seconds after its last
session ends and its last client disconnects, and the next connection
starts it again on the new version. On machines with systemd-logind, a
person can switch sooner by running `rex server stop` on the machine as
themselves, which ends their sessions.

A personal server that a `rex` command started stops on its own once it's
idle, so it picks up the new version by itself. One started with
`rex server start` keeps running the old version until you stop it and
start it again:

```sh
rex server stop
rex server start
```

## Checking the Version

`rex version` shows the version that's installed, and `rex server status`
shows the version of the server that's running:

```sh
rex version
rex server status
```

If the first line of `rex version` doesn't match the `version:` line of
`rex server status`, that server is still running the old version. Through
the login server, `rex server status` shows the version of your account's
server.

## Holding an Upgrade

To keep Rex at its current version until you're ready:

| Package manager | Hold                          | Release                         |
| --------------- | ----------------------------- | ------------------------------- |
| apt             | `sudo apt-mark hold rex`      | `sudo apt-mark unhold rex`      |
| dnf             | `sudo dnf versionlock add rex` | `sudo dnf versionlock delete rex` |
| zypper          | `sudo zypper addlock rex`     | `sudo zypper removelock rex`    |
| apk             | `apk add rex=VERSION`         | `apk add -u rex`                |

On RHEL and its rebuilds, `versionlock` is a plugin. Install it with
`sudo dnf install 'dnf-command(versionlock)'`. Fedora has it built in.

On Alpine, `VERSION` is the full version, such as `0.1.0-r0`.
`apk info -e -v rex` shows the one that's installed.

## Keeping Your Changes

Upgrades keep your changes to:

- The accounts file, `/etc/rex/accounts.jsonc`
- The PAM policy, `/etc/pam.d/rex-login-server`
- Drop-ins for `rex.service` and `rex-login-server.service`
- `/etc/conf.d/rex` and `/etc/conf.d/rex-login-server` on Alpine

Upgrades replace the services themselves, `rex.service`,
`rex-login-server.service`, and the scripts in `/etc/init.d`. Put your
changes in a drop-in or `/etc/conf.d` instead, as
[Customizing the Service](https://www.superlogical.com/rex/docs/linux/shared-server.md#customizing-the-service)
shows.

If you changed a config file and a new version of Rex changes it too, you
keep yours, and the new one is saved beside it:

| Package manager | New file saved as | Notes                                           |
| --------------- | ----------------- | ----------------------------------------------- |
| apt             | `.dpkg-dist`      | apt asks first. The install script doesn't ask. |
| dnf, zypper     | `.rpmnew`         |                                                 |
| apk             | `.apk-new`        |                                                 |

Compare the two and copy over any changes you want. The SSH fallback,
`/etc/ssh/ssh_config.d/50-rex.conf`, is the exception on dnf and zypper: an
upgrade replaces it and saves yours as `.rpmsave`.

## Client and Server Versions

Rex for Mac and the server don't need to be the same version, and either
one can be newer. A newer client can't use features an older server
doesn't have. When it needs one, it says so:

```
this server is too old for rex client ls; it needs Rex 0.1.0 or later
```

If the two are too far apart to work together at all, the server refuses
the connection, and the message ends with `update the server` or
`update the client`.

## Switching Channels and Downgrading

[Switching channels](https://www.superlogical.com/rex/docs/linux/installation.md#channels) from snapshot to preview
or stable upgrades Rex as usual. Switching back to snapshot is a downgrade,
because snapshot versions sort below every release. A downgrade doesn't
happen on its own, so ask for the version you want:

| Package manager | List versions                       | Downgrade                                         |
| --------------- | ----------------------------------- | ------------------------------------------------- |
| apt             | `apt-cache madison rex`             | `sudo apt-get install --allow-downgrades rex=VERSION` |
| dnf             | `dnf list --showduplicates rex`     | `sudo dnf downgrade rex-VERSION`                  |
| zypper          | `zypper search -s -x rex`           | `sudo zypper install --oldpackage rex-VERSION`    |
| apk             | `apk search -a -x rex`              | `apk add rex=VERSION`                             |

A downgrade restarts services the same way an upgrade does. Your data is
safe across a downgrade. A version of Rex that finds data written in a
newer format refuses to use it instead of overwriting it.

## Changing How Rex Is Installed

Keep one copy of Rex on a machine. The `--tarball` binary in
`/usr/local/bin` comes before the package's `/usr/bin/rex` on the usual
`PATH`, so with both installed, `rex` commands and the personal servers
they start run the tarball's version, whichever one you upgrade. To see
every `rex` on your `PATH`:

```sh
which -a rex
```

To move from `--tarball` to a package, install the package, then remove
the binary:

```sh
sudo rm /usr/local/bin/rex
```

To move from a package to `--tarball` or Nix, remove the package first:

| Package manager | Remove                    |
| --------------- | ------------------------- |
| apt             | `sudo apt-get remove rex` |
| dnf             | `sudo dnf remove rex`     |
| zypper          | `sudo zypper remove rex`  |
| apk             | `apk del rex`             |

Removing the package stops and disables its services, which ends every
session on the shared server. It keeps `/var/lib/rex` and the `rex`
account, so installing the package again picks up the shared server's
data.

The install script and the commands on the other install tabs set up the
same repository, so you can switch between them. On Alpine, the script
puts the repository in `/etc/apk/repositories.d/rex.list`, and the
**Alpine** tab adds it to `/etc/apk/repositories`. Keep only one of them.

## NixOS

Update the Rex input in your flake, then switch:

```sh
nix flake update rex
sudo nixos-rebuild switch --flake .
```

`nixos-rebuild switch` restarts the Rex service when Rex changes, the same
as a package upgrade: the shared server's sessions end, and account servers
keep the old version until their sessions end.

`flake.lock` holds Rex at its current version until you update it, so
there's nothing else to do to hold an upgrade.