Consolelines

Overview of Emulab Console Support

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:

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.