[[PageOutline]]
= `cereal` =

`cereal` is a serial terminal management system. `cereal` provides a framework to easily set up and maintain automated, timestamped logs of serial lines, while simultaneously allowing end user access to them.  This is probably most useful for providing automated, logged access to remote serial consoles.

`cereal` can control an arbitrary number of independently monitored and logged lines.  Direct access to the monitored lines is allowed only to a specific user (who doesn't necessarily otherwise have access to the direct serial line), but logs can be made available to any group.  Logs are rotated automatically and their total space can be limited in size.

`cereal` uses [http://www.gnu.org/software/screen/ GNU screen] as the terminal interface to the serial lines. `cereal` attaches a screen session to a specified serial terminal, and then monitors the screen session with [http://smarden.org/runit runit].  Any activity on that screen session is written to a log file.

`cereal` was conceived as a way to manage the monitoring of serial consoles on other machines.  Other than network connections, serial lines are the most useful way to interact with a machine.  All legitimate BIOS, bootloaders, and operating systems can provide console/terminal access through a serial line.  In a high-density environment, such as a rack, all machines can be configured with their consoles on a serial line.  A ''serial console server'' can then be setup with a high number of serial ports to monitor the serial consoles of all the machines in the rack.  Serial monitoring requires less space, and is more flexible and convenient that typical KVM systems.  `cereal` can be used on the serial console server to manage all the serial connections to the machines in the rack.

`cereal` is available under the [http://www.gnu.org/copyleft/gpl.html GNU General Public License], v3 or later.

== terminology ==

 * a "session" connects a "terminal", with screen, to a "host" (serial console) via serial "line"
 * one can "attach" to enabled session
 * one can "follow" enabled session (read logs)

== dependencies ==

`cereal` depends on [wiki:runit] and [http://www.gnu.org/software/screen/ GNU screen].

== hardware ==

`cereal` is particularly useful on machines with large numbers of serial ports, acting as a console server.  How can you make it so that your machine has a large number of serial ports for a reasonable price?

 * [http://www.lavalink.com/index.php?id=232 the Octopus-550], an 8-port PCI card.  These work well under linux, and CMRG has lots of experience with them.  search around a bit for the best prices.  Highly recommended.
 * [http://www.serialgear.com/8-Port-Serial-Adapter-USBG-8X-RS232.html CableMax USBG-8X-RS232 USB 8-port serial adapter] -- uses the Prolific chipset (pl2303), which has robust driver support in Linux.  Doesn't require external power or a hub for 8 ports, which is nice.  One purchased in early 2009 does indeed use `pl2303`, and works great with cereal on debian lenny.
 * [http://sewelldirect.com/USB-To-8-Serial-9-pin-RS-232-DB-9-Adaptor-3-feet_specs.asp AUM180 USB 8-port Serial adapter] -- also claims to use the prolific chipset.  haven't tried it, but looks nice and compact.

Note: If you're using udev and USB, you might have trouble getting the devices to be named consistently.  [http://kitenet.net/~joey/blog/entry/random_tip:_per-port_naming_for_identical_USB_devices/ Joey Hess has a good concise writeup of how to do that] (assuming you don't swap around your USB cables).

== download ==

[http://packages.qa.debian.org/cereal cereal is of course available in Debian.]  We recommend using debian's repositories unless you are building from source.

Access to the source is available via git:
{{{
git clone git://finestructure.net/cereal
}}}

== bugs ==

Please report bugs via [http://bugs.debian.org/cereal the Debian BTS].  If you're running debian already, this is as easy as:

{{{
reportbug cereal
}}}

We have some legacy open issues on this tracker:
[[TicketQuery(status=new|assigned|reopened&component=cereal)]]