Difference between revisions of "OpenRC"
(→/etc/rc.conf) |
(The second line in the installation section seemed to imply 'make install' ran OpenRC. I just changed the wording slightly for clarity) |
||
(39 intermediate revisions by one other user not shown) | |||
Line 1: | Line 1: | ||
{{welcome}} | {{welcome}} | ||
− | {{Navbar | + | {{Navbar GhostBSD Boot Process}} |
{{Navbar OpenRC}} | {{Navbar OpenRC}} | ||
==Introduction== | ==Introduction== | ||
− | OpenRC is a dependency-based ''init system'' that works with the system-provided init program, normally ''/sbin/init''. Currently, it does not have an init program of its own. It does not function as a replacement for the /sbin/init file. | + | |
+ | '''OpenRC''' is a dependency-based ''init system'' that works with the system-provided init program, normally ''/sbin/init''. Currently, it does not have an init program of its own. It does not function as a replacement for the /sbin/init file. OpenRC is located on /sbin/openrc. | ||
There are 105 [https://github.com/OpenRC/openrc/graphs/contributors contributors on GitHub]. | There are 105 [https://github.com/OpenRC/openrc/graphs/contributors contributors on GitHub]. | ||
GhostBSD/FreeBSD provides for booting from both the older MBR standard and the newer GUID Partition Table (GPT). | GhostBSD/FreeBSD provides for booting from both the older MBR standard and the newer GUID Partition Table (GPT). | ||
− | Once the kernel boot process is finished, the kernel passes control to the user process [https://www.freebsd.org/cgi/man.cgi?query=init&sektion=8&manpath=freebsd-release-ports init(8)], which is located at ''/sbin/init''. The ''/boot/defaults/loader.conf'' states as GhostBSD defaults: ''rc_system="openrc".'' | + | Once the kernel boot process is finished, the kernel passes control to the user process [https://www.freebsd.org/cgi/man.cgi?query=init&sektion=8&manpath=freebsd-release-ports init(8)], which is located at ''/sbin/init''. The '''[[/boot/defaults/loader.conf]]''' states as GhostBSD defaults: ''rc_system="openrc".'' |
The loader is the final stage of the three-stage bootstrap process. It is located on the file system, usually as ''/boot/loader.'' | The loader is the final stage of the three-stage bootstrap process. It is located on the file system, usually as ''/boot/loader.'' | ||
− | The loader will read ''/boot/loader.rc,'' which by default reads in ''/boot/defaults/loader.conf'' which sets reasonable defaults for variables and reads ''/boot/loader.conf'' for local changes to those variables. loader.rc then acts on these variables, loading whichever modules and kernel are selected. | + | The loader will read ''/boot/loader.rc,'' which by default reads in '''[[/boot/defaults/loader.conf]]''' which sets reasonable defaults for variables and reads '''[[/boot/loader.conf]]''' for local changes to those variables. loader.rc then acts on these variables, loading whichever modules and kernel are selected. |
+ | |||
+ | A very useful command to edit rc files is '''[[Sysrc|sysrc]]'''. | ||
==Installation== | ==Installation== | ||
Line 19: | Line 22: | ||
OpenRC requires GNU make. | OpenRC requires GNU make. | ||
− | Once you have GNU Make installed, the default OpenRC installation can be | + | Once you have GNU Make installed, the default OpenRC installation can be performed using this command: |
make install | make install | ||
Line 92: | Line 95: | ||
==Scripts to run OpenRC== | ==Scripts to run OpenRC== | ||
− | Scripts to run OpenRC are located on ''/etc/[[init.d]]/''. | + | Scripts to run OpenRC are located on '''/etc/[[init.d]]/''' and '''/usr/[[local/etc/init.d]]'''. |
==OpenRC Users Guide== | ==OpenRC Users Guide== | ||
Line 136: | Line 139: | ||
===Runlevels=== | ===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. | + | '''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 | + | The '''[[rc-status]]''' helper will print all currently active runlevels and the state of services in them. |
− | + | All runlevels are represented as folders in ''/etc/runlevels/'' with symlinks to the actual service scripts.<br/> | |
− | + | All services must reside in the '''/etc/[[Init.d|init.d]]''' or '''/usr/[[Local/etc/init.d|local/etc/init.d]]''' directories. They must also conform to the '''OpenRC''' runscript standard. | |
− | + | ||
− | + | ||
− | + | ||
− | + | 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 foo default'' - add foo to the default runlevel '''Note:''' This will not auto-start foo! You'd still have to trigger rc or run the service script by hand. | |
− | + | ||
− | Managing runlevels is usually done through the ''rc-update | + | |
FIXME: Document stacked runlevels | FIXME: Document stacked runlevels | ||
Line 189: | Line 187: | ||
Setting ''ulimit'' and nice values per service can be done through the ''rc_ulimit'' variable. | 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. | + | 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|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. | + | 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|rc.conf]]''' under LINUX CGROUPS RESOURCE MANAGEMENT. |
===Dealing with Orphaned Processes=== | ===Dealing with Orphaned Processes=== | ||
Line 212: | Line 210: | ||
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. | 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. | ||
+ | |||
+ | |||
+ | ===Additional Directories, Programs and Files related to OpenRC=== | ||
+ | |||
+ | In this directory we collect files are not described above yet. | ||
+ | |||
+ | {|class="wikitable" style="width:96.5%;background:#FFFFFF; border:2px solid #008000;text-align:left;padding: 10px" | ||
+ | |- | ||
+ | ! scope="col" style="width: 100px;"|'''Directory/Files''' | ||
+ | ! scope="col" style="width: 350px;"|'''Description''' | ||
+ | |- | ||
+ | |/boot/loader.rc||Includes additional commands; Load boot menu; Start the boot menu | ||
+ | |- | ||
+ | |/boot/loader.rc.local||set 0 | ||
+ | |- | ||
+ | |/etc/devd-openrc||Contains the following files: asus.conf, devmatch-openrc.conf, hyperv.conf, uath.conf, ulpt.conf, and zfs.conf | ||
+ | |- | ||
+ | |/etc/openrc.shutdown||[https://manpages.debian.org/testing/openrc/openrc-shutdown.8.en.html openrc-shutdown] is the utility that communicates with [https://manpages.debian.org/testing/openrc/openrc-init.8.en.html openrc-init(8)] to bring down the system or instruct openrc-init to re-execute itself. | ||
+ | |- | ||
+ | |/etc/rc.dynamicdiskless||[https://reviews.freebsd.org/D18578 OpenRC for FreeBSD] | ||
+ | |- | ||
+ | |/etc/rc.firewall||The [https://www.freebsd.org/cgi/man.cgi?query=rc.firewall&sektion=8 rc.firewall] script is used to configure rules for the kernel based firewall service. | ||
+ | |- | ||
+ | |/etc/rc.initdiskless||The post-boot initialization of an embedded FreeBSD system is controlled by [https://www.freebsd.org/doc/en_US.ISO8859-1/articles/solid-state/ro-fs.html /etc/rc.initdiskless]. | ||
+ | |- | ||
+ | |/etc/rc.resume|| If drivers can be properly loaded and unloaded, automate this by putting the appropriate commands in /etc/rc.suspend and [https://www.freebsd.org/doc/handbook/acpi-overview.html /etc/rc.resume]. | ||
+ | |- | ||
+ | |/etc/rc.sendmail||The [https://www.freebsd.org/cgi/man.cgi?query=rc.sendmail&sektion=8&n=1 rc.sendmail] script is used by /etc/rc at boot time to start [https://www.freebsd.org/cgi/man.cgi?query=sendmail&sektion=8&apropos=0&manpath=FreeBSD+12.1-RELEASE+and+Ports sendmail(8)]. It is meant to be sendmail(8) specific and not a generic script for all MTAs. It is only called by /etc/rc if the rc.conf(5) mta_start_script variable is set to /etc/rc.sendmail. | ||
+ | |||
+ | |- | ||
+ | |/etc/rc.shutdown||See [https://www.freebsd.org/cgi/man.cgi?query=rc.shutdown&apropos=0&sektion=8&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html#Operation Operation of rc.shutdown] | ||
+ | |- | ||
+ | |/etc/rc.subr||[https://www.freebsd.org/cgi/man.cgi?query=rc.subr&sektion=8&apropos=0&manpath=FreeBSD+12.1-RELEASE+and+Ports functions used by system shell scripts] | ||
+ | |- | ||
+ | |/etc/rc.suspend||If drivers can be properly loaded and unloaded, automate this by putting the appropriate commands in [https://www.freebsd.org/doc/handbook/acpi-overview.html /etc/rc.suspend] and /etc/rc.resume. | ||
+ | |- | ||
+ | |/sbin/openrc-run||[https://manpages.debian.org/testing/openrc/openrc-run.8.en.html openrc-run] 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 /etc/rc.conf and finally the script itself. At this point openrc-run then runs the command given. | ||
+ | |} | ||
==For more Information See== | ==For more Information See== |
Latest revision as of 23:21, 4 March 2021
Welcome to ![]() |
GhostBSD Boot Process | |||
---|---|---|---|
MBR and GPT | UEFI | OpenRC | /boot/ |
Back to the ![]() |
OpenRC | ||
---|---|---|
Scripts | ||
/etc/rc rc - shell |
/etc/rc.devd The generic hook into OpenRC. |
/sbin/rcorder Ordering rc-scripts |
/etc/init.d Scripts to run OpenRC |
/usr/local/etc/init.d Scripts to run OpenRC |
|
/etc/rc.d Scripts automatically executed at boot and shutdown |
/usr/local/etc/rc.d Special scripts |
|
Configuration | ||
/etc/devd.conf Configuration file for devd(8) |
/etc/conf.d Initscript Configuration Files |
/etc/rc.conf.d Smaller configuration files |
/etc/defaults/rc.conf Specifies the default settings for all the available options. |
/etc/rc.conf The global OpenRC configuration file |
/etc/rc.conf.ghostbsd GhostBSD specific configurations |
Tools/Helper | ||
/usr/sbin/sysrc Safely edit system rc files |
/bin/rc-status Shows which services are running |
/sbin/rc-update Add or delete services |
/sbin/rc-service Locate and run an OpenRC service |
||
Back to the ![]() |
Contents
- 1 Introduction
- 2 Installation
- 3 Configuration
- 4 OpenRC Developers Guide
- 5 Scripts to run OpenRC
- 6 OpenRC Users Guide
- 6.1 Purpose and description
- 6.2 Startup
- 6.3 Shutdown
- 6.4 Modifying Service Scripts
- 6.5 Runlevels
- 6.6 The Magic of conf.d
- 6.7 Start-Stop-Daemon
- 6.8 /etc/rc.conf
- 6.9 ulimit and CGroups
- 6.10 Dealing with Orphaned Processes
- 6.11 Caching
- 6.12 Convenience functions
- 6.13 Additional Directories, Programs and Files related to OpenRC
- 7 For more Information See
Introduction[edit]
OpenRC is a dependency-based init system that works with the system-provided init program, normally /sbin/init. Currently, it does not have an init program of its own. It does not function as a replacement for the /sbin/init file. OpenRC is located on /sbin/openrc.
There are 105 contributors on GitHub.
GhostBSD/FreeBSD provides for booting from both the older MBR standard and the newer GUID Partition Table (GPT). Once the kernel boot process is finished, the kernel passes control to the user process init(8), which is located at /sbin/init. The /boot/defaults/loader.conf states as GhostBSD defaults: rc_system="openrc".
The loader is the final stage of the three-stage bootstrap process. It is located on the file system, usually as /boot/loader.
The loader will read /boot/loader.rc, which by default reads in /boot/defaults/loader.conf which sets reasonable defaults for variables and reads /boot/loader.conf for local changes to those variables. loader.rc then acts on these variables, loading whichever modules and kernel are selected.
A very useful command to edit rc files is sysrc.
Installation[edit]
OpenRC requires GNU make.
Once you have GNU Make installed, the default OpenRC installation can be performed using this command:
make install
Configuration[edit]
You may wish to configure the installation by passing one or more of the below arguments to the make command
-
PROGLDFLAGS=-static
-
LIBNAME=lib64
-
DESTDIR=/tmp/openrc-image
-
MKBASHCOMP=no
-
MKNET=no
-
MKPAM=pam
-
MKPREFIX=yes
-
MKPKGCONFIG=no
-
MKSELINUX=yes
-
MKSTATICLIBS=no
-
MKSYSVINIT=yes
-
MKTERMCAP=ncurses
-
MKTERMCAP=termcap
-
MKZSHCOMP=no
-
PKG_PREFIX=/usr/pkg
-
LOCAL_PREFIX=/usr/local
-
PREFIX=/usr/local
-
BRANDING=\"Gentoo/$(uname -s)\"
-
SH=/bin/sh
Source: https://github.com/OpenRC/openrc/blob/master/README.md
Notes[edit]
From the developers:
We don't support building a static OpenRC with PAM.
You may need to use PROGLDFLAGS=-Wl,-Bstatic on glibc instead of just -static.
If you are building OpenRC for a Gentoo Prefix installation, add MKPREFIX=yes.
PKG_PREFIX should be set to where packages install to by default.
LOCAL_PREFIX should be set to where user maintained packages are. Only set LOCAL_PREFIX if different from PKG_PREFIX.
PREFIX should be set when OpenRC is not installed to /.
If any of the following files exist then we do not overwrite them
rc and rc.shutdown are the hooks from the BSD init into OpenRC.
devd.conf is modified from FreeBSD to call /etc/rc.devd which is a generic hook into OpenRC.
inittab is the same, but for SysVInit as used by most Linux distributions. This can be found in the support folder.
Obviously, if you're installing this onto a system that does not use OpenRC by default then you may wish to backup the above listed files, remove them and then install so that the OS hooks into OpenRC.
OpenRC Developers Guide[edit]
This document is aimed at developers or packagers who write OpenRC service scripts, either for their own projects, or for the packages they maintain. It contains advice, suggestions, tips, tricks, hints, and counsel; cautions, warnings, heads-ups, admonitions, proscriptions, enjoinders, and reprimands.
It is intended to prevent common mistakes that are found "in the wild" by pointing out those mistakes and suggesting alternatives. Each good/bad thing that you should/not do has a section devoted to it. We don't consider anything exotic, and assume that you will use start-stop-daemon to manage a fairly typical long-running UNIX process.
For more information see: OpenRC Service Script Writing Guide
Scripts to run OpenRC[edit]
Scripts to run OpenRC are located on /etc/init.d/ and /usr/local/etc/init.d.
OpenRC Users Guide[edit]
Source: https://github.com/OpenRC/openrc/blob/master/user-guide.md
Purpose and description[edit]
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.
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 (GhostBSD, FreeBSD, OpenBSD, DragonFlyBSD) and HURD.
Services are stateful (i.e. start; start will lead to "it's already started")
Startup[edit]
Usually PID1 (aka. init) calls the OpenRC binary (/sbin/openrc by default).
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[edit]
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[edit]
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[edit]
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.
All runlevels are represented as folders in /etc/runlevels/ with symlinks to the actual service scripts.
All services must reside in the /etc/init.d or /usr/local/etc/init.d directories. They must also conform to the OpenRC runscript standard.
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 foo default - add foo to the default runlevel Note: This will not auto-start foo! You'd still have to trigger rc or run the service script by hand.
FIXME: Document stacked runlevels
The default startup uses the runlevels sysinit, boot, and default, in that order. Shutdown uses the shutdown runlevel.
The Magic of conf.d[edit]
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[edit]
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[edit]
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[edit]
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[edit]
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[edit]
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[edit]
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.
[edit]
In this directory we collect files are not described above yet.
Directory/Files | Description |
---|---|
/boot/loader.rc | Includes additional commands; Load boot menu; Start the boot menu |
/boot/loader.rc.local | set 0 |
/etc/devd-openrc | Contains the following files: asus.conf, devmatch-openrc.conf, hyperv.conf, uath.conf, ulpt.conf, and zfs.conf |
/etc/openrc.shutdown | openrc-shutdown is the utility that communicates with openrc-init(8) to bring down the system or instruct openrc-init to re-execute itself. |
/etc/rc.dynamicdiskless | OpenRC for FreeBSD |
/etc/rc.firewall | The rc.firewall script is used to configure rules for the kernel based firewall service. |
/etc/rc.initdiskless | The post-boot initialization of an embedded FreeBSD system is controlled by /etc/rc.initdiskless. |
/etc/rc.resume | If drivers can be properly loaded and unloaded, automate this by putting the appropriate commands in /etc/rc.suspend and /etc/rc.resume. |
/etc/rc.sendmail | The rc.sendmail script is used by /etc/rc at boot time to start sendmail(8). It is meant to be sendmail(8) specific and not a generic script for all MTAs. It is only called by /etc/rc if the rc.conf(5) mta_start_script variable is set to /etc/rc.sendmail. |
/etc/rc.shutdown | See Operation of rc.shutdown |
/etc/rc.subr | functions used by system shell scripts |
/etc/rc.suspend | If drivers can be properly loaded and unloaded, automate this by putting the appropriate commands in /etc/rc.suspend and /etc/rc.resume. |
/sbin/openrc-run | openrc-run 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 /etc/rc.conf and finally the script itself. At this point openrc-run then runs the command given. |