Jack Whitham - Virtual Lab - Administrating VL2

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

		Home -> Software -> Virtual Lab -> Administrating VL2


	On this page: Administrating VL2 Installing Adding a VL2 user Removing a VL2 user Network configuration Adding a new board When things go wrong


	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

Administrating VL2

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:

A user account for each VL2 user, with
- the public key for the authorisation file in the user's home directory, e.g. "/home/username/.ssh/authorized_keys".
- the shell set to /usr/bin/relay.
- no password (i.e. password authentication is disabled.)
A single copy of the mutex daemon, always running, and a correctly configured /etc/mutexdaemon.conf file.
A Unix group for each group of VL2 users.

The following sections discuss some common administration tasks.

Installing

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

Python (version 2.5+),
Twisted (version 8.1+),
OpenSSH,
the vlab module (use the system-wide distutils installer),
the relay shell program,
the mutex daemon program,
and finally, the "setupuser" tool in the "bin/" directory of the VL2 software. Copy this to /usr/bin and make it owned by root, as for "relay" and "mutexdaemon".

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:

Instead of a normal shell program (/bin/sh), VL2 users always use the relay shell (/usr/bin/relay). Set this for any user with the command:

        usermod -s /usr/bin/relay username

VL2 users don't have passwords; password authentication is disabled. Set this for any user with the command:

        usermod -L username

VL2 users have an "authorized_keys" file in "/home/username/.ssh". This is the one half of a key pair; the other half is the authorisation file sent to the user. Generate the key pair using the command:
```
        setupuser key hostname username 
    
```
This invalidates username's existing authorisation file (if any). In the current directory, it creates "username.key" (the new authorisation file) and in the user's home directory, it creates "/home/username/.ssh/authorized_keys" (the SSH public key file). hostname must be the fully-qualified domain used to access the relay server via the Internet.

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:

For each board cluster X listed in the /etc/mutexdaemon.conf file, the mutex daemon has a list Y of the Unix groups that are allowed access to that cluster.
All users who are members of any group y in Y are allowed access to any board instance x in X.

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:

    [s3esk]
    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