Home -> Relay Shell    

  On this page:  
  VL2 documentation:  
On the relay server, the relay shell (relay) is a program which is assigned as the Unix shell for each VL2 user. This means that it replaces a more conventional shell program such as /bin/sh. After authentication, VL2 users are placed in a restricted environment in which the only valid commands are vlab protocol commands.

This component of the virtual lab is considered to be confidential, so it is not available for download. However, the documentation is still published for completeness. In the source code repository, the relay shell can be found in "nonfree/software/". A binary can be found in "bin/". The relay shell is also discussed in the administrator's manual.

Compiling the relay shell software

The instructions are the same as for the board server software. Most of the relay shell code is shared with the board server. The relay shell-specific module is:


The relay shell binary should be installed in a system directory, with sensible permissions (e.g. -rwxr-xr-x) and owned by root. "/usr/bin/relay" is a good place. The relay shell should be set as the shell for every VL2 user. This can be done using the following command:
    usermod -s /usr/bin/relay username
No configuration files are needed for the relay shell. You can test the relay shell by running it directly:
You will see a message like:
    rversion 0.1 Relay software build Jul 18 2008 11:44:39
The relay server will not start up properly unless the
mutual exclusion daemon is running. This daemon should be launched on system boot.


Every command given to the relay shell is written to syslog using the name "relay". This includes commands that are passed to the board server after a connect command has been issued. Additionally, any bit file that is uploaded (using the sendbits command) is written to the home directory of the user who uploaded it. A typical log message appears as follows, with the PID of the relay program in square brackets:
Aug 11 14:52:01 localhost relay[4391]: User (c): "setuart 0 115200"
Bit files are given timestamped file names that include the board name and bit file identifier (BID), such as:
In this case, the board name is burchtest and the bid is 672. The bit file is compressed using zlib. It does not have a standard gzip header, so it can only be decompressed by using zlib directly. However, this can be done using a simple Python program:
    import zlib, sys, os
    inname = sys.argv[ 1 ]
    outname = os.path.splitext(inname)[ 0 ] + '.bit'
    file(outname, 'wb').write(zlib.decompress(file(inname, 'rb').read()))
(Run this program with a .biz file as a parameter; a .bit file will be produced in the same directory as the input.)


On startup, the relay shell connects to the mutex daemon and uses the "setuid" command to set permissions correctly. It can then execute the following commands:

  Copyright (C) Jack Whitham 1997-2011