diff options
Diffstat (limited to 'user-guide.md')
-rw-r--r-- | user-guide.md | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/user-guide.md b/user-guide.md new file mode 100644 index 00000000..80c8a7d3 --- /dev/null +++ b/user-guide.md @@ -0,0 +1,176 @@ +# Purpose and description + +OpenRC is an init system for Unixoid operating systems. It takes care of +startup and shutdown of the whole system, including services. + +It evolved out of the Gentoo "Baselayout" package which was a custom pure-shell +startup solution. (This was both hard to maintain and debug, and not very +performant) + +Most of the core parts are written in C99 for performance and flexibility +reasons, while everything else is posix sh. +The License is 2-clause BSD + +Current size is about 10k LoC C, and about 4k LoC shell. + +OpenRC is known to work on Linux, many BSDs (FreeBSD, OpenBSD, DragonFlyBSD at +least) and HURD. + +Services are stateful (i.e. `start`; `start` will lead to "it's already started") + +# Startup + +Usually PID1 (aka. `init`) calls the OpenRC binary (`/sbin/openrc` by default). +(The default setup assumes sysvinit for this) + +openrc scans the runlevels (default: `/etc/runlevels`) and builds a dependency +graph, then starts the needed service scripts, either serialized (default) or in +parallel. + +When all the service scripts are started openrc terminates. There is no +persistent daemon. (Integration with tools like monit, runit or s6 can be done) + +# Shutdown + +On change to runlevel 0/6 or running `reboot`, `halt` etc., openrc stops all +services that are started and runs the services in the `shutdown` runlevel. + +# Modifying Service Scripts + +Any service can, at any time, be started/stopped/restarted by executing +`rc-service someservice start`, `rc-service someservice stop`, etc. +Another, less preferred method, is to run the service script directly, +e.g. `/etc/init.d/service start`, `/etc/init.d/service stop`, etc. + +OpenRC will take care of dependencies, e.g starting apache will start network +first, and stopping network will stop apache first. + +There is a special command `zap` that makes OpenRC 'forget' that a service is +started; this is mostly useful to reset a crashed service to stopped state +without invoking the (possibly broken) stop function of the service script. + +Calling `openrc` without any arguments will try to reset all services so +that the current runlevel is satisfied; if you manually started apache it will be +stopped, and if squid died but is in the current runlevel it'll be restarted. + +# Runlevels + +OpenRC has a concept of runlevels, similar to what sysvinit historically +offered. A runlevel is basically a collection of services that needs to be +started. Instead of random numbers they are named, and users can create their +own if needed. This allows, for example, to have a default runlevel with +"everything" enabled, and a "powersaving" runlevel where some services are +disabled. + +The `rc-status` helper will print all currently active runlevels and the state +of services in them: + +``` +# rc-status + * Caching service dependencies ... [ ok ] +Runlevel: default + modules [ started ] + lvm [ started ] +``` + +All runlevels are represented as folders in `/etc/runlevels/` with symlinks to +the actual service scripts. + +Calling openrc with an argument (`openrc default`) will switch to that +runlevel; this will start and stop services as needed. + +Managing runlevels is usually done through the `rc-update` helper, but could of +course be done by hand if desired. +e.g. `rc-update add nginx default` - add nginx to the default runlevel +Note: This will not auto-start nginx! You'd still have to trigger `rc` or run +the service script by hand. + +FIXME: Document stacked runlevels + +The default startup uses the runlevels `boot`, `sysinit` and `default`, in that +order. Shutdown uses the `shutdown` runlevel. + +# The Magic of `conf.d` + +Most service scripts need default values. It would be fragile to +explicitly source some arbitrary files. By convention `openrc-run` will source +the matching file in `/etc/conf.d/` for any script in `/etc/init.d/` + +This allows you to set random startup-related things easily. Example: + +``` +conf.d/foo: +START_OPTS="--extraparameter sausage" + +init.d/foo: +start() { + /usr/sbin/foo-daemon ${STARTOPTS} +} +``` + +The big advantage of this split is that most of the time editing of the service +script can be avoided. + +# Start-Stop-Daemon + +OpenRC has its own modified version of s-s-d, which is historically related and +mostly syntax-compatible to Debian's s-s-d, but has been rewritten from scratch. + +It helps with starting daemons, backgrounding, creating PID files and many +other convenience functions related to managing daemons. + +# `/etc/rc.conf` + +This file manages the default configuration for OpenRC, and it has examples of +per-service-script variables. + +Among these are `rc_parallel` (for parallelized startup), `rc_log` (logs all boot +messages to a file), and a few others. + +# ulimit and CGroups + +Setting `ulimit` and `nice` values per service can be done through the +`rc_ulimit` variable. + +Under Linux, OpenRC can use cgroups for process management as well. Once +the kernel is configured appropriately, the `rc_cgroup_mode` setting in +/etc/rc.conf should be used to control whether cgroups version one,, +two, or both are used. The default is to use both if they are available. + +By changing certain settings in the service's `conf.d` file limits can be +enforced per service. These settings are documented in detail in the +default /etc/rc.conf under `LINUX CGROUPS RESOURCE MANAGEMENT`. + +# Dealing with Orphaned Processes + +It is possible to get into a state where there are orphaned processes +running which were part of a service. For example, if you are monitoring +a service with supervise-daemon and supervise-daemon dies for an unknown +reason. The way to deal with this will be different for each system. + +On Linux systems with cgroups enabled, the cgroup_cleanup command is +added to all services. You can run it manually, when the service is +stopped, by using: + +``` +# rc-service someservice cgroup_cleanup +``` + +The `rc_cgroup_cleanup` setting can be changed to yes to make this +happen automatically when the service is stopped. + + +# Caching + +For performance reasons OpenRC keeps a cache of pre-parsed service metadata +(e.g. `depend`). The default location for this is `/${RC_SVCDIR}/cache`. + +The cache uses `mtime` to check for file staleness. Should any service script +change it'll re-source the relevant files and update the cache + +# Convenience functions + +OpenRC has wrappers for many common output tasks in libeinfo. +This allows to print colour-coded status notices and other things. +To make the output consistent the bundled service scripts all use ebegin/eend to +print nice messages. |