From b9b6f444e222136767a6cc6f0037b7298ffea271 Mon Sep 17 00:00:00 2001 From: navi Date: Sun, 27 Sep 2026 18:28:23 +0200 Subject: [PATCH 1/3] openrc-run.8: document RC_PATH and RC_SVCDIR TODO: list build-time default for RC_PATH --- man/openrc-run.8 | 39 +++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/man/openrc-run.8 b/man/openrc-run.8 index 470498199..24bccfddf 100644 --- a/man/openrc-run.8 +++ b/man/openrc-run.8 @@ -28,7 +28,7 @@ is basically an interpreter for shell scripts which provides an easy interface to the often complex system commands and daemons. When a service runs a command it first loads its multiplexed configuration file, then its master configuration file, then -.Pa /etc/rc.conf +.Pa rc.conf and finally the script itself. At this point .Nm then runs the command given. @@ -383,7 +383,7 @@ When in a jail, exclude this service from any dependencies. The service can still be run directly. Set via .Ic rc_sys in -.Pa /etc/rc.conf +.Pa rc.conf .It Dv -lxc Same as -jail, but for Linux Resource Containers (LXC). .It Dv -openvz @@ -636,6 +636,28 @@ If matches YES, TRUE, ON or 1 regardless of case then we return 0, otherwise 1. .El .Sh ENVIRONMENT +.Nm +uses the following environment variables for finding service and control directories: +.Bl -tag -width "RC_DEFAULTLEVEL" + +.It Va RC_PATH +Colon separated list of paths to look services and configurations in. +Each entry is looked up for +.Pa init.d/ , +.Pa conf.d/ , +and +.Pa rc.conf +entries . + +.It Va RC_SVCDIR +Path to the service control directory. +Default to +.Pa /run/openrc +for system services, and +.Pa $XDG_RUNTIME_DIR/openrc +for user services. +.El + .Nm sets the following environment variables for use in the service scripts: .Bl -tag -width "RC_DEFAULTLEVEL" @@ -677,21 +699,22 @@ should not be unmounted. .El .Sh FILES .Pp -Configuration files, relative to the location of the service. +Configuration files, are sourced in a loop for each entry in +.Ev RC_PATH . If a file ending with .${RC_RUNLEVEL} exists then we use that instead. .Bl -ohang -.It Pa ../conf.d/${RC_SVCNAME%%.*} +.It Pa conf.d/${RC_SVCNAME%%.*} multiplexed configuration file. Example: if ${RC_SVCNAME} is net.eth1 then look for -.Pa ../conf.d/net . -.It Pa ../conf.d/${RC_SVCNAME} +.Pa conf.d/net . +.It Pa conf.d/${RC_SVCNAME} service configuration file. -.It Pa /etc/rc.conf +.It Pa rc.conf host configuration file. .El .Pp With the exception of -.Pa /etc/rc.conf , +.Pa rc.conf , the configuration files can also influence the dependencies of the service through variables. Simply prefix the name of the dependency with rc_. Examples: From 478f94a61b870dea0dfb46c3b21c21184a392721 Mon Sep 17 00:00:00 2001 From: navi Date: Sun, 27 Sep 2026 18:30:32 +0200 Subject: [PATCH 2/3] man/openrc-service-guide.7: add a new guide manpage --- man/meson.build | 8 ++- man/openrc-service-guide.7 | 113 +++++++++++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 man/openrc-service-guide.7 diff --git a/man/meson.build b/man/meson.build index fcc3b3a4c..00d61cf46 100644 --- a/man/meson.build +++ b/man/meson.build @@ -9,6 +9,10 @@ man3 = [ 'rc_stringlist.3', ] +man7 = [ + 'openrc-service-guide.7' + ] + man8 = [ 'openrc.8', 'openrc-run.8', @@ -30,6 +34,8 @@ endif install_data(man3, install_dir : get_option('mandir') / 'man3') +install_data(man7, + install_dir : get_option('mandir') / 'man7') install_data(man8, install_dir : get_option('mandir') / 'man8') -meson.add_install_script('meson_man_links.sh', get_option('mandir'), man3 + man8) +meson.add_install_script('meson_man_links.sh', get_option('mandir'), man3 + man7 + man8) diff --git a/man/openrc-service-guide.7 b/man/openrc-service-guide.7 new file mode 100644 index 000000000..69085d7cc --- /dev/null +++ b/man/openrc-service-guide.7 @@ -0,0 +1,113 @@ +.Dd $Mdocdate$ +.Dt openrc-intro 7 +.Os + +.Sh NAME +.Nm openrc-intro +.Nd An introduction to openrc init scripts + +.Sh SYNTAX + +openrc init scripts are POSIX shell scripts, interpreted by +.Xr openrc-run 8 + +.Sh DEFAULT FUNCTIONS +openrc requires that every service provides the +.Ic start Ns () , +.Ic stop Ns () , +and +.Ic status Ns () +commands. + +In order to simplify init scripts, openrc provides default implementations to +all required commands, configured via shell variables, thus most services then +are composed of only a couple variable assignments. + +Do not define custom +.Ic start Ns () +or +.Ic stop Ns () +functions for managing daemons. + +Any service that start a daemon must define +.Va command . +For a full list of all variables, refer to +.Xr openrc-run 8 . + +.Sh _pre AND _post FUNCTIONS +In order to run preparation and checks, the init script can define pre-command +and post-command function for any command, by defining a function with said +command name, suffixed with _pre or _post. + +If those functions return a non-0 exit status, openrc will not proceed with +executing the command proper, thus +.Ic start_pre Ns () +and +.Ic stop_pre Ns () +can be used to run precondition checks and disallowing the service to be +started or stopped should they fail. + +.Sh CUSTOM COMMANDS +Custom commands can be declared and made available to users. + +Define a function for the command, and include it in either +.Va extra_commands , +.Va extra_started_commands , +or +.Va extra_stopped_commands . + +.Sh DEPENDENCIES +Dependencies across services are declared in the +.Ic depend Ns () +function, openrc will attempt to start any +.Ic need +or +.Ic want +service beforehand, and will stop/restart services when +.Ic need +services are stopped/restarted. + +For a full list of dependency types, refer to +.Xr openrc-run 8 . + +.Sh SUPERVISION +openrc provides +.Xr supervise-daemon 8 +to supervise services, it is recommended for init scripts to make use of it +in order to improve system reliability. + +To use supervise-daemon, make sure the daemon does not fork, and stays in the +foreground, then set the +.Va supervisor +variable to +.Qq Dv supervise-daemon + +.Sh EXAMPLE +.Bd -literal +#!/sbin/openrc-run + +depend() { + need nya +} + +supervisor=supervise-daemon +command=/bin/foo +command_user=foo:foo +extra_commands="checkconfig" + +checkconfig() { + /bin/foo --check-config +} + +start_pre() { + checkpath -o $command_user /run/foo + + checkconfig +} +.Ed + +.Sh SEE ALSO +.Xr openrc-run 8 + +.Sh AUTHORS +.An navi Aq Mt navi@vlhl.dev From bce1b34dd96ff16e6cf7d70cdaec90b29fcf4fa0 Mon Sep 17 00:00:00 2001 From: navi Date: Sun, 27 Sep 2026 18:32:07 +0200 Subject: [PATCH 3/3] man/openrc-user-services.7: add manpage overviewing user services Bug: https://github.com/OpenRC/openrc/issues/1069 --- man/meson.build | 3 +- man/openrc-user-services.7 | 96 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 man/openrc-user-services.7 diff --git a/man/meson.build b/man/meson.build index 00d61cf46..464ca69c8 100644 --- a/man/meson.build +++ b/man/meson.build @@ -10,7 +10,8 @@ man3 = [ ] man7 = [ - 'openrc-service-guide.7' + 'openrc-service-guide.7', + 'openrc-user-services.7' ] man8 = [ diff --git a/man/openrc-user-services.7 b/man/openrc-user-services.7 new file mode 100644 index 000000000..4ce7b487c --- /dev/null +++ b/man/openrc-user-services.7 @@ -0,0 +1,96 @@ +.Dd $Mdocdate$ +.Dt openrc-user-serivces 7 +.Os + +.Sh NAME +.Nm User Services +.Nd Overview of user services for openrc + +.Sh DESCRIPTION + +The core of openrc does not require superuser permissions, +however historically some part of it assumed such permissions, +notably for the control directory and features such as cgroups. + +.Sh ENVIRONMENT + +For directories, +.Ev RC_PATH +and +.Ev RC_SVCDIR +were introduced. See +.Xr openrc-run 8 +for more details about them. + +When +.Fl -user +is used, openrc prepends +.Pa ${XDG_CONFIG_HOME}/rc +to +.Ev RC_PATH , +as well as appending +.Pa /user +to all other entries, and sets +.Ev RC_SVCDIR +to +.Pa ${XDG_RUNTIME_DIR}/openrc + +.Sh RUNLEVELS + +.Ss boot + +The +.Sx SYSTEM SERVICE +will start the boot runlevel for users, and wait for the runlevel change +to complete before marking itself as ready. + +When combined with the +.Sx PAM +module, this guarantees that boot services are up before the user session +starts, additionally, any environment variables reexported by boot services +are made available to the new pam session. Useful for services like dbus and +.Ev DBUS_SESSION_BUS_ADDRESS . + +.Ss default + +After starting the boot runlevel, the default runlevel is started asynchronously. +The +.Sx PAM +module does not wait for default services to start before returning flow back to pam. + +.Ss shutdown + +When stopping, the +.Sx SYSTEM SERVICE +will switch to this runlevel, which stops services from boot and default. +Long running services must not be started in the shutdown runlevel. +System policies may enforce that all user processes are killed on last logout. + +.Sh PAM +openrc ships +.Lb pam_openrc.so +for the purpose of starting and stopping services on session open and session close. + +It does so by counting session and starting the system +.Dv user +service, multiplexed to the current user as +.Dv user.$USER . + +.Sh SYSTEM SERVICE + +The system service starts a new pam session for the target user, to get access to resources +like +.Ev XDG_RUNTIME_DIR +should it be made available via pam, e.g. with logind or pam_xdg. + +then executes runlevels as specified in +.Sx RUNLEVELS . + +.Sh BUGS + +At the moment, the service cgroup options don't work for user services, as openrc +lacks the ability to delegate cgroups. + +.Sh SEE ALSO + +.Xr openrc-run 8