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)