Skip to content

Install

The relay is one binary, rchat-server. Release binaries for Linux, FreeBSD and macOS are published at https://assets.r-chat.net/<version>/, each with a SHA-256 checksum. The current release is listed on Releases and on the downloads page.

The installer ships from the release tag in the public rchat-core repository, not from the download host: the release public key and the rollback floor are compiled into it at tag time, so write access to the download host cannot move them. On Linux (as root, or with sudo):

Terminal window
curl -fsSLO https://raw.githubusercontent.com/PDG-Global/rchat-core/v2.1.1/scripts/install.sh
less install.sh # read it before you run it
sudo sh install.sh

On FreeBSD, run it as root (sudo may not be installed). curl is not in the base system, so install it first; install.sh uses curl because it can keep every redirect on https:

Terminal window
pkg install -y curl
curl -fsSLO https://raw.githubusercontent.com/PDG-Global/rchat-core/v2.1.1/scripts/install.sh
less install.sh # read it before you run it
sh install.sh

The script:

  1. detects the operating system and CPU, and picks the matching binary (the static build on Linux unless you pass --gnu);
  2. reads the current version from https://assets.r-chat.net/VERSION, unless you pin one with --version;
  3. fetches the release’s signed manifest (SHA256SUMS.txt and SHA256SUMS.txt.sig) and verifies the signature with ssh-keygen -Y verify against the release public key compiled into the script. It refuses to install if the signature is invalid, the manifest does not name the requested release, or the release is below the rollback floor compiled into this installer (2.1.1);
  4. downloads the binary and checks its hash against the verified manifest — there is no fallback to a per-file checksum fetched from the download host;
  5. installs the binary to /usr/local/bin/rchat-server, replacing any older one in a single step;
  6. sets up the service user, directories and service file for the platform (below);
  7. prints the next steps.

Verification needs ssh-keygen (OpenSSH 8.0 or newer) on the machine; FreeBSD’s base system includes it, and most Linux distributions ship it in their OpenSSH client package.

It never overwrites an existing config, relay identity key or service file, and it never writes a config or a key. Running it again upgrades the binary and leaves everything else alone.

OptionEffect
--version VInstall version V instead of the current one.
--gnuOn Linux x86_64 or ARM64, install the glibc build instead of the static one.
--dry-runPrint what would be downloaded and installed, and change nothing.
--prefix DIRInstall under DIR instead of / (for images and testing; the service user is not created, and the commands to create it are printed instead).
--base-url URLDownload from another mirror. Only https:// is accepted, unless the URL is given explicitly as http://.

To see what it would do first:

Terminal window
curl -fsSLO https://raw.githubusercontent.com/PDG-Global/rchat-core/v2.1.1/scripts/install.sh
sudo sh install.sh --version 2.1.1 --dry-run

The whole script is one function called on its last line, so a download cut off half-way runs nothing.

CodeMeaning
0Installed (or the dry run finished).
1Unsupported operating system or CPU, or a bad option.
2Download failure: the version or the binary could not be fetched, or no curl/fetch or SHA-256 tool was found.
3Verification failure: the manifest or its signature could not be fetched, bad manifest signature, checksum mismatch, a release below the rollback floor, a file not listed in the signed manifest, or ssh-keygen missing or too old. Nothing was installed.
4An install step failed (creating a directory, installing the file, or creating the user).
130Interrupted.
SystemCPUBinary
Linuxx86_64, ARM64rchat-server-<arch>-linux-static (default) or rchat-server-<arch>-linux-gnu (--gnu)
LinuxARMv7rchat-server-armv7-linux
LinuxRISC-V 64rchat-server-riscv64gc-linux-gnu
FreeBSDx86_64rchat-server-x86_64-freebsd
macOSApple silicon and Intelrchat-server-macos-universal

Pick the file for your platform from the downloads page or Releases, then check it. On Linux:

Terminal window
curl -LO https://assets.r-chat.net/2.1.1/rchat-server-x86_64-linux-static
curl -LO https://assets.r-chat.net/2.1.1/rchat-server-x86_64-linux-static.sha256
echo "$(cat rchat-server-x86_64-linux-static.sha256) rchat-server-x86_64-linux-static" | sha256sum -c

On macOS use shasum -a 256 rchat-server-macos-universal; on FreeBSD use sha256 -q rchat-server-x86_64-freebsd, and compare the result with the .sha256 file by eye. Each .sha256 file holds the hash only.

Then install it:

Terminal window
sudo install -m 0755 rchat-server-x86_64-linux-static /usr/local/bin/rchat-server

What install.sh sets up:

  • the rchat system user and group, with no login shell;
  • /var/lib/rchat (mode 0700, owned by rchat) for the relay identity key and the ACME cache;
  • /etc/rchat (mode 0750, owner root, group rchat) for the config;
  • the systemd unit /etc/systemd/system/rchat-server.service, unless a unit of that name already exists there or in /lib/systemd/system or /usr/lib/systemd/system. It runs the relay as rchat with --config /etc/rchat/server.toml and lets it bind port 443 (CAP_NET_BIND_SERVICE). See Running as a service.

Then:

  1. Write the config at /etc/rchat/server.toml, mode 0640, group rchat. The quick start has a complete file for a relay on port 443 with automatic certificates; the commented template is rchat/config/server.toml in the rchat-core repository. Keep the key and the ACME cache in /var/lib/rchat:

    [server]
    relay_identity_path = "/var/lib/rchat/relay_identity.key"
    [server.acme]
    cache_dir = "/var/lib/rchat/acme"
  2. Create the relay identity, once, as the service user. It refuses to overwrite an existing key:

    Terminal window
    sudo -u rchat /usr/local/bin/rchat-server --config /etc/rchat/server.toml --init-relay-identity

    It prints the relay’s pin (rk:1:…), which you give to your users. See Relay identity.

  3. Start it:

    Terminal window
    sudo systemctl daemon-reload && sudo systemctl enable --now rchat-server

What install.sh sets up:

  • the rchat user, created with pw useradd if it is missing;
  • /var/db/rchat (mode 0700) and /var/log/rchat (mode 0750), owned by rchat;
  • /usr/local/etc/rchat (mode 0750, owner root, group rchat) for the config;
  • the rc script /usr/local/etc/rc.d/rchat (mode 0555), unless one exists.

The rc script runs the relay under daemon(8), which restarts it 5 seconds after it exits and reopens the log on SIGHUP for newsyslog. Its settings, all optional in /etc/rc.conf:

VariableDefaultMeaning
rchat_enableNOStart at boot.
rchat_runasrchatThe user the relay runs as. It is rchat_runas, not rchat_user, because rc.subr would run daemon itself as rchat_user.
rchat_config/usr/local/etc/rchat/server.tomlThe config file.
rchat_log/var/log/rchat/server.logThe log file.
rchat_log_levelwarnThe log level.

Then:

  1. Write the config at /usr/local/etc/rchat/server.toml, mode 0640, group rchat. The relay identity key goes under [server] and, with built-in ACME, the certificate cache under [server.acme], both in /var/db/rchat. Set cache_dir explicitly: the default, /var/lib/rchat/acme, does not exist on FreeBSD, and the relay would refuse to start.

    [server]
    relay_identity_path = "/var/db/rchat/relay_identity.key"
    [server.acme]
    cache_dir = "/var/db/rchat/acme"

    server-2gb.toml is a complete FreeBSD config with both already set.

  2. Create the relay identity, once, as the service user:

    Terminal window
    su -m rchat -c '/usr/local/bin/rchat-server --config /usr/local/etc/rchat/server.toml --init-relay-identity'
  3. Start it:

    Terminal window
    sysrc rchat_enable=YES && service rchat start

An unprivileged user cannot bind port 443 on FreeBSD by default. FreeBSD covers both ways to serve 443: pf forwarding to a high port inside a jail, or mac_portacl on a dedicated host.

On macOS install.sh installs the binary only, plus /usr/local/etc/rchat for the config. It installs no service file and creates no user. Run the relay under launchd with a property list of your own that starts:

/usr/local/bin/rchat-server --config /usr/local/etc/rchat/server.toml

For example, /Library/LaunchDaemons/net.r-chat.relay.plist, with UserName set to an account you created for the relay:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>net.r-chat.relay</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/rchat-server</string>
<string>--config</string>
<string>/usr/local/etc/rchat/server.toml</string>
</array>
<key>UserName</key><string>REPLACE-with-the-relay-account</string>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
</dict>
</plist>

In the config, set relay_identity_path (under [server]) and, with built-in ACME, cache_dir (under [server.acme]) to paths in a directory that account owns. The default ACME cache, /var/lib/rchat/acme, does not exist on macOS, and the relay would refuse to start. Create the identity once as that account with --init-relay-identity, then load the job with sudo launchctl bootstrap system /Library/LaunchDaemons/net.r-chat.relay.plist. The macOS binaries are signed and notarised by Apple (see Releases).

The relay’s source is in the public rchat-core repository. You need a Rust toolchain (rustup), plus a C toolchain and CMake, because the relay depends on the shared client library, which compiles BoringSSL through the boring crate.

Terminal window
git clone https://github.com/PDG-Global/rchat-core.git
cd rchat-core/rchat
cargo build --release --locked --bin rchat-server
sudo install -m 0755 target/release/rchat-server /usr/local/bin/

Then create the user, directories and service by hand. These are the commands install.sh runs.

On Linux:

Terminal window
sudo useradd --system --user-group --home-dir /var/lib/rchat --no-create-home --shell /usr/sbin/nologin rchat
sudo install -d -o rchat -g rchat -m 0700 /var/lib/rchat
sudo install -d -o root -g rchat -m 0750 /etc/rchat
curl -fsSL -o rchat-server.service https://assets.r-chat.net/2.1.1/rchat-server.service
sudo install -m 0644 rchat-server.service /etc/systemd/system/rchat-server.service

On FreeBSD (as root):

Terminal window
pw useradd rchat -d /var/db/rchat -s /usr/sbin/nologin -c "rChat relay" -w no
install -d -o rchat -g rchat -m 0700 /var/db/rchat
install -d -o rchat -g rchat -m 0750 /var/log/rchat
install -d -o root -g rchat -m 0750 /usr/local/etc/rchat
fetch -o rchat.rc https://assets.r-chat.net/2.1.1/rchat.rc
install -m 0555 rchat.rc /usr/local/etc/rc.d/rchat

Then follow steps 1 to 3 for your platform above. The unit and rc script are published for every release at https://assets.r-chat.net/<version>/.

Terminal window
rchat-server --help

Shows the command-line flags. See the CLI reference for what each one does.

Run install.sh again (or replace the binary by hand), then restart:

Terminal window
sudo systemctl restart rchat-server # Linux
service rchat restart # FreeBSD

install.sh prints the restart command when it replaced an older binary. The ACME cache and the relay identity key survive restarts, so the relay reuses its certificate and keeps its identity.

Queued offline messages are held in memory by default, so a relay restart loses them. To keep them across restarts, turn on encrypted persistence (see Offline queue).

2.1.1 is a security release: security fixes and dependency updates. Relay operators should update. Run the tagged installer again (above) and restart; the configuration, relay identity and ACME cache carry over. The installer refuses releases below its compiled rollback floor, so use the installer from the current tag.

Protocol v3 is a hard cutover: update the relay and the apps together. The relay refuses v2 apps, and they can’t connect until they are updated. The relay identity key, its pin and your configuration carry over; messages queued before the upgrade are lost.

  • [server.offline_queue] ttl_secs is capped at 259200 (72 hours). A larger value stops the relay at startup.
  • Invites. Set host under [server.decoy] (unless you use ACME), and public_port under [server] if clients dial a different port from the one the relay binds. Then print the invite with --print-invite and hand it to your users; see Inviting people to your relay. Everyone needs to show their contact code again in the new app, because codes now carry a post-quantum key.
  • Decoy site. Optionally render this relay’s own decoy site with --render-decoy and point [server.decoy] root at it; see A decoy site for each relay. Run it as the service user with --config. Without it, the built-in page differs per relay. Upgrading changes the built-in design of a relay with a host name once.
  • TLS resumption is on by default ([server.tls] session_tickets); nothing to do.
  • Memory. Each pending conversation request takes about 1.6 KB, and the default max_pending_circuit_targets is now 18,000 (about 29 MB, the memory 10,000 took before); see resource limits. New optional keys blind_ask_burst, blind_ask_refill_per_sec and pending_identity_reserve_percent keep blinded requests from crowding out first contact.

Voice and video calls need relay 2.1.0. The relay advertises the call capabilities calls-v1 (voice) and video-v1 (video) to the apps. On an older relay, rChat for Android shows “Your relay needs an update for calls”. Messages are not affected. iPhone calls are not released yet; they will need 2.1.0 too.

  • Same port, no new setup. Calls use the relay’s own HTTPS port. There are no extra ports and no separate calling server, and nothing to add to the configuration.
  • Front ends. A TCP (layer-4) passthrough carries calls the same way it carries messages; see Behind a TCP front end.
  • Bandwidth. The relay forwards the media of each call, so a call uses bandwidth on the relay in both directions. Voice is a constant stream (the app encodes it at 24 kbps, lowering to 16 kbps on a poor connection). Video uses more, and varies with the picture and the connection; the app picks the size it can carry. Each phone in a call opens two extra connections (four with video).
  • Metrics. The relay exports call counters with the rchat_media_ prefix, for example rchat_media_connections_active, rchat_media_frames_forwarded_total, rchat_media_video_connections_active and rchat_media_join_refused_total. They are relay-wide totals, with nothing per person or per call; see Metrics.
  • Keepalive and held copies. 2.1.0 also changes when the relay pings quiet connections and adds two optional keys, held_copy_max_bytes_per_connection and held_copy_max_total_bytes; see Keepalive and idle connections and resource limits. If you set connection_timeout_secs below 300, the relay logs a warning at startup.

The offline store limits changed. In your config file:

  • The old key is renamed. offline_queue_max_bytes_per_recipient under [server] is now max_bytes_per_recipient under [server.offline_queue]. The old key still works for one release: the relay logs a warning at startup and uses its value when the new key is unset. If both are set, the new key wins. Rename it before the next release, when the old key stops parsing.
  • New defaults. 4 MiB and 256 messages per recipient account (max_bytes_per_recipient, max_messages_per_recipient; before: 16 MiB and 1000). The global offline_queue_max_total_bytes stays at 256 MiB. New per-sender budgets: sender_budget_bytes 16 MiB, sender_budget_messages 1024, sender_window_secs equal to ttl_secs (never shorter), and sender_source_budget_multiplier 4.

What this means for your users: sending to offline contacts is limited to about 16 MiB per connection and 64 MiB per network address over the queue’s lifetime (at most 72 hours). People behind one shared office or carrier address share the address budget. Normal chat will not notice. Many photos or files sent to an offline contact can be refused: the sender gets a RateLimited error and no acknowledgement. Nothing already queued is dropped. You can raise the numbers within the bounds in Limits and Server configuration keys. Refusals show in rchat_rejections_total as offline_recipient_cap, offline_sender_budget and offline_source_budget.

Protocol v2 is a hard cutover: update the relay and the app together. The relay refuses older apps, and they can’t connect until they are updated.

  • Create the relay identity before the first start: --init-relay-identity (see Relay identity).
  • Remove message_queue_persist_path and trusted_proxy from the config file. The relay refuses to start while either is set. On first start it overwrites the old plaintext queue file with zeros and deletes it. Messages queued before the upgrade are lost.
  • If the relay sat behind a TLS-terminating proxy, move to a TCP front end or let the relay own port 443.
  • connection_timeout_secs must now be between 60 and 86400, and a non-loopback metrics address needs [metrics] allow_public = true.