shed.1.in

.TH SHED 1 shed\-@VERSION@
.SH NAME
shed \- Session sHell Execution Daemon
.SH SYNOPSIS
.B shed
.RB { SHED_SESSION }
.TP
.B shedc
.RB [ \-nphV ]
.RB { info | reload | relaunch | logout }
.RB { \fB start | stop | restart | hup \fP }
.IR service | all
.SH DESCRIPTION
.P
shed is a daemon intended to run as session process, it receives the
.B SHED_SESSION
optional argument to determine which set of configs to load.
.P
shed is also a completely init independient implementation of per user services
and a session process, all the features are opt in so you are not required to
"buy into" the shed way of doing things.
.P
shedc is the command to control shed, start, stop, hup and gather the status of
the running user session services, shedc requires a shed instance as parent to
work correctly, in specific it requires the
.B SHED_SESSION
and
.B SHED_SESSION_PID
env vars to be set in order to work as intended.
.SH OPTIONS
.TP
.B "\-h"
Print brief usage information to standard output and exit.
.TP
.B "\-n"
dry run, does not execute the action.
.TP
.B "\-p"
Print reply from daemon and status information with prettyprint.
.TP
.B "\-V"
Show shedc version.
.SH ACTIONS
.TP
.B "hup"
send HUP to session service.
.TP
.B "stop"
send TERM to the session service.
.TP
.B "start"
send a request to start the session service.
.TP
.B "restart"
stop the session service and then start it.
.TP
.B "logout"
send TERM to the session services and then terminate the session.
.TP
.B "reload"
reload shed, this just tells shed to re-exec.
.TP
.B "relaunch"
send TERM to the session services and reload shed.
.TP
.B "info"
shows information about the running shed daemon: SESSION, PID, client version,
daemon version, start date, rundir.
.TP
.B "status"
show status for the services.
.TP
status for the services is shown as follows:
.TP
[ + ] means the service is running
.TP
[ - ] means the service is not running
.TP
[ ? ] means the service was started but the pid was not among the active processes
.TP
[ 0 ] means the oneshot completed succesfully
.TP
[ 1 ] means the oneshot completed unsuccesfully
.SH SIGNALS
.P
The signals handled by the
.B shed
daemon:
.TP
.B "USR1"
On SIGUSR1 shed is nudged to process the QUEUE_FILE, when text is written to the
msg_socket a subshell will append it to the QUEUE_FILE, then nudge the main
process with SIGUSR1 to process the actions line by line, this signal is used
internally so externally sending it will accomplish nothing.
.TP
.B "HUP" "USR2"
On SIGHUP shed performs a
.B reload
action.
.TP
.B "INT"
On SIGINT shed stops all services and components.
.TP
.B "CONT"
On SIGCONT shed starts all components and services.
.TP
.B "TERM"
On SIGTERM shed stops all services and components.
.TP
.B "QUIT" "EXIT"
On SIGQUIT shed stops all services and components, then performs rm -rf on the
$ShedSessionDir and finally kill $SHED_SESSION_PID, which maps to the session
leader.
.SH CONFIGURATION
.P
The configuration for shed is performed in:
.B ${XDG_CONFIG_HOME:-${HOME}/.config}/shed/
with a fallback in
.B /etc/shed/
the directory may contain the shed daemon configuration file,
.B shed.rc
, the file to enable the usage of start-stop-daemon
.B use-start-stop-daemon.rc
, the file to set the log level
.B loglevel.rc
as well as subdirectories
.B shallow.d
,
.B env.d
,
.B services
and
.B components
not to mention the
.B transient
script, the following assumes the 'default' session is going to be used.

.P
The
.B shed.rc
file is just a simple key=val file with the following options:


.TP
.B set_xdg_desktop_vars
werether shed should set the XDG_SESSION_DESKTOP and XDG_CURRENT_DESKTOP env
vars, useful when for example running a window manager and wanting to have an
xdg-desktop-portal config which is set after the value of XDG_CURRENT_DESKTOP
in the form:
$XDG_CONFIG_HOME/xdg-desktop-portal/${XDG_CURRENT_DESKTOP}-portals.conf
just setting this variable to a non empty value will enable the option

.TP
.B session_desktop
value that will be exported to: XDG_SESSION_DESKTOP

.TP
.B current_desktop
value that will be exported to: XDG_CURRENT_DESKTOP

.TP
.B use_xdg_session_type
the XDG_SESSION_TYPE originally introduced by systemd and barely documented,
as with all poettering inventions, used and depended by anything and
everything that uses XDG_RUNTIME_DIR and everything in between, even if you
use login mangement like elogind the variable may be set incorrectly depending
on how your session was started, display mangers like lightdm tend to force
the variable into the correct value, but if you are not using one or are using
one which does not correct the variable it could be the incorrect value or not
even set at all, shed can correct this, just give a non empty value to this
variable and it will be set as the XDG_SESSION_TYPE, the values recognized by
systemd sd_session_get_type are:
unspecified, tty, x11, wayland, mir, web

.TP
.B set_xdg_home_dirs
if this var is set to a non empty var then the xdg home dirs will be set,
these include:
  XDG_DATA_HOME="$HOME/.local/share"
  XDG_CACHE_HOME="$HOME/.cache"
  XDG_STATE_HOME="$HOME/.local/state"
also the xdg user dirs will be set using xdg-user-dirs-update
  XDG_DESKTOP_DIR
  XDG_DOWNLOAD_DIR
  XDG_TEMPLATES_DIR
  XDG_PUBLICSHARE_DIR
  XDG_DOCUMENTS_DIR
  XDG_MUSIC_DIR
  XDG_PICTURES_DIR
  XDG_VIDEOS_DIR
  XDG_PROJECTS_DIR

.TP
.B make_xdg_home_dirs
if this var is set to a non empty var then the set xdg home dirs will be created
if they do not exist, the functions used do follow symlinks so if you have the
xdg dirs created as symlinks pointing somewhere else shed is smart enough to
account for that.

.TP
.B SHED_ENV_EXPORT_LOC
location where shed will export the following env vars:
export XDG_RUNTIME_DIR="$XDG_RUNTIME_DIR"
export XDG_SESSION_ID="$XDG_SESSION_ID"
export GUI_SESSION_PID="$GUI_SESSION_PID"
this file is useful when shed is not exec'd as part of the start up process,
which is not the ideal way to be running shed, that said a reasonable value
for the SHED_ENV_EXPORT_LOC is:
"/tmp/shed_session_${SHED_SESSION_PID}/shed.env"

.P
The
.B loglevel.rc
file, is also a simple key=val file with just the
.B LOG_LEVEL
field, the file is loaded from the libshed.sh library file.
.TP
.B "LOG_LEVEL"
The log level used by shed and shedc, by default
.B LOG_LEVEL=1
the following values are available:
    0  -  logging disabled
    1  -  show info messages
    2  -  show error messages
    3  -  show debug messages

.P
The
.B use-start-stop-daemon.rc
file, is also a simple key=val file with just the
.B USE_SSD
field, the file is loaded from the libshed.sh library file.
.TP
.B "USE_SSD"
By default
.B USE_SSD=FALSE
the following values case insensitive are taken as true:
    TRUE, true, YES, yes, ON, on, Y, y, T, t, 1

every other string on this field will be considered false.

.P
The
.B shallow.d
and
.B env.d
dirs are for .env files, the files are just shell scripts that will be loaded
directly by shed, which is itself a shell script specifically running on a posix
compliant shell interpreter at
.B /bin/sh
meaning that no bashisms are allowed in the .env files, also the /bin/sh shell
should be a posix compliant shell, at the very least bash but dash and busybox
ash are reccomended.

The files in
.B shallow.d
will be loaded first during the shallow phase of shed's initialization, then
later during the transient phase the files in
.B env.d
will be loaded, shed will skip trying to load .env files from empty and non
existant dirs.

.P
The
.B services
and
.B components
subdirs may contain service definition files, the format will be specified
below, the components directory are for services meant to run as session
components, for example in an x11 session that would be your window manager,
panel, etc, the components are started first and only during the first run,
meaning they don't get relaunched upon reloads of shed and only are terminated
upon logout, services on the other hand are started right after session
components, you can start, stop, hup and restart services, besides their
location there is no difference between definition files for session componennts
and services.

.TP
This is a simple example of a service definition file
.IR compositor
    EXEC=/usr/local/bin/picom
    E_ARGS=--vsync
    DELAY=2

.P
service definition files have no specific extension as they are just KEY=val
files, the following property keys are available:
.TP
.B "EXEC"
Program to execute, ideally use a full path, tho if only the command name is
given shed will expand it with command -v, the $HOME var can be used in the exec
definition for programs within subdirs of the HOME dir which are not in the path.
.TP
.B "E_ARGS"
Arguments to for the program, if multiple arguments will be given surround them
with double quotes.
.TP
.B "DELAY"
Delay the start up of the service by the given amount of seconds, this value is
passed directly to sleep(1)
.TP
.B "NOHUP"
This specifies that the service cannot receive the "HUP" signal, useful as not
every service will be compliant by being able to recieve the HUP signal to
reload, possible values are: 1, true, yes.
.TP
.B "NOFIRSTRUN"
This specifies that the service will not be started by start_services firstrun,
possible values are: 1, true, yes.
.TP
.B "NOSTARTALL"
This specifies that the service will not be started by start_services all,
possible values are: 1, true, yes.
.TP
.B "TYPE"
Explicitly declare the service as a
.B oneshot
or a
.B daemon
any other value including the property being empty or not set will be defaulted
to daemon.
.TP
.B "LOGFILE"
The location where stdout and stderr from the service will be redirected to, by
default it will be directed to:
.IR $XDG_RUNTIME_DIR/shed/$SHED_SESSION_PID/logs/NAME.log
where NAME is the name of the service file, so a service named compositor will
have all output directed to compositor.log
.P
The
.B transient
script, if used it is expected to be executable and located in
.B ${XDG_CONFIG_HOME:-${HOME}/.config}/shed/transient
were the script not executable or non existant during the shallow phase shed
will fallback to executing itself with
.B exec "$0"
to go into the transient phase.

The transient program has the resonsability of spawning an instance of shed as
it's child in order to complete the session initialization.

As an example of the transient script and running the transient shed instance
we are going to show sway, a popular wayland compositor, as altho shed was built
first to be a session process for x11, the development and testing has been and
continues to be done in x11, the shallow-transient model makes it easily
compatible with the manner wayland sessions work.
.TP
This is a simple example of a transient script, it should be executable:
.IR transient
    #!/bin/sh
    exec sway > "$XDG_RUNTIME_DIR/shed/$SHED_SESSION_PID/logs/sway.log"

.P
In the sway config file shed must be initiated, the initialization must be a
single instance and no attempts to spawn new instances should be done across
reloads of the configuration of the transient program, the case case of sway the
keyword "exec" is used to launch programs in this manner, check the
documentation for the program you intend to use as the transient.
.TP
This is an example snippet for the sway config:
.IR ${XDG_CONFIG_HOME:-${HOME}/.config}/sway/config
    # ... other sway configs here
    # this spawns one instance of shed in a manner in which no attempt will be
    # made to spawn more instances upon reloads of sway
    exec shed

.P
Tho this far the document has covered the 'default' session, if an argument is
passed to
.B shed
upon launch, shed will try to use a session whose name matches the passed
string, this
.B SHED_SESSION
argument is searched as a subdir inside either
.B ${XDG_CONFIG_HOME:-${HOME}/.config}/shed/
or
.B /etc/shed/
following the same convention of sub-directories and files as those for the
default session that have been outlined above, for an example if one were to
have 2 sessions set up be them
.B shed_awesome
and
.B shed_sway
then the file tree would look like:

.IR ${XDG_CONFIG_HOME}/shed/
    +-- shed_awesome/
    |   +-- components
    |   |   +-- 99x11-window-manager
    |   +-- env.d
    |   |   +-- x11-tearfree.env
    |   |   +-- gnome-keyring.env
    |   +-- services
    |   |   +-- compositor
    |   |   +-- pipewire-daemon
    |   |   +-- pipewire-daemon-pulse
    |   |   +-- pipewire-media-session
    |   |   +-- polkit-agent
    |   |   +-- xscreenlocker
    |   |   +-- xsettings-daemon
    |   +-- shed.rc
    +-- shed_sway/
        +-- components/
        |   +-- swww
        |   +-- sway-bar
        +-- env.d/
        |   +-- gnome-keyring.env
        +-- shallow.d/
        |   +-- gtk-wayland-backend.env
        |   +-- qt-wayland-backend.env
        |   +-- java-options.env
        +-- services/
        |   +-- pipewire-daemon
        |   +-- pipewire-daemon-pulse
        |   +-- pipewire-media-session
        |   +-- polkit-agent
        +-- shed.rc
        +-- transient·

.SH INITIALIZATION
.P
The initialization of the shed daemon is simple and consists of 2 phases, the
shallow and the transient, in the shallow phase shed will set up the environment
variables
.B SHED_SESSION
and
.B SHED_SESSION_PID
, usually SHED_SESSION_PID is the shallow daemon's own PID, then will proceed to
check if the variable XDG_RUNTIME_DIR is set, if not it will try it's best to
set it to a writeable location, if
.B /run/user/$UID
is not writeble it will default to
.B /tmp/${UID}-runtime-dir
and make the directory, then it will proceed to check if the
.B XDG_SESSION_ID
is set, if not it will set it to it's own cgroup, this is shed's only non
portable behaviour which relies upon a linux kernel specific feature, altho i
severely doubt shed will be useful to other unices like the BSDs as they
probably got a better solution built decades ago for this sorta stuff and is
only us in linux land that live in the obscurantism of systemd where innovation
that doesn't com from redhat is shunned and looked at with disdain, tangent
aside, next sed will check for the XDG_CONFIG_HOME env var, if not set it will
simply set it to
.B ${HOME}/.config
next shed will load the shed.rc file and proceed to set only the specified
options, the options to set the other XDG env vars are opt in just like most of
shed features and capabilites, next shed will proceed to initialize the
ShedSessionDir whose definiton is
.B $XDG_RUNTIME_DIR/shed/$SHED_SESSION_PID
as well as initialize the directores for logs, pid storage, and the socket
files, the shallow .env files are loaded from the
.B ${XDG_CONFIG_HOME:-${HOME}/.config}/shed/shallow.d
subdir, at this point the shed shallow will check if an executable transient
script exists in
.B ${XDG_CONFIG_HOME:-${HOME}/.config}/shed/transient
and proced to execute it with
.B exec
ensuring the transient script inherits the PID of the shed shallow, at this
point is the responsability of the transient program to spawn shed as it's
child. If an executable transient script wasn't found then shed will simply exec
itself with
.B exec "$0"
.P
At this point the execution of shed in the transient phase has converged, in the
transient execution the shed daemon, shed will load the transient phase .env
files from
.B ${XDG_CONFIG_HOME:-${HOME}/.config}/shed/env.d
and proceed to spawn the session components as well as the session services if
any, after which it will listen to the communications socket waiting for the
shedc program to send it actions.
.SH ENVIRONMENT
.TP
.B SHED_SESSION
Session name passed as argument, inherited by all descendants (shedc, services,
components).
Controls which config subdirectory is used. Defaults to "default" (no subdir).
Must be valid alphanumeric + dots/dashes/underscores.
.TP
.B SHED_SESSION_PID
The PID of the running shed session, required to resolve and access the
ShedSessionDir
.SH AUTHOR
.EX
eylles                 <ed.ylles1997 at gmail.com>
.EE
.SH HOMEPAGE
.TP
Source code:
.EE
https://codeberg.org/eylles/shed
.EX