GEREALCTL(1)

💖 GEREALCTL 💖

okay bestie, so this is the gerealctl manual page — it lives in section 1 of the manual (User Commands), and it's literally your group chat with the serial console. no cap.

🌸 NAME 🌸

gerealctl — manage gereal serial console sessions 🖥️✨

🎀 SYNOPSIS 🎀

gerealctl [options] command [session]

🦋 DESCRIPTION 🦋

so gerealctl is the command-line control utility for gereal(8), which is an automated serial console management system based on GNU screen and systemd. iconic combo honestly.

it lets users and admins do the whole thing: list the configured sessions, control their lifecycle via systemd, and attach to running screen sessions using a bunch of different authentication modes. it's giving full control, it's giving flexible. 💅

🌈 COMMANDS 🌈

• list — list every configured serial session. the vibes check, the roster reveal. 📋
• start session — start the given session via systemd. go bestie go 🔥
• stop session — stop the given session via systemd. rest era 😴
• restart session — restart the given session via systemd. glow-up, round two ✨
• status session — show the systemd status of the given session. wellness check 🩺
• attach session — attach to the running screen session. the main character moment 👑

💜 ATTACHMENT MODES 💜

by default, gerealctl tries the available attachment modes in this exact order, no skipping:

• direct — attach directly to the screen session as the current user, using screen -r gereal:<session> as the user that has invoked gerealctl. this can also be used with a dedicated user whose shell is set to gerealshell. lowkey the simplest way in 💫
• multiuser — attach using GNU screen's multiuser feature. this requires screen to be setuid root and the session's screenrc file to contain the multiuser on and acladd <user> directives. it's giving guest list, it's giving permissions 🎟️
• sudo — attach by invoking screen as the session owner via sudo ( sudo -u <user> screen -r gereal:<session> ). to keep sudo from asking a password, enter <youruser> ALL=(<user>) NOPASSWD: /usr/bin/screen -r gereal:* in a sudo configuration file. passwordless slay 🔐

a specific mode can be forced using the --mode option. periodt.

✨ OPTIONS ✨

• -m, --mode {direct|multiuser|sudo} — force a specific attachment mode. you pick, no algorithm deciding for you 💅
• -c, --conf file — use an alternate configuration file. the default is /etc/gereal/gereal.conf.
• -v, --verbose — enable verbose debug output. spill the tea, show me everything 🍵
• -h, --help — show help and exit. always allowed, always valid 🫶

🧚 CONFIGURATION 🧚

session configuration is read from gereal.conf(5).

okay real talk bestie: changes to the configuration require a systemctl daemon-reload to regenerate the systemd units. don't skip this step, it's not optional, it's not a vibe, it's a requirement. 😭

⭐ EXIT STATUS ⭐

• 0 — success. we ate. 🍓
• 1 — an error occurred. it's giving not it 💀

👑 SEE ALSO 👑

gereal.conf(5), screen(1), systemctl(1), sudo(8)

🌸 AUTHOR 🌸

Marc Haber <mh+debian-packages@zugschlus.de>

---

and that's the whole page, bestie 💖 this was gereal (the manual), January 2026, and it's the GEREALCTL(1) page — tysm for reading, go attach to something iconic 🦋✨