wip: new manpage docs

man/meson.build

@@ -9,6 +9,11 @@ man3 = [
   'rc_stringlist.3',
   ]
 
+man7 = [
+  'openrc-service-guide.7',
+  'openrc-user-services.7'
+  ]
+
 man8 = [
   'openrc.8',
   'openrc-run.8',
@@ -30,6 +35,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)

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:

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

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