Home -> Administrating VL2    

  On this page:  
  VL2 documentation:  
The VL2 administrator has a number of tasks, which centre around the relay server. The relay server is a Unix-like system (most likely Linux) with the following properties: The following sections discuss some common administration tasks.


To configure a system for operation as a relay server, you will need to install (in order):

The first three components are part of the Debian and Ubuntu package repositories, so you can install them with "apt" if they are not already present.

You will also need to configure the mutex daemon (see below) and arrange for it to start up on boot.

Adding a VL2 user

VL2 users are almost the same as regular Unix users; you can add a new VL2 user using any Unix administration tool (e.g. useradd). There are three differences:

You can make any user into a VL2 user by running the above three commands. The final step is to email the "username.key" file to each user.

The setupuser tool automates the process of creating a user, setting up the shell, disabling password authentication and generating a key pair. This can be done by running:

    setupuser user hostname username 
hostname must be the fully-qualified domain used to access the relay server via the Internet. If the user already exists, then this command will delete their account (but not their home directory) and recreate it! If you need to set up many users, then you can specify many user names, e.g.:
    setupuser user hostname alice bob charlie dave eve

Having added a user, you will need to give that user permission to use VL2 boards.

Removing a VL2 user

To deactivate a user, either delete their user account:

    userdel username 
or remove their "/home/username/.ssh/authorized_keys" file.

Network configuration

The relay server should be a dual-homed machine, i.e. it should be present on two networks. There must be an internal network for board servers; this must not be accessible from the external network, except via the relay server.

Don't allow the VL2 users to log in on the relay server (except using the relay shell). If they can log in, then they can bypass the VL2 security by connecting directly to the board servers (e.g. by telnet). They can also connect to the mutex daemon and disrupt the operation of VL2, e.g. by locking all the boards. VL2 is not secure against this sort of "local user" attack.

To prevent users bypassing VL2 security by SSH forwarding, add the following lines to the end of "/etc/ssh/sshd_config":

AllowTcpForwarding no
GatewayPorts no
X11Forwarding no

User Permissions

VL2 user permissions are based on Unix groups. The system works as follows:

Suppose you are teaching a class of 20 students, and you want to give all of them access to a board cluster named "s3esk". You'd begin by creating a user account for each student (see above). You'd then create a new Unix group - you could give it any name, but "s3eskgrp" will be assumed. Create the group as follows:
    groupadd s3eskgrp
Then add each student's user account to the group.
    usermod -a -G s3eskgrp username
Then create a statement in /etc/mutexdaemon.conf similar to:
    address = s3eskboard1
    address = s3eskboard2
    address = s3eskboard3
    address = s3eskboard4
    group = s3eskgrp
Finally, run
    mutexdaemon reload
to update the configuration database. The result: any of the users who are members of the Unix group s3eskgrp can now access the board cluster named "s3esk".

You can revoke the permissions for a single user by removing him/her from the group.

Adding a new board

New boards can be brought online by the process described on this page, then configured as on this page. When you have configured a board, you will have given it an IP address, a MAC address, a website URL for updates and an FPGA configuration. The IP address is then added to one of the clusters defined in /etc/mutexdaemon.conf as appropriate.

You can also use a Linux PC as a board server, by running the "embedded" binary from the "bin" directory. It will expect a "/etc/boarddaemon.conf" file, which has the same format as "econfig" in the FX12 version.

You should ensure that all of the boards in a cluster are effectively identical, because if there is more than one board in a cluster, and a user is not already using any other boards in that cluster, then assignment is random.

When things go wrong

VL2 has some ability to recover from one type of problem. FPGA board servers may go offline, e.g. because of malfunction or maintenance. After a failed attempt to connect to an offline board, the relay shell will notify the mutex daemon that the board is offline. It will then be taken "out of circulation" for five minutes; other boards in the cluster will be used. If the cluster is large enough, users will not notice. After five minutes, connections are retried. This also allows the VL2 administrator to temporarily remove boards without editing /etc/mutexdaemon.conf.

However, many other problems will require the administrator to intervene. To help with this, the relay shell and mutex daemon log commands and status data to the syslog (/var/log/syslog by default). The logging includes some of the commands sent to the board servers (up to the "useuart" command if issued). Bit files uploaded by users are also stored by the relay server. Thus, if a problem occurs, the administrator has a way to trace it to a specific user and bit file.

  Copyright (C) Jack Whitham 1997-2011