Change the relay address for access agents
Introduction
Access agents use a specific address to call back to your ScreenConnect™ sever. This "relay" address is determined by your server's URL when you built the installer. In some situations, such as moving your ScreenConnect installation to a new server, you will want your agents to use a different relay address or a different port number. This article will explain how to switch the relay address for your existing agents.
Before you begin
1. Find your current relay address.
The relay address is the URL that your access clients use to connect back to your server. You can view the relay address of an access client by connecting to it and opening the Status menu. Your relay address is the value in the "Relay Server" field.
2. Decide on a suitable hostname to use.
Use a hostname that will be available to you in the long term. Your hostname will likely be a DNS hostname (domain or subdomain name) instead of an external IP address. If you decide to use an external IP address as your hostname for your relay address, you will need to repeat this process again if you move your installation a different server.
3. Make sure no other programs are listening on your selected port.
In our example below, we will be switching our relay address port from 8041 to 443. If you're switching ports, as well, ensure that no other process is listening on your selected port.
Changing the relay address
1. Open the web.config file.
2. Add the "RelayAddressableUri" key to your web.config file.
In your web.config file, search for the RelayAddressableUri key. If you don't already have the RelayAddressableUri key, add it underneath your existing RelayListenUri tag.
For Windows:
1 | <add key="RelayListenUri" value="relay://0.0.0.0:8041/" /> |
2 | <add key="RelayAddressableUri" value="relay://remote.myscreenconnectsite.com:443/" /> |
For Linux and OS X:
1 | <add key="RelayListenUri" value="relay://0.0.0.0:8041/"> |
2 | </add> |
3 | <add key="RelayAddressableUri" value="relay://remote.myscreenconnectsite.com:443/"> |
4 | </add> |
...Where relay://remote.myscreenconnectsite.com:443 is your desired Relay Address (hostname:port).
When you have finished editing the web.config file, save your changes. Your access clients will disconnect and reconnect back to your Host page.
3. Test your new relay address on a single machine
Warning: Make sure that all access clients have reconnected before continuing.
Pick an access client from your Host page to use as a "test machine." You will probably want to pick an existing machine that is local or easy to reach, especially if you'll need to uninstall and reinstall the access client manually for troubleshooting.
Testing a new relay hostname
Select your test machine from the Host page and select the Reinstall command.
Make sure the reinstallation has completed, and ensure that the access client has disconnected and reconnected to your intended server. Once completed, connect to the machine and open the guest client window. In the Status window, the "Relay Server" field should show your new relay hostname. You can then proceed to step 4 of this article.
Testing a new relay port
Select your test machine from the Host page and select the Reinstall command.
Your access client will appear to be disconnected from the Host page. To reconnect your access client to its intended server, you will need to edit the RelayListenUri web.config key to the new port number.
Warning: Changing the RelayListenUri to a different port will disconnect all other access clients. Your access clients will reconnect when you switch the RelayListenUri key back to its original port number.
Wait until your test machine has reconnected to the Host page. Connect to the machine, open the guest client, and view the Status menu. The "Relay Server" field should show your relay hostname and your new port.
After confirming that the test machine is connecting back to the server using its new port number, switch the RelayListenUri value in your web.config file back to its original port. Wait for all of your access sessions to reconnect to the Host page, and proceed to step 4.
Troubleshooting
If your test machine does not reconnect to the Host page after you use the Reinstall command, here are some common causes:
- Your new hostname has been entered incorrectly in the web.config file. Remove the RelayAddressableUri key from the web.config file, manually uninstall and reinstall the access client on your test machine, and try these steps again from the beginning.
- Your new hostname's DNS records have not yet propagated. Try pinging or testing your hostname in your browser to see if the address resolves correctly.
- A firewall, router, or some other network device is blocking traffic to your port. Make sure your rules are configured correctly to allow traffic through your new relay port.
4. Reinstall the access clients
Once the access clients all reconnect to the server, issue a Reinstall command from the Host page. You can run the Reinstall command on all machines at once, or you can roll out the changes slowly by using the Reinstall command on certain session groups or machines at a time.
5. Change the "RelayListenUri" port number to match
If you changed the port number of the relay address, and all of your machines are now disconnected, you will need to edit the port number of your RelayListenUri value to match your new RelayAddressableUri port number.
For Windows:
1 | <add key="RelayListenUri" value="relay://+:443/" /> |
For Linux and OS X:
1 | <add key="RelayListenUri" value="relay://+:443/"> |
2 | </add> |
Your access clients should reconnect to the Host page and should be using your new hostname, port number, or both.
