CEREAL-ADMIN(8)

📦 version 0.24, in debian bookworm, ubuntu jammy, ubuntu noble

✨ CEREAL-ADMIN ✨

ok so this is cereal-admin, section 8 of the manual (Administration Commands, iykyk), and bestie... it's literally the tool that runs the whole cereal situation. let's get into it 💖

🌸 NAME 🌸

cereal-admin — administer cereal sessions. that's it. that's the vibe. 💅

🎀 SYNOPSIS 🎀

cereal-admin command [args]

🦋 DESCRIPTION 🦋

ok so cereal-admin is a program to administer cereal sessions. and what's a cereal session, you ask? it's a special (restricted) screen(1) session attached to a serial terminal. yes, that screen. the restricted one. periodt.

every 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. and every cereal session is also associated with a particular log group (LOGGROUP) whose members are allowed to "follow" the logs of the session. so like, two different levels of access. the owner gets to actually touch the terminal, the log group just gets to watch. main character energy vs. spectator energy, no cap.

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

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

(go read it, it's giving documentation 💜)

👑 SUBCOMMANDS 👑

cereal-admin takes various subcommands. here's the whole roster, bestie:

  • 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. so it exists but it's not doing anything yet. lowkey napping. 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. it's awake!! 🔥 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 sessions 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. so it's a real shutdown, not a gentle one, bestie. 💀 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.
⚠️ okay so read that again. including all history of the session and the logs. that's gone-gone. not recoverable. no take-backs. 🙈

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. when in doubt, ask for help. iconic behaviour honestly. 💖

🍓 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. (yes, that's a real filename, go look for it in the package docs, bestie ✨)

🌈 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.
🫶 note that last one: a per-session screenrc wins over the default one. it's giving main character, it's giving override privileges.

⭐ EXIT STATUS ⭐

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

so like, 0 = slay, 1 = hm, 2 = we have a situation 😭

💜 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. so like... no read + execute perms on the supervise dir = the list output might be lying to you a little bit. ngl that's just how it is. 🙈

🧚 REPORTING BUGS 🧚

report bugs to <cereal@fifthhorseman.net>.

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.

💅 "NO WARRANTY" is in all caps for a reason bestie. no safety net, no promises, read the license.

🎀 SEE ALSO 🎀

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

okay that's the whole page, you ate that, go administer some cereal sessions 💖✨

this has been cereal-admin 0.1, from March 2007 — old but iconic, and yes the manual name up top really is CEREAL-ADMIN(8), section 8, administration commands, periodt. 🫶

📦 where this page comes from