From 8878f8916b7682a333d1e40af991cd7354192be1 Mon Sep 17 00:00:00 2001 From: William Hubbs Date: Thu, 11 Jan 2018 10:57:05 -0600 Subject: Rename guide.md to user-guide.md to better describe its purpose --- guide.md | 176 ---------------------------------------------------------- user-guide.md | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 176 insertions(+), 176 deletions(-) delete mode 100644 guide.md create mode 100644 user-guide.md diff --git a/guide.md b/guide.md deleted file mode 100644 index 80c8a7d3..00000000 --- a/guide.md +++ /dev/null @@ -1,176 +0,0 @@ -# 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. 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. -- cgit v1.2.3