Add a basic OpenRC users guide
X-Gentoo-Bug: 513024 X-Gentoo-Bug-URL: https://bugs.gentoo.org/show_bug.cgi?id=513024
This commit is contained in:
Patrick Lauer
William Hubbs
parent
e52b5f59c2
commit
e82653782e
251
guide.md
Normal file
251
guide.md
Normal file
@ -0,0 +1,251 @@
|
|||||||
|
# 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 init 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.
|
||||||
|
|
||||||
|
There is a "service" helper that emulates the syntax seen on e.g. older Redhat
|
||||||
|
and Ubuntu ("service nginx start" etc.)
|
||||||
|
|
||||||
|
# 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 init scripts 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 init 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 initscript by hand.
|
||||||
|
|
||||||
|
FIXME: Document stacked runlevels
|
||||||
|
|
||||||
|
The default startup uses the runlevels "boot", "sysinit" and "default", in that
|
||||||
|
order. Shutdown uses the "shutdown" runlevel.
|
||||||
|
|
||||||
|
|
||||||
|
# Syntax of Service Scripts
|
||||||
|
|
||||||
|
Service scripts are shell scripts. OpenRC aims at using only the standardized
|
||||||
|
POSIX sh subset for portability reasons. The default interpreter (build-time
|
||||||
|
toggle) is /bin/sh, so using for example mksh is not a problem.
|
||||||
|
|
||||||
|
OpenRC has been tested with busybox sh, ash, dash, bash, mksh, zsh and possibly
|
||||||
|
others. Using busybox sh has been difficult as it replaces commands with
|
||||||
|
builtins that don't offer the expected features.
|
||||||
|
|
||||||
|
The interpreter for initscripts is #!/sbin/openrc-run
|
||||||
|
Not using this interpreter will break the use of dependencies and is not
|
||||||
|
supported. (iow: if you insist on using #!/bin/sh you're on your own)
|
||||||
|
|
||||||
|
A "depend" function declares the dependencies of this service script.
|
||||||
|
All scripts must have start/stop/status functions, but defaults are provided.
|
||||||
|
Extra functions can be added easily:
|
||||||
|
|
||||||
|
extra_commands="checkconfig"
|
||||||
|
checkconfig() {
|
||||||
|
doSomething
|
||||||
|
}
|
||||||
|
|
||||||
|
This exports the checkconfig function so that "/etc/init.d/someservice
|
||||||
|
checkconfig" will be available, and it "just" runs this function.
|
||||||
|
|
||||||
|
While commands defined in extra_commands are always available, commands
|
||||||
|
defined in extra_started_commands will only work when the service is started
|
||||||
|
and those defined in extra_stopped_commands will only work when the service is
|
||||||
|
stopped. This can be used for implementing graceful reload and similar
|
||||||
|
behaviour.
|
||||||
|
|
||||||
|
Adding a restart function will not work, this is a design decision within
|
||||||
|
OpenRC. Since there may be dependencies involved (e.g. network -> apache) a
|
||||||
|
restart function is in general not going to work.
|
||||||
|
restart is internally mapped to stop() + start() (plus handling dependencies).
|
||||||
|
If a service needs to behave differently when it is being restarted vs
|
||||||
|
started or stopped, it should test the $RC_CMD variable, for example:
|
||||||
|
|
||||||
|
[ "$RC_CMD" = restart ] && do_something
|
||||||
|
|
||||||
|
|
||||||
|
# The Depend Function
|
||||||
|
|
||||||
|
This function declares the dependencies for a service script. This
|
||||||
|
determines the order the service scripts start.
|
||||||
|
|
||||||
|
depend() {
|
||||||
|
need net
|
||||||
|
use dns logger netmount
|
||||||
|
want coolservice
|
||||||
|
}
|
||||||
|
|
||||||
|
"need" declares a hard dependency - net always needs to be started before this
|
||||||
|
service does
|
||||||
|
"use" is a soft dependency - if dns, logger or netmount is in this runlevel
|
||||||
|
start it before, but we don't care if it's not in this runlevel.
|
||||||
|
"want" is between need and use - try to start coolservice if it is
|
||||||
|
installed on the system, regardless of whether it is in the
|
||||||
|
runlevel, but we don't care if it starts.
|
||||||
|
"before" declares that we need to be started before another service
|
||||||
|
"after" declares that we need to be started after another service, without
|
||||||
|
creating a dependency (so on calling stop the two are independent)
|
||||||
|
"provide" allows multiple implementations to provide one service type, e.g.:
|
||||||
|
'provide cron' is set in all cron-daemons, so any one of them started
|
||||||
|
satisfies a cron dependency
|
||||||
|
"keyword" allows platform-specific overrides, e.g. "keyword -lxc" makes this
|
||||||
|
service script a noop in lxc containers. Useful for things like keymaps,
|
||||||
|
module loading etc. that are either platform-specific or not available
|
||||||
|
in containers/virtualization/...
|
||||||
|
|
||||||
|
FIXME: Anything missing in this list?
|
||||||
|
|
||||||
|
# The Default Functions
|
||||||
|
|
||||||
|
All service scripts are assumed to have the following functions:
|
||||||
|
|
||||||
|
start()
|
||||||
|
stop()
|
||||||
|
status()
|
||||||
|
|
||||||
|
There are default implementations in rc/sh/runscript.sh - this allows very
|
||||||
|
compact service scripts. These functions can be overridden per service script as
|
||||||
|
needed.
|
||||||
|
|
||||||
|
The default functions assume the following variables to be set in the service
|
||||||
|
script:
|
||||||
|
|
||||||
|
command=
|
||||||
|
command_args=
|
||||||
|
pidfile=
|
||||||
|
|
||||||
|
Thus the 'smallest' service scripts can be half a dozen lines long
|
||||||
|
|
||||||
|
# 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 init
|
||||||
|
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 optionally use CGroups for process management.
|
||||||
|
By default each service script's processes are migrated to their own CGroup.
|
||||||
|
|
||||||
|
By changing certain values in the conf.d file limits can be enforced per
|
||||||
|
service. It is easy to find orphan processes of a service that persist after
|
||||||
|
stop(), but by default these will NOT be terminated.
|
||||||
|
To change this add rc_cgroup_cleanup="yes" in the conf.d files for services
|
||||||
|
where you desire this functionality.
|
||||||
|
|
||||||
|
# Caching
|
||||||
|
|
||||||
|
For performance reasons OpenRC keeps a cache of pre-parsed initscript 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 initscripts all use ebegin/eend to
|
||||||
|
print nice messages.
|
||||||
Loading…
Reference in New Issue
Block a user