Skip to main content

Configure Parsec Relay Server

Updated

Note: This article is for the updated High Performance Relay (v2.0), released in October 2024. For the article on setting up the legacy relay server (v1.0), please reference the documentation here.

Before installing and configuring the Parsec Relay server (HPR), we highly recommend you review the technical reference section, which covers an overview of the HPR, prerequisites, deployment considerations, reference architecture and troubleshooting.

Prerequisites

Install

  • Connect to your Linux server using SSH, or using the console
ssh <user>@<Relay-LAN-IP>
  • Use the following command to download the Relay server files to the directory you are in
    • The .tar.gz file contains the Relay Server binary executable file, a service configuration file, the GNU Privacy Guard signature, and the Readme file. Optionally, you may choose to verify the signature of the HPR binary using GNU Privacy Guard (GPG), detailed below. This ensures that the file you have downloaded is intact and is as supplied by Parsec.
wget https://builds.parsec.app/hpr/parsechpr2.0.0.linux-amd64.tar.gz
  • Run the following command to extract the files you downloaded to the directory
tar -xvf parsechpr2.0.0.linux-amd64.tar.gz
  • Run the following commands to move the executable and service files to suitable locations
    • The binary executable file should be moved to a standard location for binary files, typically /bin. The service file must be located in the /etc/systemd/system folder to be read by systemd to initialize the service. 
cd parsechpr2.0.0
sudo cp parsechpr /bin
sudo cp parsechpr.service /etc/systemd/system

Configure Relay server

Create a new Relay (HPR)

  • Login to your Parsec for Teams admin panel 
  • Click 'Relays' 

  • Click 'Create Relay'

  • Give your Relay a name
    • To help streamline ongoing maintenance the name might reflect the location, purpose, hostname, or combination of such information

  • Click 'Reveal Secret'
  • Copy the secret to your clipboard by clicking the revealed value. Do not lose this, you will need it later. You should consider storing this in a credential manager or other secure location, at least until the Relay is connected
  • Click 'Continue'

Encrypt and store Relay Secret 

  • On the Relay server, run the following command to start the prompt to generate a new encrypted secret
    • You will be prompted for the Relay Secret you generated in the previous step. Responding to the prompt with the Relay Secret will encrypt it and store it in a suitable location for use by the relay service during authentication to the API.
sudo systemd-ask-password -n | sudo systemd-creds encrypt --name=relay-secret -p - -
  • Respond to the Password:prompt with the Relay Secret
  • Copy the SetCredentialEncrypted block to your clipboard for the next step
Password: 
••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• 
SetCredentialEncrypted=relay-secret: \
Whxqht+dQJax1aZeCGfakeAAAAABAAAADAAAABAAAABURcAygiTvHFZXbfsAAAAAZ7obj \
0NCyQQ2iC3IyEsCoJ8L9gdTe/0U1aNK+fakelV04+mAg34blAEsC4SWUTTDaUzL1+idhM \
U7o1iygas+wi9H0ZKZK2EWAiuu/8iDwttF/iw7LDU3kqJdztLsaUS9GAV9faker6S09lg \
npP/8zQyvKRoJECUFhLvRefz4JFZJKS4fakeOvRFOspghzKI=

Modify the Relay service definition file

Use your text editor of choice to modify the following in parsechpr.service

sudo nano /etc/systemd/system/parsechpr.service
  • Environment="TEAM_ID=[Team ID]"
  • ExecStart=/bin/parsechpr [Public IP Address] [Public listener port] [Private listener port]
  • Paste SetCredentialEncrypted block from the previous step
  • Save the changes
[Unit]
Description=Parsec High Performance Relay
After=network.target

[Service]
Type=simple
Restart=always
RestartSec=1
DynamicUser=yes
Environment="TEAM_ID=2fJkrBXTP0fake22bAL7MSfake"
ExecStart=/bin/parsechpr 205.250.123.456 5000 4900
SetCredentialEncrypted=relay-secret: \
Whxqht+dQJax1aZeCGfakeAAAAABAAAADAAAABAAAABURcAygiTvHFZXbfsAAAAAZ7obj \
0NCyQQ2iC3IyEsCoJ8L9gdTe/0U1aNK+fakelV04+mAg34blAEsC4SWUTTDaUzL1+idhM \
U7o1iygas+wi9H0ZKZK2EWAiuu/8iDwttF/iw7LDU3kqJdztLsaUS9GAV9faker6S09lg \
npP/8zQyvKRoJECUFhLvRefz4JFZJKS4fakeOvRFOspghzKI=

[Install]
WantedBy=multi-user.target

Start the Relay service

  • Run the following commands to start the Relay service
sudo systemctl start parsechpr
sudo systemctl enable parsechpr
  • Run the following command to show the status of the Relay service
service parsechpr status

The status should be running and the CGroup line should reflect the IP and port configuration you provided in the service definition file. An example output is below.

parsechpr.service - Parsec High Performance Relay
Loaded: loaded (/etc/systemd/system/parsechpr.service; enabled; preset: enabled)
Active: active (running) since Wed 2024-06-05 07:30:39 PDT; 12min ago
Main PID: 1018 (parsechpr)
Tasks: 5 (limit: 9327)
Memory: 261.0M (peak: 261.8M)
CPU: 494ms
CGroup: /system.slice/parsechpr.service
└─1018 /bin/parsechpr 205.250.123.456 5000 4900
Jun 05 07:30:39 2404 systemd[1]: parsechpr.service: Scheduled restart job, restart counter is at 1.
Jun 05 07:30:39 2404 systemd[1]: Started parsechpr.service - Parsec High Performance Relay.
Jun 05 07:30:39 2404 parsechpr[1018]: time=2024-06-05T07:30:39.963-07:00 level=INFO msg="Parsec - High Performance Relay v2.0.0"
Jun 05 07:30:40 2404 parsechpr[1018]: time=2024-06-05T07:30:40.182-07:00 level=INFO msg="Listener started" port=5000 allow_pairing=true

Check the Teams admin dashboard to confirm that the Relay server is online. The Relay dashboard might take up to 30 seconds to reflect an Active state for the new Relay. 

That's it! Again, we highly recommend reviewing the technical reference section for additional details regarding the Parsec Relay server.

Configure Parsec hosts to use the Relay server

Now that the relay server is configured, we'll need to tell the host computers where it is. We recommend configuring this in App Rules. The majority of deployments involve all hosts being local to the relay server, in which case only the host setting is required. For more information on when to use the client setting, please reference HPR Deployment Considerations and Options.

  • In the appropriate App Rule(s) on the Teams App Rules page, enter each Relay server's private (LAN) IP and private listener port in the 'Host High Performance Relay Server Address' field as a comma delimited list. DNS records can be used in place of IP addresses.
    • Example: HOST:PORT,HOST:PORT

HPR settings - host.png

As an alternative to configuring hosts using Teams App Rules page, the Relay server address may be manually specified in the configuration file via app_stun_address:

app_stun_address = 10.1.2.20@4900 # Use a local address if possible

An '@' character must be used to delimit the IP address and port. Up to 10 address@port
pairs may be configured, separated by commas:

app_stun_address = 10.1.2.20@23050,10.1.2.21@23051,...

NOTE: this is a different format than in the Application Configuration page on the admin panel. Please read this article to know the format to use on the config page.

Configure Parsec Clients to use the Relay Server

If you have clients on your network that need to connect to off-premise hosts through a relay, you will need to apply the relay server setting to them. We recommend configuring this in App Rules.

  • In the appropriate App Rule(s) on the Teams App Rules page, enter each Relay server's private (LAN) IP and private listener port in the 'Client High Performance Relay Server Address' field as a comma delimited list. DNS records can be used in place of IP addresses.
    • Example: relay1-IP:port,relay2-IP:port

HPR settings - client.png

As an alternative to configuring hosts to leverage the relay via the Teams App Rules page, the relay server address may be manually specified in the configuration file via app_client_stun_address:

app_client_stun_address = 10.1.2.20@4900 # Use a local address if possible

An '@' character must be used to delimit the IP address and port. Up to 10 address@port
pairs may be configured, separated by commas:

app_client_stun_address = 10.1.2.20@23050,10.1.2.21@23051,...

NOTE: this is a different format than in the Application Configuration page on the admin panel. Please read this article to know the format to use on the config page.

It is also possible to leverage DNS records to configure HPR candidates for Parsec clients.

Verifying HPR binary (optional)

Install GPG for Linux

sudo apt-get install gnupg

Import the public key

gpg --import parsechpr_public.key

Verify the binary

cd parsechpr2.0.0 
gpg --import && gpg --verify parsechpr.sig parsechpr

Verify the binary (alternative)

curl -s https://builds.parsec.app/hpr/gpg/parsechpr_public.key | gpg --import && gpg --verify parsechpr.sig parsechpr

Upon success, you will see the following in the console

gpg: Signature made Wed May 22 16:55:51 2024 EDT 
gpg: using RSA key {{some_key_id}} 
gpg: Good signature from "Parsec (ParsecHPR) <security@parsec.app>" [ultimate]

 

Related articles

Powered by Zendesk