OpenRC: Difference between revisions

Revision as of 18:52, 9 August 2025

Alpine Linux uses openrc for its init system. The init system manages the services, including the boot and shutdown of your system.

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>`
User Services
To view currently active User runlevels and state of User services	`$ 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>`
View command usage
To view command usage for all openrc commands	`$ rc-status -h` or `$ rc-status --help`

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, /proc and optionally /sys for Linux based systems. It also mounts /lib/rc/init.d as a ramdisk using tmpfs where available unless / is mounted rw at boot. rc uses /lib/rc/init.d to 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.

Configuration

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/.

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:

Warning: whilst we have improved parallel, it can still potentially lock the boot process. Don't file bugs about this.

To improve startup times, consider the idea suggested in the preventing slow services from delaying startup section.

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

rc_cgroup_mode="hybrid"

Then, one should run

# rc-service cgroups start

to take effect and

# rc-update add cgroups

to auto mount the cgroup filesystem on boot.

User services

OpenRC supports managing services for users. User services are currently experimental and available from v3.22 for the following:

Such services are said to be running in user mode and are managed with rc-update, rc-service, rc-status and openrc using the -U option (as distinct from the -u option), and without doas (nor as root).

Note: The upstream OpenRC User Guide for user services considers configuring pam in the management of user service sessions; as an experimental branch of OpenRC, this facility, including its autostart configuration, may be fluid. Many Alpine Linux installations typically may not run pam.

Prerequisites

XDG_RUNTIME_DIR variable must be set

Config files

OpenRC uses ~/.config, if $XDG_CONFIG_HOME is unset. Adjust below instructions, if $XDG_CONFIG_HOME differs. The main configuration file for OpenRC User services is ~/.config/rc/rc.conf and ~/.config/rc/runlevels/ contains the User runlevels.

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/ have customized service scripts for User services files and their respective configuration files.

Configure environment variables

For Wayland

Tip: User services like wlsunset depend on the $WAYLAND_DISPLAY environment variable and associated variables. Hence, it is recommended to use gui runlevel for all User services in Wayland.

Allow propagation of the $WAYLAND_DISPLAY and 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 gui to 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

...
if [ -z "$XDG_RUNTIME_DIR" ]; then
	XDG_RUNTIME_DIR="/tmp/$(id -u)-runtime-dir"
	mkdir -pm 0700 "$XDG_RUNTIME_DIR"
	export XDG_RUNTIME_DIR
fi
openrc -U default
exec dwm

Note: For both the above cases, logout and login for the OpenRC user services to be started, before proceeding further.

User service management

Issue the command $ rc-status -Ur to view and verify the name current user runlevel as gui and default for Wayland and Xorg, respectively, before proceeding.

To start the PipeWire user service, issue the command:

$ rc-service -U pipewire start

Verify that the above OpenRC user service is started before proceeding further:

$ rc-status -U

To enable the PipeWire user service, issue the command:

$ rc-update -U add pipewire

The above steps may be repeated for other user services, such as pipewire-pulse, wlsunset etc. Note that the pipewire-pulse service would be required to enable various functions, including setting audio levels with pactl when running pulseaudio with pulseaudio-utils and to enable associated volume user keys.

Note: Ensure that the startup of above services from /etc/xdg/autostart folder or from the startup/config file are stopped to prevent duplicate instance of services.

PAM support

Further to the note above, the default installation of OpenRC user services in Alpine Linux is without PAM support. To ensure that user services do not linger on logout, enable PAM support for OpenRC user services by installing the openrc-user-pam package.

# apk add openrc-user-pam

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 and networking might delay startup of an interactive system rather than start in the background.

This can be remedied using stacked runlevels, as per Patrycja's blog post titled OpenRC: Start services after login prompt.

Warning: If the file /etc/inittab is edited wrongly, the system may not boot. Take backup and learn how to restore using rescue disk before proceeding.

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.

Command usage

To view the command usage for all OpenRC commands (rc-update, rc-service, rc-status, openrc etc.) use the --help or -h flag. For eg:$ rc-update --help or $ rc-update -h will show usage information for rc-update.

The busybox command equivalent for traditional GNU/Linux systems is as follows:

# reboot # ⇔ shutdown now -r # halt # ⇔ shutdown now -H # poweroff # ⇔ shutdown now -P

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.

@@ Line 1: / Line 1: @@
-Alpine Linux uses [https://github.com/OpenRC/ openrc] for its init system. The init system manages the services, startup and shutdown of your computer.
+Alpine Linux uses [https://github.com/OpenRC/ openrc] for its [https://en.wikipedia.org/wiki/Init init] system. The init system manages the services, including the boot and shutdown of your system.
-To learn the basics of OpenRC quickly, refer to the [https://docs.alpinelinux.org/user-handbook/0.1a/Working/openrc.html working with OpenRC] guide from Alpine Linux documentation project.
+To learn the basics of OpenRC quickly, refer to the [https://docs.alpinelinux.org/user-handbook/0.1a/Working/openrc.html working with OpenRC] guide from the Alpine Linux documentation project.
 == Quickstart  ==
@@ Line 68: / Line 68: @@
 == Runlevels ==
-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. The default startup uses the runlevels sysinit, boot, and default, in that order. Shutdown uses the shutdown runlevel.
+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:
@@ Line 77: / Line 77: @@
 The special runlevels are:
-* '''sysinit''' - Brings up system specific stuff such as <code>/dev</code>, <code>/proc</code> and optionally <code>/sys</code> for Linux based systems. It also mounts <code>/lib/rc/init.d</code> as a ramdisk using tmpfs where available unless <code>/</code> is mounted rw at boot. <code>'''rc'''</code> uses <code>/lib/rc/init.d</code> to hold state information about the services it runs. sysinit always runs when the host first starts and should not be run again.
+* '''sysinit''' - Brings up system specific stuff such as <code>/dev</code>, <code>/proc</code> and optionally <code>/sys</code> for Linux based systems. It also mounts <code>/lib/rc/init.d</code> as a ramdisk using tmpfs where available unless <code>/</code> is mounted rw at boot. <code>'''rc'''</code> uses <code>/lib/rc/init.d</code> to 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 you should add to the boot runlevel are those which deal with the mounting of filesystems, set 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.
+* '''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.
+* '''single''' - Stops all services except for those in the '''sysinit''' runlevel.
-* '''reboot''' - Changes to the shutdown runlevel and then reboots the host.
+* '''reboot''' - Changes to the '''shutdown''' runlevel, and then reboots the host.
-* '''shutdown''' - Changes to the shutdown runlevel and then halts the host.
+* '''shutdown''' - Changes to the shutdown '''runlevel''', and then halts the host.
 === Stacked runlevels ===
-Stacked runlevels allows "inheritance" of services. A few use cases are given below:
+''Stacked'' runlevels allows for the "inheritance" of services. A few use cases are given below:-
 * [https://docs.alpinelinux.org/user-handbook/0.1a/Working/openrc.html#_runlevel_stacking Running an office runlevel with VPN service]
 * [[#Preventing slow services from delaying system startup|Preventing slow services from delaying system startup]]
@@ Line 94: / Line 96: @@
 The main configuration file for OpenRC is {{Path|/etc/rc.conf}}. The OpenRC service scripts for each service can be found at {{Path|/etc/init.d/}} and their respective service configuration files at {{Path|/etc/conf.d/}}.
-If the setting {{Codeline|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:{{Warning|whilst we have improved parallel, it can still potentially lock the boot process. Don't file bugs about this.}} To improve boot times, consider the idea suggested in the [[#Preventing slow services from delaying system startup|preventing slow services]] from delaying boot section.
+If the setting {{Codeline|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:{{Warning|whilst we have improved parallel, it can still potentially lock the boot process. Don't file bugs about this.}} To improve startup times, consider the idea suggested in the [[#Preventing slow services from delaying system startup|preventing slow services from delaying startup]] section.
 === Cgroups ===
-OpenRC supports cgroups v2 in the default configuration. To enable hybrid cgroups, edit the file {{Path|/etc/rc.conf}} and change the setting for {{ic|rc_cgroup_mode}} as follows:{{Cat|/etc/rc.conf|rc_cgroup_mode{{=}}"hybrid"}}
+OpenRC supports [https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html cgroups v2] in the default configuration. To enable hybrid cgroups, edit the file {{Path|/etc/rc.conf}} and change the setting for {{ic|rc_cgroup_mode}} as follows:{{Cat|/etc/rc.conf|rc_cgroup_mode{{=}}"hybrid"}}
-Then you should run {{Cmd|# rc-service cgroups start}}
+Then, one should run {{Cmd|# rc-service cgroups start}}
 to take effect and {{Cmd|# rc-update add cgroups}}
 to auto mount the cgroup filesystem on boot.
@@ Line 109: / Line 111: @@
 * [[PipeWire]]
 * {{pkg|wlsunset}}
+Such services are said to be running in ''user mode'' and are managed with {{ic|rc-update}}, {{ic|rc-service}}, {{ic|rc-status}} and {{ic|openrc}} using the ''-U'' option (as distinct from the ''-u'' option), and without '''doas''' (nor as root).
+{{Note|The upstream OpenRC User Guide for user services considers [https://github.com/OpenRC/openrc/blob/master/user-guide.md#auto-starting configuring pam] in the management of user service sessions;  as an experimental branch of OpenRC, this facility, including its autostart configuration, may be fluid.  Many Alpine Linux installations typically may not run pam.}}
 === Prerequisites ===
@@ Line 125: / Line 131: @@
 ==== For Wayland ====
-{{Tip|User services like {{pkg|wlsunset}} depend on "WAYLAND_DISPLAY" environment variable. Hence, it is recommonded to use '''gui''' runlevel for all User services in Wayland.}}
+{{Tip|User services like {{pkg|wlsunset}} depend on the {{ic|$WAYLAND_DISPLAY}} environment variable and associated variables. Hence, it is recommended to use '''gui''' runlevel for all User services in Wayland.}}
-* Allow propagation of the WAYLAND_DISPLAY environment variables by adding the following lines to file {{path|~/.config/rc/rc.conf}} as follows:{{Cat|~/.config/rc/rc.conf|<nowiki>rc_env_allow="WAYLAND_DISPLAY"</nowiki>}}
+* Allow propagation of the {{ic|$WAYLAND_DISPLAY}} and associated environment variables by adding the following lines to file {{path|~/.config/rc/rc.conf}} as follows:{{Cat|~/.config/rc/rc.conf|<nowiki>rc_env_allow="WAYLAND_DISPLAY"</nowiki>}}
 * Create a custom '''gui''' user runlevel:{{Cmd|$ mkdir -p ~/.config/rc/runlevels/gui}}
 * To start '''gui''' user runlevel, add the line {{ic|openrc -U gui}} to the startup file of your compositor. For eg, for [[Sway]] add:{{Cat|~/.config/sway/config|...
@@ Line 146: / Line 152: @@
 === User service management ===
-Issue the command {{ic|$ rc-status -Ur}} to view and verify the name current user runlevel as '''gui''' and '''default''' for Wayland and Xorg respectively before proceeding.
+Issue the command {{ic|$ rc-status -Ur}} to view and verify the name current user runlevel as '''gui''' and '''default''' for Wayland and Xorg, respectively, before proceeding.
-To start [[PipeWire]] user service, issue the command:{{Cmd|$ rc-service -U pipewire start}}
+To start the [[PipeWire]] user service, issue the command:{{Cmd|$ rc-service -U pipewire start}}
 Verify that the above OpenRC user service is started before proceeding further: {{Cmd|$ rc-status -U}}
-To enable [[PipeWire]] user service, issue the command: {{Cmd|$ rc-update -U add pipewire}}
+To enable the [[PipeWire]] user service, issue the command: {{Cmd|$ rc-update -U add pipewire}}
-The above steps can be repeated for other User services like {{ic|pipewire-pulse}}, {{ic|wlsunset}} etc
+The above steps may be repeated for other user services, such as {{ic|pipewire-pulse}}, {{ic|wlsunset}} etc.  Note that the {{ic|pipewire-pulse}} service would be required to enable various functions, including setting audio levels with {{ic|pactl}}  when [[PulseAudio#PulseAudio_Utils|running pulseaudio with pulseaudio-utils]] and to enable associated volume user keys.
 {{Note|Ensure that the startup of above services from {{Path|/etc/xdg/autostart}} folder or from the startup/config file are stopped to prevent duplicate instance of services.}}
@@ Line 158: / Line 164: @@
 === PAM support ===
-The default installation of OpenRC user services is without PAM support. To ensure that user services do not linger on logout, enable PAM support for OpenRC user services by installing the {{pkg|openrc-user-pam}} package.{{Cmd|# apk add {{pkg|openrc-user-pam}}}}
+Further to the [[OpenRC#User_services|note above]], the default installation of OpenRC user services in Alpine Linux is without PAM support. To ensure that user services do not linger on logout, enable PAM support for OpenRC user services by installing the {{pkg|openrc-user-pam}} package.{{Cmd|# apk add {{pkg|openrc-user-pam}}}}
 == Preventing slow services from delaying system startup ==
@@ Line 164: / Line 170: @@
 Services that take a while to start will block the boot process until they complete. E.g.: <code>iwd</code> and <code>networking</code> might delay startup of an interactive system rather than start in the background.
-This can be remedied using [[#Stacked runlevels|stacked runlevels]] as per Patrycja's blog post titled [https://ptrcnull.me/posts/openrc-async-services.html OpenRC: Start services after login prompt].
+This can be remedied using [[#Stacked runlevels|stacked runlevels]], as per Patrycja's blog post titled [https://ptrcnull.me/posts/openrc-async-services.html OpenRC: Start services after login prompt].
 {{Warning|If the file {{Path|'''/etc/inittab'''}} is edited wrongly, the system may not boot. Take backup and learn how to restore using rescue disk  before proceeding.}}
 # Create a custom runlevel '''async''':  {{Cmd|# mkdir /etc/runlevels/async}}
-# Add default as a stacked runlevel {{Cmd|# rc-update add -s default async}}
+# Add '''default''' as a stacked runlevel {{Cmd|# rc-update add -s default async}}
-# Remove slow service from default runlevel and add them to async runlevel:{{Cmd|<nowiki># rc-update del <servicename> default
+# Remove slow service from '''default''' runlevel and add them to the '''async''' runlevel:{{Cmd|<nowiki># rc-update del <servicename> default
 # rc-update add <servicename> async </nowiki>}}
-# Add changing of runlevel to async by adding the line '''::once:/sbin/openrc async''' to {{Path|/etc/inittab}} file as follows: {{Cat|/etc/inittab|<nowiki>...
+# Enable the '''async''' runlevel by adding the line '''::once:/sbin/openrc async''' to {{Path|/etc/inittab}} file as follows: {{Cat|/etc/inittab|<nowiki>...
 ::wait:/sbin/openrc default
 ::once:/sbin/openrc async -q
@@ Line 178: / Line 184: @@
 tty1::respawn:/sbin/getty 38400 tty1
 ...</nowiki>}}
-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.
+After rebooting, services from '''async''' will start separately. Other services started in '''default''' runlevel may still block [[TTY_Autologin|agetty]] from running, due to the {{ic|wait}} label.
 == Command usage ==
-To view the command usage for all OpenRC commands (rc-update, rc-service, rc-status, openrc etc.) either use --help or (-h) flag. For eg:{{ic|$ rc-update --help}} or {{ic|$ rc-update -h}} will show usage information for {{ic|rc-update}}.
+To view the command usage for all OpenRC commands ({{ic|rc-update}}, {{ic|rc-service}}, {{ic|rc-status}}, {{ic|openrc}} etc.) use the ''--help'' or ''-h'' flag. For eg:{{ic|$ rc-update --help}} or {{ic|$ rc-update -h}} will show usage information for {{ic|rc-update}}.
-The busybox command equivalent for traditional GNU/Linux systems is as follows:{{Cmd|<nowiki># reboot   # ⇔ shutdown now -r
+The [[BusyBox|busybox]] command equivalent for traditional GNU/Linux systems is as follows:{{Cmd|<nowiki># reboot   # ⇔ shutdown now -r
 # halt     # ⇔ shutdown now -H
 # poweroff # ⇔ shutdown now -P</nowiki>}}
@@ Line 190: / Line 196: @@
 == Troubleshooting ==
-Whenever a openRC service fails to run, to troubleshoot enable debugging option and run the command.
+Whenever a openRC service fails to run, troubleshoot by enabling a debugging option, and then run the command.
-For example, if running the command {{ic|rc-service greetd start}} causes greetd service to immediately crash, then alter the command to enable and view the debug:{{Cmd|# rc-service -d greetd restart}}
+For example, if running the command {{ic|rc-service greetd start}} causes the [[Greetd|greetd]] service to immediately crash, then alter the command to enable debug and to view its output:{{Cmd|# rc-service -d greetd restart}}
 === XDG_RUNTIME_DIR unset ===
@@ Line 204: / Line 210: @@
 === failed to create display ===
-When using openRC user services for {{ic|wlsunset}}, the following  error message may appear:{{Cmd|daemon.err wlsunset: failed to create display}}You will need the GUI runlevel for services that depend on WAYLAND_DISPLAY. Refer [[#For Wayland| Configure environment variables For Wayland]] section.
+When using openRC user services for {{ic|wlsunset}}, the following  error message may appear:{{Cmd|daemon.err wlsunset: failed to create display}}You will need the GUI runlevel for services that depend on {{ic|$WAYLAND_DISPLAY}}. Refer [[#For Wayland| Configure environment variables For Wayland]] section.
 == See also ==