OpenRC

From Alpine Linux

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

Refer to the excellent guide working with OpenRC from Alpine Linux documentation project to learn the basics quickly. Refer Writing Init Scripts and Multiple instances of services pages for more advanced information.

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 - adding -U or --user to most of above commands should work
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 add -U <serviceName> <runlevel>

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.

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

Runlevel "inheritance" is acheived through runlevel stacking. For more detailed information, refer Gentoo wiki.

Configuration

System-wide configuration file for OpenRC is /etc/rc.conf.

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 boot times, consider the idea suggested in the preventing slow services from delaying boot section.

cgroups v2

Since openrc 0.51 cgroups v2, or "unified", is the default. You can enable hybrid cgroups v1 & v2 by editing /etc/rc.conf and setting rc_cgroup_mode="hybrid".

Then you 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:

Prerequisites

Configuration

Follow the below configuration steps:

  1. Allow propagation of the WAYLAND_DISPLAY environment variable by adding the following lines to file ${XDG_CONFIG_HOME:-$HOME/.config}/rc/rc.conf as follows:

    Contents of rc.conf

    rc_env_allow="WAYLAND_DISPLAY"
    The above option ensures settings in ${XDG_CONFIG_HOME:-$HOME/.config}/rc/rc.conf override /etc/rc.conf. Similarly, configuration and service files in ${XDG_CONFIG_HOME:-$HOME/.config}/rc/conf.d/ and ${XDG_CONFIG_HOME:-$HOME/.config}/rc/init.d/ override /etc/user/conf.d/ and /etc/user/init.d/ respectively.
  2. For many wayland user services, a custom GUI runlevel needs to be created. To create this runlevel,run the following command:

    $ mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/rc/runlevels/gui"

  3. To start user services from the above gui runlevel, add the line openrc --user gui to the startup file of your compositor after $WAYLAND_DISPLAY is set.
    For eg, for Sway, add the following line to sway user config file ~/.config/sway/config as follows

    Contents of ~/.config/sway/config

    ... exec openrc --user gui ...
  4. If wlsunset package is installed, enable the wlsunset service by adding it to gui runlevel:

    $ rc-update add -U wlsunset gui

    To enable PipeWire User service, replace wlsunset by pipewire in the above command.
  5. Remove the startup of above services either from /etc/xdg/autostart folder or from the startup/config file, i.e wherever they were started/mentioned earlier.
  6. Logout and login to your wayland compositor for the user services to be lauched.
  7. Issuing the command $ rc-status -U will produce an output similar to below, if the above instructions have been followed:
Runlevel: gui
 pipewire                                                 [  started 04:29:55 (0) ]
 wlsunset                                                 [  started 04:29:55 (0) ]
 mako                                                     [  started 04:29:53 (1) ]
Dynamic Runlevel: hotplugged
Dynamic Runlevel: needed/wanted
 dbus                                                     [  started 04:29:55 (0) ] 
 wireplumber                                              [  started 04:29:53 (1) ]
Dynamic Runlevel: manual
Todo:

KDE plasma users are requested to test the below instructions and edit this page directly or the Discussion page.

  1. Enable PAM support for openrc user services.
  2. In the above instructions, skip steps 2 & 3. In step 4, skip the word "gui", as SDDM automatically drops the user in "default" user runlevel on logging in.


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 openrc-user-pam package.

# apk add openrc-user-pam

If greetd is used, a harmless failed error message appears for user.greetd service as per !81612#note_492385.

Preventing slow services from delaying boot

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 as per Patrycja's blog post titled OpenRC: Start services after login prompt. This solution makes use of stacked runlevels.

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 (name is “async” here, but it doesn’t matter)

    # mkdir /etc/runlevels/async

  • Add default as a stacked runlevel

    # rc-update add -s default async

  • Remove slow services from default and add them to async

    # rc-update del chronyd # rc-update add chronyd async

  • Add changing of runlevel to async 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. This change does not affect other services that start from Default runlevel and they may still block agetty from running due to the wait label.

Command usage

Usage: rc-update [options] add <service> [<runlevel>...]
  or: rc-update [options] del <service> [<runlevel>...]
  or: rc-update [options] [show [<runlevel>...]]
Options: [ asuChqVv ]
 -a, --all                         Process all runlevels
 -s, --stack                       Stack a runlevel instead of a service
 -u, --update                      Force an update of the dependency tree
 -h, --help                        Display this help output
 -C, --nocolor                     Disable color output
 -V, --version                     Display software version
 -v, --verbose                     Run verbosely
 -q, --quiet                       Run quietly (repeat to suppress errors)

Usage: rc-status [options] [-f ini] <runlevel>...
  or: rc-status [options] [-f ini] [-a | -c | -l | -m | -r | -s | -u]
Options: [ acf:lmrsSuChqVv ]
 -a, --all                         Show services from all run levels
 -c, --crashed                     Show crashed services
 -f, --format <arg>                format status to be parsable (currently arg must be ini)
 -l, --list                        Show list of run levels
 -m, --manual                      Show manually started services
 -r, --runlevel                    Show the name of the current runlevel
 -s, --servicelist                 Show service list
 -S, --supervised                  show supervised services
 -u, --unused                      Show services not assigned to any runlevel
 -h, --help                        Display this help output
 -C, --nocolor                     Disable color output
 -V, --version                     Display software version
 -v, --verbose                     Run verbosely
 -q, --quiet                       Run quietly (repeat to suppress errors)

Usage: rc-service [options] [-i] <service> <cmd>...
  or: rc-service [options] -e <service>
  or: rc-service [options] -l
  or: rc-service [options] -r <service>
Options: [ cdDe:ilr:INsSZChqVv ]
 -d, --debug                       set xtrace when running the command
 -D, --nodeps                      ignore dependencies
 -e, --exists <arg>                tests if the service exists or not
 -c, --ifcrashed                   if the service is crashed run the command
 -i, --ifexists                    if the service exists run the command
 -I, --ifinactive                  if the service is inactive run the command
 -N, --ifnotstarted                if the service is not started run the command
 -s, --ifstarted                   if the service is started run the command
 -S, --ifstopped                   if the service is stopped run the command
 -l, --list                        list all available services
 -r, --resolve <arg>               resolve the service name to an init script
 -Z, --dry-run                     dry run (show what would happen)
 -h, --help                        Display this help output
 -C, --nocolor                     Disable color output
 -V, --version                     Display software version
 -v, --verbose                     Run verbosely
 -q, --quiet                       Run quietly (repeat to suppress errors)

Usage: openrc [options] [<runlevel>]
Options: [ a:no:s:SChqVv ]
  -n, --no-stop                     do not stop any services
  -o, --override <arg>              override the next runlevel to change into
                                   when leaving single user or boot runlevels
  -s, --service <arg>               runs the service specified with the rest
                                   of the arguments
  -S, --sys                         output the RC system type, if any
  -h, --help                        Display this help output
  -C, --nocolor                     Disable color output
  -V, --version                     Display software version
  -v, --verbose                     Run verbosely
  -q, --quiet                       Run quietly (repeat to suppress errors)

Reboot/Halt/Poweroff: (And their equivalent from traditional GNU/Linux systems):

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

Troubleshooting

Whenever a openRC service fails to run, to troubleshoot enable debugging option and run the command.

For example, if running the command rc-service greetd start causes greetd service to immediately crash, then alter the command to enable and view the debug:

# rc-service -d greetd restart

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=OpenRC&oldid=30229"