Installing on FreeBSD · Rex Docs
Installing on FreeBSD
Rex can run as a server on FreeBSD so that clients can access it as a remote host.
IMPORTANT: Rex on FreeBSD is in testing. The install commands show below once you’ve logged in with Discord.
The other server pages, starting with Server Modes, apply to FreeBSD too. Where they give a Linux command or path, use the one in Commands and Paths.
System Requirements
| Requirement | Supported |
|---|---|
| Release | FreeBSD 14.0 or later |
| Architecture | x86-64, ARM64 |
| Dependencies | None. Rex uses only the base system. |
| Services | rc.d, for the shared server and the login server. The rex command runs without them. |
| Packages | .pkg, from the Rex repository |
One package serves FreeBSD 14 and every later release.
Install
Log in with Discord to see the install commands.
The install script (install.sh) adds the Rex repository to pkg and installs the rex package, so pkg upgrade updates Rex along with your other packages. It takes the same options as on Linux, such as --channel, --tarball, and --dry-run. Pass them after sh -s --.
FreeBSD has no sudo by default, so run the pkg tab’s commands as root. The first, umask 022, makes the files they create readable by every user, whatever root’s umask is. The install script needs root too, or sudo if you’ve installed it.
FreeBSD has no curl either, so the commands download with FreeBSD’s own fetch.
If a channel has no FreeBSD package yet, the script installs only the rex binary into /usr/local/bin, as --tarball does, with no services. Run the script again once the channel has a package, and it switches to the package.
pkg trusts the Rex repository by the fingerprint of its signing key, in /usr/local/etc/pkg/fingerprints/rex. If the key changes, run the install script again to trust the new one.
Channels
FreeBSD has the same three channels as Linux. To switch, change the channel name in the url line of /usr/local/etc/pkg/repos/rex.conf, then update the catalogue:
pkg update -r rex
Moving from snapshot to preview or stable upgrades Rex. Moving back to snapshot is a downgrade, which you have to ask for. See Upgrading on FreeBSD.
Package Contents
The rex package installs:
| Path | What it is |
|---|---|
/usr/local/bin/rex |
The server and the CLI, in one binary |
/usr/local/etc/rc.d/rex |
One shared server, run as the rex account. Not enabled. |
/usr/local/etc/rc.d/rex-login-server |
One server per account, after a login. Not enabled. |
rex account and group |
A locked system account with the ID 729, or the next free one, and its home at /var/db/rex |
/usr/local/etc/rex/accounts.jsonc |
The login server’s accounts. It ships empty, which admits nobody. |
/usr/local/etc/pam.d/rex-login-server |
The login server’s PAM policy |
xterm-rex terminfo |
Rex’s terminal type, in /usr/local/share/terminfo |
Unlike the Linux packages, it has no SSH fallback, because FreeBSD’s /etc/ssh/ssh_config reads no other files. See Terminfo and SSH.
Upgrades keep your changes to the accounts file, but replace the PAM policy. See Upgrading on FreeBSD. To see the package’s setup notes again, run pkg info -D rex.
Commands and Paths
The other server pages give systemd commands. On FreeBSD, use these instead:
| On systemd | On FreeBSD |
|---|---|
sudo systemctl enable --now rex.service |
sysrc rex_enable=YES, then service rex start |
sudo systemctl enable --now rex-login-server.service |
sysrc rex_login_server_enable=YES, then service rex-login-server start |
sudo systemctl reload rex-login-server.service |
service rex-login-server reload |
sudo systemctl restart rex.service |
service rex restart |
sudo systemctl disable --now rex.service |
service rex stop, then sysrc rex_enable=NO |
sudo systemctl edit rex.service |
Set rex_flags with sysrc. See Settings. |
journalctl -u rex.service |
grep ' rex\[' /var/log/messages |
journalctl -u rex-login-server.service |
grep ' rex-login-server\[' /var/log/messages |
sudo usermod --append --groups rex alice |
pw groupmod rex -m alice |
sudo usermod --shell /bin/bash rex |
pw usermod rex -s /bin/sh |
FreeBSD has no socket activation, so rex.socket and rex-login-server.socket have no FreeBSD form. Use the services instead.
Files are in different places too:
| On Linux | On FreeBSD |
|---|---|
/usr/bin/rex |
/usr/local/bin/rex |
/run/rex |
/var/run/rex |
/var/lib/rex |
/var/db/rex |
/etc/rex/accounts.jsonc |
/usr/local/etc/rex/accounts.jsonc |
/etc/pam.d/rex-login-server |
/usr/local/etc/pam.d/rex-login-server |
/etc/nologin |
/var/run/nologin |
/run/user/<uid>/rex |
~/.local/state/rex/run |
Both services log to syslog, which writes to /var/log/messages by default. The servers that the login server starts for each account log to /var/run/rex/accounts/<account>/server.log instead.
If a server exits for any reason, its service starts it again 5 seconds later. Only service rex stop stops it for good. service rex start returns as soon as the server’s process exists, which can be a moment before it accepts connections.
Settings
The services read their settings from /etc/rc.conf. Set them with sysrc, then restart the service to apply them. Upgrades replace the rc.d scripts but never change /etc/rc.conf. This example raises the shared server’s session limit:
sysrc rex_flags="--max-sessions 128"
service rex restart
| Setting | Default | Effect |
|---|---|---|
rex_flags |
None | More options for rex server run |
rex_umask |
0007 |
The file mode mask for the server and every program it starts |
rex_user |
rex |
The account the server runs as |
rex_group |
rex |
The group that may use the socket |
rex_runtime_dir |
/var/run/rex |
The directory that holds the socket |
rex_state_dir |
/var/db/rex |
The server’s data |
rex_login_server_flags |
None | More options for rex login-server |
rex_login_server_accounts |
/usr/local/etc/rex/accounts.jsonc |
The accounts file |
rex_login_server_runtime_dir |
/var/run/rex |
The login server’s socket and each account server’s directory |
rex_flags and rex_login_server_flags add options to the service’s command line. A systemd drop-in replaces the command line instead, so where another page shows a whole ExecStart line, put only the options it adds in the flags. The comment at the top of each rc.d script explains every setting.
Terminfo and SSH
Programs in Rex terminals see TERM=xterm-rex, and the package installs that terminal type for every account. ssh passes TERM on to other hosts, which usually don’t know it. To make ssh send xterm-256color to those hosts instead, for every account, run as root:
rex terminfo setup --system
FreeBSD’s /etc/ssh/ssh_config reads no other files, so this also adds a marked Include line to it. rex terminfo remove --system takes the line out again. To set it up for your own account only, run rex terminfo setup.