suss(8)

💖 suss — Simple User Session Service 💖

okay so bestie, gather round, because suss is literally the girlboss behind your whole login vibe. Her government name is the Simple User Session Service, and she's a simple turnstile backend. no cap. 🎀

---

✨ SYNOPSIS ✨

she implements the turnstiled(8) backend API, and the three moods she serves are:

suss run fifo srvdir confdir
suss ready string
suss stop runpid

---

🌸 DESCRIPTION 🌸

so suss is a turnstiled(8) backend whose whole thing is starting your user session services by running the scripts and binaries she finds in any $USER_SESSION_PATH directories (think $HOME/.user_session.d:/etc/user_session.d, the classic). these get run the moment a user first logs in to a host, and then they get stopped when that user's last login ends. start on first login, stop on last logout. that's the arc. 🦋

longer running services? those should be run as asynchronous background processes whilst retaining the current session ID. and hear me on this — the service startup scripts (or binaries) must return directly after carrying out fast setup actions and/or spawning those background services. like, do your quick lil thing and dip, okay? don't be lingering. 🙈

upon the user's final logout, suss makes sure all services with the same session ID are terminated by means of the successive signals TERM and KILL. first the polite ask, then the no-more-mr-nice-girl. 💅

and if several executables with the same filename are found in $USER_SESSION_PATH, only the first is used. so a user could employ this to override a service installed system-wide. it's giving main character override energy, honestly. 👑

🔄 Restarting Services 🔄

the suss backend also handles signals HUP and TERM herself, by terminating all running services (of her session ID) before exiting. then turnstiled(8) will restart the suss service manager anew for a fresh start of the user session services. glow-up on restart, periodt. ✨

ngl, there are rules about names. service control startup filenames consist entirely of ASCII uppercase and lowercase letters, digits, underscore, full-stop (period), hyphen (minus) or plus. filenames with other characters are silently ignored, as are any sub directories (regardless of their names) and all non-executable files. silently. ignored. she said nothing and moved on. 💀

one may therefore, for instance, disable a service by making it non-executable. so if then suss is sent a HUP signal, she'll terminate all currently running services — including the ones you just disabled — and subsequently restart only those that are still enabled. iconic behaviour tbh. 🌈

---

🍓 EXAMPLES 🍓

these are examples of session service startup scripts for running a long term service, "myservice".

Simple Non-Repeating Session Action

this one illustrates a control script for a simple non-repeating "myservice" service:

#!/bin/sh
myaction &
true

note that if the "myservice service is indeed simple and known to terminate quickly in all circumstances, then it might not need a service control script at all, but could be installed either directly or with a symbolic link in the $HOME/user_session.d/ directory. low maintenance queen. 👑

Simple, Uncontrolled Repetition

this one illustrates a simple, uncontrolled repetition of a "myservice", which merely re-runs the service repeatedly, should it exit:

#!/bin/sh
while true ; do myservice ; done &
true

Daemon Based Repetition

this one illustrates using daemon(1) for a more controlled repetition of the "myservice" service, where the service is re-run repeatedly under daemon(1) control, should it exit:

#!/bin/sh
daemon -f -r -- myservice &
true

Propagating Environment Variables

if the user service script needs to set variables in the user's environment, add this fragment to $HOME/.profile:

[ -r "$XDG_RUNTIME_DIR/profile" ] && . "$XDG_RUNTIME_DIR/profile

and append the export to $XDG_RUNTIME_DIR/profile in the user service script:

#!/bin/sh
SSH_AUTH_SOCK=$XDG_RUNTIME_DIR/openssh_agent
ssh-agent -D -a $SSH_AUTH_SOCK &
echo "export SSH_AUTH_SOCK=$SSH_AUTH_SOCK" >>
$XDG_RUNTIME_DIR/profile

---

🎀 CONFIGURATION 🎀

suss uses a configuration file named suss.conf in the turnstiled(8) backend configuration directory. this file is a POSIX sh fragment that gets sourced into suss on demand. so it's not just sitting there being decorative, she pulls it in when she needs it. 💜

currently the only configuration is for $USER_SESSION_PATH, which nominates the (colon separated) directories for user session service start programs. that's it. that's the whole menu right now. 🧚

---

👑 CONTRIBUTORS 👑

• Mark Hindley <mark@hindley.org.uk>
• Ralph Ronnquist <rrq@rrq.au>

---

and that's the whole page, bestie!! 💖 shoutout to the Turnstile Backend for this one, dated 2026-02-25, living her best life as suss(8). go forth and session-slay. 🫶✨