This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
OpenRC
OpenRC is a dependency-based init system that maintains compatibility with the system provided init program, normally located in /sbin/init. It does not function as a replacement for the /sbin/init file. OpenRC is 100% compatible with Gentoo init scripts, which means a solution can be found to run the dozens of daemons in the main Gentoo repository. OpenRC, however, is not designed to be exclusively used by Gentoo Linux and can be used on other distributions and BSD systems.
Features
OpenRC provides a number of features touted as innovative by recent init systems like systemd or upstart, such as hardware initiated initscripts run or cgroups support. It does this without requiring large layout changes to accommodate radically different designs and dependencies.
See the comparison of init systems article for more information on init systems.
OpenRC Busybox integration
Busybox can be used to replace most of the userspace utilities needed by OpenRC (init, shell, awk and other POSIX tools), by using a complete Busybox as shell for OpenRC all the calls that normally would cause a fork/exec would be spared, improving the overall speed. This process is not yet streamlined.
Please note that there are currently many Busybox applets that are incompatible with OpenRC. See bug #529086 for details.
Replacing init
In order to set a specific runlevel from the bootloader the variable softlevel= should be used.
busybox
The SysV-init /etc/inittab file provided by Gentoo is not compatible with the Busybox init.
/etc/inittabExample inittab compatible with Busybox init::sysinit:/sbin/openrc sysinit ::wait:/sbin/openrc boot ::wait:/sbin/openrc
openrc-init
Beginning with OpenRC 0.25, a new program is provided on Linux, openrc-init, which can replace /sbin/init on startup.
openrc-init will ignore the /etc/inittab file and boot OpenRC directly.
This also means that terminals will need to be activated via the /etc/init.d/agetty service as they will not spawn automatically. For example, activating tty1:
root #ln -sr /etc/init.d/agetty /etc/init.d/agetty.tty1
root #rc-update add agetty.tty1 default
Adding init=/sbin/openrc-init to the boot parameters will start this system.
The standard sysvinit tools, i.e. shutdown and reboot, will not function while openrc-init is running. Instead the openrc-shutdown command must be used to shutdown the system.
Busybox specific init.d files
TODO: busybox provides a number of applets that could be used to replace third party software like acpid or dhcp/dhcpcd.
Replacing udev with mdev
See mdev.
Replacing udev with eudev
Older Gentoo installs were using udev as the main virtual/udev provider. Based on bug #575718 it was changed to eudev. However, the rc service is still /etc/init.d/udev.
Configuration
Files
- /etc/rc.conf
- The global OpenRC configuration file.
Network management
OpenRC can be used with one of several network managers or even with none, see Network manager.
Dependency behavior
Changing the default dependencies of init scripts, might be needed to fit more complex setups. See /etc/rc.conf for how to change the default behavior; notice the rc_depend_strict option. In addition, next networking examples show how flexible OpenRC can be.
- Multiple network interfaces (example)
The SSH service must come up with the internal network, for instance eth0 and never wlan0.
Overrule the "net" dependency from /etc/init.d/sshd, and refine it to depend on "net.eth0":
/etc/conf.d/sshdrc_need="!net net.eth0"
- Multiple network interfaces in multiple runlevels (example)
The SSH service must start with eth0 (not wlan0) in "default" runlevel, but in "office" runlevel it must start with wlan0 (not eth0).
Keep the default:
/etc/rc.conf#rc_depend_strict="YES"
Make additional symlinks to sshd with the network interface names:
root #ln -s sshd /etc/init.d/sshd.eth0
root #ln -s sshd /etc/init.d/sshd.wlan0
Settings are read from /etc/conf.d/sshd.eth0 and /etc/conf.d/sshd.wlan0 now:
root #cp /etc/conf.d/sshd /etc/conf.d/sshd.eth0
root #cp /etc/conf.d/sshd /etc/conf.d/sshd.wlan0
Add the dependencies:
root #echo 'rc_need="!net net.eth0"' >> /etc/conf.d/sshd.eth0
root #echo 'rc_need="!net net.wlan0"' >> /etc/conf.d/sshd.wlan0
In this example net.eth0 and net.wlan0 read their settings from /etc/conf.d/net, or /etc/conf.d/net.office depending on the active runlevel. Add all runscripts to the different runlevels:
root #rc-update add sshd.eth0 default
root #rc-update add sshd.wlan0 office
root #rc-update add net.eth0 default office
root #rc-update add net.wlan0 default office
To switch between "default" runlevel and "office" runlevel without rebooting the computer, change to "nonetwork" runlevel in between. The network interfaces will be stopped this way, and re-read their runlevel specific configuration. This works best when "nonetwork" is a stacked runlevel in both the "default" and "office" runlevels, and the display manager and other non-network services are added to the "nonetwork" runlevel only.
default runlevel <---> nonetwork runlevel <---> office runlevel
root #rc nonetwork && rc office
root #rc nonetwork && rc default
Selecting a specific runlevel at boot
OpenRC reads the kernel command-line used at boot time, and will start the runlevel specified by the "softlevel" parameter if provided, instead of 'default'.
For instance, you can choose whether to boot into the 'default' or 'nonetwork' runlevels with the following example grub.conf configuration:
/boot/grub/grub.confExample grub.conf (GRUB Legacy)title=Regular Start-up kernel (hd0,0)/boot/kernel-3.7.10-gentoo-r1 root=/dev/sda3 title=Start without Networking kernel (hd0,0)/boot/kernel-3.7.10-gentoo-r1 root=/dev/sda3 softlevel=nonetwork
Usage
Runlevels
OpenRC can be controlled and configured using openrc, rc-update and rc-status commands.
Delete from default runlevel
root #rc-update delete dropbox default #replace dropbox with program to remove
Listing
Use rc-update show -v to display all available init scripts and their their current runlevel (if they have been added to one):
root #rc-update show -vRunning rc-update or rc-update show will display only the init scripts that have been added to a runlevel.
Named runlevels
OpenRC runlevels are directories living in /etc/runlevels to create additional runlevels is enough to issue:
root #install -d /etc/runlevels/$runlevelStacked runlevels
Is possible manage variants using rc-update -s.
An usage example for using stacked runlevel on laptop to group networking services based on location is at OpenRC/StackedRunlevel.
Prefix
Gentoo Prefix installs Gentoo within an offset, known as a prefix, allowing users to install Gentoo in another location in the filesystem hierarchy, hence avoiding conflicts. Next to this offset, Gentoo Prefix runs unprivileged, meaning no root user or rights are required to use it.
By using an offset (the "prefix" location), it is possible for many "alternative" user groups to benefit from a large part of the packages in the Gentoo Linux Portage tree. Currently users of the following systems successfully run Gentoo Prefix: Mac OS X on PPC and x86, Linux on x86, x86_64 and ia64, Solaris 10 on Sparc, Sparc/64, x86 and x86_64, FreeBSD on x86, AIX on PPC, Interix on x86, Windows on x86 (with the help of Interix), HP-UX on PARISC and ia64.
OpenRC runscript already support prefix-installed daemons, during the Summer of Code 2012 work will be done to implement full secondary/session daemon behavior to complete the overall feature set provided by Prefix.
OpenRC/Prefix, a tutorial for trying it out.
Hotplug
OpenRC can be triggered by external events, such as new hardware from udev. See OpenRC/Event Driven for details.
Manually recovering crashed services
If you have a process that crashes upon start you will see the following when you go to check it's status.
root #/etc/init.d/docker status
* status: crashed
root #/etc/init.d/docker start
* WARNING: docker has already been started
root #/etc/init.d/docker stop
* Caching service dependencies ... [ ok ]
* Stopping docker ...
* Failed to stop docker [ !! ]
* ERROR: docker failed to stop
To remedy this situation you will need to zap the process which in the following example is the docker service.
root #/etc/init.d/docker zapAutomatic respawning crashed services
OpenRC can return state of services to runlevel setting state, to provide stateful init scripts and automatic respawning. What you need is to run openrc (for default runlevel). Crashed services start and manual run services will stop. To prevent this you can run openrc -n (--not-stop)
By default openrc will attempt just to start crashed services, not restart. This сontrolled by rc_crashed_stop (default NO) and rc_crashed_start (default YES) options in /etc/rc.conf.
CGroups support
OpenRC starting with version 0.12 has extended cgroups support. See OpenRC/CGroups for details.
Chroot support
root #mkdir /lib64/rc/init.d
root #ln -s /lib64/rc/init.d /run/openrc
root #touch /run/openrc/softlevel
root #emerge --oneshot sys-apps/openrc
/etc/rc.confOpenRC config filerc_sys="prefix" rc_controller_cgroups="NO" rc_depend_strict="NO" rc_need="!net !dev !udev-mount !sysfs !checkfs !fsck !netmount !logger !clock !modules"