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.
Install with install.sh
Section titled “Install with install.sh”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):
curl -fsSLO https://raw.githubusercontent.com/PDG-Global/rchat-core/v2.1.1/scripts/install.shless install.sh # read it before you run itsudo sh install.shOn 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:
pkg install -y curlcurl -fsSLO https://raw.githubusercontent.com/PDG-Global/rchat-core/v2.1.1/scripts/install.shless install.sh # read it before you run itsh install.shThe script:
- detects the operating system and CPU, and picks the matching binary (the static build on Linux unless you pass
--gnu); - reads the current version from
https://assets.r-chat.net/VERSION, unless you pin one with--version; - fetches the release’s signed manifest (
SHA256SUMS.txtandSHA256SUMS.txt.sig) and verifies the signature withssh-keygen -Y verifyagainst 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); - 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;
- installs the binary to
/usr/local/bin/rchat-server, replacing any older one in a single step; - sets up the service user, directories and service file for the platform (below);
- 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.
| Option | Effect |
|---|---|
--version V | Install version V instead of the current one. |
--gnu | On Linux x86_64 or ARM64, install the glibc build instead of the static one. |
--dry-run | Print what would be downloaded and installed, and change nothing. |
--prefix DIR | Install 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 URL | Download from another mirror. Only https:// is accepted, unless the URL is given explicitly as http://. |
To see what it would do first:
curl -fsSLO https://raw.githubusercontent.com/PDG-Global/rchat-core/v2.1.1/scripts/install.shsudo sh install.sh --version 2.1.1 --dry-runThe whole script is one function called on its last line, so a download cut off half-way runs nothing.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 | Installed (or the dry run finished). |
1 | Unsupported operating system or CPU, or a bad option. |
2 | Download failure: the version or the binary could not be fetched, or no curl/fetch or SHA-256 tool was found. |
3 | Verification 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. |
4 | An install step failed (creating a directory, installing the file, or creating the user). |
130 | Interrupted. |
Supported platforms
Section titled “Supported platforms”| System | CPU | Binary |
|---|---|---|
| Linux | x86_64, ARM64 | rchat-server-<arch>-linux-static (default) or rchat-server-<arch>-linux-gnu (--gnu) |
| Linux | ARMv7 | rchat-server-armv7-linux |
| Linux | RISC-V 64 | rchat-server-riscv64gc-linux-gnu |
| FreeBSD | x86_64 | rchat-server-x86_64-freebsd |
| macOS | Apple silicon and Intel | rchat-server-macos-universal |
Download and verify by hand
Section titled “Download and verify by hand”Pick the file for your platform from the downloads page or Releases, then check it. On Linux:
curl -LO https://assets.r-chat.net/2.1.1/rchat-server-x86_64-linux-staticcurl -LO https://assets.r-chat.net/2.1.1/rchat-server-x86_64-linux-static.sha256echo "$(cat rchat-server-x86_64-linux-static.sha256) rchat-server-x86_64-linux-static" | sha256sum -cOn 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:
sudo install -m 0755 rchat-server-x86_64-linux-static /usr/local/bin/rchat-serverLinux (systemd)
Section titled “Linux (systemd)”What install.sh sets up:
- the
rchatsystem user and group, with no login shell; /var/lib/rchat(mode0700, owned byrchat) for the relay identity key and the ACME cache;/etc/rchat(mode0750, ownerroot, grouprchat) 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/systemor/usr/lib/systemd/system. It runs the relay asrchatwith--config /etc/rchat/server.tomland lets it bind port 443 (CAP_NET_BIND_SERVICE). See Running as a service.
Then:
-
Write the config at
/etc/rchat/server.toml, mode0640, grouprchat. The quick start has a complete file for a relay on port 443 with automatic certificates; the commented template isrchat/config/server.tomlin 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" -
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-identityIt prints the relay’s pin (
rk:1:…), which you give to your users. See Relay identity. -
Start it:
Terminal window sudo systemctl daemon-reload && sudo systemctl enable --now rchat-server
FreeBSD (rc.d)
Section titled “FreeBSD (rc.d)”What install.sh sets up:
- the
rchatuser, created withpw useraddif it is missing; /var/db/rchat(mode0700) and/var/log/rchat(mode0750), owned byrchat;/usr/local/etc/rchat(mode0750, ownerroot, grouprchat) for the config;- the rc script
/usr/local/etc/rc.d/rchat(mode0555), 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:
| Variable | Default | Meaning |
|---|---|---|
rchat_enable | NO | Start at boot. |
rchat_runas | rchat | The 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.toml | The config file. |
rchat_log | /var/log/rchat/server.log | The log file. |
rchat_log_level | warn | The log level. |
Then:
-
Write the config at
/usr/local/etc/rchat/server.toml, mode0640, grouprchat. The relay identity key goes under[server]and, with built-in ACME, the certificate cache under[server.acme], both in/var/db/rchat. Setcache_direxplicitly: 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.tomlis a complete FreeBSD config with both already set. -
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' -
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.
macOS (launchd)
Section titled “macOS (launchd)”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.tomlFor 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).
Build from source
Section titled “Build from source”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.
git clone https://github.com/PDG-Global/rchat-core.gitcd rchat-core/rchatcargo build --release --locked --bin rchat-serversudo 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:
sudo useradd --system --user-group --home-dir /var/lib/rchat --no-create-home --shell /usr/sbin/nologin rchatsudo install -d -o rchat -g rchat -m 0700 /var/lib/rchatsudo install -d -o root -g rchat -m 0750 /etc/rchatcurl -fsSL -o rchat-server.service https://assets.r-chat.net/2.1.1/rchat-server.servicesudo install -m 0644 rchat-server.service /etc/systemd/system/rchat-server.serviceOn FreeBSD (as root):
pw useradd rchat -d /var/db/rchat -s /usr/sbin/nologin -c "rChat relay" -w noinstall -d -o rchat -g rchat -m 0700 /var/db/rchatinstall -d -o rchat -g rchat -m 0750 /var/log/rchatinstall -d -o root -g rchat -m 0750 /usr/local/etc/rchatfetch -o rchat.rc https://assets.r-chat.net/2.1.1/rchat.rcinstall -m 0555 rchat.rc /usr/local/etc/rc.d/rchatThen 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>/.
Check the binary
Section titled “Check the binary”rchat-server --helpShows the command-line flags. See the CLI reference for what each one does.
Upgrading
Section titled “Upgrading”Run install.sh again (or replace the binary by hand), then restart:
sudo systemctl restart rchat-server # Linuxservice rchat restart # FreeBSDinstall.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).
Upgrading to 2.1.1
Section titled “Upgrading to 2.1.1”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.
Upgrading to 2.0.0 (protocol v3)
Section titled “Upgrading to 2.0.0 (protocol v3)”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_secsis capped at 259200 (72 hours). A larger value stops the relay at startup.- Invites. Set
hostunder[server.decoy](unless you use ACME), andpublic_portunder[server]if clients dial a different port from the one the relay binds. Then print the invite with--print-inviteand 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-decoyand point[server.decoy] rootat 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_targetsis now 18,000 (about 29 MB, the memory 10,000 took before); see resource limits. New optional keysblind_ask_burst,blind_ask_refill_per_secandpending_identity_reserve_percentkeep blinded requests from crowding out first contact.
Upgrading to 2.1.0 (calls)
Section titled “Upgrading to 2.1.0 (calls)”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 examplerchat_media_connections_active,rchat_media_frames_forwarded_total,rchat_media_video_connections_activeandrchat_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_connectionandheld_copy_max_total_bytes; see Keepalive and idle connections and resource limits. If you setconnection_timeout_secsbelow300, the relay logs a warning at startup.
Offline store limits
Section titled “Offline store limits”The offline store limits changed. In your config file:
- The old key is renamed.
offline_queue_max_bytes_per_recipientunder[server]is nowmax_bytes_per_recipientunder[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 globaloffline_queue_max_total_bytesstays at 256 MiB. New per-sender budgets:sender_budget_bytes16 MiB,sender_budget_messages1024,sender_window_secsequal tottl_secs(never shorter), andsender_source_budget_multiplier4.
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.
Upgrading to protocol v2
Section titled “Upgrading to protocol v2”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_pathandtrusted_proxyfrom 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_secsmust now be between 60 and 86400, and a non-loopback metrics address needs[metrics] allow_public = true.