Overview of Emulab Console Support

NOTE: The following text assumes that you have PCI-based serial MUX cards that you can plug in to a PC to make a "tipserver." If you have a standalone network console server box, we have not done much in the way of support for these. See ConsoleServer for some preliminary notes on how we hacked up support for a Linux Networx Icebox.

Experimental nodes in Emulab often have serial consoles attached to them, and those serial lines are typically scattered amongst one or more machines with serial muxes attached. Emulab makes those console lines available to users when they swap in an experiment; they can look at the console logs, or they can start an interactive session so they can log in on the console. Since we do not want to give users accounts on all of the various machines where serial lines are hosted, Emulab employs a set of control processes and daemons to provide secure remote access to users in the same project that the experiment belongs to.

Once you have read this document, you should look at the Installation page to continue setting up your console support.

Capture

Capture is a daemon that runs on the tip servers. There is a capture process for each serial line, whose job is to both mediate access, and to record all console output into a log file for real-time or postmortem debugging. As with any serial line, only one user can interact with the console at a time, but anyone can view the log file (via the web interface) whenever they want, as long as they have permission to do so. For capture, permission means that the user connecting provides a secret key (specific to that one console line) that is known only to administrators or users in the same project. Users get that key via the web interface or via the Emulab XMLRPC server, although in practice users do not actually interact at that level, since we provide a wrapper to hide that detail (more on this later).

When capture starts up, it will generate a secret key and write that to a file in /var/log/tiplogs called "pcxxx.acl". An example acl file is:

host:   tipserv.emulab.net
port:   1608
keylen: 64
key:
ce9c7951707d56ca5996ee21577ca2457b9e5a3bd9ff5e6812561d1ed498d525

Capture then contacts the capserver daemon on Boss to tell it the same information so that boss can record the information in the Emulab DB. For each node with a console line, there is an entry in the "tiplines" table. The capserver daemon's job is simply to record this information each time capture restarts.

The host:port is the address to which users can connect to the capture process to start an interactive session on the console. Once the client connects, it will send a small header packet with the secret key. If capture likes the key, access to the console is granted.

On Boss, when an experiment is swapped out, access to the console lines must be revoked. This is accomplished by contacting the capture process for each serial line, and sending it a signal that tells it to terminate the client connection and regenerate the secret key. The new secret key is then sent over to Boss as per the description above of the capserver daemon.

console.bin

console.bin is a client that connects to a running capture process on either the same machine or another machine. The argument is either the name of a node or the name of an "acl" file containing the port and key information. If a node name is supplied, as in:

tipserver> console.bin pcxxx

then console.bin will look for the acl file in /var/log/tiplogs, so in practice this form is used only by testbed administrators on the tipserver machines. It can also be invoked as:

tipserver> console.bin /some/file/name

where the file contains the same port/key info as the acl file. This form is typically invoked on Boss or ops or an experimental node, from a wrapper script that gets the port/key info from the Emulab DB on Boss. More on this below.

Once the connection is established, console.bin will exec telnet for the user.

console

console is a perl wrapper around console.bin, and is intended to be run by an Emulab user on either ops or an experimental node. The wrapper contacts the XMLRPC server on Boss to get the port/key info for the node, writes that to a temporary file, and then invokes console.bin as described in the previous section. The user must have the proper permission to access the node (a member of the project that the experiment belongs to), or else the XMLRPC server returns a permission error.

On Boss, console is a slightly different wrapper, since there is no need to contact the XMLRPC server; the info is right there in the Emulab DB. It is typically the case that the user trying to access the console line is a testbed administrator, and hence not actually a member of the project the experiment belongs to. The Boss version of the wrapper pulls the information out of the DB, writes it to a temporary file, and invokes console.bin as described in the previous section.

tiptunnel

tiptunnel is a variation of console.bin that is compiled with SSL enabled, and is intended to be used on a non-local network to access a console line. SSL is used to prevent the secret key from being snooped by a third party. Otherwise, tiptunnel usage is equivalent to console.bin. Popular with Emulab users is to compile tiptunnel to run on their desktop machine, and have it invoked from their Web Browser when clicking on the "ssh to console" button on the Show Experiment page for an experiment. The port/key info is returned securely to the browser, so that it can be passed to tiptunnel.

More information about this can be found on the Emulab web site, including how to install tiptunnel so that your web browser can run it.

capserver

This is a very simple daemon that runs on Boss on a reserved port. It listens for connections from the tipserver machines, and records the new secret key and port in the Emulab DB. Log output is written (via syslog) to /usr/testbed/log/capserver.log so that you can see the history of key generations.