Installing on Linux

Rex can run as a server on Linux so that clients can access it as a remote host.

IMPORTANT: Rex on Linux is in testing. Only members of a Linux testing wave can install it for now, and the install commands show below once you’ve logged in.

System Requirements

The Alpine package holds the musl build of Rex. It’s dynamically linked, not static, because Rex loads PAM at run time. On other distributions, including other musl ones, install the binary alone with --tarball, which picks the musl build on a musl system.

Install

The install script (install.sh) is a convenience that adds the Rex repository to apt, dnf, zypper, or apk and installs the rex package, so updates arrive with your normal system updates. Running it again upgrades Rex, as Upgrading covers. To see what it would do first, add -s -- --dry-run after sh. On Arch, NixOS, and other distributions without a Rex repository, it explains the options and exits.

Pass options after sh -s --. For example, to install only the binary on a distribution without a Rex repository, such as Arch:

curl -fsSL -u "rex:$REX_PACKAGE_TOKEN" https://pkgs.superlogical.com/rex/install.sh | sh -s -- --tarball

Channels

Rex publishes to three channels:

The install script defaults to stable but until the first stable release exists, will fall back to preview and say so in the output.

To switch channels later, change the channel name in the repository file: Suites: in /etc/apt/sources.list.d/rex.sources, or the name and baseurl lines in /etc/yum.repos.d/rex.repo or zypper’s repository. On Alpine, change it in /etc/apk/repositories.d/rex.list if the install script set up the repository, or in the Rex line in /etc/apk/repositories if you added it yourself, then run apk update.

Moving from snapshot to preview or stable upgrades Rex. Moving back to snapshot is a downgrade, which you have to ask for. See Switching Channels and Downgrading.

Package Contents

The rex package installs:

On Alpine, OpenRC scripts at /etc/init.d/rex and /etc/init.d/rex-login-server take the place of the two services. The package never ships /etc/conf.d/rex or /etc/conf.d/rex-login-server, so your changes to the services go there.

Upgrades keep your changes to the accounts file and the PAM policy. See Keeping Your Changes.

Alpine

Alpine has no sudo by default, so run the commands on these pages as root. Alpine uses OpenRC instead of systemd. Where a page gives a systemctl command, use the OpenRC form:

/etc/conf.d/rex is a shell script that OpenRC reads before the service’s own script, so a command_args set there replaces the server’s command line. Shared Server and Remote Access show what to put in it.

The services need OpenRC, which a full Alpine install has. Containers often don’t. To install it, run apk add openrc.

On musl, who and last don’t list Rex sessions, because musl keeps no utmp or wtmp. lastlog records logins as usual.

Nix and NixOS

Rex has a flake for each channel, at https://pkgs.superlogical.com/rex/nix/<channel>.tar.gz. It packages the release binary rather than building Rex from source, for x86-64 and ARM64 Linux. Until the first release, Nix needs the token in a netrc file. Where that file goes depends on which Nix you installed:

• Nix from nixos.org, or NixOS, reads /etc/nix/netrc, as the Nix tab shows.
• Determinate Nix ignores /etc/nix/netrc and ~/.config/nix/netrc. Its daemon builds /nix/var/determinate/netrc from the files listed under authentication.additionalNetrcSources in /etc/determinate/config.json, as the Determinate tab shows. Don’t edit /nix/var/determinate/netrc itself, because the daemon rewrites it.

To tell which you have, run nix --version. Determinate Nix prints Determinate Nix.

If /etc/determinate/config.json already exists, the Determinate tab’s second command stops with File exists instead of replacing it. Add /etc/determinate/rex.netrc to its additionalNetrcSources list yourself, then run the remaining commands. Determinate Nix makes the merged netrc file readable by every user on the machine, token included.

To try Rex without installing it:

nix run https://pkgs.superlogical.com/rex/nix/snapshot.tar.gz -- --help

The channel URL always serves the newest release on its channel, but flake.lock records the exact release, so a lock keeps working after newer releases come out. To move to the newest one, run nix flake update rex.

The NixOS Module

On NixOS, add the flake as an input and import rex.nixosModules.default. The module runs Rex as a systemd service in one of two modes, the same two the packages ship:

• services.rex.enable runs one shared server as the rex account, on /run/rex/server.sock. Members of the rex group can connect.
• services.rex.loginServer.enable runs one root process that identifies each caller, maps them to an account, and runs a server per account as that account. It listens on /run/rex/login-server.sock.

They can’t both be on. Either mode also installs rex for every user, puts Rex’s terminal type where the service can find it, and adds the SSH fallback to /etc/ssh/ssh_config.

A shared server that one person can use:

{
  inputs.rex.url = "https://pkgs.superlogical.com/rex/nix/snapshot.tar.gz";

  outputs = { nixpkgs, rex, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        rex.nixosModules.default
        {
          services.rex.enable = true;
          users.users.alice = {
            isNormalUser = true;
            extraGroups = [ "rex" ];
          };
        }
      ];
    };
  };
}

A login server that lets Alice use her own account over Tailscale Serve. The module writes the accounts to /etc/rex/accounts.jsonc, but doesn’t create them:

{
  services.tailscale.enable = true;
  users.users.alice.isNormalUser = true;

  services.rex.loginServer = {
    enable = true;
    accounts.alice.principals = [ "tailscale:alice@example.com" ];
    tailscaleServe.enable = true;
  };
}

The host must be logged in to Tailscale, with HTTPS enabled for the tailnet. Changes to the accounts reload the login server without ending sessions. Connections whose account is no longer allowed are closed.