Jack Whitham - Virtual Lab

		JACK WHITHAM PhD MEng Professional Activities - Publications - Software - Articles

		Home -> Software -> Virtual Lab -> Relay Shell


	On this page: Relay Shell Compiling the relay shell software Installation Logging Operation


	VL2 documentation: Introduction Administrating VL2 Authorisation File Board Server Board Server Hardware Debug Device Design Goals Downloads EMS Client Extending VL2 Mutual Exclusion Daemon PPC Linux for FX12 FPGAs Relay Shell Using VL2 vlab Module vlab Protocol vlabif Module vlabif Protocol vlabifhw

Relay Shell

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:

relay.c - the relay shell main function and select engine.

Installation

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:

    /usr/bin/relay

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.

Logging

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:

/home/vluser/2008-08-11--14-52-01--burchtest-672.biz

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.)

Operation

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:

connect. Connect requests are passed on to the mutex daemon as "boardrequest" commands. The mutex daemon replies with an error (if the request is denied) or with a "boardassign" message containing an IP address and port number (if the request is accepted). The relay server takes appropriate action: informing the client and connecting to the address in the second case.
userrequest. This command is forwarded to the mutex daemon.
usinguart/loadready. These commands come from the board server. They are forwarded to the client, but they also affect the logging process. "usinguart" stops the logging process on the grounds that future messages are binary data being relayed between a UART and the client. "loadready" causes bit file data to be captured and stored on disk.


		Copyright (C) Jack Whitham 1997-2011