OpenRC
Alpine Linux uses OpenRC for its init system. The init system manages the services, including the boot and shutdown of your system. Don't confuse OpenRC init with system init (the first process that is executed aka pid 1). OpenRC also supports managing services for users.
To learn the basics of OpenRC quickly, refer to the working with OpenRC guide from the Alpine Linux documentation project.
Quickstart
| Action | Command | |
| Managing a service - start,stop and restart | ||
Start ServiceName now |
# rc-service ServiceName start | |
Stop ServiceName now |
# rc-service ServiceName stop | |
Restart ServiceName now |
# rc-service ServiceName restart | |
| Adding and removing service from runlevels | ||
Add ServiceName to runlevel |
# rc-update add ServiceName runlevel | |
Remove ServiceName from runlevel |
# rc-update del ServiceName runlevel | |
| Check services in a runlevel and their status | ||
To check status of ServiceName |
$ rc-service ServiceName status | |
To view services configured at runlevel |
$ rc-update show runlevel | |
| To view currently active runlevels and state of services | $ rc-status | |
| Check and manage runlevels | ||
| To view available runlevels | $ rc-status -l | |
To change to a different runlevel |
# openrc runlevel | |
| Stacked runlevels | ||
To add s-runlevel as a stacked runlevel |
# rc-update add -s s-runlevel runlevel | |
To remove s-runlevel as a stacked runlevel |
# rc-update del -s s-runlevel runlevel |
|
| User Services | ||
To view currently active user runlevels and state of user services (-U) |
$ rc-status -U | |
To change to a different user runlevel |
$ openrc -U runlevel | |
Add user ServiceName to user runlevel |
$ rc-update -U add ServiceName runlevel | |
To add s-runlevelas a stacked user runlevel |
$ rc-update -U add -s s-runlevel runlevel | |
Runlevels
A runlevel is basically a collection of services that needs to be started when certain conditions are met. Instead of using runlevel numbers, such as is used traditionally with SysV init, these are named, and users can create their own, if needed. The default startup uses the sysinit, boot, and default runlevels, in that order. Shutdown uses the shutdown runlevel.
The available runlevels are:
- default - Used if no runlevel is specified. (This is generally the runlevel you want to add services to.)
- hotplugged
- manual
The special runlevels are:
- sysinit - Brings up system specific stuff such as
/dev,/procand optionally/sysfor Linux based systems. It also mounts/lib/rc/init.das a ramdisk using tmpfs where available unless/is mounted rw at boot.rcuses/lib/rc/init.dto hold state information about the services it runs. sysinit always runs when the host first starts and should not be run again. - boot - Generally, the only services that one should add to the boot runlevel are those which deal with the mounting of filesystems, setting the initial state of attached peripherals, and logging. Hotplugged services are added to the boot runlevel by the system. All services in the boot and sysinit runlevels are automatically included in all other runlevels except for those listed here.
- single - Stops all services except for those in the sysinit runlevel.
- reboot - Changes to the shutdown runlevel, and then reboots the host.
- shutdown - Changes to the shutdown runlevel, and then halts the host.
Stacked runlevels
Stacked runlevels allows for the "inheritance" of services. A few use cases are given below:-
For more detailed information, refer Gentoo wiki.
Config files
The main configuration file for OpenRC is /etc/rc.conf. The OpenRC service scripts for each service can be found at /etc/init.d/ and their respective service configuration files at /etc/conf.d/.
Command usage
OpenRC provides the following commands:
rc-updaterc-servicerc-statusopenrc
To view the command usage for all OpenRC commands, use the --help or -h flag. For example: $ rc-update --help or $ rc-update -h will show usage information for rc-update.
To start, stop or restart a service ServiceName immediately at the current runlevel:-
$ doas rc-service ServiceName start
$ doas rc-service ServiceName stop
To add or delete a service to/from the sequence of services that need to start automatically in future sessions at the boot runlevel:
$ doas rc-update add ServiceName boot
Note that the default runlevel is assumed, so it does not need to be stated explicitly:
$ doas rc-update add ServiceName
$ doas rc-update del ServiceName
List the current status of all services; to display the status of all user services add -U :
$ rc-status
List the assigned runlevels of all services; to display the runlevels of user services add -U :
$ rc-update
Refer to the OpenRC user guide for more detailed information.
Cgroups
OpenRC supports cgroups v2 in the default configuration. To enable hybrid cgroups, edit the file /etc/rc.conf and change the setting for rc_cgroup_mode as follows:
Contents of /etc/rc.conf
Then, one should run
# rc-service cgroups start
to take effect and
# rc-update add cgroups
to auto mount the cgroup filesystem on boot.
Local service
Use the /etc/local.d/ directory to place programs or scripts which are to be run when the local service is started or stopped.
If a file in this directory is executable and it has a .start extension, it will be run when the local service is started. If a file is executable and it has a .stop extension, it will be run when the local service is stopped. For more info refer README
To enable the local service, issue the command:
# rc-update add local
Preventing slow services from delaying system startup
Services that take a while to start will block the boot process until they complete. E.g.: iwd,networking,chrony etc... might delay startup of an interactive system rather than start in the background.
Parallel services
If the setting rc_parallel="YES" is configured, the OpenRC system tries to start services in parallel for a slight speed improvement.
This setting however comes with a message from openRC developers:
Stacked runlevel method
Slow services can also be started after login prompt using stacked runlevels.
- Create a custom runlevel async:
# mkdir /etc/runlevels/async
- Add default as a stacked runlevel
# rc-update add -s default async
- Remove slow service from default runlevel and add them to the async runlevel:
# rc-update del ServiceName default
# rc-update add ServiceName async
- Enable the async runlevel by adding the line ::once:/sbin/openrc async to /etc/inittab file as follows:
Contents of /etc/inittab
... ::wait:/sbin/openrc default ::once:/sbin/openrc async -q # Set up a couple of getty's tty1::respawn:/sbin/getty 38400 tty1 ...
After rebooting, services from async will start separately. Other services started in default runlevel may still block agetty from running, due to the wait label.
User services
OpenRC supports managing services for users. User services are currently experimental and available from v3.22. Here is the list of OpenRC User services available currently.
Such services are said to be running in user mode and are managed with usual OpenRC commands using the -U option (as distinct from the -u option), and without doas (nor as root).
Prerequisites
- XDG_RUNTIME_DIR variable must be set
Config files for user services
OpenRC uses $XDG_CONFIG_HOME/rc for its user service configuration. If $XDG_CONFIG_HOME is unset, the fallback ~/.config is used.
The main configuration file for OpenRC User services is ~/.config/rc/rc.conf.
Runlevels
Runlevels are represented by directories in $XDG_CONFIG_HOME/rc/runlevels. The default runlevel is sysinit and needs to be created explicitly in order to be enabled:
$ mkdir -p ${XDG_CONFIG_HOME:-~/.config}/rc/runlevels/sysinit
To start the default runlevel (sysinit), use:
$ openrc -U
To start another runlevel, use:
$ openrc -U $RUNLEVEL
Add the above line to ~/.profile to automatically start the runlevel after logging in.
If automatic start-up of a runlevel needs to be enforced by the system administrator, see PAM support below.
Services
The service scripts for each OpenRC user service provided as part of official packages can be found at /etc/user/init.d/ and their respective service configuration files at /etc/user/conf.d/.
The folders ~/.config/rc/init.d/ and ~/.config/rc/conf.d/ can have user customized service scripts for User services and their respective configuration files. These scripts override official files at /etc/user/, if their service names match.
Configure environment variables
For Wayland
$WAYLAND_DISPLAY environment variable. Hence, it is recommended to use gui runlevel for such services. Even though PipeWire can run at default runlevel, ensure that all your User services can run at the chosen runlevel.- Allow propagation of the
$WAYLAND_DISPLAYand associated environment variables by adding the following lines to file ~/.config/rc/rc.conf as follows:Contents of ~/.config/rc/rc.conf
rc_env_allow="WAYLAND_DISPLAY" - Create a custom gui user runlevel:
$ mkdir -p ~/.config/rc/runlevels/gui
- To start gui user runlevel, add the line
openrc -U guito the startup file of your compositor. For eg, for Sway add:Contents of ~/.config/sway/config
... exec openrc -U gui
For Xorg
If Elogind is not used, ensure that XDG_RUNTIME_DIR is set manually in ~/.xinitrc. For eg, for dwm add:
Contents of ~/.xinitrc
User service management
Issue the command $ rc-status -Ur to view and verify the current user runlevel as gui and default for Wayland and Xorg, respectively, before proceeding.
To start ServiceName user service, issue the command:
$ rc-service -U ServiceName start
Verify that the above OpenRC user service is started before proceeding further:
$ rc-status -U
To enable ServiceName user service, issue the command:
$ rc-update -U add ServiceName
PAM support
The default installation of OpenRC user services in Alpine Linux is without PAM support.
In scenarios where services should not be allowed to linger on logout, PAM support for OpenRC user services can be enabled by installing the openrc-user-pam package.
# apk add openrc-user-pam
Troubleshooting
Whenever a openRC service fails to run, troubleshoot by enabling a debugging option, and then run the command.
For example, if running the command rc-service greetd start causes the greetd service to immediately crash, then alter the command to enable debug and to view its output:
# rc-service -d greetd restart
XDG_RUNTIME_DIR unset
While configuring user services, running the command $ doas rc-update add -U pipewire gui will generate the above error XDG_RUNTIME_DIR unset. Always issue the command as normal user $ rc-update add -U pipewire gui and do NOT use doas.
ERROR: user.greetd failed to start
While using user services with greetd, the above error message will appear. This failed error message for user.greetd service is harmless as per !81612#note_492385.
failed to create display
When using openRC user services for wlsunset, the following error message may appear:
daemon.err wlsunset: failed to create display
You will need the GUI runlevel for services that depend on $WAYLAND_DISPLAY. Refer Configure environment variables For Wayland section.