Jack Whitham - Virtual Lab - Mutual Exclusion Daemon

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

		Home -> Software -> Virtual Lab -> Mutual Exclusion Daemon


	On this page: Mutual Exclusion Daemon Sample configuration file Controlling the mutex daemon 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

Mutual Exclusion Daemon

On the relay server, the mutual exclusion daemon (mutexdaemon) is a daemon (server program) that provides the following services:

Board database. On startup, the daemon reads a list of logical and physical VL2 boards from the "/etc/mutexdaemon.conf" file. This read-only database is used to (1) authorise user connections to specific logical boards, and (2) look up IP addresses for the physical boards. Users can only connect to boards that are listed in the board database (there is no way to connect to an arbitrary IP address). Access to a specific board can also be restricted to users in a specific Unix group.
Clustering. Several physical boards can be given the same logical board name. When a user asks for this name, he/she is allocated a free board from the cluster.
Mutual exclusion. Each physical board is automatically locked for a single user upon connection, and unlocked after disconnection. (That user can open more than one connection to this board.)

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 mutex daemon can be found in "nonfree/software/" and the "bin/" directory.

The mutex daemon is also discussed in the administrator's manual.

Installing the mutex daemon

The daemon is written in Twisted Python, so it requires a system-wide installation of the vlab component. Use the distutils installer from the download page. Having done this, copy "mutexdaemon" from the "bin/" directory to "/usr/bin" and make it executable and owned by root.

Then, write a configuration file (see below) and arrange for the daemon to start up with your computer by adding the following line to "/etc/rc.local":

    twistd --pidfile=/var/run/mutexdaemon.pid --syslog -y /usr/bin/mutexdaemon

Sample configuration file

The mutex daemon configuration file is "/etc/mutexdaemon.conf". Here is a sample:

    [burchtest]
    address = 192.168.124.51
    address = 192.168.124.53
    address = 192.168.124.56
    group = jack 
    group = vltest 
    group = vluser

    [s3esk]
    address = 192.168.124.52 
    group = vltest 
    group = vluser

In this sample configuration, there are two logical board names ("burchtest" and "s3esk"). The first of these has three physical boards, with addresses 192.168.124.51, 192.168.124.53, and 192.168.124.56. It is available to users in the Unix groups named jack, vltest and vluser. The second logical board ("s3esk") has only one physical board with address 192.168.124.52. This is available to users in the Unix groups vltest and vluser.

Controlling the mutex daemon

Updating the configuration/user database/group database. If you change the configuration or anything it relies on (/etc/passwd, /etc/group), your changes will not be recognised automatically. The following actions may change the configuration:

Editing /etc/mutexdaemon.conf
Adding a user
Adding a user to a group
Adding a group
Removing a user or group

One way to make the mutex daemon read the changes is to restart it by force, i.e. by killing the process and then running the twistd command again. But this will cause serious problems if any users are active in the VL2 system at the time, because mutual exclusion locks will have been reset while they were being used. Therefore, you should issue the following command:

    mutexdaemon reload

This command tests the new configuration, including the user and group databases, and then instructs the daemon to reload it from disk. This does not reset any locks. If you delete a board from the configuration while it is in use, then the mutex daemon will maintain its lock until the final user disconnects, but no further connections will be allowed. If you delete a user while that user is active, then the semantics are similar: that user can maintain his/her connection, but not make new ones.

Examining the status of the system. The command:

    mutexdaemon query

prints a list of clusters, and boards within each cluster, along with information about who is using each one and which ones are offline. If you change the configuration, be sure to run the reload command first, because the query command expects the database on disk to be current.

Logging

Every command given to the mutex daemon is written to syslog.

Operation

On startup, the mutex daemon reads /etc/mutexdaemon.conf, /etc/passwd and /etc/group. It uses this information to build its board database. (This action is repeated if you issue a reload command.) It creates a Unix socket named /tmp/mutexdaemon: every relay shell will connect to this socket after startup. If it is not available, or if the mutex daemon is not running, the relay shell will exit with an error. Each relay shell will consult the mutex daemon as part of processing a "connect" vlab protocol message.

The mutex daemon services three types of request from the relay shell:

setuid. Informs the mutex daemon of the Unix user id of the relay shell. This affects the availability of boards. Obviously the relay shell is trusted to send the correct value; VL2 is not secure if users are able to log in using other shells.
userrequest. Requests a list of users for a specific logical board name. This covers all of the physical boards with that name. The information is returned as one or more "userinfo" messages. This is used by the "query" command.
boardrequest. Requests a lock for a logical board. Connection information for one of the physical boards with that name may be returned using a "boardassign" command. Locks are held until the relay shell disconnects from the mutex daemon.


		Copyright (C) Jack Whitham 1997-2011