Installing and feeding VRS on headless Linux VPS

Credits to Chris for this tutorial.

This is a tutorial for installing Virtual Radar Server (VRS) on a Virtual Private Server (VPS) running Linux without a display. This is a common low-cost configuration. VRS is installed with its Web Admin interface under the Mono framework.

Versions used

  • VPS running Debian 10 (Buster) and up to date
  • VRS 2.4.4 20th December 2019
  • PiAware 3.8.0 SD card image
  • Mono 5.18.0.240 (this is what the latest Debian installed)

Assumptions in this tutorial

  • The VPS is sitting on vps.example.com 5. Substitute your VPS’s hostname or IP.
  • The VPS is running a systemd based Linux
  • Root access to install packages and manipulate the filesystem
  • The VPS is already as secure as needed
  • A PiAware feeder is already running and working fine. MLAT is also enabled in this example.
  • The VPS wil listen for ADS-B data on port 28000 and MLAT data on port 28001
  • nano is used as the text editor, substitue with your preferred editor if desired
  • tmux is used as the terminal multiplexer, substitute with screen if desired

Regarding security, this is subjective but generally it’s not a bad idea to restrict access to the VPS to yourself and your feeder while the config is in progress since VRS creates an unencrypted server with various levels of access. Many VPSs have a separate firewall admin panel, or perhaps you already have something like iptables running. Using public key ssh, disabling root login, disabling unused services and keeping it up to date are all good things.

VPS preparation

Install wget if not already installed.

$ sudo apt install wget

Install tmux if not already installed. If you’re already using screen and happy with that use that instead. Having one of these installed will allow VRS to stay running when disconnected from the VPS.

$ sudo apt install tmux

Install Mono, the open-source .NET framework. VRS requires this framework to run.

$ sudo apt install mono-complete

Stop and disable the MonoDoc service which just got installed on port 8084.

$ sudo systemctl stop mono-xsp4
$ sudo systemctl disable mono-xsp4

Make a directory for VRS to live in.

$ sudo mkdir /opt/vrs

VRS installation

Install VRS by grabbing the tarball and unpacking into /opt/vrs

$ cd
$ wget http://www.virtualradarserver.co.uk/Files/VirtualRadar.tar.gz
$ sudo cp VirtualRadar.tar.gz /opt/vrs
$ cd /opt/vrs
$ sudo tar xzvf VirtualRadar.tar.gz
$ sudo rm VirtualRadar.tar.gz

Install the VRS SQLite correction.

$ cd
$ wget http://www.virtualradarserver.co.uk/Files/VirtualRadar.exe.config.tar.gz
$ mv VirtualRadar.exe.config.tar.gz VirtualRadar.exe.config.tar
$ tar xvf VirtualRadar.exe.config.tar
$ sudo mv VirtualRadar.exe.config /opt/vrs

Install the VRS Web Admin interface.

$ cd
$ wget http://www.virtualradarserver.co.uk/Files/VirtualRadar.WebAdminPlugin.tar.gz
$ sudo cp VirtualRadar.WebAdminPlugin.tar.gz /opt/vrs
$ cd /opt/vrs
$ sudo tar xzvf VirtualRadar.WebAdminPlugin.tar.gz
$ sudo rm VirtualRadar.WebAdminPlugin.tar.gz

VRS Web Admin configuration

Create VRS admin user and config files

Start VRS to create an admin user called ‘vrsadmin’ and config files. The config files will be installed into ~/.local/share/VirtualRadar. Choose a strong password XXXXXXXX.

$ cd
$ mono /opt/vrs/VirtualRadar.exe -nogui -createAdmin:vrsadmin -password:XXXXXXXX

You’ll see VRS starting. Try accessing the Web Admin panel by visiting your VPS in a browser at the following URL. Note that under Mono all these URLs are case-sensitive, ie Index.html, Settings.html, etc

http://vps.example.com:8080/VirtualRadar/WebAdmin/Index.html

Work around restricted access default

Chances are this won’t work and you’ll have a blank browser page. This is because by default VRS restricts access to WebAdmin to the local network, and since you cannot access it you cannot change that setting. The workaround is to save the setting for unrestricted access directly into a local config file.

In the VPS terminal press ‘q’ to stop VRS. Go to the config files.

$ cd .local/share/VirtualRadar

Create a new config file called PluginsConfiguration.txt.

$ nano PluginsConfiguration.txt

Paste in the text below (all one line) and press Ctrl-x to save the file.

VirtualRadar.Plugin.WebAdmin.Options=%7b%22DataVersion%22%3a2%2c%22Enabled%22%3atrue%2c%22Access%22%3a%7b%22DefaultAccess%22%3a0%2c%22Addresses%22%3a%5b%5d%7d%7d

Access VRS web admin pages

Start VRS again and reload the URL again. It should now be available.

$ cd
$ mono /opt/vrs/VirtualRadar.exe -nogui

You should also be able to access the map. Open this URL in a separate tab and it should bounce you over to the desktop page as with normal Windows-running VRS.

http://vps.example.com:8080/VirtualRadar/

Change web server port if required

By default it’s on port 8080. If you want to change that create the file below.

In the VPS terminal press ‘q’ to stop VRS. Go to the config files.

$ cd .local/share/VirtualRadar

Create a new config file called InstallerConfiguration.xml.

$ nano InstallerConfiguration.xml

Paste in the text below. Change the port to whatever you want it to be. Press Ctrl-x to save the file.

<?xml version="1.0" encoding="utf-8" ?>
<InstallerSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <WebServerPort>8080</WebServerPort>
</InstallerSettings>

Restart VRS.

$ mono /opt/vrs/VirtualRadar.exe -nogui

It’s a good idea to clear your browser cookies and history so it’s not auto-completing the previous URL. Go to the WebAdmin and display URLs again in separate tabs using the new port XXXXX.

http://vps.example.com:XXXXX/VirtualRadar/WebAdmin/Index.html
http://vps.example.com:XXXXX/VirtualRadar/

This tutorial will continue to use port 8080.

VRS receiver configuration

The rest of the config is done from within the VRS web admin interface. This contains all the features present in the Windows VRS Tools / Options panel. Have a play around to see what’s there.

VRS Web Admin menu

Increase security for Web Admin and map access

The above workaround set the Web Admin interface to Unrestricted so it is open to everyone. To lock it back down click on Plugin: Web Admin and change it to Deny and add in an exception for your own IP address. Or leave it as Unrestricted if you’re happy that your VPS’s firewall is taking care of access control.

Next click on Options / Users and tick the box “User must authenticate” and add a non-admin user for normal access to the map.

Configure Receivers

Remember the assumption made at the start of this tutorial – the VPS wil listen for ADS-B data on port 28000 and MLAT data on port 28001. Use whatever ports work for you.

Click on Options / Receiver Locations and enter a Name, Latitude and Longitude of your PiAware installation (you can get this from your stats page if logged in).

Locations

Click on Receivers and add a new one with the name ADS-B. Format AVR or Beast Raw Feed. Select the location you configured. Tick Push Receiver. Enter port 28000. Untick Send keep-alive packets (Mono does not support them). For Access you can set this to Deny by default and then add an exception for your PiAware’s IP, or you can leave it unrestricted if you’re happy that your VPS’s firewall has this covered. Close the dialog to save the changes.

Now add another receiver, same settings as above except with the name MLAT and port 28001.

Click on Merged Feed and add a new one. Give it a name, select both receivers just configured and tick the MLAT box for the MLAT receiver. Close the dialog to save changes.

Go back to Receivers and select which one to use by default for the three options shown. Here you can see the merged receiver being used, which will display both the ADS-B and MLAT data.

Default receivers

*** SAVE YOUR CHANGES ***

IMPORTANT – SCROLL TO THE BOTTOM OF THE OPTIONS PAGE AND CLICK SAVE

If you don’t do that, all the above configuration is lost when you leave the Options page!

Testing the VRS config

In the VRS Web Admin page click on Home and check that both receivers are now waiting for data.

Keep both this tab and the map tab open to see when data is being received.

Testing the ADS-B receiver

Log in to a PiAware terminal and enter the command below to test the ADS-B feeder. The socat command mirrors the data from the ADS-B feed port to the waiting port on the remote server. The advantage of this approach is that it’s very simple, no new software has to be installed in PiAware and no local ports need to be opened for something to connect in to.

Raw ADS-B data comes from port 30005 and is being sent to port 28000 on the server. Raw MLAT data comes from port 30105 and is being sent to port 28001 on the server.

$ socat -u TCP:localhost:30005 TCP:vps.example.com:28000

Look at the Web Admin page and you should see the ADS-B receiver is now showing connected and is receiving data. You should also see aircraft appear on the map.

Hit Ctrl-c on the PiAware terminal to quit the socat command.

Testing the MLAT receiver

Same idea, enter the command below and watch to see the MLAT receiver light up.

$ socat -u TCP:localhost:30105 TCP:vps.example.com:28001

Hopefully this worked. If so then the final step is to put it together.

Fixing everything in place

Running VRS 24/7 in tmux

On the VPS stop VRS by pressing ‘q’. At the prompt start tmux.

$ tmux

This puts you in a new terminal window with a green banner at the bottom showing that you’re in window [0]. Start VRS again.

$ mono /opt/vrs/VirtualRadar.exe -nogui

Note that you need to reload the Web Admin and map web pages if you stop and restart VRS.

Now that it’s running, press Ctrl-b then d to detach from the terminal. It’s still running with VRS running inside it. You can now exit the VPS if you wish. To re-attach to the terminal at a later time, use the command

$ tmux attach

To quit a tmux terminal use the exit command from in it as you normally would to quit a terminal.

Other useful tmux commands:

Show all terminal sessions: tmux ls
Create a new session inside tmux: Ctrl-b c
Switch session 0,1,2…: Ctrl-b 0, Ctrl-b 1, Ctrl-b 2

There are plenty more features 1 to play with.

Feeding from PiAware 24/7

The problem with socat is that if the connection drops momentarily it will exit with a Broken Pipe error. The script below checks for each socat feed and starts it if it’s not running. This script is then run every 5 minutes from cron. This means in the event of any kind of disruption, once it’s fixed the PiAware box will be back to feeding VRS automatically within 5 minutes.

In PiAware edit a new file called vrsfeed.

$ cd
$ nano vrsfeed

Paste in the text below. Press Ctrl-x to save the file.

#!/bin/bash

# Start ADS-B transmission if not already running
if [[ -z $(ps -ef | grep '[s]ocat.*30005') ]]; then
  socat -u TCP:localhost:30005 TCP:vps.example.com:28000 &> /dev/null &
fi

# Start MLAT transmission if not already running
if [[ -z $(ps -ef | grep '[s]ocat.*30105') ]]; then
  socat -u TCP:localhost:30105 TCP:vps.example.com:28001 &> /dev/null &
fi

Make the file executable.

$ chmod +x vrsfeed

Move it to /usr/local/bin.

$ sudo mv vrsfeed /usr/local/bin

Open crontab.

$ crontab -e

After the comments enter the text below. This runs the script every 5 minutes. Save the file with Ctrl-x.

*/5 * * * * /usr/local/bin/vrsfeed &> /dev/null

crontab

Run the feeder script and watch the Web Admin page to see that both receivers start receiving data.

$ vrsfeed

Finally, restart PiAware to see that it comes up and starts feeding automatically.

$ sudo shutdown -r now

Keep an eye on the Web Admin page as PiAware reboots. Within 5 minutes it should start receiving data and aircraft are all visible on the map.

Additional steps

Final testing

You can do a final test if you want. Disconnect PiAware from your network and then reconnect. Check that it starts feeding again within 5 minutes. Log into the VPS, attach to tmux and quit then restart VRS. Again check that PiAware starts feeding again within 5 minutes. It should be automatic.

Adding more feeders

You can add your friends to this setup and see all your feeders aggregated on the one page. Log in to the Web Admin URL. Add a location for the new feeder. Create push receivers for both ADS-B and MLAT data for the new feeder, choosing two new unused port numbers, eg 28002 and 28003 in this example. If you’re restricting access by IP make sure to use the right values and be wary of dynamic IPs that are prone to change. Create more merged receivers to slice and dice the views as desired.

Add them as new (non-admin) users with their own password or just all use the same username and password if that works better for you.

Then send them the vrsfeed script modified for the new port numbers and have them install it and set up cron.

If you’re using a firewall on your VPS make sure it allows the new feeders through and gives them access to see the map.

Default page layout

Customising the layout for each new browser is a real pain. Fortunately VRS has a way to deal with that 1. Using a Windows installation of VRS go to the desktop.html page and get everything the way you want it. Then repeat for the mobile.html page. Then go to the settings.html page and click Export Settings. Copy all the text that appears.

initial

In the Web Admin page go to Options / Initial Settings and paste the text into the box and click Save. Now new browser sessions will have the layout you created.

Logos and silhouettes

On the VPS create a place for them in /opt/vrs

$ cd /opt/vrs
$ sudo mkdir OperatorLogos
$ sudo mkdir SilhouetteLogos

Find a source for each (eg these 5). Download the files into your home directory with wget, extract the image files and move them into the directories above. Then in the Web Admin panel go to Options / Data Sources and add the paths from above.

logos

More security

VRS only provides http access, not https access. Please be wary of that when accessing your VRS site from a third-party network, eg hotel wifi. Either VPN to your home or use a VPN which you trust. One way to address this could be to install a local web proxy on the VPS and then have that running SSL with Let’s Encrypt and feeding into VRS locally. I’m not sure where to start with that so another project for another day. I welcome any ideas on how to achieve it, the more straightforward the better.

Take a look in Web Admin at Options / Web Server / Restrictions on Internet Users. Be aware that receiver range plots make it easy to identify your location (or locations for multiple feeders). If this is just used by friends then it’s likely not a problem but if it’s more open then be aware and disable them if necessary.

VRS under Mono vs .NET

Take a look at VRS’s limitations when using Mono compared with .NET 5. You can go through the Web Admin panel and disable things which are not relevant such as UPnP and audio.

Quick link from PiAware

This is quick and dirty edit to get a link to the VRS page on the PiAware start page. In a PiAware terminal backup then edit the main index page.

$ cd /var/www/html
$ sudo cp index.html index.html.original
$ sudo nano index.html

Scroll to the line before the </body> at the end and paste in the text below (one line), editing it for your VRS link. Save with Ctrl-x.

<br><p align="center">[ <a href="http://vps.example.com:8080/VirtualRadar">VRS</a> ]</p>

VRS link

Bandwidth

I’ve read that a feeder sending both ADS-B and MLAT uses about 15Kb/second. This comes to around 40Gb/month per feeder. Then there’s also web traffic and airport-data photos. Make sure your VPS has enough bandwidth and you’re not going to get an unexpected bill at the end of the month. If you have a control panel which lets you see data used keep an eye on it for the first week or two.

VRS on PiAware?

From what I’ve read it looks like it’s possible to install Mono on PiAware and install VRS the same way as on the VPS using this guide. In that case the issue of the Web Admin panel being locked out and needing the config file workaround probably won’t come up since it will be getting accessed from the same network it’s running on. VRS supports Rebroadcast Servers 4, where a configured Receiver can be retransmitted out as a Push Feed, essentially replacing socat. If someone was looking at running VRS locally on their Pi anyway this is certainly worth exploring. I think there could be some tension between the desire to keep the OS fully up to date for VRS and Mono, but not wanting to update it in order to reduce the risk of breaking PiAware.

Conclusion and thanks

This was a fun project and allows a couple of my friends and I to pool our receivers on a single centralised map. Thanks to various contributors here for posts giving clues and ideas for the commands and to various people on the VRS forums for things like the Web Admin workaround. Thanks also to those involved in VRS development.

If you have a VPS or a spare Linux box please feel free to try this out and let me know if it worked for you and was useful.

Credits to Chris