Upgrading · Rex Docs
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. On FreeBSD, nothing restarts until you restart it. See FreeBSD.
Upgrading the Package Copy link to this section
| 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 |
| Arch Linux | sudo pacman -Syu |
| Omarchy | omarchy update |
| Alpine | apk update && apk add -u rex |
| FreeBSD | pkg upgrade -r rex 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. |
| Amazon Linux 2 | Run the install script again. |
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 Copy link to this section
The package restarts the Rex services that are running, and leaves stopped ones stopped. In containers without a running init system, it restarts nothing, and neither does the FreeBSD package. See FreeBSD.
The package never restarts rex.socket or rex-login-server.socket. A server that a socket started restarts like any other, and one that hasn’t started yet runs the new version when the first client connects. If a new version changes a socket unit, the change applies once you stop the socket and its service and start the socket again, or at the next reboot.
| 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 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:
rex server stop
rex server start
Checking the Version Copy link to this section
rex version shows the version that’s installed, and rex server status shows the version of the server that’s running:
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 Copy link to this section
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 |
| pacman | Add IgnorePkg = rex under [options] in /etc/pacman.conf |
Remove that line |
| apk | apk add rex=VERSION |
apk add -u rex |
| pkg | pkg lock rex |
pkg unlock 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 Copy link to this section
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,rex-login-server.service, and their sockets /etc/conf.d/rexand/etc/conf.d/rex-login-serveron Alpine/etc/rc.confon FreeBSD
Upgrades replace the services themselves, rex.service, rex-login-server.service, rex.socket, rex-login-server.socket, the scripts in /etc/init.d, and the scripts in /usr/local/etc/rc.d on FreeBSD. On FreeBSD, they replace the PAM policy too. See FreeBSD. Put your changes in a drop-in or /etc/conf.d instead, as 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 |
|
| pkg | .sample |
Only the accounts file. pkg updates the sample on every upgrade. |
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 Copy link to this section
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 Copy link to this section
Switching 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 |
| pacman | One version only. See Arch Linux. | sudo pacman -U URL |
| apk | apk search -a -x rex |
apk add rex=VERSION |
| pkg | pkg search -r rex rex |
See FreeBSD. |
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 Copy link to this section
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:
which -a rex
To move from --tarball to a package, install the package, then remove the binary:
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 |
| pacman | sudo pacman -R rex |
| apk | apk del rex |
| pkg | pkg delete rex |
Removing the package stops and disables its services and sockets, which ends every session on the shared server. rex-bin from the AUR doesn’t, so stop and disable them yourself first. See Arch Linux.
Removing the package keeps /var/lib/rex and the rex account, so installing the package again picks up the shared server’s data. On FreeBSD, it keeps /var/db/rex, and your settings in /etc/rc.conf.
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 Copy link to this section
Update the Rex input in your flake, then switch:
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.
FreeBSD Copy link to this section
pkg can’t restart services, so after an upgrade, the services that were running keep the old version. pkg says which ones at the end of its output, and so does the install script. Restart each one when you’re ready:
service rex restart
service rex-login-server restart
Restarting rex ends every session on the shared server, the same as on Linux. Restarting rex-login-server keeps each account’s server and its sessions, and they keep the old version until their sessions end.
Upgrades keep your changes to the accounts file, but replace the PAM policy in /usr/local/etc/pam.d. To change the policy, edit a copy in /etc/pam.d instead, as Login Server shows.
pkg doesn’t downgrade with pkg install, so delete the newer version first. Deleting stops both services, which ends every session on the shared server:
pkg delete rex
pkg install -r rex rex-VERSION
VERSION is the full version, such as 0.0.1792508098.g07b896. pkg info rex shows the one that’s installed.