doc.rustdesk.com/content/self-host/rustdesk-server-pro/relay/_index.en.md

title, weight, description, keywords

title	weight	description	keywords
Configure Relay Servers	17	Add extra RustDesk relay servers to a Server Pro deployment and use geolocation to route connections through the closest available hbbr instance.	rustdesk relay server rustdesk hbbr rustdesk geolocation relay rustdesk additional relay rustdesk server pro relay

Use this guide to add extra relay servers to RustDesk Server Pro and improve regional performance with geolocation-aware routing.

When do you need additional relay servers?

You need additional relay servers when users connect across regions and direct hole punching is not always possible. Extra hbbr nodes let RustDesk route relay traffic through a closer region, which can reduce latency and improve session quality when relay is required.

Relay setup checklist

1. Deploy an extra hbbr relay server in the target region.
2. Set the KEY environment variable on hbbr to the public key in id_ed25519.pub, or copy id_ed25519 and id_ed25519.pub to the relay server.
3. Open TCP ports 21117 and 21119.
4. Add the new relay hostnames or IP addresses in the RustDesk Pro web console.
5. Install the MaxMind GeoLite2 City database on hbbs.
6. Reload geo settings and confirm the new relay appears in the logs.

How to install additional relay servers with Docker

{{% notice note %}} The simple install creates a relay server (the hbbr process) implicitly on the same machine, you do not need to specify relay server explicitly.

If you wanna create additional relay server explicitly on another machine, please run hbbr by following OSS installation. You can find hbbr in rustdesk-server-linux-amd64.tar.gz, rustdesk-server-hbbr_<version>-<arch>.deb, rustdesk-server-windows-x86_64.tar.gz or in docker (sudo docker run ... rustdesk/rustdesk-server-pro hbbr).

hbbr does not require a license and is the same as the open source version. {{% /notice %}}

You can have several relay servers running across the globe and leverage GeoLocation automatically to use the closest relay server, giving you a faster experience when connecting to remote computers. hbbs automatically checks if these relay servers are online every several seconds, it only choose online relay servers.

{{% notice note %}} Known issue: https://github.com/rustdesk/rustdesk/discussions/7934 {{% /notice %}}

Set the KEY environment variable on hbbr to the public key in id_ed25519.pub, or copy id_ed25519 and id_ed25519.pub to the relay server.

Docker Compose

An additional relay server only needs hbbr; hbbs and depends_on are not required. Choose one of the following key configuration methods:

• Keep the environment section and set KEY to the contents of id_ed25519.pub, as shown below.
• Remove the entire environment section and put id_ed25519 and id_ed25519.pub in ./data.

Create a compose.yml file with the following content.

services:
  hbbr:
    container_name: hbbr
    image: docker.io/rustdesk/rustdesk-server-pro:latest
    environment:
      KEY: "<PUBLIC_KEY>"
    command: hbbr
    volumes:
      - ./data:/root
    network_mode: "host"
    restart: unless-stopped

Docker

Set the key with an environment variable

Set KEY to the contents of id_ed25519.pub.

# sudo docker run --name hbbr -e KEY="<PUBLIC_KEY>" -td --net=host rustdesk/rustdesk-server-pro hbbr

Use key files

The Docker example below uses the key-file method.

1 - If docker is already installed, connect to your server via SSH and create a volume for hbbr.

# docker volume create hbbr

The volume hbbr should be located in /var/lib/docker/volumes/hbbr/_data.

2 - Copy the private key pair to the volume location, in this case we will use SCP to copy the files.

The command syntax is scp <path/filename> username@server:</destination/path>.

# scp id_ed25519 root@100.100.100.100:/var/lib/docker/volumes/hbbr/_data
# scp id_ed25519.pub root@100.100.100.100:/var/lib/docker/volumes/hbbr/_data

3 - Deploy the hbbr container using the volume previously created. This volume has the private key pair needed to run your private relay server.

# sudo docker run --name hbbr -v hbbr:/root -td --net=host rustdesk/rustdesk-server-pro hbbr

The rustdesk/rustdesk-server image still accepts -k <KEY>. To use the mounted key file, run it with -k _:

# sudo docker run --name hbbr -v hbbr:/root -td --net=host rustdesk/rustdesk-server hbbr -k _

Here, _ is a special value rather than the key itself. It tells hbbr to load or generate id_ed25519, derive its public key, and use that key to validate relay requests. RustDesk Server Pro versions earlier than 1.8.6 also accepted -k _ to load id_ed25519.

Starting with RustDesk Server Pro 1.8.6, the -k option for hbbr is deprecated and ignored. If KEY is not set, hbbr derives the public key from id_ed25519, or reads it from id_ed25519.pub if the private key file does not exist. If neither file exists, hbbr runs in public relay mode.

4 - Check the running logs to verify that hbbr is running using your key pair.

# docker logs hbbr

INFO [src/common.rs:121] **Private key comes from id_ed25519**
NFO [src/relay_server.rs:581] Key: XXXXXXXXXXXXXXXXXXXXX
INFO [src/relay_server.rs:60] #blacklist(blacklist.txt): 0
INFO [src/relay_server.rs:75] #blocklist(blocklist.txt): 0
INFO [src/relay_server.rs:81] Listening on tcp :21117

Depending on your OS, you might want to block/allow IPs using a firewall.

In our case, running Ubuntu we want to allow any TCP connections, to ports 21117 and 21119.

# sudo ufw allow proto tcp from any to any port 21117,21119

Enable the firewall

# sudo ufw enable

Check the status

# ufw status

Status: active

To                         Action      From
--                         ------      ----
21117,21119/tcp            ALLOW       Anywhere
21117,21119/tcp (v6)       ALLOW       Anywhere (v6)

How to configure geolocation in the web console

Register and Download the GeoLite2 City database file

To use geo location, hbbs needs access to the MaxMind GeoLite2 City database. The database is free and you can register to download the file and get an API key.

Start by creating an account (if you don’t have one) by going to the website. Go to Download Databases and download GeoLite2 City, choose the gzip file and you should have the mmdb file when decompressing it.

If you installed RustDesk Pro using the installation script on a Linux machine, the mmdb file needs to be moved to /var/lib/rustdesk-server/.

For Docker installations the file should be in the volume you mapped when deploying the container mapped to /root.

Get an API key to automate the process - Linux servers

You need to update this file regularly and we can use a cronjob to do that. You will need an API key to access the download link which is free.

Go to Manage License Keys and generate a new license key.

You can automate the download process in a few ways, but you add the following command to your crontab replacing {Your Access Key} with the API key you got from the previous step.

/usr/bin/curl -L --silent 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key={Your Access Key}&suffix=tar.gz' | /bin/tar -C '/var/lib/rustdesk-server/' -xvz --keep-newer-files --strip-components=1 --wildcards '*GeoLite2-City.mmdb'

Change settings in RustDesk Pro Web Console

Add your relay server IP addresses or DNS names (DNS is supported as of version 1.1.11) to the Relay Servers. Port is not required, 21117 port is used explicitly.

Add a Geo Override but adding the server IP address and the coordinates where the server is located.

Click Reload Geo and your list should look similar to this.

To confirm the results, check your hbbs logs when clicking Reload Geo, you should see a message showing the relay server IP addresses and their coordinates.

If you are running RustDesk Pro on a Linux machine use the command RUST_LOG=debug ./hbbs to view the logs. If you are running on a Docker container user docker logs hbbs.

RUST_LOG=debug ./hbbs

INFO [src/common.rs:130] GEOIP_FILE: ./GeoLite2-City.mmdb
INFO [src/common.rs:159] override 1xx.xxx.xxx.x7: -1.xx 5x.xxx
[src/common.rs:159] override 1xx.xxx.xxx.xx8: -3.xxx 5x.xxxx
[src/common.rs:159] override 7xx.xxx.xxxx.xx1: 6.xxx 5x.xxxx
GEOIP_FILE loaded, #overrides 3
INFO [src/common.rs:119] relay-servers=["1xx.xxx.xxx.x7", "1xx.xxx.xxx.xx8", "7xx.xxx.xxx.xx1"]
NFO [src/rendezvous_server.rs:1467] parsed relay servers: [("1xx.xxxx.xxx.xx7", Some((-1x, xxx))), ("1xx.xxx.xxx.xx8", Some((-3x, xxx))), ("7xx.xxx.xxx.xx1", Some((6x, xxx)))]

You can also confirm the relay requests directly on your hbbr instances, simply by checking the container logs.

# docker logs hbbr

INFO [src/relay_server.rs:436] Relayrequest 0593e64e-4fe8-4a59-a94f-b3420ab043eb from [::ffff:100.100.123.233]:52038 got paired
INFO [src/relay_server.rs:442] Both are raw