NAME

       cereal-admin - administer cereal sessions

SYNOPSIS

       cereal-admin command [args]

DESCRIPTION

       cereal-admin  is  a  program  to  administer cereal sessions.  A cereal session is a special (restricted)
       screen(1) session attached to a serial terminal.  Each cereal session  is  owned  by  a  particular  user
       (USER)  who  is  allowed  to "attach" to the cereal screen session and interact with the specified serial
       terminal via screen.  Each cereal session is also associated with a particular log group (LOGGROUP) whose
       members are allowed to "follow" the logs of the session.

       Cereal  was  designed  to  monitor serial lines connected to the serial consoles of remote machines.  The
       cereal system is outlined at:

          http://cmrg.fifthhorseman.net/wiki/cereal

SUBCOMMANDS

       cereal-admin takes various subcommands:

       create SESSION TTY BAUD USER LOGGROUP
              Create a new session named SESSION on tty TTY, with baud rate BAUD.  USER is the  user  that  will
              own  the  session,  and  LOGGROUP  is  the  group  that  will  be  able to follow the session non-
              interactively (ie. read the logs).  Once created, the session will be in a "stopped"  state.   `c'
              may be used in place of `create'.

       start [options] SESSION [SESSION]...
              Start session(s).  For each session specified, the session directory is registered in the runsvdir
              directory.  The screen session will be attached to the serial terminal and logging of the terminal
              will begin.  `s' may be used in place of `start'.  options: -a (--all) to enable all sessions.

       restart [options] SESSION [SESSION]...
              Restart  session(s).   This sends running sessions a "restart" signal, and starts session that are
              not running.  This can be used when changes have been made to the screenrc, for instance.  `r' may
              be  used  in  place  of `restart'.  options: -a (--all) to disable all sessions, -r (--running) to
              restart just the currently running sessions.

       stop [options] SESSION [SESSION]...
              Stop session(s).  This kills the screen session attached to the serial terminal by sending  it  an
              "exit"  signal, and then unregistering the session directory from the runsvdir directory.  `k' may
              be used in place of `stop'.  options: -a (--all) to disable all sessions.

       destroy [options] SESSION [SESSION]...
              Destroy session(s) entirely.  This will destroy the session directory, including  all  history  of
              the  session  and the logs.  `d' may be used in place of `destroy'.  options: -a (--all) to remove
              all sessions.

       list [SESSION]...
              List session(s).  With no arguments, will list all sessions.  The leading three characters in  the
              list indicate: whether the session is running (+) or not (-) or in some unknown state (?), whether
              the user can attach to the session (a) or not (-), whether the user can follow the session (f)  or
              not  (-).   If  the  session  state  is  unknown  (?),  it's  usually  because the user asking for
              information about the session can't read the session stat file.  `l'  may  be  used  in  place  of
              `list'.

       help   Output a brief usage summary.  `h' or `?' may be used in place of `help'.

LOGS

       Logs are handled by svlogd.  For information on how to control session log handling, please see svlogd(8)
       and/or log-limits.txt from the documentation of this package.

FILES

       /etc/cereal/screenrc
              Default cereal screenrc file.

       /etc/cereal/cereal-admin.conf
              Configuration file to set parameters for session creation and management.

       /var/lib/cereal/sessions/$SESSION/screenrc
              Special screenrc file for session SESSION.  The  presence  of  this  file  overrides  the  default
              screenrc file /etc/cereal/screenrc.

EXIT STATUS

       Exit status is 0 if OK, 1 if minor problems, 2 if serious trouble.

AUTHOR

       Written by Jameson Rollins and Daniel Kahn Gillmor.

BUGS

       If  the  invoking user does not have read and execute access to the cereal session's supervise directory,
       `cereal-admin list' may not always indicate that session's status accurately.

REPORTING BUGS

       Report bugs to <cereal@fifthhorseman.net>.

COPYRIGHT

       Copyright © 2007 Jameson Rollins and Daniel Kahn Gillmor
       This is free software.  You may redistribute copies of it under the  terms  of  the  GNU  General  Public
       License <http://www.gnu.org/licenses/gpl.html>.  There is NO WARRANTY, to the extent permitted by law.

SEE ALSO

       cereal(1), screen(1), runsvdir(8), svlogd(8)