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)