Alpine Linux - User contributions [en]

OpenRC

2025-09-12T13:07:21Z

StruanR: /* Quickstart */

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. OpenRC also supports managing [[#User services|services for users]].

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 ==

{|align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| width="50%" |Action
| |Command
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | '''Managing a service - start,stop and restart'''
|-
| Start {{ic|ServiceName}} now || {{ic|$ rc-service {{ic|ServiceName}} start}}
|-
| Stop {{ic|ServiceName}} now || {{ic|$ rc-service {{ic|ServiceName}} stop}}
|-
| Restart {{ic|ServiceName}} now || {{ic|$ rc-service {{ic|ServiceName}} restart}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | '''Adding and removing service from runlevels'''
|-
| Add {{ic|ServiceName}} to {{ic|runlevel}} || {{ic|$ rc-update add {{ic|ServiceName}} {{ic|runlevel}}}}
|-
| Remove {{ic|ServiceName}} from {{ic|runlevel}} || {{ic|$ rc-update del {{ic|ServiceName}} {{ic|runlevel}}}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Check services in a runlevel and their status'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To check status of {{ic|ServiceName}} || {{ic|$ rc-service {{ic|ServiceName}} status}}
|-
| To view services configured at {{ic|runlevel}} || {{ic|$ rc-update show {{ic|runlevel}}}}
|-
| To view currently active runlevels and state of services || {{ic|$ rc-status}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Check and manage runlevels'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To view available runlevels || {{ic|$ rc-status -l}}
|-
| To change to a different {{ic|runlevel}} || {{ic|$ openrc {{ic|runlevel}}}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Stacked runlevels'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To add {{ic|s-runlevel}} as a stacked {{ic|runlevel}} || {{ic|$ rc-update add -s {{ic|s-runlevel}}{{ic|runlevel}}}}
|-
| To remove {{ic|s-runlevel}} as a stacked {{ic|runlevel}} || {{ic|$ rc-update del -s {{ic|s-runlevel}} {{ic|runlevel}}}}
| -
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" |'''User Services'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To view currently active User runlevels and state of User services || {{ic|$ rc-status -U}}
|-
| To change to a different user {{ic|runlevel}} || {{ic|$ openrc -U {{ic|runlevel}}}}
|-
| Add User {{ic|ServiceName}} to user {{ic|runlevel}} || {{ic|$ rc-update -U add {{ic|ServiceName}} {{ic|runlevel}}}}
|-
| To add {{ic|s-runlevel}}as a stacked user {{ic|runlevel}} || {{ic|$ rc-update -U add -s {{ic|s-runlevel}} {{ic|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 <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 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:-
* [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]]
For more detailed information, refer [https://wiki.gentoo.org/wiki/OpenRC/Stacked%20runlevel Gentoo wiki].

== Config files ==

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

== Command usage ==

OpenRC provides the following commands:
* {{ic|rc-update}}
* {{ic|rc-service}}
* {{ic|rc-status}}
* {{ic|openrc}}

To view the command usage for all OpenRC commands, 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}}.

To {{ic|start}}, {{ic|stop}} or {{ic|restart}} a service {{ic|ServiceName}} immediately at the current runlevel:
{{cmd|$ doas rc-service {{ic|ServiceName}} start}}
{{cmd|$ doas rc-service {{ic|ServiceName}} stop}}

To {{ic|add}} or {{ic|delete}} a service to/from the sequence of services that need to start automatically in future sessions at the {{ic|boot}} runlevel:
{{cmd|$ doas rc-update add {{ic|ServiceName}} boot}}
Note that the {{ic|'''default'''}} runlevel is assumed, so it does not need to be stated explicitly:
{{cmd|$ doas rc-update add {{ic|ServiceName}}}}
{{cmd|$ doas rc-update del {{ic|ServiceName}}}}

List the current status of all services; to display the status of all ''user services'' add '''-U''' :
{{cmd|$ rc-status}}
List the assigned runlevels of all services; to display the runlevels of ''user services'' add '''-U''' :
{{cmd|$ rc-update}}

Refer to the [https://github.com/OpenRC/openrc/blob/master/user-guide.md OpenRC user guide] for more detailed information.

== Cgroups ==

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

== Local service ==

Use the {{Path|/etc/local.d/}} directory to place programs or scripts which are to be run when the {{ic|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 [https://github.com/OpenRC/openrc/blob/master/local.d/README README]

To enable the {{ic|local}} service, issue the command:{{Cmd|# 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.: {{ic|iwd}},{{ic|networking}},{{ic|chrony}} etc... might delay startup of an interactive system rather than start in the background.

=== Parallel services ===

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

=== Stacked runlevel method ===

Slow services can also be [https://ptrcnull.me/posts/openrc-async-services.html started after login prompt] using [[#Stacked runlevels|stacked runlevels]].
{{Warning|Editing the file {{Path|'''/etc/inittab'''}} wrongly will render the system unusable. Take backup and learn to restore it 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}}
# 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>}}
# 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

# Set up a couple of getty's
tty1::respawn:/sbin/getty 38400 tty1
...</nowiki>}}
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.

== User services ==

OpenRC supports managing services for users. User services are currently experimental and available from [[Release_Notes_for_Alpine_3.22.0#OpenRC_User_services|v3.22]]. Here is the [https://pkgs.alpinelinux.org/contents?file=*&path=%2Fetc%2Fuser%2Finit.d&name=&branch=edge&repo=&arch=x86_64 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 {{path|$XDG_CONFIG_HOME/rc}} for its user service configuration. If <code>$XDG_CONFIG_HOME</code> is unset, the fallback {{path|~/.config}} is used.

The main configuration file for OpenRC User services is {{path|~/.config/rc/rc.conf}}.

==== Runlevels ====

Runlevels are represented by directories in {{path|$XDG_CONFIG_HOME/rc/runlevels}}. The default runlevel is <code>sysinit</code> 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 (<code>sysinit</code>), use:

openrc -U

To start another runlevel, use:

openrc -U $RUNLEVEL

Add the above line to <code>~/.profile</code> 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|PAM support]] below.

==== Services ====

The service scripts for each OpenRC user service provided as part of official packages can be found at {{Path|/etc/user/init.d/}} and their respective service configuration files at {{Path|/etc/user/conf.d/}}.

The folders {{path|~/.config/rc/init.d/}} and {{path|~/.config/rc/conf.d/}} can have user customized service scripts for User services and their respective configuration files. These scripts override official files at {{Path|/etc/user/}}, if their service names match.

=== Configure environment variables ===

==== For Wayland ====
{{Tip|User services like {{pkg|wlsunset}} depend on the {{ic|$WAYLAND_DISPLAY}} environment variable. Hence, it is [https://gitlab.alpinelinux.org/alpine/aports/-/issues/17375#note_530383 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 {{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|...
exec openrc -U gui}}

==== For Xorg ====

If [[Elogind]] is not used, ensure that [[Wayland#Creating_and_exporting_XDG_RUNTIME_DIR_manually|XDG_RUNTIME_DIR]] is set manually in {{path|~/.xinitrc}}. For eg, for [[dwm]] add:{{Cat|~/.xinitrc|<nowiki>...
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</nowiki>}}

{{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 {{ic|$ rc-status -Ur}} to view and verify the current user runlevel as '''gui''' and '''default''' for Wayland and Xorg, respectively, before proceeding.

To start {{ic|ServiceName}} user service, issue the command:{{Cmd|$ rc-service -U {{ic|ServiceName}} start}}
Verify that the above OpenRC user service is started before proceeding further: {{Cmd|$ rc-status -U}}
To enable {{ic|ServiceName}} user service, issue the command: {{Cmd|$ rc-update -U add ServiceName}}

{{Tip|Once a user service is configured, to prevent duplicate instance, remove them from {{Path|/etc/xdg/autostart}} folder or from the startup/config file.}}

=== 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 [https://wiki.gentoo.org/wiki/OpenRC#lingering linger] on logout, PAM support for OpenRC user services can be enabled by installing the {{pkg|openrc-user-pam}} package.{{Cmd|# apk add {{pkg|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 {{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 ===

While configuring [[#User services|user services]], running the command {{ic|$ doas rc-update add -U pipewire gui}} will generate the above error {{ic|XDG_RUNTIME_DIR unset}}. Always issue the command as normal user {{ic|$ rc-update add -U pipewire gui}} and do NOT use {{ic|doas}}.

=== ERROR: user.greetd failed to start ===

While using [[#User services|user services]] with [[greetd]], the above error message will appear. This failed error message for {{ic|user.greetd}} service is harmless as per {{MR|81612#note_492385}}.

=== 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 {{ic|$WAYLAND_DISPLAY}}. Refer [[#For Wayland| Configure environment variables For Wayland]] section.

== See also ==

* [[Writing Init Scripts]]
* [[Multiple Instances of Services]]
* [https://github.com/OpenRC/openrc/blob/master/user-guide.md OpenRC user Guide]
* [https://github.com/OpenRC/openrc/blob/master/service-script-guide.md OpenRC Service Script Writing Guide]
* [https://wiki.gentoo.org/wiki/OpenRC Gentoo Wiki]
* [https://wiki.archlinux.org/title/OpenRC ArchWiki]
* [https://wiki.postmarketos.org/wiki/OpenRC PostmarketOS Wiki]
* [https://ptrcnull.me/posts/openrc-async-services.html Start services after login prompt]

[[Category:Booting]]
[[Category:System Administration]]
[[Category:Services]]

OpenRC

2025-09-12T08:49:04Z

StruanR: Fix typo

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. OpenRC also supports managing [[#User services|services for users]].

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 ==

{|align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| width="50%" |Action
| |Command
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | '''Managing a service - start,stop and restart'''
|-
| Start {{ic|ServiceName}} now || {{ic|# rc-service {{ic|ServiceName}} start}}
|-
| Stop {{ic|ServiceName}} now || {{ic|# rc-service {{ic|ServiceName}} stop}}
|-
| Restart {{ic|ServiceName}} now || {{ic|# rc-service {{ic|ServiceName}} restart}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | '''Adding and removing service from runlevels'''
|-
| Add {{ic|ServiceName}} to {{ic|runlevel}} || {{ic|# rc-update add {{ic|ServiceName}} {{ic|runlevel}}}}
|-
| Remove {{ic|ServiceName}} from {{ic|runlevel}} || {{ic|# rc-update del {{ic|ServiceName}} {{ic|runlevel}}}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Check services in a runlevel and their status'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To check status of {{ic|ServiceName}} || {{ic|$ rc-service {{ic|ServiceName}} status}}
|-
| To view services configured at {{ic|runlevel}} || {{ic|$ rc-update show {{ic|runlevel}}}}
|-
| To view currently active runlevels and state of services || {{ic|$ rc-status}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Check and manage runlevels'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To view available runlevels || {{ic|$ rc-status -l}}
|-
| To change to a different {{ic|runlevel}} || {{ic|# openrc {{ic|runlevel}}}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Stacked runlevels'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To add {{ic|s-runlevel}} as a stacked {{ic|runlevel}} || {{ic|# rc-update add -s {{ic|s-runlevel}} {{ic|runlevel}}}}
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" |'''User Services'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To view currently active User runlevels and state of User services || {{ic|$ rc-status -U}}
|-
| To change to a different user {{ic|runlevel}} || {{ic|$ openrc -U {{ic|runlevel}}}}
|-
| Add User {{ic|ServiceName}} to user {{ic|runlevel}} || {{ic|$ rc-update -U add {{ic|ServiceName}} {{ic|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 <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 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:-
* [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]]
For more detailed information, refer [https://wiki.gentoo.org/wiki/OpenRC/Stacked%20runlevel Gentoo wiki].

== Config files ==

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

== Command usage ==

OpenRC provides the following commands:
* {{ic|rc-update}}
* {{ic|rc-service}}
* {{ic|rc-status}}
* {{ic|openrc}}

To view the command usage for all OpenRC commands, 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}}.

To {{ic|start}}, {{ic|stop}} or {{ic|restart}} a service {{ic|ServiceName}} immediately at the current runlevel:
{{cmd|$ doas rc-service {{ic|ServiceName}} start}}
{{cmd|$ doas rc-service {{ic|ServiceName}} stop}}

To {{ic|add}} or {{ic|delete}} a service to/from the sequence of services that need to start automatically in future sessions at the {{ic|boot}} runlevel:
{{cmd|$ doas rc-update add {{ic|ServiceName}} boot}}
Note that the {{ic|'''default'''}} runlevel is assumed, so it does not need to be stated explicitly:
{{cmd|$ doas rc-update add {{ic|ServiceName}}}}
{{cmd|$ doas rc-update del {{ic|ServiceName}}}}

List the current status of all services; to display the status of all ''user services'' add '''-U''' :
{{cmd|$ rc-status}}
List the assigned runlevels of all services; to display the runlevels of ''user services'' add '''-U''' :
{{cmd|$ rc-update}}

Refer to the [https://github.com/OpenRC/openrc/blob/master/user-guide.md OpenRC user guide] for more detailed information.

== Cgroups ==

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

== Local service ==

Use the {{Path|/etc/local.d/}} directory to place programs or scripts which are to be run when the {{ic|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 [https://github.com/OpenRC/openrc/blob/master/local.d/README README]

To enable the {{ic|local}} service, issue the command:{{Cmd|# 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.: {{ic|iwd}},{{ic|networking}},{{ic|chrony}} etc... might delay startup of an interactive system rather than start in the background.

=== Parallel services ===

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

=== Stacked runlevel method ===

Slow services can also be [https://ptrcnull.me/posts/openrc-async-services.html started after login prompt] using [[#Stacked runlevels|stacked runlevels]].
{{Warning|Editing the file {{Path|'''/etc/inittab'''}} wrongly will render the system unusable. Take backup and learn to restore it 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}}
# 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>}}
# 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

# Set up a couple of getty's
tty1::respawn:/sbin/getty 38400 tty1
...</nowiki>}}
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.

== User services ==

OpenRC supports managing services for users. User services are currently experimental and available from [[Release_Notes_for_Alpine_3.22.0#OpenRC_User_services|v3.22]]. Here is the [https://pkgs.alpinelinux.org/contents?file=*&path=%2Fetc%2Fuser%2Finit.d&name=&branch=edge&repo=&arch=x86_64 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 {{path|$XDG_CONFIG_HOME/rc}} for its user service configuration. If <code>$XDG_CONFIG_HOME</code> is unset, the fallback {{path|~/.config}} is used.

The main configuration file for OpenRC User services is {{path|~/.config/rc/rc.conf}}.

==== Runlevels ====

Runlevels are represented by directories in {{path|$XDG_CONFIG_HOME/rc/runlevels}}. The default runlevel is <code>sysinit</code> 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 (<code>sysinit</code>), use:

openrc -U

To start another runlevel, use:

openrc -U $RUNLEVEL

Add the above line to <code>~/.profile</code> 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|PAM support]] below.

==== Services ====

The service scripts for each OpenRC user service provided as part of official packages can be found at {{Path|/etc/user/init.d/}} and their respective service configuration files at {{Path|/etc/user/conf.d/}}.

The folders {{path|~/.config/rc/init.d/}} and {{path|~/.config/rc/conf.d/}} can have user customized service scripts for User services and their respective configuration files. These scripts override official files at {{Path|/etc/user/}}, if their service names match.

=== Configure environment variables ===

==== For Wayland ====
{{Tip|User services like {{pkg|wlsunset}} depend on the {{ic|$WAYLAND_DISPLAY}} environment variable. Hence, it is [https://gitlab.alpinelinux.org/alpine/aports/-/issues/17375#note_530383 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 {{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|...
exec openrc -U gui}}

==== For Xorg ====

If [[Elogind]] is not used, ensure that [[Wayland#Creating_and_exporting_XDG_RUNTIME_DIR_manually|XDG_RUNTIME_DIR]] is set manually in {{path|~/.xinitrc}}. For eg, for [[dwm]] add:{{Cat|~/.xinitrc|<nowiki>...
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</nowiki>}}

{{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 {{ic|$ rc-status -Ur}} to view and verify the current user runlevel as '''gui''' and '''default''' for Wayland and Xorg, respectively, before proceeding.

To start {{ic|ServiceName}} user service, issue the command:{{Cmd|$ rc-service -U {{ic|ServiceName}} start}}
Verify that the above OpenRC user service is started before proceeding further: {{Cmd|$ rc-status -U}}
To enable {{ic|ServiceName}} user service, issue the command: {{Cmd|$ rc-update -U add ServiceName}}

{{Tip|Once a user service is configured, to prevent duplicate instance, remove them from {{Path|/etc/xdg/autostart}} folder or from the startup/config file.}}

=== 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 [https://wiki.gentoo.org/wiki/OpenRC#lingering linger] on logout, PAM support for OpenRC user services can be enabled by installing the {{pkg|openrc-user-pam}} package.{{Cmd|# apk add {{pkg|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 {{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 ===

While configuring [[#User services|user services]], running the command {{ic|$ doas rc-update add -U pipewire gui}} will generate the above error {{ic|XDG_RUNTIME_DIR unset}}. Always issue the command as normal user {{ic|$ rc-update add -U pipewire gui}} and do NOT use {{ic|doas}}.

=== ERROR: user.greetd failed to start ===

While using [[#User services|user services]] with [[greetd]], the above error message will appear. This failed error message for {{ic|user.greetd}} service is harmless as per {{MR|81612#note_492385}}.

=== 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 {{ic|$WAYLAND_DISPLAY}}. Refer [[#For Wayland| Configure environment variables For Wayland]] section.

== See also ==

* [[Writing Init Scripts]]
* [[Multiple Instances of Services]]
* [https://github.com/OpenRC/openrc/blob/master/user-guide.md OpenRC user Guide]
* [https://github.com/OpenRC/openrc/blob/master/service-script-guide.md OpenRC Service Script Writing Guide]
* [https://wiki.gentoo.org/wiki/OpenRC Gentoo Wiki]
* [https://wiki.archlinux.org/title/OpenRC ArchWiki]
* [https://wiki.postmarketos.org/wiki/OpenRC PostmarketOS Wiki]
* [https://ptrcnull.me/posts/openrc-async-services.html Start services after login prompt]

[[Category:Booting]]
[[Category:System Administration]]
[[Category:Services]]

Radeon Video

2025-07-09T22:45:37Z

StruanR:

{{TOC right}}

The following instructions are for modern AMD GPU chipsets covered by the <code>radeon</code> and <code>amdgpu</code> drivers.

== Firmware ==

For [https://en.wikipedia.org/wiki/List%20of%20AMD%20graphics%20processing%20units Vega and later], the {{Pkg|linux-firmware-amdgpu}} package is required. Otherwise, the {{Pkg|linux-firmware-radeon}} should be used.

Programs using [https://www.vulkan.org/ Vulkan] may require the {{Pkg|mesa-vulkan-ati}} package to be installed.

See [https://wiki.gentoo.org/wiki/AMDGPU the relevant section on the Gentoo Wiki] for a more granular list of product names and microarchitecture names.

== Kernel Modesetting (KMS) ==

To enable [[KMS]] at boot:

# Run <code>lspci -k | grep amdgpu</code> and <code>lspci -k | grep radeon</code> to find your module. For example it will return <code>Kernel driver in use: amdgpu</code> for the <code>amdgpu</code> module when running the first command.
# Add the <code>radeon</code> or <code>amdgpu</code> and <code>fbcon</code> modules to {{Path|/etc/modules}}: {{Cmd|$ echo radeon >> /etc/modules<br />$ echo fbcon >> /etc/modules}} or {{Cmd|$ echo amdgpu >> /etc/modules<br />$ echo fbcon >> /etc/modules}}
# Install <code>mkinitfs</code>: {{Cmd|apk add mkinitfs}}
# Enable the <code>kms</code> feature in the <code>mkinitfs</code> configuration by adding it to the <var>features</var> variable, e.g., {{cat|/etc/mkinitfs/mkinitfs.conf|features{{=}}"keymap cryptsetup kms ata base ide scsi usb virtio ext4"}}
# Run <code>mkinitfs</code>.
# Reboot to test the configuration.

== Wayland ==

Install the following packages as needed:

* {{Pkg|mesa-dri-gallium}}: '''necessary''' Mesa drivers.
* {{Pkg|mesa-va-gallium}}: VA-API drivers, for hardware accelerated video encoding and decoding

If driver auto-selection does not work, e.g. no mouse cursor under Sway, manual driver selection might be needed:

* <code>export MESA_LOADER_DRIVER_OVERRIDE=r300</code>: for AMD's Radeon R300, R400, and R500 GPUs.
* <code>export MESA_LOADER_DRIVER_OVERRIDE=r600</code>: for AMD's Radeon R600 GPUs up to Northern Islands. Officially supported by AMD.
* <code>export MESA_LOADER_DRIVER_OVERRIDE=radeonsi</code>: for AMD's Southern Island GPUs and later. Officially supported by AMD.

For VA-API:
* <code>export LIBVA_DRIVER_NAME=r600</code>
* <code>export LIBVA_DRIVER_NAME=radeonsi</code>

== Xorg ==
{{Main|Xorg}}
Install either the Free Software driver {{Pkg|xf86-video-ati}} or the proprietary amdgpu firmware {{Pkg|linux-firmware-amdgpu}}.

<code>modprobe fbcon</code> might be needed to avoid black screen when leaving Xorg.

== See also ==

* [https://wiki.archlinux.org/title/AMDGPU AMDGPU - ArchWiki]
* [https://wiki.archlinux.org/title/ATI ATI - ArchWiki]

[[Category:Drivers]]
[[Category:Graphics]]