Alpine Linux - User contributions [en]

Infinitime

2026-04-23T16:06:31Z

WhyNotHugo: Create page (lists build dependencies)

[https://infinitime.io/ InfiniTime] is an open source firmware for the Pinetime smartwatch written in C++ and based on [https://www.freertos.org/ FreeRTOS].

All dependencies for compiling the firmware are packaged in the Alpine repositories, and can be installed via:

<pre>
apk add -t .infinitime-dev \
cmake \
gcc-arm-none-eabi \
lv_font_conv \
nrf5-sdk \
py3-cbor2 \
py3-cryptography \
py3-intelhex
</pre>

System Disk Mode

2026-04-20T16:08:53Z

WhyNotHugo: /* See also */

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This mode is suitable for use cases like [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

{{Tip|If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux.}}

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

The [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] script performs a traditional hard disk install of your running system and can be customized using [[Alpine_setup_scripts#Environment_Variables|environment variables]]. A working [[Configure_Networking#Connectivity_testing|internet access]] configured in step 1 below is mandatory to complete this installation, if '''Extended image''' is not used. The detailed steps are given below:

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# The above command detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the optional [[Alpine_setup_scripts#Environment_Variables|environment variable]] <Code>BOOTLOADER</Code> and completes the installation by transferring your running system's configuration to the hard disk.
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

* If you are using [[Bootloaders#Syslinux|ExtLinux/SysLinux]], then ensure that {{Codeline|APPEND}} line in the file {{Path|/boot/extlinux.conf}} has <code>root=UUID=<UUID ID></code> or <code>root=/dev/sdXY</code> and the same matches the root path in the {{Path|/etc/fstab}} file. Also ensure that modules has the appropriate filesystem like <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
# root=UUID=<UUID ID> can be used also in the APPEND Line.
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to Reboot the Computer.

If the fsck Command does Fix the Corruption on the Root File System but the '''Error: Mounting Root Failed''' still persists then the next step would be to ReBuild the '''initramfs''' File System with the '''mkinitfs''' Command then Reboot. You need to '''Mount the Root Partition''' and [[Chroot]] into the Mounted Root Partition before running the mkinitfs Command as shown in the [[Initramfs init|initramfs]] page.

==== Check File System Kernel Modules are Loading ====

Run the below command to output the File System Kernel modules, where the file system can be one among the following: '''ext2''', '''ext3''', '''ext4''', '''btrfs''', '''xfs''', '''fat''':

{{Cmd|<nowiki># lsmod | grep <File System></nowiki>}}

An example output is given below for the above command, with necessary abbreviations explained:

<Pre>
alpinepc:~# lsmod | grep ext4

ext4 1155072 2
crc16 12288 1 ext4
mbcache 16384 1 ext4
jbd2 200704 1 ext4
</Pre>
EXT4 = [[Filesystems|File System]] 
CRC16 = EXT4 Compression Support 
MBCACHE = MetaData Cache 
JBD2 = Journaling 

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]
* [[Data Disk Mode]]
* [[Diskless Mode]]

[[Category:Installation]]

Data Disk Mode

2026-04-20T16:08:23Z

WhyNotHugo: /* See Also */ System Disk Mode

In Data Disk mode also the operating system runs from system RAM, thus it enjoys the same accelerated operation speed as [[Diskless Mode|diskless]] mode. However, swap storage and the entire {{Path|/var}} directory tree get mounted from a persistent storage device (two newly created partitions). The directory {{Path|/var}} holds e.g. all log files, mailspools, databases, etc., as well as <code>[[Alpine_local_backup|lbu]]</code> backup commits and the package cache. This mode is useful for having RAM accelerated servers with variable amounts of user-data that exceed the available RAM size. It enables the entire current system state (not just the boot state) to survive a system crash in accordance with the particular filesystem guarantees.

== Installation ==
{{Seealso|Diskless Mode}}
Following the [[Installation#Installation_Step_Details|Installation steps]] to complete the [[Installation#Base_configuration|base configuration]] completes the pre-setup of [[Diskless_Mode|"diskless"]] Alpine Linux system. In data disk mode, the boot device may also remain the initial (and possibly read-only) installation media, or be copied to a partition (e.g. /dev/sdXY) with <code>[[Alpine_setup_scripts#setup-bootable|setup-bootable]]</code>. Refer [[Create_a_Bootable_Device|Creating a bootable device]] for creating a bootable medium to boot the Data Disk Mode Installation.

As per Bug: [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10474 #10474], <Code>setup-alpine</Code> script will create the data partition and mount it as /var, but '''setup-alpine's "data" disk mode can not yet configure lbu config storage settings automatically'''. The '''current workaround''', is to select "none" at the 'where to store configs' prompt (as the new data partition is not listed anyway) and configure lbu manually after <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> exits, and before rebooting:

# Identify the created data partition, e.g. <code>/dev/sd''XY''</code>, and its filesystemtype, e.g. using <code>''lsblk''</code>
# Manually edit the lbu backups location in <code>/etc/lbu/lbu.conf</code> and configure <code>LBU_MEDIA=sd''XY''</code> (according to the previous findings).
# Save the configuration on that partition for the next boot with <code>lbu commit</code>.
# If (a new) partition fails to get mounted, execute: <code>mkdir /media/''sdXY'' ; echo "/dev/sd''XY'' /media/sd''XY'' ''fstype'' noauto,rw 0 0" >> /etc/fstab</code>, and try <code>lbu commit</code> again.

== See Also ==
* [[Alpine_local_backup|Alpine Local backup Utility - ''lbu''']]
* [[Alpine_Package_Keeper#Local_Cache|Local package cache]]
* [[Manually editing a existing apkovl]]
* [[Back Up a Flash Memory Installation]]
* [[Upgrading_Alpine#Upgrading_Alpine_Linux_on_other_removable_media_(such_as_CF/USB)|Upgrading Diskless to New Alpine Linux Release]]
* [[PXE boot#Specifying an apkovl|Diskless PXE Boot]]
* [[How to make a custom ISO image with mkimage]]
* [[QEMU#Live_mode|QEMU Diskless example]]
* [[Alpine local backup#Include special files.2Ffolders to the apkovl|Include special files section]] - To include custom files outside of <code>/etc</code> in .apkovl file.
* [[System Disk Mode]]

[[Category:Diskless]]

PipeWire

2026-04-14T16:50:14Z

WhyNotHugo: /* Realtime scheduling */ The details for configuring limits apply to the PAM configuration, not the rtkit configuration.

{{TOC right}}
[https://pipewire.org/ PipeWire] is a multimedia processing engine that aims to improve audio and video handling on Linux. PipeWire can act as a replacement for both [[PulseAudio]] and [[ALSA]] servers.

== Prerequisites ==

* [[XDG_RUNTIME_DIR]] must be set in the running environment.
* [[D-Bus#D-Bus_session_bus|D-Bus session bus]] must be running.
* [[Setting_up_a_new_user#Creating_a_new_user|Non-root user accounts]] require appropriate [[Setting_up_a_new_user#Groups_for_desktop_usage|groups for desktop usage]].
* WirePlumber requires [[eudev]] for ALSA device discovery.

== Installation ==

Install {{Pkg|pipewire}} and {{Pkg|wireplumber}} (session manager).

{{Cmd|# apk add pipewire wireplumber}}

=== Pulseaudio interface ===

The package {{Pkg|pipewire-pulse}} allows pulseaudio applications and [[#GUI_tools|GUI tools]] to use PipeWire as audio server in the backend.

{{Cmd|# apk add pipewire-pulse}}

=== JACK compatibility ===

Since PipeWire replaces JACK, Install {{Pkg|pipewire-jack}} package, so it provides ABI-compatible libraries for JACK applications.

{{Cmd|# apk add pipewire-jack}}

=== ALSA support ===

Install {{Pkg|pipewire-alsa}} package to provide support for ALSA applications.

{{Cmd|# apk add pipewire-alsa}}

=== GUI tools ===

* {{Pkg|pavucontrol}}: simple GUI app for controlling sound, outputs, etc. Consider using {{Pkg|pavucontrol-qt}} when using [[KDE|Plasma]].

: [[#Pulseaudio_interface|Pulseaudio interface]] is mandatory for {{Ic|pavucontrol}} to work with PipeWire.

* {{Pkg|xfce4-mixer}}: XFCE Audio mixer.

: Currently available in the [[Repositories#Testing|testing]] repository.

* {{Pkg|qpwgraph}}: graph manager dedicated to PipeWire with Qt GUI Interface.

== Launch PipeWire ==

Most [[Desktop_environments_and_Window_managers#Desktop_environments|desktop environments]] launch PipeWire automatically in Alpine Linux upon relogging (i.e. logging out and logging in) after [[#Installation|installing the above packages]]. Proceed with the section below only if PipeWire is [[#Testing|not launched]] after a relogin/reboot.

{{Note|[[#PipeWire_user_service|PipeWire user service]] is the recommended method to launch PipeWire and will replace [[#pipewire-launcher|pipewire-launcher]]. Do '''NOT''' use both methods to avoid running multiple instances of PipeWire.}}

=== PipeWire user service ===

Since [[Release_Notes_for_Alpine_3.22.0#OpenRC_User_services|Alpine 3.22]], PipeWire can be launched as a user service.

==== User service prerequisites ====

* Ensure the [[OpenRC#Prerequisites|OpenRC User service Prerequisites]] are met and [[OpenRC#Configure environment variables|environment variables are configured]].
* PipeWire will fail to start, if [[#Realtime scheduling|realtime scheduling]] is not configured.
* Issue the command {{ic|$ rc-status -Ur}} to view and verify the current user runlevel as '''gui''' and '''default''' for Wayland and Xorg respectively.

==== User service management ====

To start the {{Ic|pipewire}} user service and its {{Ic|wireplumber}} session manager:

{{Cmd|$ rc-service -U pipewire start
$ rc-service -U wireplumber start}}

To enable the {{Ic|pipewire}} and {{Ic|wireplumber}} user services in [[Wayland]], in [[Xorg]] change {{Ic|gui}} to {{Ic|default}}:

{{Cmd|$ rc-update -U add pipewire gui
$ rc-update -U add wireplumber gui}}

The above steps may be repeated for {{Ic|pipewire-pulse}} user service.

{{Note|The {{ic|pipewire-pulse}} user 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.}}

=== pipewire-launcher ===

{{Note|The {{Ic|pipewire-launcher}} script will be removed in the future to be replaced with the [[#PipeWire_user_service|PipeWire user service]].}}

Launch PipeWire by using the <code>pipewire-launcher</code> script. You'll probably get quite a few errors but just ignore them for now.

{{Cmd|$ /usr/libexec/pipewire-launcher}}

If xinitrc is used, add {{Path|/usr/libexec/pipewire-launcher}} to your {{Path|~/.xinitrc}}.

If you do not use GUI by default, add the following stanza to your shell configuration file:

{{Cmd|export $(dbus-launch)
/usr/libexec/pipewire-launcher}}

== Configuration ==

PipeWire and WirePlumber store their default configuration in {{Path|/usr/share/pipewire}} and {{Path|/usr/share/wireplumber}} respectively. If you want to edit the configuration, you need to move it to {{Path|/etc}}:

{{Cmd|<nowiki># cp -a /usr/share/pipewire /etc
# cp -a /usr/share/wireplumber /etc</nowiki>}}

=== Screen sharing on Wayland ===

Applications which don't implement native Wayland screensharing rely on [https://github.com/flatpak/xdg-desktop-portal xdg-desktop-portal] plus the correct backend for your compositor. Screen sharing is known to work on:
* GNOME with <code>xdg-desktop-portal-gtk</code>
* KDE Plasma with <code>xdg-desktop-portal-kde</code> and Firefox
* Sway with <code>xdg-desktop-portal-wlr</code> and Firefox, see [[Sway]] for details

=== Bluetooth audio ===
{{Main|Bluetooth}}
* Enable PulseAudio support as described above
* Install bluetooth service packages: <code>bluez bluez-openrc pipewire-spa-bluez</code>
* Optional: install GUI manager for bluetooth <code>blueman</code>
* Enable and start bluetooth service: <code>rc-update add bluetooth; rc-service bluetooth start</code>
* Restart PipeWire
* Use commandline program <code>bluetoothctl</code> or GUI program <code>blueman-manager</code> to scan and pair bluetooth audio devices.
* Use pavucontrol to adjust volume and manually select high definition bluetooth codecs.

=== Video ===

Video should work out-of-the-box with v4l2 devices (e.g. a lot of webcams) and [https://gstreamer.freedesktop.org/ GStreamer] applications.

=== Realtime scheduling ===

Realtime scheduling will increase certain threads priorities to assist with low latency audio processing. By default, PipeWire tries to enable realtime scheduling with the [https://docs.pipewire.org/page_module_rt.html rt module].

This can be done in one of two ways: via {{Pkg|rtkit}} or via PAM.

==== Without PAM ====

If the current session is not using [[PAM]] and the system [[D-Bus]] is available, the rt module will try to use {{Pkg|rtkit}}. Only users in the {{Ic|rtkit}} group shall be allowed to increase priorities via this mechanism.

==== Using PAM ====

Since [https://gitlab.freedesktop.org/pipewire/pipewire/-/releases/0.3.66 PipeWire 0.3.66], a [[PAM]] configuration is included. This configuration applies to sessions started via PAM for members of the {{Ic|pipewire}} group.

The default system wide settings are defined in {{Path|/etc/security/limits.d/25-pw-rlimits.conf}}. Parameters such as <var>rt.prio</var> may be adapted according to each use case as necessary. Alternatively, it can be set at [https://docs.pipewire.org/page_module_rt.html user level] within the ceiling set by the system's rlimits.

{{Cat|~/.config/pipewire/pipewire.conf.d/my-rt-args.conf|<nowiki>context.modules = [
{ name = libpipewire-module-rt
args = {
#nice.level = 20
#rt.prio = 88
}
flags = [ ifexists nofail ]
}
]</nowiki>}}

== Testing ==

Use the <code>wpctl</code> utility from {{Pkg|wireplumber}} to test the working of PipeWire:

{{Cmd|$ wpctl status}}

=== pw-cat playback ===

Test sound is working using an audio file in a format supported by [http://www.mega-nerd.com/libsndfile/ libsndfile]{{insecure url|Server refuses HTTPS connections}} (e.g. flac, opus, ogg, wav). Use <code>pw-cat</code> utility from {{Pkg|pipewire-tools}}:

{{Cmd|$ pw-cat -p test.flac
$ pw-play /usr/share/sounds/alsa/Front_Center.wav
}}

=== pw-cat recording ===

If you have a microphone test audio recording is working.

{{Cmd|$ pw-cat -r --list-targets
$ pw-cat -r recording.flac
(Speak for a while then stop it with Ctrl+c)
$ pw-cat -p recording.flac
}}

=== PulseAudio ===

Test PulseAudio clients using a media player, as most use PulseAudio.

=== JACK ===

Use <code>jack_simple_client</code> from {{Pkg|jack-simple-clients}}:

{{Cmd|$ jack_simple_client}}

You should hear a sustained beep.

== Troubleshooting ==

=== `wpctl status` shows no targets ===

First, check whether ALSA knows about your sound card using the <code>aplay</code> utility from {{pkg|alsa-utils}} package:

{{Cmd|$ aplay -l}}

If sound devices are found, the issue is likely with your PipeWire configuration. Ensure that [[eudev]] is installed, and consider double-checking the instructions above.

If no sound devices are found, your sound card may not be supported in the version of the Linux Kernel you're running. You should search online for fixes relating to your current kernel version and the codec of your sound card. You can find each of these with:

{{Cmd|$ uname -r
$ cat /proc/asound/card0/codec* {{!}} grep Codec}}

Modern devices might require {{Pkg|sof-firmware}}, which is the case if you get <code>sof firmware file is missing</code> errors in dmesg.

=== Error acquiring bus address: Cannot autolaunch D-Bus without X11 $DISPLAY ===

Check and ensure that [[D-Bus#D-Bus session bus|D-Bus session bus]] is started along with your GUI session i.e. you are in a tty.

=== Connection failure: Connection refused ===

When using [[Wayland]], ensure that [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]] is configured correctly. If this is not set, PipeWire will create a directory in your home folder instead, called {{Path|~/pulse}}, and on attempting to run {{Ic|pavucontrol}} or {{Ic|pactl}}, you will get the following error:

{{Cmd|$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused}}

If you are running Alpine 3.22+ and continue to experience this error after verifying that [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]] is correctly set, ensure that the <code>pipewire-pulse</code> [[#PipeWire_user_service|user service is running]].

=== Bluetooth connect failed: br-connection-profile-unavailable ===

Ensure {{Ic|wireplumber}}, the session manager, is running.

=== Play/Pause buttons not working on bluetooth headphones ===

Check {{Path|/var/log/messages}} for lines similar to:

{{Cat|/var/log/messages|bluetoothd[3463]: profiles/audio/avctp.c:uinput_create() Can't open input device: No such file or directory (2)
bluetoothd[3463]: profiles/audio/avctp.c:init_uinput() AVRCP: failed to init uinput for WH-1000XM5}}

Then {{Ic|bluez}} is trying to register the headphones buttons as an input devices, but <code>uinput</code> is not loaded. Try <code>modprobe uinput</code>. If this works, see [[Architecture#Loading_of_Kernel_Modules|Loading of Kernel Modules]] for instructions on how to make sure this module is loaded automatically on each startup.

=== RTKit error: org.freedesktop.DBus.Error.ServiceUnknown ===

mod.rt ../src/modules/module-rt.c:330:translate_error: RTKit error: org.freedesktop.DBus.Error.ServiceUnknown
mod.rt ../src/modules/module-rt.c:995:do_rtkit_setup: RTKit does not give us MaxRealtimePriority, using 1
mod.rt ../src/modules/module-rt.c:330:translate_error: RTKit error: org.freedesktop.DBus.Error.ServiceUnknown
mod.rt ../src/modules/module-rt.c:1000:do_rtkit_setup: RTKit does not give us MinNiceLevel, using 0
mod.rt ../src/modules/module-rt.c:330:translate_error: RTKit error: org.freedesktop.DBus.Error.ServiceUnknown
mod.rt ../src/modules/module-rt.c:1005:do_rtkit_setup: RTKit does not give us RTTimeUSecMax, using -1

Follow [[#Realtime scheduling|Realtime scheduling]] section to resolve the above error message.

== See also ==

* [[Bluetooth]]
* Official PipeWire links
** [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home Wiki]
** [https://docs.pipewire.org Documentation site]
** [https://gitlab.freedesktop.org/pipewire/pipewire Source repository]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/PipeWire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

XDG RUNTIME DIR

2026-04-09T05:15:30Z

WhyNotHugo: /* Initialising via mkrundir */ no longer has issues in containers

Various daemons and applications depend on the <code>XDG_RUNTIME_DIR</code> environment variable being set, including [[Wayland]], [[PipeWire]] and others. This variable should point to a private, ephemeral directory owned by the current user. The exact semantics and details for this variable (and the directory to which it points) are documented in the [https://specifications.freedesktop.org/basedir/latest/#variables XDG base directory specification].

A few mechanisms exist to properly initialise this variable and its corresponding directory, as described below. Only one should be used for a user's session; configuring multiple of these mechanisms will lead to misbehaviours.

== Initialising via elogind ==

When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by '''elogind'''.

== Initialising via pam_rundir ==

[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by pam_rundir.

[https://github.com/ifreund/dumb_runtime_dir dumb_runtime_dir] is functionally equivalent and has cleaner, simpler code, but is not currently packaged in Alpine.

== Initialising via mkrundir ==

[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. The path to <code>XDG_RUNTIME_DIR</code> is printed by mkrundir. A shell init script (e.g.: {{Path|~/.profile}} must include an entry as follows at the '''top''' of the file {{Cat|~/.profile|...
export XDG_RUNTIME_DIR{{=}}$(mkrundir)
...}}

See [https://whynothugo.nl/journal/2026/04/02/creating-an-xdg%20runtime%20dir/ this article] for background on its design.

== Initialising manually in /tmp ==

Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.

The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/xdg/"${UID}"-xdg-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir -p "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</nowiki>}}

== See also ==

* An overview of different approaches for [https://whynothugo.nl/journal/2026/04/02/creating-an-xdg_runtime_dir/ creating an XDG_RUNTIME_DIR]

XDG RUNTIME DIR

2026-04-09T05:14:45Z

WhyNotHugo: /* Initialising via mkrundir */

Various daemons and applications depend on the <code>XDG_RUNTIME_DIR</code> environment variable being set, including [[Wayland]], [[PipeWire]] and others. This variable should point to a private, ephemeral directory owned by the current user. The exact semantics and details for this variable (and the directory to which it points) are documented in the [https://specifications.freedesktop.org/basedir/latest/#variables XDG base directory specification].

A few mechanisms exist to properly initialise this variable and its corresponding directory, as described below. Only one should be used for a user's session; configuring multiple of these mechanisms will lead to misbehaviours.

== Initialising via elogind ==

When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by '''elogind'''.

== Initialising via pam_rundir ==

[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by pam_rundir.

[https://github.com/ifreund/dumb_runtime_dir dumb_runtime_dir] is functionally equivalent and has cleaner, simpler code, but is not currently packaged in Alpine.

== Initialising via mkrundir ==

[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. The path to <code>XDG_RUNTIME_DIR</code> is printed by mkrundir. A shell init script (e.g.: {{Path|~/.profile}} must include an entry as follows at the '''top''' of the file {{Cat|~/.profile|...
export XDG_RUNTIME_DIR{{=}}$(mkrundir)
...}}

As per [https://git.sr.ht/~whynothugo/mkrundir mkrundir] website, this might have issues inside containers, due to privilege escalation.

== Initialising manually in /tmp ==

Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.

The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/xdg/"${UID}"-xdg-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir -p "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</nowiki>}}

== See also ==

* An overview of different approaches for [https://whynothugo.nl/journal/2026/04/02/creating-an-xdg_runtime_dir/ creating an XDG_RUNTIME_DIR]

APKBUILD examples:Python

2026-04-07T21:55:22Z

WhyNotHugo:

Typical Python packages use Python-specific build systems, making their <code>build()</code> and <code>package()</code> functions different compared to an application which uses ''make''.

== Considerations ==

=== pkgname ===

Package name for a Python ''library'' must be prefixed with ''py3-''.

For an 'executable' (for example, <code>black</code>, <code>binwalk</code>), you generally don't need to prefix it.

=== arch ===

; noarch : Use for pure Python packages (i.e. without compiled code).
; all (and others) : Use for packages with native extensions (i.e. with compiled code).

=== depends ===

'''Do not''' add python3 to <tt>depends=</tt> (it's auto-detected via dynamic linking to python library).

=== source ===

Most Python packages are published in [https://pypi.python.org/pypi PyPI](the Python Package Index).
If the package has a source tarball available in PyPI (that’s true for most packages), and it contains tests (some explicitly remove them from PyPI), you should reference it in <tt>source=</tt> as:

<pre>
https://files.pythonhosted.org/packages/source/${_pyname%${_pyname#?}}/$_pyname/$_pyname-$pkgver.tar.gz
</pre>

where <tt>_pyname</tt> is the real name of the Python package.

Otherwise, use the normal upstream git tarballs.

== Examples ==

=== pep517 invocation ===

<pre>
pkgname="py3-foo"
_pyname=foo
...
depends="py3-bar py3-baz"
makedepends="py3-gpep517 py3-setuptools py3-wheel python3-dev"
checkdepends="py3-pytest"
subpackages="$pkgname-pyc"
source="$pkgname-$pkgver.tar.gz::https://github.com/xyz/foo/archive/refs/tags/v$pkgver.tar.gz"
builddir="$srcdir/$_pyname-$pkgver"
...

build() {
gpep517 build-wheel --wheel-dir .dist --output-fd 3 3>&1
}

check() {
python3 -m venv --clear --system-site-packages testenv
testenv/bin/python3 -m installer .dist/*.whl
testenv/bin/python3 -m pytest
}

package() {
python3 -m installer -d "$pkgdir" \
dist/*.whl
}
</pre>

Depending on the <code>build-backend</code> in the pyproject.toml, the package should depend on py3-setuptools, py3-flit-core, py3-poetry-core or py3-hatchling at build time. If a project specifies literally <code>flit</code> or <code>poetry</code>, patch it to use the <code>-core</code> variant.

[[Category:Development]] [[Category:Python]]

XDG RUNTIME DIR

2026-04-02T08:52:27Z

WhyNotHugo: Consolidate intro

Various daemons and applications depend on the <code>XDG_RUNTIME_DIR</code> environment variable being set, including [[Wayland]], [[PipeWire]] and others. This variable should point to a private, ephemeral directory owned by the current user. The exact semantics and details for this variable (and the directory to which it points) are documented in the [https://specifications.freedesktop.org/basedir/latest/#variables XDG base directory specification].

A few mechanisms exist to properly initialise this variable and its corresponding directory, as described below. Only one should be used for a user's session; configuring multiple of these mechanisms will lead to misbehaviours.

== Initialising via elogind ==

When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by '''elogind'''.

== Initialising via pam_rundir ==

[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by pam_rundir.

[https://github.com/ifreund/dumb_runtime_dir dumb_runtime_dir] is functionally equivalent and has cleaner, simpler code, but is not currently packaged in Alpine.

== Initialising via mkrundir ==

[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user-$UID}} by mkrundir. In your shell init script (e.g.: {{Path|~/.profile}} include an entry as follows at the '''top''' of the file {{Cat|~/.profile|...
export XDG_RUNTIME_DIR{{=}}$(mkrundir)
...}}

As per [https://git.sr.ht/~whynothugo/mkrundir mkrundir] website, this might have issues inside containers, due to privilege escalation.

== Initialising manually in /tmp ==

Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.

The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/xdg/"${UID}"-xdg-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir -p "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</nowiki>}}

== See also ==

* An overview of different approaches for [https://whynothugo.nl/journal/2026/04/02/creating-an-xdg_runtime_dir/ creating an XDG_RUNTIME_DIR]

XDG RUNTIME DIR

2026-04-02T08:51:42Z

WhyNotHugo:

Various daemons and applications depend on <code>XDG_RUNTIME_DIR</code> being set, including [[Wayland]], [[PipeWire]] and others.

The exact semantics and details for this variable (and the directory to which it points) are documented in the [https://specifications.freedesktop.org/basedir/latest/#variables XDG base directory specification].

A few mechanisms exist to properly initialise this variable and its corresponding directory, as described below. Only one should be used for a user's session; configuring multiple of these mechanisms will lead to misbehaviours.

== Initialising via elogind ==

When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by '''elogind'''.

== Initialising via pam_rundir ==

[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by pam_rundir.

[https://github.com/ifreund/dumb_runtime_dir dumb_runtime_dir] is functionally equivalent and has cleaner, simpler code, but is not currently packaged in Alpine.

== Initialising via mkrundir ==

[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user-$UID}} by mkrundir. In your shell init script (e.g.: {{Path|~/.profile}} include an entry as follows at the '''top''' of the file {{Cat|~/.profile|...
export XDG_RUNTIME_DIR{{=}}$(mkrundir)
...}}

As per [https://git.sr.ht/~whynothugo/mkrundir mkrundir] website, this might have issues inside containers, due to privilege escalation.

== Initialising manually in /tmp ==

Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.

The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/xdg/"${UID}"-xdg-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir -p "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</nowiki>}}

== See also ==

* An overview of different approaches for [https://whynothugo.nl/journal/2026/04/02/creating-an-xdg_runtime_dir/ creating an XDG_RUNTIME_DIR]

Steam

2026-03-26T07:24:22Z

WhyNotHugo: /* Troubleshooting */ recommend gamescope

This page explains how to run [https://store.steampowered.com/about/ Steam], a popular game distribution platform by Valve on Alpine Linux. Steam requires glibc to run, and thus won't run natively on Alpine Linux. The simplest approach is to run it as [[Flatpak]]. Other workarounds involve using a virtual machine, a chroot or a container. It is theoretically possible to run the windows version of Steam using {{Pkg|wine}}.

== Installation via Flatpak ==

# Follow the [[Flatpak#Installing_Flatpak|Flatpak]] wiki page and ensure that [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.
# Install the Steam flatpak package from Flathub.{{Cmd|$ flatpak --user install com.valvesoftware.Steam}}
# After installation Steam can be started either using its .desktop file or from the command line: {{Cmd|$ flatpak run com.valvesoftware.Steam}}

== Installation via Rootfs ==

The [https://git.sr.ht/~whynothugo/steam-container steam-container] project provides a Makefile to provision a rootfs with Arch Linux and runs Steam in a [[Bubblewrap]] container.

== Troubleshooting ==

=== My controllers aren't detected ===

By default regular desktop users don't have permission to interact with controllers' device nodes. The exact solution varies depending on whether udev, logind or mdevd are being used:

==== With udev and logind ====

On systems with [[udev]] and [[Elogind]], the rules from the official Steam package address this. They are available as an Alpine package.

# apk add {{pkg|steam-devices|arch=x86_64}}

These udev rules rely on the <code>TAG+="uaccess"</code>, and will not work without [[Elogind]].

==== With udev without logind ====

On systems with [[udev]] and without logind, the above rules can be used as reference, modifying them to change device ownership to a user or group of your choosing (typically, plugdev).

==== With mdevd ====

With mdevd, you'll need to write your own rules. Be sure that they precede te generic input rule, since the first match wins. The following example sets changes group ownership for a "Nintendo Switch Pro Controller" to the "plugdev" group, and sets permissions so that any member of the group may access the device:

# Nintendo Switch Pro Controller (must precede generic input rule)
DEVPATH=/devices/virtual/misc/uhid/0005:057E:2009\.[0-9A-F]{4}/input/input[0-9]+;.* root:plugdev 660

=== SteamVR won't launch ===

Out of the box SteamVR might not be able to launch and give you various errors. Steam tries to fix this itself by setting the right capabilities on the SteamVR binary, but this doesn't work in the Flatpak. Instead we'll have do it manually.

# setcap CAP_SYS_NICE+ep ~/.var/app/com.valvesoftware.Steam/data/Steam/steamapps/common/SteamVR/bin/linux64/vrcompositor-launcher

Then restart Steam.

There is an issue for this [https://github.com/flathub/com.valvesoftware.Steam/issues/636#issuecomment-779763326 on the Flathub repository].

=== Steam - Error: OpenGL GLX extension not supported by display ===

Add the Mesa gallium driver and reboot your system.

# apk add {{pkg|mesa-dri-gallium|arch=x86_64}}

=== eventfd: Too many open files ===

Due to a low amount of allowed open file descriptors, Proton games may crash shortly after launching. This can be worked around by disabling esync but many games will perform measurably worse without it. Instead, user limits should be increased. In order to do this, you will need [[PAM]] and a PAM enabled login.

Add the following to <code>/etc/security/limits.conf</code>:
@users hard nofile 524288

{{Note|Although you should already belong to the users group, you can run <code>groups</code> to check.}}

Reboot and run <code>ulimit -Hn</code> to verify the new limits are applied.

=== dbus-launch: no such file or directory ===

Set up [[D-Bus|dbus]] for your session.

=== Steam games launched via Proton crash before creating a window ===

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.

As your last resort, you can try installing [https://github.com/GloriousEggroll/proton-ge-custom proton-ge-custom], but please note that in order for this to be even detected by Steam, you will need to install Steam via Nix due to high level of isolation that Flatpaks utilize. This can however come at the expense of your [https://tosdr.org/en/service/180 privacy].

=== Steam spams dmesg with x86/split lock detection entries ===

Add the below line to {{path|/etc/sysctl.conf}}:
kernel.split_lock_mitigate = 0

=== Steam hangs on start with a steamwebhelper popup ===

If this happens and {{path|~/.var/app/com.valvesoftware.Steam/.local/share/Steam/logs/steamwebhelper.log}} says that you are missing X server or <var>DISPLAY</var>, it means your <var>DISPLAY</var> is not present in the activation environment. For more information please see https://github.com/ValveSoftware/steam-for-linux/issues/10554

'''[[Sway]]''': Go into your sway config file and ensure that <var>DISPLAY</var> appears in the {{ic|dbus-update-activation environment}} line, as well as the [https://github.com/swaywm/sway/wiki#systemd-and-dbus-activation-environments others stated here], then restart:
<pre>exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP=sway SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME</pre>
For more information about this line, please see the [[Sway|Alpine Linux wiki entry]] on Sway

'''Hyprland''': Add an exec-once to the configuration file at {{path|~/.config/hypr/hyprland}} to set <var>DISPLAY</var>. Similarly to Sway you may already have a line that sets other variables. If so, add <var>DISPLAY</var> to the line. The line should look similar to this:

<pre>exec-once = dbus-update-activation-environment DISPLAY</pre>

=== Game look blurry ===

When using factional scaling, consider using [[gamescope]] to mediate sizes between the compositor and games, so that games render at a native resolution and are not scaled by the compositor:

gamescope -W 3440 -H 1440 -e flatpak run com.valvesoftware.Steam

Replace 3440 and 1440 with your monitor's native resolution.

== See Also ==
* [[Gaming on Alpine|Gaming on Alpine Linux]]
* [[Flatpak]]
* [https://github.com/ValveSoftware/gamescope Gamescope] - SteamOS session compositing window manager, available on Alpine Linux as {{Pkg|gamescope}}
* [https://wiki.postmarketos.org/wiki/Steam Steam on postmarketOS]

[[category:Gaming]]

Steam

2026-03-26T07:20:43Z

WhyNotHugo: /* Troubleshooting */ controllers: cover other usage scenarios

This page explains how to run [https://store.steampowered.com/about/ Steam], a popular game distribution platform by Valve on Alpine Linux. Steam requires glibc to run, and thus won't run natively on Alpine Linux. The simplest approach is to run it as [[Flatpak]]. Other workarounds involve using a virtual machine, a chroot or a container. It is theoretically possible to run the windows version of Steam using {{Pkg|wine}}.

== Installation via Flatpak ==

# Follow the [[Flatpak#Installing_Flatpak|Flatpak]] wiki page and ensure that [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.
# Install the Steam flatpak package from Flathub.{{Cmd|$ flatpak --user install com.valvesoftware.Steam}}
# After installation Steam can be started either using its .desktop file or from the command line: {{Cmd|$ flatpak run com.valvesoftware.Steam}}

== Installation via Rootfs ==

The [https://git.sr.ht/~whynothugo/steam-container steam-container] project provides a Makefile to provision a rootfs with Arch Linux and runs Steam in a [[Bubblewrap]] container.

== Troubleshooting ==

=== My controllers aren't detected ===

By default regular desktop users don't have permission to interact with controllers' device nodes. The exact solution varies depending on whether udev, logind or mdevd are being used:

==== With udev and logind ====

On systems with [[udev]] and [[Elogind]], the rules from the official Steam package address this. They are available as an Alpine package.

# apk add {{pkg|steam-devices|arch=x86_64}}

These udev rules rely on the <code>TAG+="uaccess"</code>, and will not work without [[Elogind]].

==== With udev without logind ====

On systems with [[udev]] and without logind, the above rules can be used as reference, modifying them to change device ownership to a user or group of your choosing (typically, plugdev).

==== With mdevd ====

With mdevd, you'll need to write your own rules. Be sure that they precede te generic input rule, since the first match wins. The following example sets changes group ownership for a "Nintendo Switch Pro Controller" to the "plugdev" group, and sets permissions so that any member of the group may access the device:

# Nintendo Switch Pro Controller (must precede generic input rule)
DEVPATH=/devices/virtual/misc/uhid/0005:057E:2009\.[0-9A-F]{4}/input/input[0-9]+;.* root:plugdev 660

=== SteamVR won't launch ===

Out of the box SteamVR might not be able to launch and give you various errors. Steam tries to fix this itself by setting the right capabilities on the SteamVR binary, but this doesn't work in the Flatpak. Instead we'll have do it manually.

# setcap CAP_SYS_NICE+ep ~/.var/app/com.valvesoftware.Steam/data/Steam/steamapps/common/SteamVR/bin/linux64/vrcompositor-launcher

Then restart Steam.

There is an issue for this [https://github.com/flathub/com.valvesoftware.Steam/issues/636#issuecomment-779763326 on the Flathub repository].

=== Steam - Error: OpenGL GLX extension not supported by display ===

Add the Mesa gallium driver and reboot your system.

# apk add {{pkg|mesa-dri-gallium|arch=x86_64}}

=== eventfd: Too many open files ===

Due to a low amount of allowed open file descriptors, Proton games may crash shortly after launching. This can be worked around by disabling esync but many games will perform measurably worse without it. Instead, user limits should be increased. In order to do this, you will need [[PAM]] and a PAM enabled login.

Add the following to <code>/etc/security/limits.conf</code>:
@users hard nofile 524288

{{Note|Although you should already belong to the users group, you can run <code>groups</code> to check.}}

Reboot and run <code>ulimit -Hn</code> to verify the new limits are applied.

=== dbus-launch: no such file or directory ===

Set up [[D-Bus|dbus]] for your session.

=== Steam games launched via Proton crash before creating a window ===

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.

As your last resort, you can try installing [https://github.com/GloriousEggroll/proton-ge-custom proton-ge-custom], but please note that in order for this to be even detected by Steam, you will need to install Steam via Nix due to high level of isolation that Flatpaks utilize. This can however come at the expense of your [https://tosdr.org/en/service/180 privacy].

=== Steam spams dmesg with x86/split lock detection entries ===

Add the below line to {{path|/etc/sysctl.conf}}:
kernel.split_lock_mitigate = 0

=== Steam hangs on start with a steamwebhelper popup ===

If this happens and {{path|~/.var/app/com.valvesoftware.Steam/.local/share/Steam/logs/steamwebhelper.log}} says that you are missing X server or <var>DISPLAY</var>, it means your <var>DISPLAY</var> is not present in the activation environment. For more information please see https://github.com/ValveSoftware/steam-for-linux/issues/10554

'''[[Sway]]''': Go into your sway config file and ensure that <var>DISPLAY</var> appears in the {{ic|dbus-update-activation environment}} line, as well as the [https://github.com/swaywm/sway/wiki#systemd-and-dbus-activation-environments others stated here], then restart:
<pre>exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP=sway SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME</pre>
For more information about this line, please see the [[Sway|Alpine Linux wiki entry]] on Sway

'''Hyprland''': Add an exec-once to the configuration file at {{path|~/.config/hypr/hyprland}} to set <var>DISPLAY</var>. Similarly to Sway you may already have a line that sets other variables. If so, add <var>DISPLAY</var> to the line. The line should look similar to this:

<pre>exec-once = dbus-update-activation-environment DISPLAY</pre>

== See Also ==
* [[Gaming on Alpine|Gaming on Alpine Linux]]
* [[Flatpak]]
* [https://github.com/ValveSoftware/gamescope Gamescope] - SteamOS session compositing window manager, available on Alpine Linux as {{Pkg|gamescope}}
* [https://wiki.postmarketos.org/wiki/Steam Steam on postmarketOS]

[[category:Gaming]]

Steam

2026-03-26T07:13:54Z

WhyNotHugo: Mention my steam-container script

This page explains how to run [https://store.steampowered.com/about/ Steam], a popular game distribution platform by Valve on Alpine Linux. Steam requires glibc to run, and thus won't run natively on Alpine Linux. The simplest approach is to run it as [[Flatpak]]. Other workarounds involve using a virtual machine, a chroot or a container. It is theoretically possible to run the windows version of Steam using {{Pkg|wine}}.

== Installation via Flatpak ==

# Follow the [[Flatpak#Installing_Flatpak|Flatpak]] wiki page and ensure that [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.
# Install the Steam flatpak package from Flathub.{{Cmd|$ flatpak --user install com.valvesoftware.Steam}}
# After installation Steam can be started either using its .desktop file or from the command line: {{Cmd|$ flatpak run com.valvesoftware.Steam}}

== Installation via Rootfs ==

The [https://git.sr.ht/~whynothugo/steam-container steam-container] project provides a Makefile to provision a rootfs with Arch Linux and runs Steam in a [[Bubblewrap]] container.

== Troubleshooting ==

=== My controllers aren't detected ===

By default Steam doesn't have permission to read your controllers.
This can be fixed by installing an [[udev]] rule from the official Steam package, but the udev rules are also available as an Alpine package.

# apk add {{pkg|steam-devices|arch=x86_64}}

These udev rules rely on the <code>TAG+="uaccess"</code>, and are therefore only expected to work reliably when using [[Elogind]].

=== SteamVR won't launch ===

Out of the box SteamVR might not be able to launch and give you various errors. Steam tries to fix this itself by setting the right capabilities on the SteamVR binary, but this doesn't work in the Flatpak. Instead we'll have do it manually.

# setcap CAP_SYS_NICE+ep ~/.var/app/com.valvesoftware.Steam/data/Steam/steamapps/common/SteamVR/bin/linux64/vrcompositor-launcher

Then restart Steam.

There is an issue for this [https://github.com/flathub/com.valvesoftware.Steam/issues/636#issuecomment-779763326 on the Flathub repository].

=== Steam - Error: OpenGL GLX extension not supported by display ===

Add the Mesa gallium driver and reboot your system.

# apk add {{pkg|mesa-dri-gallium|arch=x86_64}}

=== eventfd: Too many open files ===

Due to a low amount of allowed open file descriptors, Proton games may crash shortly after launching. This can be worked around by disabling esync but many games will perform measurably worse without it. Instead, user limits should be increased. In order to do this, you will need [[PAM]] and a PAM enabled login.

Add the following to <code>/etc/security/limits.conf</code>:
@users hard nofile 524288

{{Note|Although you should already belong to the users group, you can run <code>groups</code> to check.}}

Reboot and run <code>ulimit -Hn</code> to verify the new limits are applied.

=== dbus-launch: no such file or directory ===

Set up [[D-Bus|dbus]] for your session.

=== Steam games launched via Proton crash before creating a window ===

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.

As your last resort, you can try installing [https://github.com/GloriousEggroll/proton-ge-custom proton-ge-custom], but please note that in order for this to be even detected by Steam, you will need to install Steam via Nix due to high level of isolation that Flatpaks utilize. This can however come at the expense of your [https://tosdr.org/en/service/180 privacy].

=== Steam spams dmesg with x86/split lock detection entries ===

Add the below line to {{path|/etc/sysctl.conf}}:
kernel.split_lock_mitigate = 0

=== Steam hangs on start with a steamwebhelper popup ===

If this happens and {{path|~/.var/app/com.valvesoftware.Steam/.local/share/Steam/logs/steamwebhelper.log}} says that you are missing X server or <var>DISPLAY</var>, it means your <var>DISPLAY</var> is not present in the activation environment. For more information please see https://github.com/ValveSoftware/steam-for-linux/issues/10554

'''[[Sway]]''': Go into your sway config file and ensure that <var>DISPLAY</var> appears in the {{ic|dbus-update-activation environment}} line, as well as the [https://github.com/swaywm/sway/wiki#systemd-and-dbus-activation-environments others stated here], then restart:
<pre>exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP=sway SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME</pre>
For more information about this line, please see the [[Sway|Alpine Linux wiki entry]] on Sway

'''Hyprland''': Add an exec-once to the configuration file at {{path|~/.config/hypr/hyprland}} to set <var>DISPLAY</var>. Similarly to Sway you may already have a line that sets other variables. If so, add <var>DISPLAY</var> to the line. The line should look similar to this:

<pre>exec-once = dbus-update-activation-environment DISPLAY</pre>

== See Also ==
* [[Gaming on Alpine|Gaming on Alpine Linux]]
* [[Flatpak]]
* [https://github.com/ValveSoftware/gamescope Gamescope] - SteamOS session compositing window manager, available on Alpine Linux as {{Pkg|gamescope}}
* [https://wiki.postmarketos.org/wiki/Steam Steam on postmarketOS]

[[category:Gaming]]

Talk:OpenRC

2026-03-24T16:37:32Z

WhyNotHugo: /* User Services -> Runlevels */

The [https://wiki.alpinelinux.org/wiki/OpenRC#Preventing_slow_services_from_delaying_boot Preventing slow services from delaying boot] passage currently uses '''chronyd''' as an example of a service that may delay boot. The passage could be improved:-

1. There is another, simpler and safer method to prevent a slow startup by '''chronyd''' that could be listed first and avoids dealing with the expressed danger of editing {{Path|/etc/inittab}} wrongly and its implied stunting of system boot.

The method has been suggested helpfully in various places:
* In the second paragraph of the file to be edited: {{Path|/etc/conf.d/chronyd}}
* https://whynothugo.nl/journal/2023/11/19/setting-up-an-alpine-linux-workstation/#chronyd-blocks-at-startup
* https://gist.github.com/c0m4r/e38d41d0e31f6adda4b4c5a88ba0a453#NTP

The method is to edit {{Path|/etc/conf.d/chronyd}} and to change the line {{Codeline|1=FAST_STARTUP=no}} to {{Codeline|1=FAST_STARTUP=yes}}.

2. Technically, '''chronyd''' is not a boot service but rather launches at the default level ({{Codeline|rc-update add chronyd default}}), so the subheading may need to be improved. There is [https://wiki.alpinelinux.org/w/index.php?search=%22%5B%5B%23Preventing+slow+services+from+delaying+boot%7C%22&title=Special%3ASearch&profile=default&fulltext=1 only one wiki page] that links to that subheading, and it is in this very same OpenRC wiki page, so it should be easy to change the subheading title, say, from ''"Preventing slow services from delaying boot"'' to ''"Preventing slow services from delaying system launch"'' or ''...system startup''. The link is mentioned twice in this wiki page, so those passages could be reviewed:
* https://wiki.alpinelinux.org/wiki/OpenRC#Stacked_runlevels
* https://wiki.alpinelinux.org/wiki/OpenRC#Configuration

Alternatively, an ''Include:Chronyd - Startup Speed Enhancement'' page could be started for inclusion here and wherever else (Any future ''Chrony'' page, for example) that would include the current inittab method and the FAST_STARTUP method.
[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 16:21, 8 August 2025 (UTC)

:Please note also that the external link about the {{Path|inittab}} method, [https://ptrcnull.me/posts/openrc-async-services/ OpenRC: Start services after login prompt], is now broken. Please consider whether perhaps the reference/attribution is suitable, as it stands. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 16:33, 8 August 2025 (UTC)
:[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]])

:: Thanks for submitting a thorough feedback. Highly appreciated. I have fixed the external links and internal links and updated section heading as per your suggestion. Service '''chrony''' was meant to be example to explain the concept. For now i've removed the word chrony. Regarding adding {{Codeline|1=FAST_STARTUP=yes}} to Chrony page, i'm quite hesitant to touch pages where i lack knowledge. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 20:02, 8 August 2025 (UTC)

The below Note may add confusion to users. Please consider rewording or removal.
{{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.}}
* The experimental is already there "User services are currently experimental ". If necessary that can be '''highlighted'''.
* I request a rewording to tell user on what he's supposed to do for pam. In the current form, the Note does not help the user on how to proceed.
- [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 11:03, 11 August 2025 (UTC)

::- Thank you for your kind attention on the wiki. I have tried to address your concern by removing the note plus the reference to it under [[OpenRC#PAM_support|PAM support]] instead of elaborating on the upstream OpenRC configuration user guide passage regarding pam.

::- On a different topic, while hoping to keep the wiki a clear user guide, do we want to simultaneously reference more in-depth examinations about user services that may be significant to developers? For example, consider a possible closing passage under ''User Services'', or under a new ''Further reading'' section, or perhaps in a briefer form under ''See also'':

:::'For a more in-depth examination of OpenRC user services, consider useful discussions regarding DE-dependent (''desktop environment'') vs DE-independent environment variables discussed in an [https://github.com/OpenRC/openrc/pull/723 upstream thread] about user services, and whether the variables ought to be passed on filtered (not in whole) or not. Other useful assessments were laid out in an excellent though now [https://wiki.gentoo.org/wiki/OpenRC/Legacy_user_services outdated Gentoo wiki page] about legacy user services that furthermore had examined {{pkg|wlsunset}} when used as a user service in Wayland; their current [https://wiki.gentoo.org/wiki/OpenRC#User_services User Services page] adds further useful and more up-to-date contributions.'

::This passage could be left here for any further discussion or added to the wiki with or without any edits, as may be seen to be suitable; I am grateful either way.

::- Perhaps one should consider moving the paragraph about allowing parallel services into the section '''Preventing slow services from delaying system startup''', as a subheading called "Parallel services". It could be placed after the introductory paragraph, "Services that take a while to start will block ...". This ''parallel services'' passage is not immediately relevant in its current location as the second paragraph about OpenRC configuration. It may simply appear there from early days in the preparation of the page.

::The suggestion that currently appears there could then be listed as a second subheading (after the "Parallel services" subheading suggested above), to be titled, say, "Async runlevel method", "Stacked runlevel method", "Inittab method" or as suitable.

::- Are we satisfied to keep the [[OpenRC#Command_usage|Command usage]] section where it is, deep down on this page, or would it be more pertinent to give command usage examples nearer to the introductory section of the wiki page, perhaps at the beginning of [OpenRC#Quickstart|Quickstart] table or immediately after it (retaining the ''Command usage'' subheading or not)? Perhaps this ''Command usage'' passage has suffered displacement from newer passages.

::This passage could additionally illustrate the most commonly used OpenRC commands at the beginning of the Quickstart section with a handful of complete {{ic|rc-service}} and {{ic|rc-update}} command line instructions; otherwise, full examples of common OpenRC clis first appear in the disproportionally long ''User Services'' section, and OpenRC instructions are otherwise introduced quickly, with no complete cli example, in the current ''QuickStart'' table:

'''Commonly-used OpenRC commands'''
Start, stop (or {ic|restart}}) a service, for example, at the boot runlevel (do not use employ the '<' nor '>'):
{{cmd|doas rc-service <serviceName> start boot}}
{{cmd|doas rc-service <serviceName> stop boot}}
Add or delete a service to/from the sequence of services that need to start automatically in future sessions at the {{ic|default}} runlevel; note that the '''default''' runlevel is assumed, so it does not need to be stated explicitly:
{{cmd|doas rc-update add <serviceName> default}}
{{cmd|doas rc-update del <serviceName>}}
List the current statuses of all services; however, do not use {{ic|doas}} nor the equivalent command as root to display the statuses of any ''user service'':
{{cmd|doas rc-status}}
List the assigned runlevels of all services; likewise, do not use {{ic|doas}} nor root to display the runlevels of user services:
{{cmd|doas rc-update}}

::Alternatively, the above ''Commonly-used OpenRC commands'' passage, with or without any edits as may be seen to be suitable, could simply not be included.

::- The current passage in [[OpenRC#Command_usage|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 [...]" could be moved into the Quickstart section instead of leaving it near the end of the page.

::- The ''Command usage'' section further contains a paragraph that is irrelevant to OpenRC: 'The busybox command equivalent for traditional GNU/Linux systems is as follows [...]'. This paragraph would be more relevant, if at all, for example:-
::* In the [[BusyBox]] page, if suitable; or
::* In the [[Comparison_with_other_distros 'Rosetta Stone']] page, perhaps under a new heading there, say, ''Userspace commands'' or ''Command line instructions'', seeing how, currently, there are only sections for ''Package management'', ''Runlevel & Initscripts'' and ''Config files''; or
::* Being culled from this page.

::Thank you. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 21:44, 11 August 2025 (UTC)
::: Thanks once again for the detailed suggestions. Hope i've done everything as suggested. Please make necessary amends, if i have missed out something. Highly appreciated. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 10:03, 12 August 2025 (UTC)

== Warning in PAM support ==

Dear [[User:WhyNotHugo]], I'm not sure about the need for warning in the PAM support section. I have been using User services with PAM support for the past few months without any issues and i have not seen any bug reports filed regarding this. btw:i'm using pamrundir and i tested dwm with the manual XDG_RUNTIME_DIR script as added there. I believe Warning should be sparingly used in Wiki, if there are unresolved/known issues. - [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 15:59, 5 September 2025 (UTC)

:[[User:Prabuanand]] This was solved shortly after your comment, thanks. Feel free to remove this talk subsection. [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 16:32, 24 March 2026 (UTC)

== User Services -> Runlevels ==

Dear [[User:WhyNotHugo]], This section probably requires some rewriting.
* I'm not sure when this sysinit runlevel is used/required "mkdir -p ${XDG_CONFIG_HOME:-~/.config}/rc/runlevels/sysinit".
* in the command openrc -U $RUNLEVEL. Instead of $RUNLEVEL, consider using <> as [[Help:Reading#Placeholder|placeholder]].
* Will adding "exec openrc -U gui" to ~/.profile support both Wayland and Xorg? Shouldn't the Compositor startup file be used for this for wayland? --[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 16:13, 5 September 2025 (UTC)
:I just now tested adding "exec openrc -U gui" to ~/.profile and i got locked out with "XDG_RUNTIME_DIR unset". Only after removing this, i could login to tty. Sway too did not start with this option. Here are my [git.sr.ht:~prabuanand/dotfiles dotfiles] for reference. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 16:55, 5 September 2025 (UTC)

::[[User:Prabuanand]]: Using '''exec openrc -U gui''' in '''~/.profile''' would be too early, DISPLAY or WAYLAND_DISPLAY would not be set, and services which rely on those would fail to start. We might want to clarify this explicitly. XDG_RUNTIME_DIR needs to be set before any service that relies on it (including the compositor) [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 16:37, 24 March 2026 (UTC)

::Dear [[User:WhyNotHugo]], Thank you for your excellent contributions to Linux, and to Alpine Linux in particular. I support [[User:Prabuanand|Prabuanand]]'s excellent and extensive impressions/observations above however, including those further above in the 'Warning in PAM support' discussion. I would be grateful for your input about them.

::Additionally, I suspect that two further points of guidance in your edits warrant review or elaboration on the wiki page:-
::*Your claim that '''sysinit''' is the default level; please elaborate why '''default''' would not be the default runlevel here, for my better understanding and for the sake of newcomers to Alpine Linux's wiki.
::*Note also that your instruction did not revert the runlevel back to '''sysinit''' on my system, even with the user ('''-U ''') switch: {{Cmd|$ openrc -U}}
::*Your edit proposing a command to revert to the sysinit runlevel appears to run contrary to the guidance [[OpenRC#Runlevels|currently in the wiki]], that ''"sysinit always runs when the host first starts and should not be run again."''
::Thanks again for your help addressing our concerns. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 17:43, 12 September 2025 (UTC)

:::'''sysinit''' is used by default when you don't explicitly specify another runlevel. My statement describes the behaviour of OpenRC itself, it's not my decision. I've talked to navi about it, and it seems to not be intentional, but it's still the current behaviour. [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 16:37, 24 March 2026 (UTC)

Dear [[User:StruanR]],
I am grateful for your improvements of the wiki, kindly continue them! Please note that certain edits, however, changing a root prompt to a user prompt, were in various cases inaccurate, and I have reverted those. Perhaps the wiki could be made clearer that to modify ''system'' services or runlevels, one generally requires a root prompt or doas/sudo; to display/check those, a user prompt may suffice. Note, on the other hand, that to modify ''user'' services (using the '''-U''' switch), a root prompt or doas/sudo would not generally be used. I hope this helps.
Your other edits were helpful, thank you!
I took the chance to amend some previous passages made by other helpful contributors while I was at it. Please continue helping out with the wiki! [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 17:43, 12 September 2025 (UTC)

:: +1, we should have a dedicated page for OpenRC User services. [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 16:37, 24 March 2026 (UTC)

Talk:OpenRC

2026-03-24T16:32:16Z

WhyNotHugo: /* Warning in PAM support */

The [https://wiki.alpinelinux.org/wiki/OpenRC#Preventing_slow_services_from_delaying_boot Preventing slow services from delaying boot] passage currently uses '''chronyd''' as an example of a service that may delay boot. The passage could be improved:-

1. There is another, simpler and safer method to prevent a slow startup by '''chronyd''' that could be listed first and avoids dealing with the expressed danger of editing {{Path|/etc/inittab}} wrongly and its implied stunting of system boot.

The method has been suggested helpfully in various places:
* In the second paragraph of the file to be edited: {{Path|/etc/conf.d/chronyd}}
* https://whynothugo.nl/journal/2023/11/19/setting-up-an-alpine-linux-workstation/#chronyd-blocks-at-startup
* https://gist.github.com/c0m4r/e38d41d0e31f6adda4b4c5a88ba0a453#NTP

The method is to edit {{Path|/etc/conf.d/chronyd}} and to change the line {{Codeline|1=FAST_STARTUP=no}} to {{Codeline|1=FAST_STARTUP=yes}}.

2. Technically, '''chronyd''' is not a boot service but rather launches at the default level ({{Codeline|rc-update add chronyd default}}), so the subheading may need to be improved. There is [https://wiki.alpinelinux.org/w/index.php?search=%22%5B%5B%23Preventing+slow+services+from+delaying+boot%7C%22&title=Special%3ASearch&profile=default&fulltext=1 only one wiki page] that links to that subheading, and it is in this very same OpenRC wiki page, so it should be easy to change the subheading title, say, from ''"Preventing slow services from delaying boot"'' to ''"Preventing slow services from delaying system launch"'' or ''...system startup''. The link is mentioned twice in this wiki page, so those passages could be reviewed:
* https://wiki.alpinelinux.org/wiki/OpenRC#Stacked_runlevels
* https://wiki.alpinelinux.org/wiki/OpenRC#Configuration

Alternatively, an ''Include:Chronyd - Startup Speed Enhancement'' page could be started for inclusion here and wherever else (Any future ''Chrony'' page, for example) that would include the current inittab method and the FAST_STARTUP method.
[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 16:21, 8 August 2025 (UTC)

:Please note also that the external link about the {{Path|inittab}} method, [https://ptrcnull.me/posts/openrc-async-services/ OpenRC: Start services after login prompt], is now broken. Please consider whether perhaps the reference/attribution is suitable, as it stands. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 16:33, 8 August 2025 (UTC)
:[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]])

:: Thanks for submitting a thorough feedback. Highly appreciated. I have fixed the external links and internal links and updated section heading as per your suggestion. Service '''chrony''' was meant to be example to explain the concept. For now i've removed the word chrony. Regarding adding {{Codeline|1=FAST_STARTUP=yes}} to Chrony page, i'm quite hesitant to touch pages where i lack knowledge. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 20:02, 8 August 2025 (UTC)

The below Note may add confusion to users. Please consider rewording or removal.
{{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.}}
* The experimental is already there "User services are currently experimental ". If necessary that can be '''highlighted'''.
* I request a rewording to tell user on what he's supposed to do for pam. In the current form, the Note does not help the user on how to proceed.
- [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 11:03, 11 August 2025 (UTC)

::- Thank you for your kind attention on the wiki. I have tried to address your concern by removing the note plus the reference to it under [[OpenRC#PAM_support|PAM support]] instead of elaborating on the upstream OpenRC configuration user guide passage regarding pam.

::- On a different topic, while hoping to keep the wiki a clear user guide, do we want to simultaneously reference more in-depth examinations about user services that may be significant to developers? For example, consider a possible closing passage under ''User Services'', or under a new ''Further reading'' section, or perhaps in a briefer form under ''See also'':

:::'For a more in-depth examination of OpenRC user services, consider useful discussions regarding DE-dependent (''desktop environment'') vs DE-independent environment variables discussed in an [https://github.com/OpenRC/openrc/pull/723 upstream thread] about user services, and whether the variables ought to be passed on filtered (not in whole) or not. Other useful assessments were laid out in an excellent though now [https://wiki.gentoo.org/wiki/OpenRC/Legacy_user_services outdated Gentoo wiki page] about legacy user services that furthermore had examined {{pkg|wlsunset}} when used as a user service in Wayland; their current [https://wiki.gentoo.org/wiki/OpenRC#User_services User Services page] adds further useful and more up-to-date contributions.'

::This passage could be left here for any further discussion or added to the wiki with or without any edits, as may be seen to be suitable; I am grateful either way.

::- Perhaps one should consider moving the paragraph about allowing parallel services into the section '''Preventing slow services from delaying system startup''', as a subheading called "Parallel services". It could be placed after the introductory paragraph, "Services that take a while to start will block ...". This ''parallel services'' passage is not immediately relevant in its current location as the second paragraph about OpenRC configuration. It may simply appear there from early days in the preparation of the page.

::The suggestion that currently appears there could then be listed as a second subheading (after the "Parallel services" subheading suggested above), to be titled, say, "Async runlevel method", "Stacked runlevel method", "Inittab method" or as suitable.

::- Are we satisfied to keep the [[OpenRC#Command_usage|Command usage]] section where it is, deep down on this page, or would it be more pertinent to give command usage examples nearer to the introductory section of the wiki page, perhaps at the beginning of [OpenRC#Quickstart|Quickstart] table or immediately after it (retaining the ''Command usage'' subheading or not)? Perhaps this ''Command usage'' passage has suffered displacement from newer passages.

::This passage could additionally illustrate the most commonly used OpenRC commands at the beginning of the Quickstart section with a handful of complete {{ic|rc-service}} and {{ic|rc-update}} command line instructions; otherwise, full examples of common OpenRC clis first appear in the disproportionally long ''User Services'' section, and OpenRC instructions are otherwise introduced quickly, with no complete cli example, in the current ''QuickStart'' table:

'''Commonly-used OpenRC commands'''
Start, stop (or {ic|restart}}) a service, for example, at the boot runlevel (do not use employ the '<' nor '>'):
{{cmd|doas rc-service <serviceName> start boot}}
{{cmd|doas rc-service <serviceName> stop boot}}
Add or delete a service to/from the sequence of services that need to start automatically in future sessions at the {{ic|default}} runlevel; note that the '''default''' runlevel is assumed, so it does not need to be stated explicitly:
{{cmd|doas rc-update add <serviceName> default}}
{{cmd|doas rc-update del <serviceName>}}
List the current statuses of all services; however, do not use {{ic|doas}} nor the equivalent command as root to display the statuses of any ''user service'':
{{cmd|doas rc-status}}
List the assigned runlevels of all services; likewise, do not use {{ic|doas}} nor root to display the runlevels of user services:
{{cmd|doas rc-update}}

::Alternatively, the above ''Commonly-used OpenRC commands'' passage, with or without any edits as may be seen to be suitable, could simply not be included.

::- The current passage in [[OpenRC#Command_usage|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 [...]" could be moved into the Quickstart section instead of leaving it near the end of the page.

::- The ''Command usage'' section further contains a paragraph that is irrelevant to OpenRC: 'The busybox command equivalent for traditional GNU/Linux systems is as follows [...]'. This paragraph would be more relevant, if at all, for example:-
::* In the [[BusyBox]] page, if suitable; or
::* In the [[Comparison_with_other_distros 'Rosetta Stone']] page, perhaps under a new heading there, say, ''Userspace commands'' or ''Command line instructions'', seeing how, currently, there are only sections for ''Package management'', ''Runlevel & Initscripts'' and ''Config files''; or
::* Being culled from this page.

::Thank you. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 21:44, 11 August 2025 (UTC)
::: Thanks once again for the detailed suggestions. Hope i've done everything as suggested. Please make necessary amends, if i have missed out something. Highly appreciated. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 10:03, 12 August 2025 (UTC)

== Warning in PAM support ==

Dear [[User:WhyNotHugo]], I'm not sure about the need for warning in the PAM support section. I have been using User services with PAM support for the past few months without any issues and i have not seen any bug reports filed regarding this. btw:i'm using pamrundir and i tested dwm with the manual XDG_RUNTIME_DIR script as added there. I believe Warning should be sparingly used in Wiki, if there are unresolved/known issues. - [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 15:59, 5 September 2025 (UTC)

:[[User:Prabuanand]] This was solved shortly after your comment, thanks. Feel free to remove this talk subsection. [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 16:32, 24 March 2026 (UTC)

== User Services -> Runlevels ==

Dear [[User:WhyNotHugo]], This section probably requires some rewriting.
* I'm not sure when this sysinit runlevel is used/required "mkdir -p ${XDG_CONFIG_HOME:-~/.config}/rc/runlevels/sysinit".
* in the command openrc -U $RUNLEVEL. Instead of $RUNLEVEL, consider using <> as [[Help:Reading#Placeholder|placeholder]].
* Will adding "exec openrc -U gui" to ~/.profile support both Wayland and Xorg? Shouldn't the Compositor startup file be used for this for wayland? --[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 16:13, 5 September 2025 (UTC)
:I just now tested adding "exec openrc -U gui" to ~/.profile and i got locked out with "XDG_RUNTIME_DIR unset". Only after removing this, i could login to tty. Sway too did not start with this option. Here are my [git.sr.ht:~prabuanand/dotfiles dotfiles] for reference. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 16:55, 5 September 2025 (UTC)

::Dear [[User:WhyNotHugo]], Thank you for your excellent contributions to Linux, and to Alpine Linux in particular. I support [[User:Prabuanand|Prabuanand]]'s excellent and extensive impressions/observations above however, including those further above in the 'Warning in PAM support' discussion. I would be grateful for your input about them.

::Additionally, I suspect that two further points of guidance in your edits warrant review or elaboration on the wiki page:-
::*Your claim that '''sysinit''' is the default level; please elaborate why '''default''' would not be the default runlevel here, for my better understanding and for the sake of newcomers to Alpine Linux's wiki.
::*Note also that your instruction did not revert the runlevel back to '''sysinit''' on my system, even with the user ('''-U ''') switch: {{Cmd|$ openrc -U}}
::*Your edit proposing a command to revert to the sysinit runlevel appears to run contrary to the guidance [[OpenRC#Runlevels|currently in the wiki]], that ''"sysinit always runs when the host first starts and should not be run again."''
::Thanks again for your help addressing our concerns. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 17:43, 12 September 2025 (UTC)

Dear [[User:StruanR]],
I am grateful for your improvements of the wiki, kindly continue them! Please note that certain edits, however, changing a root prompt to a user prompt, were in various cases inaccurate, and I have reverted those. Perhaps the wiki could be made clearer that to modify ''system'' services or runlevels, one generally requires a root prompt or doas/sudo; to display/check those, a user prompt may suffice. Note, on the other hand, that to modify ''user'' services (using the '''-U''' switch), a root prompt or doas/sudo would not generally be used. I hope this helps.
Your other edits were helpful, thank you!
I took the chance to amend some previous passages made by other helpful contributors while I was at it. Please continue helping out with the wiki! [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 17:43, 12 September 2025 (UTC)

Sway

2026-03-01T01:30:48Z

WhyNotHugo: /* Setup-desktop */

Sway

2026-02-11T20:34:02Z

WhyNotHugo: /* Prerequisites */ eudev is not required for any of sway's functionality

Wayland

2026-02-11T20:33:11Z

WhyNotHugo: /* error: XDG_RUNTIME_DIR is invalid or not set in the environment */ Update link to XDG_RUNTIME_DIR

[https://en.wikipedia.org/wiki/Wayland%20(protocol) Wayland] is a new display protocol that aims to replace [[Xorg|X11]]. Wayland requires a [[Seat manager|seat manager]] to work.

The {{ic|setup-wayland-base}} script installs and enables [[elogind]] as [[Seat manager|seat manager]] besides enabling [[Repositories#Community|community repository]] and [[eudev]].

== Compositors ==

Display servers that implement the Wayland display server protocol are also called Wayland compositors because they additionally perform the task of a compositing window manager.

Multiple compositor implementations exist, including [[Sway]], [https://en.wikipedia.org/wiki/Mutter%20(software) Mutter] ([[GNOME]]'s compositor) and [https://en.wikipedia.org/wiki/KWin Kwin] ([[KDE]]'s compositor). The following [[:Category:Compositor|compositors]] are available in Alpine Linux.

== XWayland ==

XWayland is an X server that can be instructed to run under Wayland so as to enable certain native X11 applications that have not been fully upgraded for Wayland. However, XWayland is a compatibility layer that is still not sufficiently effective to run native X11 graphical applications that still require running as root without advanced configuration, such as '''gparted''', as XWayland does not have root permissions as per Wayland protocols and for the sake of enhanced security.

Although the X11 protocol design seeks to include flexibility and network transparency, consider that the use of XWayland reintroduces certain [https://biggo.com/news/202511040138_X11-Wayland-Security-Debate X11 design vulnerabilities] into a Wayland session that was originally designed to avoid them, potentially including ''keylogging'' (capturing keystrokes)/taking screenshots/moving/resizing of other windows, although patches are applied where possible.

{{Pkg|xwayland}} is typically bundled with compositors. To check performance without XWayland, attempt to disable it on the compositor first (this can be achieved, for example, in [[Sway]], by adding the line {{ic|xwayland disable}}, say, near the top of the {{Path|~/.config/sway/config}} file). If performance for your packages appears satisfactory, the package could be attempted to be removed in various compositors, including '''Sway''', but it is a dependency on others, such as '''Labwc''', '''river-classic''', '''Cagebreak'''; ensure that '''apk''' does not indicate that it is a dependency to a given package when removing it:
{{Cmd|$ doas apk del xwayland}}

== Wayback ==
{{Main|Wayback}}

Wayback is another X11 compatibility layer, but unlike XWayland, it enables hosting a full X11 desktop environment on Wayland by enabling XWayland to run in rootful mode (future plans include enabling Wayback rootless mode). This enables [[Xfce]] and [[MATE]] to run fully under Wayland. However, as of December 2025, Wayback is still in alpha quality and thus not recommended for production.

== XDG_RUNTIME_DIR ==

As per the protocol specifications, Wayland compositors require the <code>XDG_RUNTIME_DIR</code> variable to be set. When setting paths for {{ic|XDG_RUNTIME_DIR}}, at all times they should follow [https://specifications.freedesktop.org/basedir/latest/#variables '''XDG specifications'''].

{{Note|<code>XDG_RUNTIME_DIR</code> MUST be initialised before the Wayland compositor and the D-Bus session instances are started.}}

For techniques on properly initialising this variable, see [[XDG_RUNTIME_DIR]].

== Troubleshooting ==

=== error: XDG_RUNTIME_DIR is invalid or not set in the environment ===

The above error message appears when starting services/applications that require the environment variable [[XDG_RUNTIME_DIR]] to be set. Fix it using one of the above methods before proceeding.

== See also ==

* [[Kodi]]
* [https://wiki.archlinux.org/title/Wayland Wayland - Arch Wiki]
* [https://wiki.gentoo.org/wiki/Wayland Wayland - Gentoo Wiki]
* [https://en.wikipedia.org/wiki/Wayland_(protocol) Wayland (protocol) - Wikipedia]

[[Category:Desktop]]
[[Category:Wayland]]
[[Category:Compositor]]

PipeWire

2026-02-11T20:32:40Z

WhyNotHugo: /* Prerequisites */ XDG_RUNTIME_DIR

{{TOC right}}
[https://pipewire.org/ PipeWire] is a multimedia processing engine that aims to improve audio and video handling on Linux. PipeWire can act as a replacement for both [[PulseAudio]] and [[ALSA]] servers.

== Prerequisites ==

* [[XDG_RUNTIME_DIR]] must be set in the running environment.
* [[D-Bus#D-Bus_session_bus|D-Bus session bus]] must be running.
* [[Setting_up_a_new_user#Creating_a_new_user|Non-root user accounts]] require appropriate [[Setting_up_a_new_user#Groups_for_desktop_usage|groups for desktop usage]].
* WirePlumber requires [[eudev]] for ALSA device discovery.

== Installation ==

Install {{Pkg|pipewire}} and {{Pkg|wireplumber}} (session manager).

{{Cmd|# apk add pipewire wireplumber}}

=== Pulseaudio interface ===

The package {{Pkg|pipewire-pulse}} allows pulseaudio applications and [[#GUI_tools|GUI tools]] to use PipeWire as audio server in the backend.

{{Cmd|# apk add pipewire-pulse}}

=== JACK compatibility ===

Since PipeWire replaces JACK, Install {{Pkg|pipewire-jack}} package, so it provides ABI-compatible libraries for JACK applications.

{{Cmd|# apk add pipewire-jack}}

=== ALSA support ===

Install {{Pkg|pipewire-alsa}} package to provide support for ALSA applications.

{{Cmd|# apk add pipewire-alsa}}

=== GUI tools ===

* {{Pkg|pavucontrol}}: simple GUI app for controlling sound, outputs, etc. Consider using {{Pkg|pavucontrol-qt}} when using [[KDE|Plasma]].

: [[#Pulseaudio_interface|Pulseaudio interface]] is mandatory for {{Ic|pavucontrol}} to work with PipeWire.

* {{Pkg|xfce4-mixer}}: XFCE Audio mixer.

: Currently available in the [[Repositories#Testing|testing]] repository.

* {{Pkg|qpwgraph}}: graph manager dedicated to PipeWire with Qt GUI Interface.

== Launch PipeWire ==

Most [[Desktop_environments_and_Window_managers#Desktop_environments|desktop environments]] launch PipeWire automatically in Alpine Linux upon relogging (i.e. logging out and logging in) after [[#Installation|installing the above packages]]. Proceed with the section below only if PipeWire is [[#Testing|not launched]] after a relogin/reboot.

{{Note|[[#PipeWire_user_service|PipeWire user service]] is the recommended method to launch PipeWire and will replace [[#pipewire-launcher|pipewire-launcher]]. Do '''NOT''' use both methods to avoid running multiple instances of PipeWire.}}

=== PipeWire user service ===

Since [[Release_Notes_for_Alpine_3.22.0#OpenRC_User_services|Alpine 3.22]], PipeWire can be launched as a user service.

==== User service prerequisites ====

* Ensure the [[OpenRC#Prerequisites|OpenRC User service Prerequisites]] are met and [[OpenRC#Configure environment variables|environment variables are configured]].
* PipeWire will fail to start, if [[#Realtime scheduling|realtime scheduling]] is not configured.
* Issue the command {{ic|$ rc-status -Ur}} to view and verify the current user runlevel as '''gui''' and '''default''' for Wayland and Xorg respectively.

==== User service management ====

To start the {{Ic|pipewire}} user service and its {{Ic|wireplumber}} session manager:

{{Cmd|$ rc-service -U pipewire start
$ rc-service -U wireplumber start}}

To enable the {{Ic|pipewire}} and {{Ic|wireplumber}} user services in [[Wayland]], in [[Xorg]] change {{Ic|gui}} to {{Ic|default}}:

{{Cmd|$ rc-update -U add pipewire gui
$ rc-update -U add wireplumber gui}}

The above steps may be repeated for {{Ic|pipewire-pulse}} user service.

{{Note|The {{ic|pipewire-pulse}} user 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.}}

=== pipewire-launcher ===

{{Note|The {{Ic|pipewire-launcher}} script will be removed in the future to be replaced with the [[#PipeWire_user_service|PipeWire user service]].}}

Launch PipeWire by using the <code>pipewire-launcher</code> script. You'll probably get quite a few errors but just ignore them for now.

{{Cmd|$ /usr/libexec/pipewire-launcher}}

If xinitrc is used, add {{Path|/usr/libexec/pipewire-launcher}} to your {{Path|~/.xinitrc}}.

If you do not use GUI by default, add the following stanza to your shell configuration file:

{{Cmd|export $(dbus-launch)
/usr/libexec/pipewire-launcher}}

== Configuration ==

PipeWire and WirePlumber store their default configuration in {{Path|/usr/share/pipewire}} and {{Path|/usr/share/wireplumber}} respectively. If you want to edit the configuration, you need to move it to {{Path|/etc}}:

{{Cmd|<nowiki># cp -a /usr/share/pipewire /etc
# cp -a /usr/share/wireplumber /etc</nowiki>}}

=== Screen sharing on Wayland ===

Applications which don't implement native Wayland screensharing rely on [https://github.com/flatpak/xdg-desktop-portal xdg-desktop-portal] plus the correct backend for your compositor. Screen sharing is known to work on:
* GNOME with <code>xdg-desktop-portal-gtk</code>
* KDE Plasma with <code>xdg-desktop-portal-kde</code> and Firefox
* Sway with <code>xdg-desktop-portal-wlr</code> and Firefox, see [[Sway]] for details

=== Bluetooth audio ===
{{Main|Bluetooth}}
* Enable PulseAudio support as described above
* Install bluetooth service packages: <code>bluez bluez-openrc pipewire-spa-bluez</code>
* Optional: install GUI manager for bluetooth <code>blueman</code>
* Enable and start bluetooth service: <code>rc-update add bluetooth; rc-service bluetooth start</code>
* Restart PipeWire
* Use commandline program <code>bluetoothctl</code> or GUI program <code>blueman-manager</code> to scan and pair bluetooth audio devices.
* Use pavucontrol to adjust volume and manually select high definition bluetooth codecs.

=== Video ===

Video should work out-of-the-box with v4l2 devices (e.g. a lot of webcams) and [https://gstreamer.freedesktop.org/ GStreamer] applications.

=== Realtime scheduling ===

Realtime scheduling will increase certain threads priorities to assist with low latency audio processing. By default, PipeWire tries to enable realtime scheduling with the [https://docs.pipewire.org/page_module_rt.html rt module].

==== Option1 ====

Since [https://gitlab.freedesktop.org/pipewire/pipewire/-/releases/0.3.66 PipeWire 0.3.66], when you have a [[PAM]] login session, you should add your user to the {{Ic|pipewire}} group.

==== option2 ====

If you don't have [[PAM]] but [[D-Bus]] is available, the rt module will try to use {{Pkg|rtkit}}; if this is the case, add your user to the {{Ic|rtkit}} group.

The default system wide settings are defined in {{Path|/etc/security/limits.d/25-pw-rlimits.conf}}. You may want to adjust settings for parameters like <var>rt.prio</var>, if required. Alternatively, it can be set at [https://docs.pipewire.org/page_module_rt.html user level] within the ceiling set by the system's rlimits.

{{Cat|~/.config/pipewire/pipewire.conf.d/my-rt-args.conf|<nowiki>context.modules = [
{ name = libpipewire-module-rt
args = {
#nice.level = 20
#rt.prio = 88
}
flags = [ ifexists nofail ]
}
]</nowiki>}}

== Testing ==

Use the <code>wpctl</code> utility from {{Pkg|wireplumber}} to test the working of PipeWire:

{{Cmd|$ wpctl status}}

=== pw-cat playback ===

Test sound is working using an audio file in a format supported by [http://www.mega-nerd.com/libsndfile/ libsndfile]{{insecure url|Server refuses HTTPS connections}} (e.g. flac, opus, ogg, wav). Use <code>pw-cat</code> utility from {{Pkg|pipewire-tools}}:

{{Cmd|$ pw-cat -p test.flac
$ pw-play /usr/share/sounds/alsa/Front_Center.wav
}}

=== pw-cat recording ===

If you have a microphone test audio recording is working.

{{Cmd|$ pw-cat -r --list-targets
$ pw-cat -r recording.flac
(Speak for a while then stop it with Ctrl+c)
$ pw-cat -p recording.flac
}}

=== PulseAudio ===

Test PulseAudio clients using a media player, as most use PulseAudio.

=== JACK ===

Use <code>jack_simple_client</code> from {{Pkg|jack-simple-clients}}:

{{Cmd|$ jack_simple_client}}

You should hear a sustained beep.

== Troubleshooting ==

=== `wpctl status` shows no targets ===

First, check whether ALSA knows about your sound card using the <code>aplay</code> utility from {{pkg|alsa-utils}} package:

{{Cmd|$ aplay -l}}

If sound devices are found, the issue is likely with your PipeWire configuration. Ensure that [[eudev]] is installed, and consider double-checking the instructions above.

If no sound devices are found, your sound card may not be supported in the version of the Linux Kernel you're running. You should search online for fixes relating to your current kernel version and the codec of your sound card. You can find each of these with:

{{Cmd|$ uname -r
$ cat /proc/asound/card0/codec* {{!}} grep Codec}}

Modern devices might require {{Pkg|sof-firmware}}, which is the case if you get <code>sof firmware file is missing</code> errors in dmesg.

=== Error acquiring bus address: Cannot autolaunch D-Bus without X11 $DISPLAY ===

Check and ensure that [[D-Bus#D-Bus session bus|D-Bus session bus]] is started along with your GUI session i.e. you are in a tty.

=== Connection failure: Connection refused ===

When using [[Wayland]], ensure that [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]] is configured correctly. If this is not set, PipeWire will create a directory in your home folder instead, called {{Path|~/pulse}}, and on attempting to run {{Ic|pavucontrol}} or {{Ic|pactl}}, you will get the following error:

{{Cmd|$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused}}

If you are running Alpine 3.22+ and continue to experience this error after verifying that [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]] is correctly set, ensure that the <code>pipewire-pulse</code> [[#PipeWire_user_service|user service is running]].

=== Bluetooth connect failed: br-connection-profile-unavailable ===

Ensure {{Ic|wireplumber}}, the session manager, is running.

=== Play/Pause buttons not working on bluetooth headphones ===

Check {{Path|/var/log/messages}} for lines similar to:

{{Cat|/var/log/messages|bluetoothd[3463]: profiles/audio/avctp.c:uinput_create() Can't open input device: No such file or directory (2)
bluetoothd[3463]: profiles/audio/avctp.c:init_uinput() AVRCP: failed to init uinput for WH-1000XM5}}

Then {{Ic|bluez}} is trying to register the headphones buttons as an input devices, but <code>uinput</code> is not loaded. Try <code>modprobe uinput</code>. If this works, see [[Architecture#Loading_of_Kernel_Modules|Loading of Kernel Modules]] for instructions on how to make sure this module is loaded automatically on each startup.

=== RTKit error: org.freedesktop.DBus.Error.ServiceUnknown ===

mod.rt ../src/modules/module-rt.c:330:translate_error: RTKit error: org.freedesktop.DBus.Error.ServiceUnknown
mod.rt ../src/modules/module-rt.c:995:do_rtkit_setup: RTKit does not give us MaxRealtimePriority, using 1
mod.rt ../src/modules/module-rt.c:330:translate_error: RTKit error: org.freedesktop.DBus.Error.ServiceUnknown
mod.rt ../src/modules/module-rt.c:1000:do_rtkit_setup: RTKit does not give us MinNiceLevel, using 0
mod.rt ../src/modules/module-rt.c:330:translate_error: RTKit error: org.freedesktop.DBus.Error.ServiceUnknown
mod.rt ../src/modules/module-rt.c:1005:do_rtkit_setup: RTKit does not give us RTTimeUSecMax, using -1

Follow [[#Realtime scheduling|Realtime scheduling]] section to resolve the above error message.

== See also ==

* [[Bluetooth]]
* Official PipeWire links
** [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home Wiki]
** [https://docs.pipewire.org Documentation site]
** [https://gitlab.freedesktop.org/pipewire/pipewire Source repository]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/PipeWire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

XDG RUNTIME DIR

2026-02-11T20:30:16Z

WhyNotHugo: Typos, wording

Various daemons and applications depend on <code>XDG_RUNTIME_DIR</code> being set, including [[Wayland]], [[PipeWire]] and others.

A few mechanisms exist to properly initialise this variable and its corresponding directory, as described below. Only one should be used for a user's session; configuring multiple of these mechanisms will lead to misbehaviours.

== Initialising via elogind ==

When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by '''elogind'''.

== Initialising via pam_rundir ==

[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by pam_rundir.

== Initialising via mkrundir ==

[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user-$UID}} by mkrundir. In your shell init script (e.g.: {{Path|~/.profile}} include an entry as follows at the '''top''' of the file {{Cat|~/.profile|...
export XDG_RUNTIME_DIR{{=}}$(mkrundir)
...}}

As per [https://git.sr.ht/~whynothugo/mkrundir mkrundir] website, this might have issues inside containers, due to privilege escalation.

== Initialising manually in /tmp ==

Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.

The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/xdg/"${UID}"-xdg-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir -p "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</nowiki>}}

Wayland

2026-02-11T20:29:42Z

WhyNotHugo: /* XDG_RUNTIME_DIR */ move into standalone article

[https://en.wikipedia.org/wiki/Wayland%20(protocol) Wayland] is a new display protocol that aims to replace [[Xorg|X11]]. Wayland requires a [[Seat manager|seat manager]] to work.

The {{ic|setup-wayland-base}} script installs and enables [[elogind]] as [[Seat manager|seat manager]] besides enabling [[Repositories#Community|community repository]] and [[eudev]].

== Compositors ==

Display servers that implement the Wayland display server protocol are also called Wayland compositors because they additionally perform the task of a compositing window manager.

Multiple compositor implementations exist, including [[Sway]], [https://en.wikipedia.org/wiki/Mutter%20(software) Mutter] ([[GNOME]]'s compositor) and [https://en.wikipedia.org/wiki/KWin Kwin] ([[KDE]]'s compositor). The following [[:Category:Compositor|compositors]] are available in Alpine Linux.

== XWayland ==

XWayland is an X server that can be instructed to run under Wayland so as to enable certain native X11 applications that have not been fully upgraded for Wayland. However, XWayland is a compatibility layer that is still not sufficiently effective to run native X11 graphical applications that still require running as root without advanced configuration, such as '''gparted''', as XWayland does not have root permissions as per Wayland protocols and for the sake of enhanced security.

Although the X11 protocol design seeks to include flexibility and network transparency, consider that the use of XWayland reintroduces certain [https://biggo.com/news/202511040138_X11-Wayland-Security-Debate X11 design vulnerabilities] into a Wayland session that was originally designed to avoid them, potentially including ''keylogging'' (capturing keystrokes)/taking screenshots/moving/resizing of other windows, although patches are applied where possible.

{{Pkg|xwayland}} is typically bundled with compositors. To check performance without XWayland, attempt to disable it on the compositor first (this can be achieved, for example, in [[Sway]], by adding the line {{ic|xwayland disable}}, say, near the top of the {{Path|~/.config/sway/config}} file). If performance for your packages appears satisfactory, the package could be attempted to be removed in various compositors, including '''Sway''', but it is a dependency on others, such as '''Labwc''', '''river-classic''', '''Cagebreak'''; ensure that '''apk''' does not indicate that it is a dependency to a given package when removing it:
{{Cmd|$ doas apk del xwayland}}

== Wayback ==
{{Main|Wayback}}

Wayback is another X11 compatibility layer, but unlike XWayland, it enables hosting a full X11 desktop environment on Wayland by enabling XWayland to run in rootful mode (future plans include enabling Wayback rootless mode). This enables [[Xfce]] and [[MATE]] to run fully under Wayland. However, as of December 2025, Wayback is still in alpha quality and thus not recommended for production.

== XDG_RUNTIME_DIR ==

As per the protocol specifications, Wayland compositors require the <code>XDG_RUNTIME_DIR</code> variable to be set. When setting paths for {{ic|XDG_RUNTIME_DIR}}, at all times they should follow [https://specifications.freedesktop.org/basedir/latest/#variables '''XDG specifications'''].

{{Note|<code>XDG_RUNTIME_DIR</code> MUST be initialised before the Wayland compositor and the D-Bus session instances are started.}}

For techniques on properly initialising this variable, see [[XDG_RUNTIME_DIR]].

== Troubleshooting ==

=== error: XDG_RUNTIME_DIR is invalid or not set in the environment ===

The above error message appears when starting services/applications that require the environment variable [[#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]] to be set. Fix it using one of the above methods before proceeding.

== See also ==

* [[Kodi]]
* [https://wiki.archlinux.org/title/Wayland Wayland - Arch Wiki]
* [https://wiki.gentoo.org/wiki/Wayland Wayland - Gentoo Wiki]
* [https://en.wikipedia.org/wiki/Wayland_(protocol) Wayland (protocol) - Wikipedia]

[[Category:Desktop]]
[[Category:Wayland]]
[[Category:Compositor]]

XDG RUNTIME DIR

2026-02-11T20:29:32Z

WhyNotHugo: New article (mostly moved over from Wayland).

Various daemons and applications depend on <code>XDG_RUNTIME_DIR</code> being set, including [[Wayland]], [[PipeWire] and others.

A few mechanisms exist to initialise this directory, as described below. Only one should be used for a user's session; configuring multiple of these mechanisms will lead to misbehaviours.

== Initialising via elogind ==

When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by '''elogind'''.

== Initialising via pam_rundir ==

[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by pam_rundir.

== Initialising via mkrundir ==

[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user-$UID}} by mkrundir. In your shell init script (e.g.: {{Path|~/.profile}} include an entry as follows at the '''top''' of the file {{Cat|~/.profile|...
export XDG_RUNTIME_DIR{{=}}$(mkrundir)
...}}

As per [https://git.sr.ht/~whynothugo/mkrundir mkrundir] website, this might have issues inside containers, due to privilege escalation.

== Initialising manually in /tmp ==

Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.

The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/xdg/"${UID}"-xdg-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir -p "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</nowiki>}}

Nftables

2026-01-28T00:21:29Z

WhyNotHugo: /* See also */

{{DISPLAYTITLE:nftables}}The [https://netfilter.org/projects/nftables nftables] project provides userspace tools to control the Linux nftables subsystem.

== Installation ==

To use the {{ic|nft}} command from the {{Pkg|nftables}} package, install it first:{{Cmd|# apk add {{Pkg|nftables}}}}

== Configuration ==

The default {{ic|nftables}}-shipped rules will block all incoming connections. The service that loads the rules from the {{Path|/etc/nftables.d}} folder can be enabled with: {{Cmd|# rc-service nftables start}}
Make it start on future sessions also:
{{Cmd|# rc-update add nftables boot}}
However, there may be further packaged rules shipped with additional installed packages.

=== Packaged rules ===

==== Downloading and enabling rules ====

If there are {{ic|nftables}} rules elsewhere, in the {{Path|/usr/share/nftables.avail}} folder, then they must be enabled: server software packages that are accompanied by an <code>-nftrules</code> package, for example, include the typical default rules to expose the server, but the rules are only downloaded and must then be enabled e.g. the {{pkg|openssh-nftrules}} package will only download rules to open the default port(s) used by {{pkg|openssh}}.

{{Tip|On Alpine Linux Edge and from v3.23 onwards, all <code>-nftrules</code> that are available for your current installation, as well as for any future package to be installed, can be ''downloaded'' by installing {{Pkg|nftables-rulesets}} from the main repo:
{{Cmd|# apk add nftables-rulesets}}
}}
These rules are '''''not''''' active upon package installation: they are only downloaded into that {{Path|/usr/share/nftables.avail/}} directory. The user can then enable them, either by:
* symlinking them individually to {{Path|/etc/nftables.d/}}. For example, if there is the rule {{Path|/usr/share/nftables.avail/sshd.nft}}, then issue the command below:{{Cmd|# ln -s /usr/share/nftables.avail/sshd.nft /etc/nftables.d/sshd.nft}} or by
* adding the configuration line <code>include "/usr/share/nftables.avail/*.nft"</code> into {{Path|/etc/nftables.nft}}.

==== Reloading rules ====

The new ruleset can then be applied by simply ''reloading'' the service, or by rebooting. Reloading preserves the connections (the connection-tracking ''"conntrack"'' state), so it is preferable to ''restarting'' the service:
{{Cmd|# rc-service nftables reload}}
or, alternatively, load the new ruleset with:
{{Cmd|# nft -f /etc/nftables.nft}}
The '''nftables''' service is an init script that, when started or reloaded, runs once to load the rules and then exits. It is not a daemon, so it will not appear afterwards under {{ic|# rc-status}}.

== See also ==

* [https://wiki.nftables.org/wiki-nftables/index.php/Main_Page nftables project Wiki]
* [https://wiki.archlinux.org/title/Nftables ArchWiki - nftables]
* [[Uncomplicated Firewall]] - Firewall program with higher level abstractions
* [[Tutorials_and_Howtos#Firewall|Tutorials and Howtos - Firewall]]
* [[Configure a Wireguard interface (wg)]]

[[Category:Firewall]]

Configure a Wireguard interface (wg)

2026-01-28T00:20:31Z

WhyNotHugo: Document how to prevent leaks from private networks.

{{TOC right}}

[https://en.wikipedia.org/wiki/WireGuard WireGuard] multiple platform vpn solution. WireGuard itself is now integrated into the linux kernel since v5.6. Only the userland configuration tools are required.

== Installation ==

The most straightforward method to configure WireGuard is to use the tool <code>wg-quick</code> available in the package {{pkg|wireguard-tools-wg-quick}}.

Install the meta package {{pkg|wireguard-tools}} to install the necessary WireGuard packages and {{pkg|iptables}} as follows: {{Cmd|# apk add wireguard-tools iptables}}

== Configuration ==

=== Create Server Keys and Interface Config ===

Create a server private and public key: {{Cmd|<nowiki># wg genkey | tee server.privatekey | wg pubkey > server.publickey</nowiki>}}

Then, we create a new config file {{Path|/etc/wireguard/wg0.conf}} using these new keys as follows:{{Cat|/etc/wireguard/wg0.conf|<nowiki>
[Interface]
Address = 192.168.2.1/24, fddd::ffff/64
ListenPort = 45340
PrivateKey = <server private key value> # the key from the previously generated privatekey file
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;iptables -A FORWARD -o %i -j ACCEPT; ip6tables -A FORWARD -i %i -j ACCEPT; ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;ip6tables -A FORWARD -o %i -j ACCEPT
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;iptables -D FORWARD -o %i -j ACCEPT; ip6tables -D FORWARD -i %i -j ACCEPT; ip6tables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;ip6tables -D FORWARD -o %i -j ACCEPT

[Peer]
PublicKey = <client public key value> # obtained from client device via wireguard connection setup process
AllowedIPs = 192.168.2.2/32, fddd::1/128</nowiki>}}

The PostUp and PostDown iptable rules forward traffic from the wg0 subnet (192.168.2.1/24) to the lan subnet on interface eth0. Refer to [https://github.com/pirate/wireguard-docs#user-content-config-reference this WireGuard documentation] for information on adding peers to the config file.

Bring up the new {{ic|wg0}} interface:{{Cmd|# wg-quick up wg0}}

To take it down, we can use <code>wg-quick down wg0</code> which will clean up the interface and remove the iptables rules.

{{Note|If running in a Docker container, you will need to run with <code>--cap-add{{=}}NET_ADMIN</code> to modify your interfaces.}}

=== Use with network interfaces ===

To enable connecting with Wireguard on boot, open your {{Path|/etc/network/interfaces}} and add this information after your auto other network interfaces as follows:{{Cat|/etc/network/interfaces|<nowiki>...
auto wg0
iface wg0 inet static
pre-up wg-quick up /etc/wireguard/wg0.conf</nowiki>}}

=== Service configuration ===

Since Alpine 3.20, {{pkg|wireguard-tools-openrc}} package provides an OpenRC initd service file.

To use this, install the package:{{Cmd|# apk add wireguard-tools-openrc }}

To use the WireGuard OpenRC script with {{ic|wg-quick.wg0}}, create a symbolic link to it with the configuration name as follows:{{Cmd|# ln -s /etc/init.d/wg-quick /etc/init.d/wg-quick.wg0}}

Add the {{ic|wg-quick.wg0}} service to the default runlevel:{{Cmd|# rc-update add wg-quick.wg0}}
To start|stop|restart the [[OpenRC]] service:{{Cmd|# rc-service wg-quick.wg0 start}}

=== Enable IP Forwarding ===

With a NAT destination rule in place on your router, you should be able connect to the wireguard instance and access the host. However, if you intend for peers to be able to access external resources (including the internet), you will need to enable ip forwarding.

Edit the file {{Path|/etc/sysctl.conf}} or a <code>.conf</code> file under {{Path|/etc/sysctl.d/}} folder add the following line as follows:{{Cat|/etc/sysctl.conf|
net.ipv4.ip_forward {{=}} 1
net.ipv6.conf.all.forwarding {{=}} 1
net.ipv6.conf.default.forwarding {{=}} 1}}

Add the sysctl service to run at boot:{{Cmd|# rc-update add sysctl}}

Then either reboot or run {{ic|# sysctl -p /etc/sysctl.conf}} to reload the settings. To ensure forwarding is turned on, run {{ic|# sysctl -a | grep ip_forward}} and ensure <Code>net.ipv4.ip_forward</code> is set to <code>1</code>.

In the file {{Path|/etc/conf.d/iptables}}, Change the setting as follows:{{Cat|/etc/conf.d/iptables|...
IPFORWARD{{=}}"yes"}}

== Running with modloop ==

If you are running [[Diskless Mode]] i.e from a RAM disk, you can't modify the modloop.

You can get around it by unpacking the modloop, mounting the unpacked modules folder, then installing WireGuard.

#!/bin/sh
apk add squashfs-tools # install squashfs tools to unpack modloop
unsquashfs -d /root/squash /lib/modloop-lts # unpack modloop to root dir
umount /.modloop # unmount existing modloop
mount /root/squash/ /.modloop/ # mount unpacked modloop
apk del wireguard-lts # uninstall previous WireGuard install
apk add wireguard-lts
apk add wireguard-tools

You can repack the squash filesystem or put this script in the /etc/local.d/ path so it runs at boot-up.

== Preventing leaks ==

When using a private network over Wireguard, it may be desirable to prevent traffic from leaking onto other networks with the same range (e.g.: a Wi-Fi network using the same range).

Suppose we are using the network <code>fd00:feed:c0de::</code> over Wireguard. To prevent leaks using [[nftables]], use the following <code>/etc/nftables.d/private-network.nft</code>:

#!/usr/sbin/nft -f

table inet filter {
chain output {
type filter hook output priority 0;

# Allow traffic to fd00:feed:c0de::1 only via wg0.
ip6 daddr fd00:feed:c0de::1 oifname "wg0" accept

# Drop all other attempts to reach fd00:feed:c0de::1.
ip6 daddr fd00:feed:c0de::1 drop
}
}

== See also ==

* [https://github.com/pirate/wireguard-docs WireGuard documentation]

[[Category:Networking]]

How to get regular stuff working

2025-12-14T19:55:18Z

WhyNotHugo: /* Core utilities */ s/original/GNU

Alpine Linux is built around [[Musl]] libc and [[BusyBox]] and software packages are thinned out and split into [[#Subpackages and missing functionality|subpackages]]. This makes it small and very resource efficient. The [[BusyBox#BusyBox applets|utilities in BusyBox]] tend to only implement standard options and lack GNU-specific extensions. This page explains how to get the utilities typically found in GNU/Linux distributions.

== Core utilities ==
{{Main|GNU core utilities}}

Most of the basic file, shell and text manipulation utilities commonly grouped under [https://en.wikipedia.org/wiki/List_of_GNU_Core_Utilities_commands Core Utilities] are provided by [[BusyBox]]. To replace it with GNU {{pkg|coreutils}} package:{{Cmd|# apk add {{pkg|coreutils}}}}

== Util-linux ==

A set of approximately 100 basic Linux system utilities not included in GNU Core Utilities, such as <code>mount</code>, <code>cfdisk</code>, <code>more</code>, <code>lsblk</code> and <code>kill</code> are maintained under [https://en.wikipedia.org/wiki/Util-linux Util-linux]. The {{pkg|util-linux}} package is split into multiple subpackages, so it is possible to install only some of them individually. To have the complete {{pkg|util-linux}} package:{{Cmd|# apk add {{pkg|util-linux}}}}

The full featured file pager utility <code>less</code> can be installed from the {{pkg|less}} package.

== Search utilities ==

Standard search tools <code>xargs</code> and <code>find</code> can be installed by via the {{pkg|findutils}} package as follows:{{Cmd|# apk add {{pkg|findutils}} }}

GNU Grep is also available as the {{pkg|grep}} package.

== Shell management ==
{{Main|Shell management}}
The default shell used by Alpine Linux is the Busybox variant of the [[Shell_management#Ash_shell|ash shell]]. This is a POSIX compliant shell. All popular shells are available in Alpine Linux and the [[Shell_management#Change_default_shell|default shell can be changed]], if desired.

== Hardware management ==

Install {{pkg|pciutils}} and {{pkg|usbutils}} for identifying and configuring PCI and USB hardware using the full featured version of <code>lspci</code> and <code>lsusb</code> commands respectively. {{Cmd|# apk add {{pkg|pciutils}} {{pkg|usbutils}}}}

The packages {{pkg|hwdata-pci}} and {{pkg|hwdata-usb}} are dependencies for the above utilities and they are installed automatically. These packages can be removed once the hardware configuration has been completed.

== Disk management ==
{{Main|File management}}
Managing disks including removable disks is much easier with udisks.{{Cmd|# apk add {{pkg|udisks2}}}} To see the mounted disks:{{Cmd|# udisksctl status}}

== Network management ==
{{Main|Configure Networking}}
For network, you may want to install {{pkg|iproute2}}. {{Cmd|# apk add {{pkg|iproute2}}}}

== Subpackages and missing functionality ==

When a package is installed in Alpine Linux, no assumption is made on what features the user wants, so [[Alpine_Package_Keeper#Subpackages|subpackages]] are not installed by default. The user might get a false impression of missing functionality.

For eg: The {{pkg|networkmanager}} package for [[NetworkManager]], the standard network configuration tool has 20+ subpackages based on features. If the user installs {{pkg|networkmanager}} package or {{pkg|network-manager-applet}} only the NetworkManager utility and the applet will get installed. To manage Wifi networks or to use commands like <Code>nmcli</Code> and <Code>nmtui</Code> the user is expected to add the required subpackages {{pkg|networkmanager-wifi}}, {{pkg|networkmanager-cli}} and {{pkg|networkmanager-tui}} respectively.

In other Linux distributions when NetworkManager is installed, all the above features plus bluetooth, adsl, wwan, vpn, l2tp, ppp etc are automatically installed along with their dependencies.

== Development environment ==
{{Main|Developer_Documentation}}
Compiling in Alpine Linux may be more challenging because it uses [Musl] instead of glibc. The {{pkg|build-base}} meta package provides regular compiler stuff such as {{pkg|binutils}}, {{pkg|gcc}}, {{pkg|g++}}, {{pkg|make}} etc..

{{Cmd|# apk add {{pkg|build-base}}}}

The {{pkg|alpine-sdk}} meta package is provided to build packages for Alpine Linux. It includes {{pkg|abuild}}, {{pkg|build-base}}, and {{pkg|git}}.

{{Cmd|# apk add {{pkg|alpine-sdk}}}}

To install CMake:

{{Cmd|# apk add {{pkg|cmake}} {{pkg|extra-cmake-modules}}}}

{{pkg|ccache}} and a lot other tools are also available in Alpine Linux.

[[Category:Installation]]
[[category: System Administration]]

How to get regular stuff working

2025-12-14T19:54:35Z

WhyNotHugo: Remove baseless reference

Alpine Linux is built around [[Musl]] libc and [[BusyBox]] and software packages are thinned out and split into [[#Subpackages and missing functionality|subpackages]]. This makes it small and very resource efficient. The [[BusyBox#BusyBox applets|utilities in BusyBox]] tend to only implement standard options and lack GNU-specific extensions. This page explains how to get the utilities typically found in GNU/Linux distributions.

== Core utilities ==
{{Main|GNU core utilities}}

Most of the basic file, shell and text manipulation utilities commonly grouped under [https://en.wikipedia.org/wiki/List_of_GNU_Core_Utilities_commands Core Utilities] are provided by [[BusyBox]]. To replace it with original {{pkg|coreutils}} package:{{Cmd|# apk add {{pkg|coreutils}}}}

== Util-linux ==

A set of approximately 100 basic Linux system utilities not included in GNU Core Utilities, such as <code>mount</code>, <code>cfdisk</code>, <code>more</code>, <code>lsblk</code> and <code>kill</code> are maintained under [https://en.wikipedia.org/wiki/Util-linux Util-linux]. The {{pkg|util-linux}} package is split into multiple subpackages, so it is possible to install only some of them individually. To have the complete {{pkg|util-linux}} package:{{Cmd|# apk add {{pkg|util-linux}}}}

The full featured file pager utility <code>less</code> can be installed from the {{pkg|less}} package.

== Search utilities ==

Standard search tools <code>xargs</code> and <code>find</code> can be installed by via the {{pkg|findutils}} package as follows:{{Cmd|# apk add {{pkg|findutils}} }}

GNU Grep is also available as the {{pkg|grep}} package.

== Shell management ==
{{Main|Shell management}}
The default shell used by Alpine Linux is the Busybox variant of the [[Shell_management#Ash_shell|ash shell]]. This is a POSIX compliant shell. All popular shells are available in Alpine Linux and the [[Shell_management#Change_default_shell|default shell can be changed]], if desired.

== Hardware management ==

Install {{pkg|pciutils}} and {{pkg|usbutils}} for identifying and configuring PCI and USB hardware using the full featured version of <code>lspci</code> and <code>lsusb</code> commands respectively. {{Cmd|# apk add {{pkg|pciutils}} {{pkg|usbutils}}}}

The packages {{pkg|hwdata-pci}} and {{pkg|hwdata-usb}} are dependencies for the above utilities and they are installed automatically. These packages can be removed once the hardware configuration has been completed.

== Disk management ==
{{Main|File management}}
Managing disks including removable disks is much easier with udisks.{{Cmd|# apk add {{pkg|udisks2}}}} To see the mounted disks:{{Cmd|# udisksctl status}}

== Network management ==
{{Main|Configure Networking}}
For network, you may want to install {{pkg|iproute2}}. {{Cmd|# apk add {{pkg|iproute2}}}}

== Subpackages and missing functionality ==

When a package is installed in Alpine Linux, no assumption is made on what features the user wants, so [[Alpine_Package_Keeper#Subpackages|subpackages]] are not installed by default. The user might get a false impression of missing functionality.

For eg: The {{pkg|networkmanager}} package for [[NetworkManager]], the standard network configuration tool has 20+ subpackages based on features. If the user installs {{pkg|networkmanager}} package or {{pkg|network-manager-applet}} only the NetworkManager utility and the applet will get installed. To manage Wifi networks or to use commands like <Code>nmcli</Code> and <Code>nmtui</Code> the user is expected to add the required subpackages {{pkg|networkmanager-wifi}}, {{pkg|networkmanager-cli}} and {{pkg|networkmanager-tui}} respectively.

In other Linux distributions when NetworkManager is installed, all the above features plus bluetooth, adsl, wwan, vpn, l2tp, ppp etc are automatically installed along with their dependencies.

== Development environment ==
{{Main|Developer_Documentation}}
Compiling in Alpine Linux may be more challenging because it uses [Musl] instead of glibc. The {{pkg|build-base}} meta package provides regular compiler stuff such as {{pkg|binutils}}, {{pkg|gcc}}, {{pkg|g++}}, {{pkg|make}} etc..

{{Cmd|# apk add {{pkg|build-base}}}}

The {{pkg|alpine-sdk}} meta package is provided to build packages for Alpine Linux. It includes {{pkg|abuild}}, {{pkg|build-base}}, and {{pkg|git}}.

{{Cmd|# apk add {{pkg|alpine-sdk}}}}

To install CMake:

{{Cmd|# apk add {{pkg|cmake}} {{pkg|extra-cmake-modules}}}}

{{pkg|ccache}} and a lot other tools are also available in Alpine Linux.

[[Category:Installation]]
[[category: System Administration]]

Kodi

2025-12-13T16:39:16Z

WhyNotHugo: Wording

[https://kodi.tv/ Kodi] (formerly XBMC) is a software media centre available in the Alpine community repositories.

Kodi can run under [[Xorg]], [[Wayland]] or any other graphical environment.

= kodi-gbm =

{{Pkg|kodi-gbm}} runs without any Xorg or Wayland environment, managing hardware input/output itself. It support HDR, and is most suitable for dedicated devices or sessions.

In order for keyboard input to work, at least one of the following conditions must be met:

* {{Pkg|libudev-zero}} is installed (simplest approach).
* eudev is running (untested).

Wayland

2025-12-13T16:38:41Z

WhyNotHugo: /* See also */ Backlink to Kodi

[https://en.wikipedia.org/wiki/Wayland%20(protocol) Wayland] is a new display protocol that aims to replace [[Xorg|X11]]. Wayland requires a [[Seat manager|seat manager]] to work.

The {{ic|setup-wayland-base}} script installs and enables [[elogind]] as [[Seat manager|seat manager]] besides enabling [[Repositories#Community|community repository]] and [[eudev]].

== Compositors ==

Display servers that implement the Wayland display server protocol are also called Wayland compositors because they additionally perform the task of a compositing window manager.

Multiple compositor implementations exist, including [[Sway]], [https://en.wikipedia.org/wiki/Mutter%20(software) Mutter] ([[GNOME]]'s compositor) and [https://en.wikipedia.org/wiki/KWin Kwin] ([[KDE]]'s compositor). The following [[:Category:Compositor|compositors]] are available in Alpine Linux.

== XDG_RUNTIME_DIR ==

As per the protocol specifications, Wayland compositors require the <code>XDG_RUNTIME_DIR</code> variable to be set. When setting paths for {{ic|XDG_RUNTIME_DIR}}, at all times they should follow [https://specifications.freedesktop.org/basedir/latest/#variables '''XDG specifications'''].

{{Note|If <code>XDG_RUNTIME_DIR</code> variable is set inside startup script/file, it MUST be initialised before the Wayland compositor and the D-Bus session instances are started.}}

=== With elogind ===

When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by '''elogind'''.

=== With pam_rundir ===

[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by pam_rundir.

=== With mkrundir ===

[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user-$UID}} by mkrundir. In your shell init script (e.g.: {{Path|~/.profile}} include an entry as follows at the '''top''' of the file {{Cat|~/.profile|...
export XDG_RUNTIME_DIR{{=}}$(mkrundir)
...}}

As per [https://git.sr.ht/~whynothugo/mkrundir mkrundir] website, this might have issues inside containers, due to privilege escalation.

=== Creating and exporting XDG_RUNTIME_DIR manually ===

Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.

The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>if [ -z "$XDG_RUNTIME_DIR" ]; then
XDG_RUNTIME_DIR="/run/user/$(id -u)"

mkdir -pm 0700 "$XDG_RUNTIME_DIR"
export XDG_RUNTIME_DIR
fi
</nowiki>}}

== Troubleshooting ==

=== error: XDG_RUNTIME_DIR is invalid or not set in the environment ===

The above error message appears when starting services/applications that require the environment variable [[#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]] to be set. Fix it using one of the above methods before proceeding.

== See also ==

* [[Kodi]]
* [https://wiki.archlinux.org/title/Wayland Wayland - Arch Wiki]
* [https://wiki.gentoo.org/wiki/Wayland Wayland - Gentoo Wiki]
* [https://en.wikipedia.org/wiki/Wayland_(protocol) Wayland (protocol) - Wikipedia]

[[Category:Desktop]]
[[Category:Wayland]]
[[Category:Compositor]]

Xorg

2025-12-13T16:38:27Z

WhyNotHugo: /* See also */ Backlink to Kodi

[https://www.x.org/wiki/ Xorg] is an open source implementation of the X Window System. It used to be the de-facto standard way to launch graphical applications. [[Wayland]] is its recent alternative. [https://gitlab.freedesktop.org/wayback/wayback Wayback] is a X11 compatibility layer which allows for running full X11 desktop environments using Wayland components.

== Installation ==

Xorg can be installed automatically by running the [[Alpine_setup_scripts#setup-xorg-base|setup-xorg-base]] script as follows:{{Cmd|# setup-xorg-base}}

The above command installs the following packages {{pkg|xorg-server}}, {{pkg|xf86-input-libinput}}, {{pkg|xinit}}, {{pkg|eudev}}, {{pkg|mesa-dri-gallium}} and Sets up [[Include:Setup Device Manager|eudev]]

Install atleast one X11 based [[Desktop environments and Window managers|desktop]] before proceeding further.

== Configuration ==

You may also want per-user configuration. Create the {{Path|~/.xinitrc}} file to start the window manager with <code>startx</code> or <code>xinit</code>. If you installed {{pkg|cwm}} desktop, the {{Path|~/.xinitrc}} file should be as follows:{{Cat|~/.xinitrc|exec cwm}}

If [[D-Bus#Installation|D-Bus]] is installed and enabled along with {{pkg|cwm}} desktop, the {{Path|~/.xinitrc}} file should be as follows:{{Cat|~/.xinitrc|exec dbus-launch --exit-with-session cwm}}

Xorg sessions can be started via [[Display_manager|display manager]] or manually with command: {{Cmd|$ startx }}

== Video drivers ==

Most basic X features should work fine with just using the default [[#Kernel Modesetting|kernel video-modesetting]] drivers. For better performance or in case of errors, install legacy [[Xf86 Video]] drivers or [[Graphics driver|graphics drivers]].

== Input packages ==

You probably at least want {{pkg|xf86-input-libinput}} or {{pkg|xf86-input-evdev}}. The former is for Wayland with wrapper for Xorg and is installed by the [[#Installation|setup-xorg-base]] script. The {{pkg|xf86-input-evdev}} package is Xorg only.

For touchpad tapping support on many laptops:{{Cmd|# apk add xf86-input-synaptics}}

If the Numlock settings are not working, or getting 'setleds not found' errors: {{cmd|# apk add kbd}}

If some input device is not working at all, the available xf86-input drivers can be listed with: {{cmd|$ apk search xf86-input}}

The following legacy drivers are not packaged at least as of 2/2022:
* xf86-input-mouse
* xf86-input-keyboard

== Configure xorg-server (optional) ==

On most systems, xorg should be able to autodetect all devices. However you can still configure xorg-server by hand by launching: {{Cmd|# Xorg -configure}}

This will create a {{Path|/root/xorg.conf.new}} file. You can modify this file to fit your needs. When finished modifying and testing the above configuration file, move it to {{Path|/etc/X11/xorg.conf}} for normal usage.

== Keyboard Layout (optional) ==

If you use a keyboard layout different than "us", and you are using a window manager or desktop environment that does not support to configure the keyboard layout itself, then you need to install {{pkg|setxkbmap}} package: {{Cmd|# apk add setxkbmap}}

Then try {{Cmd|# setxkbmap <%a language layout from /usr/share/X11/xkb/rules/xorg.lst%>}}

In order to make it persistent add this section to {{Path|/etc/X11/xorg.conf}}:
{{Cmd|Section "InputClass"
Identifier "Keyboard Default"
MatchIsKeyboard "yes"
Option "XkbLayout" "<%a language layout from /usr/share/X11/xkb/rules/xorg.lst%>"
EndSection
}}

Another way to change the keymap when logging into X is to use {{Path|~/.xinitrc}}. The following example loads a British keymap, simply add this line to the beginning of the file as follows :{{Cat|~/.xinitrc|setxkbmap gb &
...}}

== See also ==

* [https://www.x.org/wiki/ Xorg Wiki]
* [[Wayland]]
* [[Kodi]]

[[category: Desktop]]

Kodi

2025-12-13T16:38:05Z

WhyNotHugo:

[https://kodi.tv/ Kodi] (formerly XBMC) is a software media centre available in the Alpine community repositories.

Kodi can run under [[Xorg]], [[Wayland]] or without a graphical environment.

= kodi-gbm =

{{Pkg|kodi-gbm}} runs without any Xorg or Wayland environment, managing hardware input/output itself. It support HDR, and is most suitable for dedicated devices or sessions.

In order for keyboard input to work, at least one of the following conditions must be met:

* {{Pkg|libudev-zero}} is installed (simplest approach).
* eudev is running (untested).

Kodi

2025-12-13T16:31:32Z

WhyNotHugo: Formatting

[https://kodi.tv/ Kodi] (formerly XBMC) is a software media centre available in the Alpine community repositories.

Kodi can run under Xorg, Wayland or without a graphical environment.

= kodi-gbm =

{{Pkg|kodi-gbm}} runs without any Xorg or Wayland environment, managing hardware input/output itself. It support HDR, and is most suitable for dedicated devices or sessions.

In order for keyboard input to work, at least one of the following conditions must be met:

* {{Pkg|libudev-zero}} is installed (simplest approach).
* eudev is running (untested).

Kodi

2025-12-13T16:31:10Z

WhyNotHugo: Initial writeup

[https://kodi.tv/ Kodi] (formerly XBMC) is a software media centre available in the Alpine community repositories.

Kodi can run under Xorg, Wayland or without a graphical environment.

# kodi-gbm

{{Pkg|kodi-gbm}} runs without any Xorg or Wayland environment, managing hardware input/output itself. It support HDR, and is most suitable for dedicated devices or sessions.

In order for keyboard input to work, at least one of the following conditions must be met:

- {{Pkg|libudev-zero}} is installed (simplest approach).
- eudev is running (untested).

Syslog

2025-12-05T23:15:54Z

WhyNotHugo: Move other distributions further down

{{TOC right}}

Syslog collects log data from multiple programs either to RAM or to a file, and handles log rotation. Alpine installs <code>syslog</code> as provided by {{pkg|busybox}} per default, but it also packages [https://pkgs.alpinelinux.org/packages?name=*syslog* other implementations], such as {{pkg|rsyslog}}, {{pkg|syslog-ng}}, [https://skarnet.org/software/s6/s6-socklog.html s6-socklog] (from {{pkg|s6}}) and [[logbookd]]. This role is typically fulfilled by <code>journald</code> on systemd-based systems.

== busybox syslog ==
=== Running syslogd ===
Depending on how you have installed Alpine, it is already running (check with <code>ps a | grep syslogd</code>). Otherwise enable it at boot and start it with the following commands:

{{cmd|<nowiki># rc-update add syslog boot
# rc-service syslog start
</nowiki>}}

=== Configuration ===
Edit {{path|/etc/conf.d/syslog}} to change the options used when running <code>syslogd</code>. All available options can be looked up with <code>syslogd --help</code>.

=== Reading logs ===
{{cmd|<nowiki># tail -f /var/log/messages
Shows all messages and follows the log
# tail -f /var/log/messages | grep ssh
Only shows SSH related messages, also follows the log
</nowiki>}}

When <code>-C</code> is enabled in the configuration:
{{cmd|<nowiki># logread -f
# logread -f | grep ssh
</nowiki>}}

== Writing logs ==
Many applications are able to write to the syslog by default (e.g. <code>sshd</code>). If you wish to write manually to it, use the <code>logger</code> program.

{{cmd|$ logger "hello world"}}

== See also ==
* [https://wiki.gentoo.org/wiki/Logging Gentoo Wiki - Logging]

[[category:System Administration]]

Install Alpine on LXC

2025-10-20T18:09:57Z

WhyNotHugo: Typo, grammar

== LXC ==

[https://en.wikipedia.org/wiki/LXC LXC] is an operating-system-level virtualization method for running multiple isolated Linux systems (containers) on a control host using a single Linux kernel.

This article contains instructions for installing Alpine Linux on LXC container. For using LXC on an Alpine host, see [[LXC]].

With LXC you can run Alpine Linux on container and start services in it using native Alpine Linux' init system (openrc).

== Preparation ==

=== LXC installation ===
You have to install "lxc" package on your host system. For example, in Arch Linux you can install it by running:
{{Cmd|# pacman -S lxc}}

=== Bridge creation ===
You also have to create network bridge on your host.

[https://wiki.archlinux.org/index.php/Network_bridge Setting up bridge in Arch Linux or Arch Linux based systems]

[https://help.ubuntu.com/community/NetworkConnectionBridge Setting up bridge in Ubuntu or Ubuntu based systems]

Here is example, how to setup bridge with netctl:

Copy sample file "bridge"
{{Cmd|# cp /etc/netctl/examples/bridge /etc/netctl/myBridge}}

Modify your bridge configuration file as needed (network interfaces: eno1 and tap0 are, of cource, according to your needs)
{{cat|/etc/netctl/myBridge|Description{{=}}"Bridge connection"
Interface{{=}}br0
Connection{{=}}bridge
BindsToInterfaces{{=}}(eno1 tap0)
IP{{=}}dhcp
}}

Stop active connection
{{Cmd|# systemctl stop dhcpcd}}

Start your bridge
{{Cmd|# netctl start myBridge}}

Perhaps you may wish to setup your system to start your bridge automatically at boot time.

== Container creation ==

To install Alpine Linux edge version run:
{{Cmd|# lxc-create --name alpine-edge -t alpine -- --release edge}}

You can also configure shared directory which will be accessible from both host and container. In this example we make host's /media/d directory available in container
{{Cmd|# mkdir /var/lib/lxc/alpine-edge/rootfs/media/d}}

Add the following lines to the container's configuration file:
{{Cat|/var/lib/lxc/alpine-edge/config|...
lxc.network.type {{=}} veth
lxc.network.flags {{=}} up
lxc.network.link {{=}} br0
lxc.mount.entry{{=}}/media/d media/d none bind 0 0
}}

Booting container:
{{cmd|# lxc-start -n alpine-edge}}

Shutting down container:
{{cmd|# lxc-stop -n alpine-edge}}

Going to Alpine Linux console:
{{cmd|# lxc-attach -n alpine-edge}}

== Container setup ==

Modify your apk/repositories configuration file. It is recommended to include "main", "testing" and "community" repositories.
{{Cat|/etc/apk/repositories|http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/testing
http://dl-cdn.alpinelinux.org/alpine/edge/community
}}

Upgrading your Alpine Linux system:
{{cmd|# apk update && apk upgrade -a}}

Starting services:
{{Cmd|# /etc/init.d/service_name start}}
or
{{Cmd|# rc-service service_name start}}

Adding services to autostart
{{Cmd|# rc-update add service_name}}

Restarting your container:
{{Cmd|reboot}}

[[Category:Virtualization]]

Install Alpine on LXC

2025-10-20T18:09:35Z

WhyNotHugo: Link to LXC

== LXC ==

[https://en.wikipedia.org/wiki/LXC LXC] is an operating-system-level virtualization method for running multiple isolated Linux systems (containers) on a control host using a single Linux kernel.

This article contains instruction to install Alpine Linux on LXC container. For using LXC on an Alpine host, see [[LXC]].

With LXC you can run Alpine Linux on container and start services in it using native Alpine Linux' init system (openrc).

== Preparation ==

=== LXC installation ===
You have to install "lxc" package on your host system. For example, in Arch Linux you can install it by running:
{{Cmd|# pacman -S lxc}}

=== Bridge creation ===
You also have to create network bridge on your host.

[https://wiki.archlinux.org/index.php/Network_bridge Setting up bridge in Arch Linux or Arch Linux based systems]

[https://help.ubuntu.com/community/NetworkConnectionBridge Setting up bridge in Ubuntu or Ubuntu based systems]

Here is example, how to setup bridge with netctl:

Copy sample file "bridge"
{{Cmd|# cp /etc/netctl/examples/bridge /etc/netctl/myBridge}}

Modify your bridge configuration file as needed (network interfaces: eno1 and tap0 are, of cource, according to your needs)
{{cat|/etc/netctl/myBridge|Description{{=}}"Bridge connection"
Interface{{=}}br0
Connection{{=}}bridge
BindsToInterfaces{{=}}(eno1 tap0)
IP{{=}}dhcp
}}

Stop active connection
{{Cmd|# systemctl stop dhcpcd}}

Start your bridge
{{Cmd|# netctl start myBridge}}

Perhaps you may wish to setup your system to start your bridge automatically at boot time.

== Container creation ==

To install Alpine Linux edge version run:
{{Cmd|# lxc-create --name alpine-edge -t alpine -- --release edge}}

You can also configure shared directory which will be accessible from both host and container. In this example we make host's /media/d directory available in container
{{Cmd|# mkdir /var/lib/lxc/alpine-edge/rootfs/media/d}}

Add the following lines to the container's configuration file:
{{Cat|/var/lib/lxc/alpine-edge/config|...
lxc.network.type {{=}} veth
lxc.network.flags {{=}} up
lxc.network.link {{=}} br0
lxc.mount.entry{{=}}/media/d media/d none bind 0 0
}}

Booting container:
{{cmd|# lxc-start -n alpine-edge}}

Shutting down container:
{{cmd|# lxc-stop -n alpine-edge}}

Going to Alpine Linux console:
{{cmd|# lxc-attach -n alpine-edge}}

== Container setup ==

Modify your apk/repositories configuration file. It is recommended to include "main", "testing" and "community" repositories.
{{Cat|/etc/apk/repositories|http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/testing
http://dl-cdn.alpinelinux.org/alpine/edge/community
}}

Upgrading your Alpine Linux system:
{{cmd|# apk update && apk upgrade -a}}

Starting services:
{{Cmd|# /etc/init.d/service_name start}}
or
{{Cmd|# rc-service service_name start}}

Adding services to autostart
{{Cmd|# rc-update add service_name}}

Restarting your container:
{{Cmd|reboot}}

[[Category:Virtualization]]

Sway

2025-10-14T22:09:00Z

WhyNotHugo: /* Screen Lock and suspend-to-RAM */ Remove elogind instructions; link to dedicated page

[https://swaywm.org Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the [[i3wm |i3 window manager]]. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

== Prerequisites ==

* Internet [[Configure_Networking#Connectivity_testing|connectivity]], unless the packages have been pre-fetched into a local cache.
* Install appropriate [[Graphics driver]] drivers for your hardware. Without graphics drivers [[#Video Driver Issues|errors]] are likely to occur.
* A [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]].
* The [[Repositories#Managing_repositories|community repositories must be enabled]].
* Set up [[eudev]].
* Wayland compositors need raw access to input and output devices, typically mediated by a [[seat manager]]. Either [[seatd]] or [[elogind]] work fine, but installing both leads to conflicts.
{{Tip|Except for the first two [[#Prerequisites|prerequisites]], all of the others are automatically handled if the desktop is [[#Setup-desktop|installed using the following setup-desktop]] script.}}

== Setup-desktop ==

The [[setup-desktop]] command automates the Sway desktop installation with [[eudev]] and [[elogind]].

{{cmd|# setup-desktop sway}}

Proceed to the [[Sway#Starting Sway|Starting Sway]] section, as no [[Display manager|display manager]] is being installed nor configured by the script that would boot into a graphical login screen.

== Manual Installation ==

The installation steps below allow you to pick and choose various components for your Sway desktop.

=== Install Fonts ===

Install [https://dejavu-fonts.github.io/ DejaVu] fonts ({{Pkg|font-dejavu}}), which have good [https://home.unicode.org/ Unicode] coverage:

{{cmd|# apk add font-dejavu}}

=== Install Sway ===

{{cmd|# apk add sway \
xwayland \ # if you need the xserver
foot \ # default terminal emulator. Modify $term in config for a different one.
wmenu \ # default Wayland native menu for choosing program and screensharing monitor
swaylock swaylockd \ # lockscreen tool
swaybg \ # display wallpaper
grim \ # screenshot tool
wl-clipboard \ # clipboard management
i3status \ # simple status bar
swayidle # idle management (DPMS) daemon
}}

For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway Sway's wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland Gentoo's wiki].

== Configuration ==

===Sway config File ===

Copy the default Sway configuration file to {{Path|~/.config/sway/config}} so that it can be customized as per each user's choices:

{{cmd|$ mkdir -p ~/.config/sway
$ cp /etc/sway/config ~/.config/sway/}}

Read through it to learn the default keybindings.
Sway's configuration is mostly backward compatible with that of [[I3wm|i3]]'s, and if you are looking for a solution for a specific issue, you could try checking whether it hasn't been provided for the i3 window manager.

====Quickstart - config File====
To set up an environment that launches applications full-sized and to {{Key|Alt}}+{{Key|Tab}} between these much as in [[Xfce|XFCE]] or in various other desktop environments, then a quick setup of the {{Path|config}} file could effect this. This proposed setup may be of benefit for both desktop/non-technical and technical use. ''Step 4'' is indicated to be sidestepped by those electing an {{Pkg|i3}}-style, tiled default layout.

A launchbar is not set up "out of the box", nor here, so this section only reviews essential ''keybindings'' (or "shortcuts"), saving first-time users from immediately requiring to digest a longer ''"cheatsheet"'' of keybindings that might include resizing, moving and swapping windows (called ''"views"''), say, from smaller tiles (called ''"containers"'') into larger tiles; these may be learned at a later stage.

The quickstart configuration of the {{Path|config}} file ''may be prepared within or without '''Sway''''' e.g. within an '''Xorg''' session or another compositor, or on another installation, before eventually copying over the finished {{Path|config}} file onto the target system – except:
* If one prefers alternative applications to those proposed initially in ''Step 6'' for assignment into specific workspaces. Any such modifications (to be executed in ''Step 7'') could be performed: (a) simply during one's first '''Sway''' session; or (b) by determining what those applications' {{ic|app_id}} / {{ic|class}} are (as detailed in ''Step 7''), possibly in another '''Wayland''' session or externally e.g. from documentation.
* One will likewise require to verify at some point whether one's chosen applications are installed on the target system; and to install those missing (last step, ''Step 12'').

'''''Step 1:'' Assign the main modifier key'''. In a text editor, open the {{Path|/home/<var>username</var>/.config/sway/config}} file that had been copied over. We will declare what would be the main modifier key for many of our keybindings: {{Key|Window}}, {{Key|Alt}} or otherwise. The {{Path|config}} file has already set the main modifier, called the {{ic|$mod}} key, to default as the {{ic|Mod4}} key, also known as the {{Key|Window}}, {{ic|Super}} or ''Logo'' key. Verify this towards the beginning of the file:

<Pre>
# Logo key. Use Mod1 for Alt.
set $mod Mod4
</Pre>

As proposed there, one could change that {{ic|$mod}} key to be the {{Key|Alt}} key a.k.a. the {{ic|Mod1}} key. To change the {{ic|$mod}} key assignment, as with any line in this file, one could edit/delete the lines or comment such line out i.e. add a hashtag ('''''#''''') at the start of any line that does not begin with a hashtag, so that such line would not be executed by '''Sway''' but would be left there for reference; and then enter the customised version of that line below it. Note that '''Sway''' [https://github.com/swaywm/sway/wiki#comments does not support] comments at the end of an executable line, following a hashtag.

According to the {{ic|man 5 sway}} page, ''XKB modifier names'' can be used to refer to modifier keys, plus certain aliases found among the following list, all of these "{{ic|codes}}" being acceptable for use throughout the configuration file:

* {{ic|Mod1}} - {{Key|Alt}} - Alternatively expressed as {{ic|Alt}};
* {{ic|Mod2}} - Although not universally mapped, here it refers to the {{Key|Num Lock}} key;
* {{ic|Mod3}} - It could be programmed, as an XKB modifier key;
* {{ic|Mod4}} - Alternatively expressed as the {{ic|Super}} key, a.k.a. the {{Key|Window}} or ''Logo'' key;
* {{ic|Mod5}} - {{Key|AltGr}};
* {{ic|Lock}} - {{Key|Caps Lock}};
* {{ic|Control}} - {{Key|Ctrl}} - Alternatively expressed as {{ic|Ctrl}}; and
* {{ic|Shift}} - {{Key|Shift}}.

It might be best not to use the {{Key|Ctrl}} key as the ''main modifier'', as it is often used in applications e.g. {{Key|Control}}+{{Key|c}} to ''copy'', {{Key|Control}}+{{Key|b}} for ''bold'', etc. Similarly when considering the {{ic|Shift}} as main modifier.

So, if one were to choose, say, the {{Key|Alt}} key as the main modifier, that {{ic|Mod4}} line could be changed to: {{ic|set $mod Alt}} or {{ic|set $mod Mod1}}. We will preserve the default, {{ic|Mod4}} ({{Key|Window}}), as the main modifier. Note that any modification will not be manifested until one chooses at any time to reload the {{Path|config}} file by hitting {{ic|$mod+Shift+c}} (cf. ''Step 10'').

'''''Step 2:'' Declare what your default terminal and menu launcher will be'''. In this {{Path|config}} file, these are currently configured to be the {{Pkg|foot}} terminal; and {{Pkg|wmenu}}, which supplies the {{ic|wmenu-run}} command:

<Pre>
# Your preferred terminal emulator
set $term foot
# Your preferred application launcher
set $menu wmenu-run
</Pre>

You could leave these 'as is' if you are happy with these selections. Otherwise, substitute any of them.

A word to the wise regarding one's initial choice of ''terminal'' ''if not currently running '''Sway''''': if a different terminal were to be chosen, then one would not be able to {{Key|Alt}}+{{Key|Tab}} back and forth from a launched '''foot''' terminal into other opened workspaces unless that terminal's {{ic|app_id}} / {{ic|class}} could somehow be determined and specified by the user in ''Step 7''. It may be more suitable therefore to leave '''foot''' as the default terminal until one of these could be determined once a '''Sway''' session is run, so that the terminal ('''foot''') would land in a specified workspace when launched, and then easily {{Key|Alt}}+{{Key|Tab}} to and from it. Alternatively, one could left-click on the chosen terminal's workspace button on the top {{Pkg|swaybar}} in order to switch to that workspace. (Note also that '''foot''' would already be installed if '''Sway''' had been installed using {{ic|$ doas setup-desktop sway}}). On the other hand, ''if one is currently running '''Sway''''', then it is straightforward to change this default terminal choice here, if so wished; a tweak for the preferred terminal could be made in ''Step 7''.

One's choice of menu launcher here is more flexible, regardless of the compositor/window manager currently being used, as the launcher will appear in any workspace currently displayed on-screen – a.k.a. the workspace ''in focus'' – using the keybinding declared in the following step (''Step 3''). Insert the preferred launcher's launch command here. For example, one may prefer {{Pkg|rofi}} over '''wmenu'''; Alpine Linux's '''rofi''' port now supports '''Wayland''', just as [https://github.com/davatorium/rofi rofi's mainline version] officially has since 2025. If so, that {{ic|set $menu wmenu-run}} line could be changed as follows:

<Pre>
set $menu '/usr/bin/rofi -combi-modi run,drun,window,filebrowser -show combi -sort'
</Pre>

With that menu instruction, whenever '''rofi''' is launched using the keybinding reviewed in the next step, it would first offer a ''combi'' (combination) menu of all packages and of <code>.desktop</code> files that match the the command name while it is being typed in; alternatively, one could follows this on by hitting {{Key|Control}}+{{Key|Tab}}, which in turn would offer (a) a ''drun'' menu (a launcher strictly of <code>.desktop</code> files); (b) a listing of opened ''"window"''/view selections; or (c) a simple ''filebrowser'', etc.

A tally of the chosen packages is being kept for any required installation later.

'''''Step 3:'' Choose key combinations to open the terminal and launcher and others'''. From the configuration file:

<Pre>
bindsym $mod+Return exec $term
[...]
bindsym $mod+d exec $menu
</Pre>

Modify these keybindings if so wished, which refer to the terminal and application launcher chosen in ''Step 2''. Ensure that any different chosen key combination(s) has/have not already been assigned elsewhere in this {{Path|config}} file. Make note of your chosen terminal and menu keybindings so as to know how to launch them later. As it stands:
* {{Key|Window}}+{{Key|Return}} for your terminal;
* {{Key|Window}}+{{Key|m}} for your menu launcher;
Substitute the {{Key|Window}} key for your assigned {{ic|$mod}} key, or with any other chosen combination that has not been used elsewhere in the configuration file.

Keybindings may also be made without requiring to define applications as variables that use the {{ic|set}} instruction and the {{ic|$}} variable prefix. For example, having ensured that there was no previous binding for {{ic|Control+Alt+w}}, one could add the following keybinding:

<Pre>
# LibreOffice Writer shortcut
bindsym Control+Alt+w exec '/usr/bin/libreoffice --writer'
</Pre>

'''''Step 4:'' Applications to launch full-sized and in tabbed layout (Optional)'''. At the beginning of the {{ic|# Layout stuff:}} section, Consider inserting:

<Pre>
workspace_layout tabbed
</Pre>

Then, each launched application will launch full-sized. Each application will be named in a tab.
If opting for a default tiled layout, this step is omitted. Tiling sends applications by default into tiles/"containers", splitting the screen, unless assigned to different workspaces in ''Steps 6-7''. A further alternative would be: {{ic|workspace_layout stacking}}.

'''''Step 5:'' Focus when launched (Optional)'''. Make '''Sway''' to immediately focus on any newly-opened application. At the end of the {{ic|# Workspaces:}} section in this {{Path|config}} file, consider adding:

<Pre>
for_window [app_id=.*] focus
</Pre>

This may be suitable to avoid having to navigate to its tab/workspace. It also ensures that dialog boxes such as ''"Open ..."'' and ''"Save as..."'' appear in the currently focused workspace.

'''''Step 6:'' Assign workspaces'''. This is proposed for your most oftenly-used applications, so that most applications will land into different workspaces, and then one could {{Key|Alt}}+{{Key|Tab}} between those applications/workspaces.

Consider copying and pasting the following model in this same {{ic|# Workspaces:}} passage. Customise each line for user preferences. These specify the {{ic|app_id}} for various applications, including that of the {{Pkg|keepassxc}} password vault, the lean {{Pkg|corepad}} text editor and {{Pkg|okular}} pdf viewer. Then, one finishes off each line with a chosen workspace number. (There may be no documented upper limit of workspaces, but one would need two keystrokes to move applications into two-digit workspaces if and when such keybindings were eventually learned and used.)

<Pre>
# APPLICATIONS TO APPEAR IN SPECIFIC WORKSPACES
assign [app_id="foot"] 1
assign [app_id="chromium"] 2
assign [app_id="org.keepassxc.KeePassXC"] 3
assign [app_id="cc.cubocore.CorePad"] 4
assign [app_id="libreoffice-writer"] 5
assign [app_id="libreoffice-calc"] 6
assign [app_id="org.kde.okular"] 7
assign [app_id="thunar"] 8
</Pre>

One could use workspace names instead of numbers, but then one would need to change their instances in the default {{Path|config}} file. Some applications, not listed here, may require identification by their {{ic|class}} name instead of by {{ic|app_id}} – particularly, some that were originally designed for '''X11''' (such as '''xterm''') – see ''Step 6''. '''Sway''' supplies the {{ic|swaymsg}} command that could determine the {{ic|app_id}} and/or {{ic|class}} name of one's chosen applications.

{{Tip|The '''keepassxc''' password vault is assigned to appear in a different workspace than the '''chromium''' browser. After both are launched, then one would be able to {{Key|Alt}}+{{Key|Tab}} between the two workspaces to fetch/paste password data without engaging a browser password extension, if preferred.}}

If alternative applications are to be assigned workspaces, proceed to the next step.

'''''Step 7:'' Assign alternative application choices for specific workspaces (Optional)'''. This may require being run in a '''Sway''' session. ''If not currently running Sway'', then consider conserving whichever part of the code block in ''Step 6'' that is applicable for user purposes in the configuration file and resuming this ''Step 7'' once the first '''Sway''' session is run.

This step may succeed alternatively in a different '''Wayland''' compositor provided that: (a) '''Sway''' or {{Pkg|sway-bash-completion}} has been installed, seeing how either supply the required {{ic|swaymsg}} command; or (b) one has a different means of determining the {{ic|app_id}} / {{ic|class}} of the alternative application(s).
<ol start="1">
<li> Launch the alternative applications that are to be assigned to workspaces.</li>
<li> Run {{ic|<nowiki>swaymsg -t get_tree | grep "app_id"</nowiki>}} in a terminal. The command examines metadata for your opened windows, and the result is then whittled down (or ''"grepped"'') to display {{ic|app_id}} values. For example: </li>
<pre> $ swaymsg -t get_tree | grep "app_id"
"app_id": "Alacritty",
"app_id": "firefox-esr",
"app_id": "librewolf",
"app_id": "pavucontrol-qt",
"app_id": "featherpad",
"app_id": "audacious",
"app_id": "org.gnome.Epiphany",
"app_id": "org.qutebrowser.qutebrowser",
</pre></ol>
<ol start="3">
<li> Plug the {{ic|app_id}} values for any preferred applications into the {{ic|assign}} listings code block above; end each line with a chosen workspace number.</li>
<li> In case any application name did not appear with an {{ic|app_id}}, then it is possible that the application was originally designed for '''Xorg''' and has not been fully adapted for ''"pure '''Wayland'''"'': for example, {{Pkg|xterm}}. In that case, one would need to determine what its {{ic|class}} is instead: ''with {{Pkg|xwayland}} installed and not disabled'' in '''Sway''', launch '''xterm'''; then, in a terminal, run:</li>
<pre>
$ swaymsg -t get_tree | grep "class"
"class": "XTerm",
</pre>
<li>Determine the {{ic|class}} values for the remainder of the preferred applications that required {{ic|class}} identifiers instead of {{ic|app_id}} and create lines for them in the {{ic|assign}} code block above. For instance, for '''xterm''' to land in workspace 9, add a line to specify its ''class'' and its assigned workspace ''number'':
<pre>
assign [class="XTerm"] 9
</pre><li>
</ol>

'''''Step 8:'' Navigating between applications in different workspaces'''. Tell '''Sway''' what will be the chosen way to ''tab back'' through the workspaces that contain launched applications on a single monitor, say, {{Key|Alt}}+{{Key|Tab}}. In the {{ic|# Moving around:}} passage, consider adding:-

<Pre>
bindsym Alt+Tab workspace prev_on_output
bindsym Super+Tab workspace next_on_output
</Pre>

We have additionally assigned {{Key|Super}}+{{Key|Tab}} to tab ''forwards'' through workspaces, in case that this could be useful to the user (optional).

As mentioned, one can alternatively focus a different workspace by left-clicking on its worskpace button in the '''swaybar'''.

'''''Step 9:'' Navigating between applications within the same workspace'''. If two or more instances of the same application get launched (say, two instances of '''foot'''), then they will both appear in the same workspace that had been assigned to them, if any. In such case, {{Key|Alt}}+{{Key|Tab}} would not work to navigate between these because that keybinding navigates between applications being displayed in ''different'' workspaces. Instead, one may navigate between those two instances/tabs within that same workspace in ''three alternative ways''; no edits need be done, but one may need to make note of these methods:-

* The default {{Path|config}} file has already bound {{ic|$mod+Left}} and {{ic|$mod+Right}} to switch focus onto tabs shown to the left and right within the same workspace; in our setup, that would be {{Key|Window}}+{{Key|←}} and {{Key|Window}}+{{Key|→}}.
* The default {{Path|config}} file has similarly bound {{ic|$mod+$left}} and {{ic|$mod+$right}} for these same commands; the {{ic|$left}} and {{ic|$right}} ''"key variables"'', along with two others, have been defined in a fashion that would be familiar to those using {{Pkg|vim}}:

<pre>
set $left h
set $down j
set $up k
set $right l </pre>

:Although the {{ic|Left}} key ({{Key|←}}) is distinct from the {{ic|$left}} key (assigned here to be the {{Key|h}} key), this {{Path|config}} file has ''bound them both'' to enact the same action when combined with the {{ic|$mod}} key, specifically, to move ''left'' through tabs in the same workspace (different users prefer alternative methods):

<pre>
bindsym $mod+$left focus left
[...]
bindsym $mod+Left focus left </pre>

:Similarly for the {{ic|$right}} and {{ic|Right}} keys.

* Alternatively, one could ''left-click'' on a tab to focus on a specific application instance, similarly to how one might click on ''taskbar'' items in other desktop environments.

Any applications that were not assigned into a workspace in the {{ic|assign}} ''Steps 6-7'' above will also launch into the workspace currently focused. In such cases, therefore, their tabs would be created in the current workspace too, and one could navigate between such applications, within that same workspace, using any way reviewed in this step also.

'''''Step 10:'' Floating, dragging, tiling, fullscreen, etc'''.
* One may make a focused application to '''float''', and to toggle ''"floating"'' off as-and-when needed, with: {{ic|$mod+Shift+space}} . In our setup: {{Key|Window}}+{{Key|Shift}}+{{Key|Space}}.

* The {{Path|config}} file points out that one may ''"drag floating windows by holding down $mod and left mouse button"''. Seeing how {{ic|$mod}} was kept assigned as the {{Key|Window}} key: {{Key|Window}}+'''drag'''. The window needs to be floating first; in some instances, one may need to drag at the tab.

* One could make some applications to launch "floating" by default (optional). An application that is sometimes made to float by default is the {{Pkg|galculator}} calculator pad; just add:
:{{ic|<nowiki>for_window [app_id="galculator"] floating enable</nowiki>}}

* To toggle through '''tiled layouts''' within a workspace: {{ic|$mod+e}} / {{Key|Window}}+{{Key|e}}

* To return to '''full-sized tabs''' i.e. window-sized after being in a tiled layout, yet not fullscreen, thereby retaining toolbars, etc: {{ic|$mod+w}} / {{Key|Window}}+{{Key|w}} . Floating windows and fullscreen windows need to be toggled off first.

* To toggle in and out of '''fullscreen''': {{ic|$mod+f}} / {{Key|Window}}+{{Key|f}}

Take note of two final keybindings, or modify these first:

* To '''reload''' the '''Sway''' configuration file after editing it during a session: {{ic|$mod+Shift+c}} / {{Key|Window}}+{{Key|Shift}}+{{Key|c}}

* To '''exit''' '''Sway''' and the login session (save your work first): {{ic|$mod+Shift+e}} / {{Key|Window}}+{{Key|Shift}}+{{Key|e}}

'''''Step 11:'' Add variables and autostart instructions'''. These could be added to the beginning of this {{Path|config}} file. Typically, various environment variables would require being set before launching a '''Wayland''' compositor, for example, in {{Path|~/.profile}} . Do not add ampersands ('''&''') at the end of each line in {{Path|config}}, unlike with {{Path|.xinitrc}} syntax in '''Xorg'''.

{{Pkg|xwayland}}, if not required, can be disabled by inserting a line here to that effect. Alternatively, omit that line or comment it out by using a hashtag, as in the following example of autostart instructions, where '''Sway''' is assumed to have been launched [[Sway#Starting_Sway|using a {{ic|dbus-run-session}}]]; gui runlevel is started now if '''PipeWire''' and associated services are being [[PipeWire#Pipewire_user_service|launched as user services]]; and where '''chromium''' is also autostarted:

<Pre>
exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP=sway SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME
# xwayland disable
# Start gui runlevel for PipeWire and associated services to launch now
exec openrc -U gui
exec /usr/bin/chromium
</Pre>

{{Tip|Running ''"pure '''Wayland'''"'' – i.e. without the '''xwayland''' layer/package – may remove a possible attack surface. '''Xwayland''' could be required, however, to run certain '''Xorg'''-designed software, such as {{Pkg|xterm}}. One may also investigate '''libreoffice''' and '''okular''' functionality.}}

'''''Step 12:'' Install selected packages'''. Ensure that all mentioned applications have been installed: {{ic|apk info -e <var>package1</var> <var>package2</var>}}. Substitute entries in the following list with one's packages mentioned in the {{Path|config}} file:

{{Cmd|$ apk info -e foot wmenu chromium keepassxc corepad libreoffice okular thunar xterm galculator}}

'''wmenu''' was preserved for that listing; swap it out for '''rofi''' or otherwise, if necessary. One may have decided also not to include '''xterm''', etc.

Install any application not appearing in the output of that instruction.

For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].

=== PipeWire and Screensharing ===

The Sway compositor has no involvement with audio playback. In order for screensharing to work, [[PipeWire]] is required. Therefore, installing [[PipeWire#Installation|PipeWire]] is recommended for audio playback too.

Since v3.22, Alpine Linux provides the necessary scripts to start PipeWire as a [[OpenRC#user services|user service]] in OpenRC.

From a screensharing perspective, applications are split into two categories:-

* Those which use the native Wayland [https://wayland.app/protocols/wlr-screencopy-unstable-v1 wlr-screencopy] protocol
* Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).

Applications in the first group require no additional setup. Applications in the second group (which include Firefox and Chromium) require setting up ''xdg portals'' in addition to [[PipeWire#Installation|PipeWire]].

{{Cmd|# apk add xdg-desktop-portal xdg-desktop-portal-wlr}}

If you are using a <code>dbus-run-session</code> wrapper to launch Sway, you will also need to set D-Bus variables in order for the portal and for [[#PipeWire and Screensharing|screensharing]] features to work; add the following line to the beginning of Sway's {{Path|config}} file:

exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME

The {{ic|XDG_CURRENT_DESKTOP}} environment variable may be set by various methods, including:-
* by amending its mention in that {{ic|dbus-update-activation-environment}} line, editing it to specify {{ic|XDG_CURRENT_DESKTOP{{=}}sway}} ; or
* by exporting it from within an applicable environment configuration file, such as:

:{{Cat| $XDG_CONFIG_HOME/.profile|<nowiki>
export XDG_CURRENT_DESKTOP=sway
</nowiki>}}

:However, this method is not universal, as it would require resetting the {{ic|XDG_CURRENT_DESKTOP}} variable for any different desktop/compositor/window manager that may be launched afterwards, possibly by employing a launcher similar to the wrapper script alternative described for '''Sway''' [[Sway#Automatically_Launch_Sway_on_tty1|below]]; or
* by being set automatically by the display manager, as is commonplace, but none is supplied by '''Sway'''.

=== Screen Lock and suspend-to-RAM ===

{{Tip| For a seat manager-agnostic and DE-/WM-agnostic tool, consider installing the {{Pkg|zzz}} utility, available in the [[Repositories#Community|community]] repository, or the {{Pkg|powerctl}} utility from the [[Repositories#Testing|testing]] repository, in order to manage suspend and hibernation.}}

For usage of the <Code>loginctl suspend</Code> command, see [[Elogind]].

To put the system to sleep after 600 seconds, use:

exec swayidle -w timeout 600 'doas /usr/bin/powerctl mem'

Do not lock the screen if program is running in full screen:

==== Idle inhibition ====

for_window [app_id="^.*"] inhibit_idle fullscreen

{{Todo|The option below, related to <Code>wayland-pipewire-idle-inhibit</Code>, needs to be tested. If you find the option below to be working, please remove this Todo.}}

If you do not want to lock the screen while media is being played through [[PipeWire]], then install the {{pkg|wayland-pipewire-idle-inhibit}} package, and add the following to Sway's {{Path|config}} file:

exec wayland-pipewire-idle-inhibit

Make changes to the {{Path|~/.config/wayland-pipewire-idle-inhibit/config.toml}} configuration file or to whichever configuration file you may have referenced instead through the <Code> --config <PATH></Code>, if required, as per the [https://github.com/rafaelrc7/wayland-pipewire-idle-inhibit?tab=readme-ov-file#config project's website].

=== Elogind and swayidle ===

<code>swayidle</code> has integration with <code>elogind</code>, and it can handle ''before-sleep'' events.

If using <code>swayidle before-sleep</code>, then there will be a race condition, so that when you resume the computer from ''suspend'', the screen will show the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.

To solve this issue, do the following.

Create the <code>/etc/elogind/system-sleep/10-swaylock.sh</code> file, and then add the following script to this file:
{{Cat|/etc/elogind/system-sleep/10-swaylock.sh|<nowiki>
#!/bin/sh
if [ "${1}" == "pre" ]; then
touch /tmp/swaylock-sleep
sleep 1
fi
</nowiki>}}

Then set it to executable.

Later, once Sway is installed, add the following line to its {{Path|config}} file:

exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep

With this line, the screen will be promptly locked before ''suspend-to-RAM'' starts.

=== Brightness Control ===

Refer to [[Backlight]] for information on brightness control.

=== Output Scaling for High Resolution Displays ===

Without further configuration, program interfaces may be too small to use on high resolution displays.

Sway supports the per-display configuration of:-

* fractional (e.g. 1.5x); and
* integer scaling (e.g. 2x)

However, fractional scaling is discouraged due both to the performance impact and to the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT-based toolkit scaling is recommended. See [[Sway#Toolkit Scaling|See below]].

==== Scaling with wdisplays ====

To enable Sway scaling, the user can first preview different scaling factors with the {{Pkg|wdisplays}} package. Note the output name (''eDP-1'', ''LVDS-1'') and try apply scaling factors such as 1 and 2. To make changes permanent, add the following line, completed with your settings, to Sway's {{Path|config}} file.

<pre>
output <name> scale <factor>
</pre>

==== Toolkit Scaling ====

To use toolkit scaling, say, at x2, add the following, for instance, to your {{Path|~/.profile}}:

# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2

# for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
# or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"

=== Notification Daemon ===

[[mako]] is a lightweight notification daemon that works seamlessly with Sway.

=== Screenshots ===

A simple tool that works well under Wayland is {{pkg|grimshot}}. Example keybindings:-

<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

See Sway's [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway wiki article] for a listing of further screenshot tools.

=== Make Clipboard Content Persistent ===

By default, the clipboard content does not persist after terminating the program: if you copy some text from Firefox and then exit Firefox, then the copied text is also lost.

Install {{Pkg|clipman}} from the community repo, and then add the following to Sway's {{Path|config}} file:

<pre>
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
</pre>

=== Firefox Picture-in-Picture Mode/Floating Windows ===

Add this to your Sway configuration file (modify the numeric values to suit your needs and your display):

<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Start with NumLock Enabled ===

Add the following to your Sway {{Path|config}} file:

input type:keyboard xkb_numlock enabled

=== Change mouse cursor theme and size ===

Add to your Sway {{Path|config}} file:

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

For example, set a mouse cursor using the '''GNOME Adwaita''' theme:

seat seat0 xcursor_theme Adwaita 16

You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your configuration does not result in change, try logging out and in.

{{Note|Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Custom Keyboard Layout ===

To use a custom keyboard layout, just use:

<pre>
input type:keyboard {
xkb_file /path/to/my/custom/layout
}
</pre>

=== Flatpaks ===

{{main|Flatpak}}

As mentioned in [[Flatpak#Portals|Flatpak]] page, install the minimal required portal related packages i.e {{pkg|xdg-desktop-portal}}, {{pkg|xdg-desktop-portal-gtk}} and {{pkg|xdg-desktop-portal-wlr}}. After installing the packages, add the following to the ''autostart'' section in your Sway {{Path|config}} file to avoid [[Flatpak#GDBus_Error|GDBus errors]].
<pre>
exec /usr/libexec/xdg-desktop-portal
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
</pre>

These startup instructions are only needed, if these are not started automatically via other means.

== Starting Sway ==

=== Manually Launch Sway ===

You can launch Sway manually by issuing the <Code>sway</Code> command from a TTY.

{{Cmd|$ sway}}

{{Tip|When using [[Wayland]], for [[PipeWire]] and screensharing to work in Firefox and Chromium, a [[D-Bus]] is required. In the absence of a [[OpenRC#User_services|user service manager]], consider running <Code>sway</Code> with <code>dbus-run-session</code>, a convenient wrapper that will explicitly export the path of the session bus.{{Cmd|$ dbus-run-session sway}}
}}

=== Automatically Launch Sway on tty1 ===

Adding the following lines to {{Path|~/.profile}} or to its equivalent will ensure that <Code>sway</Code> launches automatically, with a D-Bus, ''only'' from ''tty1''. This is handy for troubleshooting, because if the Sway configuration ever falters, one could troubleshoot by logging into a different TTY (''tty2''-''tty6''), and your startup script then will not attempt to launch the faulty Sway environment from there also.
{{Cat| ~/.profile|<nowiki>
...

if [ "$(tty)" = "/dev/tty1" ]; then
exec dbus-run-session sway
fi
...</nowiki>}}

=== Using a Wrapper Script to Launch Sway ===

Instead of using {{Path|~/.profile}} or its equivalent file, a [https://man.sr.ht/~kennylevinsen/greetd/#how-to-set-xdg_session_typewayland wrapper script] can be placed at {{Path|/usr/local/bin/sway-run}}. This script can be used to launch <Code>sway</Code> from either a TTY or by [[greetd]], a lightweight [[Display manager|display manager]], as follows: {{Cat|/usr/local/bin/sway-run|<nowiki>#!/bin/sh
# Session
export XDG_SESSION_TYPE=wayland
export XDG_SESSION_DESKTOP=sway
export XDG_CURRENT_DESKTOP=sway

# Wayland stuff
export MOZ_ENABLE_WAYLAND=1
export QT_QPA_PLATFORM=wayland
export SDL_VIDEODRIVER=wayland
export _JAVA_AWT_WM_NONREPARENTING=1

# Launch Sway with a D-Bus server
exec dbus-run-session sway "$@" </nowiki>}}

Make the file executable:
{{Cmd|# chmod +x /usr/local/bin/sway-run}}

== Troubleshooting ==

If you encounter any issues, try running <Code>sway -Vc /etc/sway/config</Code>. It will run <Code>sway</Code> with the default config file and set the output to be more verbose. It is generally a good idea to track your configuration files with ''git'' (if and when you use a remote repository for them, keep it private, for security reasons).

To capture the Sway error log in a file for troubleshooting, replace <code>sway</code> in your startup file by:

sway -d 2> ~/sway_error.log

Alternatively, you can also issue the below command from TTY.

{{Cmd|$ sway -d 2> ~/sway_error.log}}

=== Video Driver Issues ===

After installing Sway, and while launching it for the first time, a lack of appropriate [[#Install Graphics Drivers|video drivers]] may cause various error messages such as:

* "unable to create backend"
* "Failed to create renderer"

Install the necessary drivers in order for your [[#Install Graphics Drivers|graphics card]] to work with Sway.

=== XDG_RUNTIME_DIR is not set in the environment. Aborting ===

If [[seatd]] is used instead of [[elogind]], the error message '''XDG_RUNTIME_DIR is not set in the environment. Aborting''' might be encountered.

Ensure that the mandatory steps outlined in the [[Seatd]] wiki page are completed in order to set the [[XDG_RUNTIME_DIR]] variable.

=== No backend was able to open a seat ===

If no [[seat manager]] is available, then the error below will appear.

<Pre>
[libseat] [libseat/libseat.c:73] libseat_open_seat : No backend was able to open a seat
[backend/session/libseat.c:102] Unable to create seat : Function not implemented
[backend/backend.c:303] Failed to open any DRM device
[sway/server.c:49] Unable to create backend
</Pre>

Ensure that either [[Elogind]] or [[Seatd]] is properly configured and running.

=== Firefox (Flatpak) and/or GTK Apps ===

==== Disappearing Cursor ====

You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively, one could install an [https://pkgs.alpinelinux.org/packages?name=*-icon-theme&branch=edge&repo=&arch=x86_64&origin=&flagged=&maintainer= icon theme] package for all users.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Nvidia Issues ===

{{Draft|This section is partly outdated and could benefit from contributions in view of Nvidia's [https://docs.nvidia.com/drive/drive-os-5.2.3.0L/drive-os/index.html#page/DRIVE_OS_Linux_SDK_Development_Guide/Windows%20Systems/window_system_wayland.html current support] of Wayland. Help is encouraged.}}
{{Main|NVIDIA}}
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your <Code>WLR_BACKENDS</Code> environmental variables to <code>drm,libinput</code> or <code>x11</code> (add {{Pkg|libinput}} here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install {{Pkg|libinput}} first''').

== See also ==

* [https://github.com/swaywm/sway/wiki/ Sway Wiki]
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]

[[Category:Compositor]]

Sway

2025-10-14T22:06:18Z

WhyNotHugo: /* PipeWire and Screensharing */ Remove reference to obsolete script

[https://swaywm.org Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the [[i3wm |i3 window manager]]. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

== Prerequisites ==

* Internet [[Configure_Networking#Connectivity_testing|connectivity]], unless the packages have been pre-fetched into a local cache.
* Install appropriate [[Graphics driver]] drivers for your hardware. Without graphics drivers [[#Video Driver Issues|errors]] are likely to occur.
* A [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]].
* The [[Repositories#Managing_repositories|community repositories must be enabled]].
* Set up [[eudev]].
* Wayland compositors need raw access to input and output devices, typically mediated by a [[seat manager]]. Either [[seatd]] or [[elogind]] work fine, but installing both leads to conflicts.
{{Tip|Except for the first two [[#Prerequisites|prerequisites]], all of the others are automatically handled if the desktop is [[#Setup-desktop|installed using the following setup-desktop]] script.}}

== Setup-desktop ==

The [[setup-desktop]] command automates the Sway desktop installation with [[eudev]] and [[elogind]].

{{cmd|# setup-desktop sway}}

Proceed to the [[Sway#Starting Sway|Starting Sway]] section, as no [[Display manager|display manager]] is being installed nor configured by the script that would boot into a graphical login screen.

== Manual Installation ==

The installation steps below allow you to pick and choose various components for your Sway desktop.

=== Install Fonts ===

Install [https://dejavu-fonts.github.io/ DejaVu] fonts ({{Pkg|font-dejavu}}), which have good [https://home.unicode.org/ Unicode] coverage:

{{cmd|# apk add font-dejavu}}

=== Install Sway ===

{{cmd|# apk add sway \
xwayland \ # if you need the xserver
foot \ # default terminal emulator. Modify $term in config for a different one.
wmenu \ # default Wayland native menu for choosing program and screensharing monitor
swaylock swaylockd \ # lockscreen tool
swaybg \ # display wallpaper
grim \ # screenshot tool
wl-clipboard \ # clipboard management
i3status \ # simple status bar
swayidle # idle management (DPMS) daemon
}}

For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway Sway's wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland Gentoo's wiki].

== Configuration ==

===Sway config File ===

Copy the default Sway configuration file to {{Path|~/.config/sway/config}} so that it can be customized as per each user's choices:

{{cmd|$ mkdir -p ~/.config/sway
$ cp /etc/sway/config ~/.config/sway/}}

Read through it to learn the default keybindings.
Sway's configuration is mostly backward compatible with that of [[I3wm|i3]]'s, and if you are looking for a solution for a specific issue, you could try checking whether it hasn't been provided for the i3 window manager.

====Quickstart - config File====
To set up an environment that launches applications full-sized and to {{Key|Alt}}+{{Key|Tab}} between these much as in [[Xfce|XFCE]] or in various other desktop environments, then a quick setup of the {{Path|config}} file could effect this. This proposed setup may be of benefit for both desktop/non-technical and technical use. ''Step 4'' is indicated to be sidestepped by those electing an {{Pkg|i3}}-style, tiled default layout.

A launchbar is not set up "out of the box", nor here, so this section only reviews essential ''keybindings'' (or "shortcuts"), saving first-time users from immediately requiring to digest a longer ''"cheatsheet"'' of keybindings that might include resizing, moving and swapping windows (called ''"views"''), say, from smaller tiles (called ''"containers"'') into larger tiles; these may be learned at a later stage.

The quickstart configuration of the {{Path|config}} file ''may be prepared within or without '''Sway''''' e.g. within an '''Xorg''' session or another compositor, or on another installation, before eventually copying over the finished {{Path|config}} file onto the target system – except:
* If one prefers alternative applications to those proposed initially in ''Step 6'' for assignment into specific workspaces. Any such modifications (to be executed in ''Step 7'') could be performed: (a) simply during one's first '''Sway''' session; or (b) by determining what those applications' {{ic|app_id}} / {{ic|class}} are (as detailed in ''Step 7''), possibly in another '''Wayland''' session or externally e.g. from documentation.
* One will likewise require to verify at some point whether one's chosen applications are installed on the target system; and to install those missing (last step, ''Step 12'').

'''''Step 1:'' Assign the main modifier key'''. In a text editor, open the {{Path|/home/<var>username</var>/.config/sway/config}} file that had been copied over. We will declare what would be the main modifier key for many of our keybindings: {{Key|Window}}, {{Key|Alt}} or otherwise. The {{Path|config}} file has already set the main modifier, called the {{ic|$mod}} key, to default as the {{ic|Mod4}} key, also known as the {{Key|Window}}, {{ic|Super}} or ''Logo'' key. Verify this towards the beginning of the file:

<Pre>
# Logo key. Use Mod1 for Alt.
set $mod Mod4
</Pre>

As proposed there, one could change that {{ic|$mod}} key to be the {{Key|Alt}} key a.k.a. the {{ic|Mod1}} key. To change the {{ic|$mod}} key assignment, as with any line in this file, one could edit/delete the lines or comment such line out i.e. add a hashtag ('''''#''''') at the start of any line that does not begin with a hashtag, so that such line would not be executed by '''Sway''' but would be left there for reference; and then enter the customised version of that line below it. Note that '''Sway''' [https://github.com/swaywm/sway/wiki#comments does not support] comments at the end of an executable line, following a hashtag.

According to the {{ic|man 5 sway}} page, ''XKB modifier names'' can be used to refer to modifier keys, plus certain aliases found among the following list, all of these "{{ic|codes}}" being acceptable for use throughout the configuration file:

* {{ic|Mod1}} - {{Key|Alt}} - Alternatively expressed as {{ic|Alt}};
* {{ic|Mod2}} - Although not universally mapped, here it refers to the {{Key|Num Lock}} key;
* {{ic|Mod3}} - It could be programmed, as an XKB modifier key;
* {{ic|Mod4}} - Alternatively expressed as the {{ic|Super}} key, a.k.a. the {{Key|Window}} or ''Logo'' key;
* {{ic|Mod5}} - {{Key|AltGr}};
* {{ic|Lock}} - {{Key|Caps Lock}};
* {{ic|Control}} - {{Key|Ctrl}} - Alternatively expressed as {{ic|Ctrl}}; and
* {{ic|Shift}} - {{Key|Shift}}.

It might be best not to use the {{Key|Ctrl}} key as the ''main modifier'', as it is often used in applications e.g. {{Key|Control}}+{{Key|c}} to ''copy'', {{Key|Control}}+{{Key|b}} for ''bold'', etc. Similarly when considering the {{ic|Shift}} as main modifier.

So, if one were to choose, say, the {{Key|Alt}} key as the main modifier, that {{ic|Mod4}} line could be changed to: {{ic|set $mod Alt}} or {{ic|set $mod Mod1}}. We will preserve the default, {{ic|Mod4}} ({{Key|Window}}), as the main modifier. Note that any modification will not be manifested until one chooses at any time to reload the {{Path|config}} file by hitting {{ic|$mod+Shift+c}} (cf. ''Step 10'').

'''''Step 2:'' Declare what your default terminal and menu launcher will be'''. In this {{Path|config}} file, these are currently configured to be the {{Pkg|foot}} terminal; and {{Pkg|wmenu}}, which supplies the {{ic|wmenu-run}} command:

<Pre>
# Your preferred terminal emulator
set $term foot
# Your preferred application launcher
set $menu wmenu-run
</Pre>

You could leave these 'as is' if you are happy with these selections. Otherwise, substitute any of them.

A word to the wise regarding one's initial choice of ''terminal'' ''if not currently running '''Sway''''': if a different terminal were to be chosen, then one would not be able to {{Key|Alt}}+{{Key|Tab}} back and forth from a launched '''foot''' terminal into other opened workspaces unless that terminal's {{ic|app_id}} / {{ic|class}} could somehow be determined and specified by the user in ''Step 7''. It may be more suitable therefore to leave '''foot''' as the default terminal until one of these could be determined once a '''Sway''' session is run, so that the terminal ('''foot''') would land in a specified workspace when launched, and then easily {{Key|Alt}}+{{Key|Tab}} to and from it. Alternatively, one could left-click on the chosen terminal's workspace button on the top {{Pkg|swaybar}} in order to switch to that workspace. (Note also that '''foot''' would already be installed if '''Sway''' had been installed using {{ic|$ doas setup-desktop sway}}). On the other hand, ''if one is currently running '''Sway''''', then it is straightforward to change this default terminal choice here, if so wished; a tweak for the preferred terminal could be made in ''Step 7''.

One's choice of menu launcher here is more flexible, regardless of the compositor/window manager currently being used, as the launcher will appear in any workspace currently displayed on-screen – a.k.a. the workspace ''in focus'' – using the keybinding declared in the following step (''Step 3''). Insert the preferred launcher's launch command here. For example, one may prefer {{Pkg|rofi}} over '''wmenu'''; Alpine Linux's '''rofi''' port now supports '''Wayland''', just as [https://github.com/davatorium/rofi rofi's mainline version] officially has since 2025. If so, that {{ic|set $menu wmenu-run}} line could be changed as follows:

<Pre>
set $menu '/usr/bin/rofi -combi-modi run,drun,window,filebrowser -show combi -sort'
</Pre>

With that menu instruction, whenever '''rofi''' is launched using the keybinding reviewed in the next step, it would first offer a ''combi'' (combination) menu of all packages and of <code>.desktop</code> files that match the the command name while it is being typed in; alternatively, one could follows this on by hitting {{Key|Control}}+{{Key|Tab}}, which in turn would offer (a) a ''drun'' menu (a launcher strictly of <code>.desktop</code> files); (b) a listing of opened ''"window"''/view selections; or (c) a simple ''filebrowser'', etc.

A tally of the chosen packages is being kept for any required installation later.

'''''Step 3:'' Choose key combinations to open the terminal and launcher and others'''. From the configuration file:

<Pre>
bindsym $mod+Return exec $term
[...]
bindsym $mod+d exec $menu
</Pre>

Modify these keybindings if so wished, which refer to the terminal and application launcher chosen in ''Step 2''. Ensure that any different chosen key combination(s) has/have not already been assigned elsewhere in this {{Path|config}} file. Make note of your chosen terminal and menu keybindings so as to know how to launch them later. As it stands:
* {{Key|Window}}+{{Key|Return}} for your terminal;
* {{Key|Window}}+{{Key|m}} for your menu launcher;
Substitute the {{Key|Window}} key for your assigned {{ic|$mod}} key, or with any other chosen combination that has not been used elsewhere in the configuration file.

Keybindings may also be made without requiring to define applications as variables that use the {{ic|set}} instruction and the {{ic|$}} variable prefix. For example, having ensured that there was no previous binding for {{ic|Control+Alt+w}}, one could add the following keybinding:

<Pre>
# LibreOffice Writer shortcut
bindsym Control+Alt+w exec '/usr/bin/libreoffice --writer'
</Pre>

'''''Step 4:'' Applications to launch full-sized and in tabbed layout (Optional)'''. At the beginning of the {{ic|# Layout stuff:}} section, Consider inserting:

<Pre>
workspace_layout tabbed
</Pre>

Then, each launched application will launch full-sized. Each application will be named in a tab.
If opting for a default tiled layout, this step is omitted. Tiling sends applications by default into tiles/"containers", splitting the screen, unless assigned to different workspaces in ''Steps 6-7''. A further alternative would be: {{ic|workspace_layout stacking}}.

'''''Step 5:'' Focus when launched (Optional)'''. Make '''Sway''' to immediately focus on any newly-opened application. At the end of the {{ic|# Workspaces:}} section in this {{Path|config}} file, consider adding:

<Pre>
for_window [app_id=.*] focus
</Pre>

This may be suitable to avoid having to navigate to its tab/workspace. It also ensures that dialog boxes such as ''"Open ..."'' and ''"Save as..."'' appear in the currently focused workspace.

'''''Step 6:'' Assign workspaces'''. This is proposed for your most oftenly-used applications, so that most applications will land into different workspaces, and then one could {{Key|Alt}}+{{Key|Tab}} between those applications/workspaces.

Consider copying and pasting the following model in this same {{ic|# Workspaces:}} passage. Customise each line for user preferences. These specify the {{ic|app_id}} for various applications, including that of the {{Pkg|keepassxc}} password vault, the lean {{Pkg|corepad}} text editor and {{Pkg|okular}} pdf viewer. Then, one finishes off each line with a chosen workspace number. (There may be no documented upper limit of workspaces, but one would need two keystrokes to move applications into two-digit workspaces if and when such keybindings were eventually learned and used.)

<Pre>
# APPLICATIONS TO APPEAR IN SPECIFIC WORKSPACES
assign [app_id="foot"] 1
assign [app_id="chromium"] 2
assign [app_id="org.keepassxc.KeePassXC"] 3
assign [app_id="cc.cubocore.CorePad"] 4
assign [app_id="libreoffice-writer"] 5
assign [app_id="libreoffice-calc"] 6
assign [app_id="org.kde.okular"] 7
assign [app_id="thunar"] 8
</Pre>

One could use workspace names instead of numbers, but then one would need to change their instances in the default {{Path|config}} file. Some applications, not listed here, may require identification by their {{ic|class}} name instead of by {{ic|app_id}} – particularly, some that were originally designed for '''X11''' (such as '''xterm''') – see ''Step 6''. '''Sway''' supplies the {{ic|swaymsg}} command that could determine the {{ic|app_id}} and/or {{ic|class}} name of one's chosen applications.

{{Tip|The '''keepassxc''' password vault is assigned to appear in a different workspace than the '''chromium''' browser. After both are launched, then one would be able to {{Key|Alt}}+{{Key|Tab}} between the two workspaces to fetch/paste password data without engaging a browser password extension, if preferred.}}

If alternative applications are to be assigned workspaces, proceed to the next step.

'''''Step 7:'' Assign alternative application choices for specific workspaces (Optional)'''. This may require being run in a '''Sway''' session. ''If not currently running Sway'', then consider conserving whichever part of the code block in ''Step 6'' that is applicable for user purposes in the configuration file and resuming this ''Step 7'' once the first '''Sway''' session is run.

This step may succeed alternatively in a different '''Wayland''' compositor provided that: (a) '''Sway''' or {{Pkg|sway-bash-completion}} has been installed, seeing how either supply the required {{ic|swaymsg}} command; or (b) one has a different means of determining the {{ic|app_id}} / {{ic|class}} of the alternative application(s).
<ol start="1">
<li> Launch the alternative applications that are to be assigned to workspaces.</li>
<li> Run {{ic|<nowiki>swaymsg -t get_tree | grep "app_id"</nowiki>}} in a terminal. The command examines metadata for your opened windows, and the result is then whittled down (or ''"grepped"'') to display {{ic|app_id}} values. For example: </li>
<pre> $ swaymsg -t get_tree | grep "app_id"
"app_id": "Alacritty",
"app_id": "firefox-esr",
"app_id": "librewolf",
"app_id": "pavucontrol-qt",
"app_id": "featherpad",
"app_id": "audacious",
"app_id": "org.gnome.Epiphany",
"app_id": "org.qutebrowser.qutebrowser",
</pre></ol>
<ol start="3">
<li> Plug the {{ic|app_id}} values for any preferred applications into the {{ic|assign}} listings code block above; end each line with a chosen workspace number.</li>
<li> In case any application name did not appear with an {{ic|app_id}}, then it is possible that the application was originally designed for '''Xorg''' and has not been fully adapted for ''"pure '''Wayland'''"'': for example, {{Pkg|xterm}}. In that case, one would need to determine what its {{ic|class}} is instead: ''with {{Pkg|xwayland}} installed and not disabled'' in '''Sway''', launch '''xterm'''; then, in a terminal, run:</li>
<pre>
$ swaymsg -t get_tree | grep "class"
"class": "XTerm",
</pre>
<li>Determine the {{ic|class}} values for the remainder of the preferred applications that required {{ic|class}} identifiers instead of {{ic|app_id}} and create lines for them in the {{ic|assign}} code block above. For instance, for '''xterm''' to land in workspace 9, add a line to specify its ''class'' and its assigned workspace ''number'':
<pre>
assign [class="XTerm"] 9
</pre><li>
</ol>

'''''Step 8:'' Navigating between applications in different workspaces'''. Tell '''Sway''' what will be the chosen way to ''tab back'' through the workspaces that contain launched applications on a single monitor, say, {{Key|Alt}}+{{Key|Tab}}. In the {{ic|# Moving around:}} passage, consider adding:-

<Pre>
bindsym Alt+Tab workspace prev_on_output
bindsym Super+Tab workspace next_on_output
</Pre>

We have additionally assigned {{Key|Super}}+{{Key|Tab}} to tab ''forwards'' through workspaces, in case that this could be useful to the user (optional).

As mentioned, one can alternatively focus a different workspace by left-clicking on its worskpace button in the '''swaybar'''.

'''''Step 9:'' Navigating between applications within the same workspace'''. If two or more instances of the same application get launched (say, two instances of '''foot'''), then they will both appear in the same workspace that had been assigned to them, if any. In such case, {{Key|Alt}}+{{Key|Tab}} would not work to navigate between these because that keybinding navigates between applications being displayed in ''different'' workspaces. Instead, one may navigate between those two instances/tabs within that same workspace in ''three alternative ways''; no edits need be done, but one may need to make note of these methods:-

* The default {{Path|config}} file has already bound {{ic|$mod+Left}} and {{ic|$mod+Right}} to switch focus onto tabs shown to the left and right within the same workspace; in our setup, that would be {{Key|Window}}+{{Key|←}} and {{Key|Window}}+{{Key|→}}.
* The default {{Path|config}} file has similarly bound {{ic|$mod+$left}} and {{ic|$mod+$right}} for these same commands; the {{ic|$left}} and {{ic|$right}} ''"key variables"'', along with two others, have been defined in a fashion that would be familiar to those using {{Pkg|vim}}:

<pre>
set $left h
set $down j
set $up k
set $right l </pre>

:Although the {{ic|Left}} key ({{Key|←}}) is distinct from the {{ic|$left}} key (assigned here to be the {{Key|h}} key), this {{Path|config}} file has ''bound them both'' to enact the same action when combined with the {{ic|$mod}} key, specifically, to move ''left'' through tabs in the same workspace (different users prefer alternative methods):

<pre>
bindsym $mod+$left focus left
[...]
bindsym $mod+Left focus left </pre>

:Similarly for the {{ic|$right}} and {{ic|Right}} keys.

* Alternatively, one could ''left-click'' on a tab to focus on a specific application instance, similarly to how one might click on ''taskbar'' items in other desktop environments.

Any applications that were not assigned into a workspace in the {{ic|assign}} ''Steps 6-7'' above will also launch into the workspace currently focused. In such cases, therefore, their tabs would be created in the current workspace too, and one could navigate between such applications, within that same workspace, using any way reviewed in this step also.

'''''Step 10:'' Floating, dragging, tiling, fullscreen, etc'''.
* One may make a focused application to '''float''', and to toggle ''"floating"'' off as-and-when needed, with: {{ic|$mod+Shift+space}} . In our setup: {{Key|Window}}+{{Key|Shift}}+{{Key|Space}}.

* The {{Path|config}} file points out that one may ''"drag floating windows by holding down $mod and left mouse button"''. Seeing how {{ic|$mod}} was kept assigned as the {{Key|Window}} key: {{Key|Window}}+'''drag'''. The window needs to be floating first; in some instances, one may need to drag at the tab.

* One could make some applications to launch "floating" by default (optional). An application that is sometimes made to float by default is the {{Pkg|galculator}} calculator pad; just add:
:{{ic|<nowiki>for_window [app_id="galculator"] floating enable</nowiki>}}

* To toggle through '''tiled layouts''' within a workspace: {{ic|$mod+e}} / {{Key|Window}}+{{Key|e}}

* To return to '''full-sized tabs''' i.e. window-sized after being in a tiled layout, yet not fullscreen, thereby retaining toolbars, etc: {{ic|$mod+w}} / {{Key|Window}}+{{Key|w}} . Floating windows and fullscreen windows need to be toggled off first.

* To toggle in and out of '''fullscreen''': {{ic|$mod+f}} / {{Key|Window}}+{{Key|f}}

Take note of two final keybindings, or modify these first:

* To '''reload''' the '''Sway''' configuration file after editing it during a session: {{ic|$mod+Shift+c}} / {{Key|Window}}+{{Key|Shift}}+{{Key|c}}

* To '''exit''' '''Sway''' and the login session (save your work first): {{ic|$mod+Shift+e}} / {{Key|Window}}+{{Key|Shift}}+{{Key|e}}

'''''Step 11:'' Add variables and autostart instructions'''. These could be added to the beginning of this {{Path|config}} file. Typically, various environment variables would require being set before launching a '''Wayland''' compositor, for example, in {{Path|~/.profile}} . Do not add ampersands ('''&''') at the end of each line in {{Path|config}}, unlike with {{Path|.xinitrc}} syntax in '''Xorg'''.

{{Pkg|xwayland}}, if not required, can be disabled by inserting a line here to that effect. Alternatively, omit that line or comment it out by using a hashtag, as in the following example of autostart instructions, where '''Sway''' is assumed to have been launched [[Sway#Starting_Sway|using a {{ic|dbus-run-session}}]]; gui runlevel is started now if '''PipeWire''' and associated services are being [[PipeWire#Pipewire_user_service|launched as user services]]; and where '''chromium''' is also autostarted:

<Pre>
exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP=sway SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME
# xwayland disable
# Start gui runlevel for PipeWire and associated services to launch now
exec openrc -U gui
exec /usr/bin/chromium
</Pre>

{{Tip|Running ''"pure '''Wayland'''"'' – i.e. without the '''xwayland''' layer/package – may remove a possible attack surface. '''Xwayland''' could be required, however, to run certain '''Xorg'''-designed software, such as {{Pkg|xterm}}. One may also investigate '''libreoffice''' and '''okular''' functionality.}}

'''''Step 12:'' Install selected packages'''. Ensure that all mentioned applications have been installed: {{ic|apk info -e <var>package1</var> <var>package2</var>}}. Substitute entries in the following list with one's packages mentioned in the {{Path|config}} file:

{{Cmd|$ apk info -e foot wmenu chromium keepassxc corepad libreoffice okular thunar xterm galculator}}

'''wmenu''' was preserved for that listing; swap it out for '''rofi''' or otherwise, if necessary. One may have decided also not to include '''xterm''', etc.

Install any application not appearing in the output of that instruction.

For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].

=== PipeWire and Screensharing ===

The Sway compositor has no involvement with audio playback. In order for screensharing to work, [[PipeWire]] is required. Therefore, installing [[PipeWire#Installation|PipeWire]] is recommended for audio playback too.

Since v3.22, Alpine Linux provides the necessary scripts to start PipeWire as a [[OpenRC#user services|user service]] in OpenRC.

From a screensharing perspective, applications are split into two categories:-

* Those which use the native Wayland [https://wayland.app/protocols/wlr-screencopy-unstable-v1 wlr-screencopy] protocol
* Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).

Applications in the first group require no additional setup. Applications in the second group (which include Firefox and Chromium) require setting up ''xdg portals'' in addition to [[PipeWire#Installation|PipeWire]].

{{Cmd|# apk add xdg-desktop-portal xdg-desktop-portal-wlr}}

If you are using a <code>dbus-run-session</code> wrapper to launch Sway, you will also need to set D-Bus variables in order for the portal and for [[#PipeWire and Screensharing|screensharing]] features to work; add the following line to the beginning of Sway's {{Path|config}} file:

exec dbus-update-activation-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP SWAYSOCK I3SOCK XCURSOR_SIZE XCURSOR_THEME

The {{ic|XDG_CURRENT_DESKTOP}} environment variable may be set by various methods, including:-
* by amending its mention in that {{ic|dbus-update-activation-environment}} line, editing it to specify {{ic|XDG_CURRENT_DESKTOP{{=}}sway}} ; or
* by exporting it from within an applicable environment configuration file, such as:

:{{Cat| $XDG_CONFIG_HOME/.profile|<nowiki>
export XDG_CURRENT_DESKTOP=sway
</nowiki>}}

:However, this method is not universal, as it would require resetting the {{ic|XDG_CURRENT_DESKTOP}} variable for any different desktop/compositor/window manager that may be launched afterwards, possibly by employing a launcher similar to the wrapper script alternative described for '''Sway''' [[Sway#Automatically_Launch_Sway_on_tty1|below]]; or
* by being set automatically by the display manager, as is commonplace, but none is supplied by '''Sway'''.

=== Screen Lock and suspend-to-RAM ===

{{Tip| For a seat manager-agnostic and DE-/WM-agnostic tool, consider installing the {{Pkg|zzz}} utility, available in the [[Repositories#Community|community]] repository, or the {{Pkg|powerctl}} utility from the [[Repositories#Testing|testing]] repository, in order to manage suspend and hibernation.}}

Putting the system to sleep with the <Code>loginctl suspend</Code> command from [[Elogind]] requires elevated privileges or additional configuration.

To put the system to sleep after 600 seconds, use:

exec swayidle -w timeout 600 'doas /bin/loginctl suspend'

Do not lock the screen if program is running in full screen:

for_window [app_id="^.*"] inhibit_idle fullscreen

{{Todo|The option below, related to <Code>wayland-pipewire-idle-inhibit</Code>, needs to be tested. If you find the option below to be working, please remove this Todo.}}

If you do not want to lock the screen while media is being played through [[PipeWire]], then install the {{pkg|wayland-pipewire-idle-inhibit}} package, and add the following to Sway's {{Path|config}} file:

exec wayland-pipewire-idle-inhibit

Make changes to the {{Path|~/.config/wayland-pipewire-idle-inhibit/config.toml}} configuration file or to whichever configuration file you may have referenced instead through the <Code> --config <PATH></Code>, if required, as per the [https://github.com/rafaelrc7/wayland-pipewire-idle-inhibit?tab=readme-ov-file#config project's website].

=== Elogind and swayidle ===

<code>swayidle</code> has integration with <code>elogind</code>, and it can handle ''before-sleep'' events.

If using <code>swayidle before-sleep</code>, then there will be a race condition, so that when you resume the computer from ''suspend'', the screen will show the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.

To solve this issue, do the following.

Create the <code>/etc/elogind/system-sleep/10-swaylock.sh</code> file, and then add the following script to this file:
{{Cat|/etc/elogind/system-sleep/10-swaylock.sh|<nowiki>
#!/bin/sh
if [ "${1}" == "pre" ]; then
touch /tmp/swaylock-sleep
sleep 1
fi
</nowiki>}}

Then set it to executable.

Later, once Sway is installed, add the following line to its {{Path|config}} file:

exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep

With this line, the screen will be promptly locked before ''suspend-to-RAM'' starts.

=== Brightness Control ===

Refer to [[Backlight]] for information on brightness control.

=== Output Scaling for High Resolution Displays ===

Without further configuration, program interfaces may be too small to use on high resolution displays.

Sway supports the per-display configuration of:-

* fractional (e.g. 1.5x); and
* integer scaling (e.g. 2x)

However, fractional scaling is discouraged due both to the performance impact and to the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT-based toolkit scaling is recommended. See [[Sway#Toolkit Scaling|See below]].

==== Scaling with wdisplays ====

To enable Sway scaling, the user can first preview different scaling factors with the {{Pkg|wdisplays}} package. Note the output name (''eDP-1'', ''LVDS-1'') and try apply scaling factors such as 1 and 2. To make changes permanent, add the following line, completed with your settings, to Sway's {{Path|config}} file.

<pre>
output <name> scale <factor>
</pre>

==== Toolkit Scaling ====

To use toolkit scaling, say, at x2, add the following, for instance, to your {{Path|~/.profile}}:

# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2

# for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
# or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"

=== Notification Daemon ===

[[mako]] is a lightweight notification daemon that works seamlessly with Sway.

=== Screenshots ===

A simple tool that works well under Wayland is {{pkg|grimshot}}. Example keybindings:-

<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

See Sway's [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway wiki article] for a listing of further screenshot tools.

=== Make Clipboard Content Persistent ===

By default, the clipboard content does not persist after terminating the program: if you copy some text from Firefox and then exit Firefox, then the copied text is also lost.

Install {{Pkg|clipman}} from the community repo, and then add the following to Sway's {{Path|config}} file:

<pre>
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
</pre>

=== Firefox Picture-in-Picture Mode/Floating Windows ===

Add this to your Sway configuration file (modify the numeric values to suit your needs and your display):

<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Start with NumLock Enabled ===

Add the following to your Sway {{Path|config}} file:

input type:keyboard xkb_numlock enabled

=== Change mouse cursor theme and size ===

Add to your Sway {{Path|config}} file:

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

For example, set a mouse cursor using the '''GNOME Adwaita''' theme:

seat seat0 xcursor_theme Adwaita 16

You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your configuration does not result in change, try logging out and in.

{{Note|Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Custom Keyboard Layout ===

To use a custom keyboard layout, just use:

<pre>
input type:keyboard {
xkb_file /path/to/my/custom/layout
}
</pre>

=== Flatpaks ===

{{main|Flatpak}}

As mentioned in [[Flatpak#Portals|Flatpak]] page, install the minimal required portal related packages i.e {{pkg|xdg-desktop-portal}}, {{pkg|xdg-desktop-portal-gtk}} and {{pkg|xdg-desktop-portal-wlr}}. After installing the packages, add the following to the ''autostart'' section in your Sway {{Path|config}} file to avoid [[Flatpak#GDBus_Error|GDBus errors]].
<pre>
exec /usr/libexec/xdg-desktop-portal
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
</pre>

These startup instructions are only needed, if these are not started automatically via other means.

== Starting Sway ==

=== Manually Launch Sway ===

You can launch Sway manually by issuing the <Code>sway</Code> command from a TTY.

{{Cmd|$ sway}}

{{Tip|When using [[Wayland]], for [[PipeWire]] and screensharing to work in Firefox and Chromium, a [[D-Bus]] is required. In the absence of a [[OpenRC#User_services|user service manager]], consider running <Code>sway</Code> with <code>dbus-run-session</code>, a convenient wrapper that will explicitly export the path of the session bus.{{Cmd|$ dbus-run-session sway}}
}}

=== Automatically Launch Sway on tty1 ===

Adding the following lines to {{Path|~/.profile}} or to its equivalent will ensure that <Code>sway</Code> launches automatically, with a D-Bus, ''only'' from ''tty1''. This is handy for troubleshooting, because if the Sway configuration ever falters, one could troubleshoot by logging into a different TTY (''tty2''-''tty6''), and your startup script then will not attempt to launch the faulty Sway environment from there also.
{{Cat| ~/.profile|<nowiki>
...

if [ "$(tty)" = "/dev/tty1" ]; then
exec dbus-run-session sway
fi
...</nowiki>}}

=== Using a Wrapper Script to Launch Sway ===

Instead of using {{Path|~/.profile}} or its equivalent file, a [https://man.sr.ht/~kennylevinsen/greetd/#how-to-set-xdg_session_typewayland wrapper script] can be placed at {{Path|/usr/local/bin/sway-run}}. This script can be used to launch <Code>sway</Code> from either a TTY or by [[greetd]], a lightweight [[Display manager|display manager]], as follows: {{Cat|/usr/local/bin/sway-run|<nowiki>#!/bin/sh
# Session
export XDG_SESSION_TYPE=wayland
export XDG_SESSION_DESKTOP=sway
export XDG_CURRENT_DESKTOP=sway

# Wayland stuff
export MOZ_ENABLE_WAYLAND=1
export QT_QPA_PLATFORM=wayland
export SDL_VIDEODRIVER=wayland
export _JAVA_AWT_WM_NONREPARENTING=1

# Launch Sway with a D-Bus server
exec dbus-run-session sway "$@" </nowiki>}}

Make the file executable:
{{Cmd|# chmod +x /usr/local/bin/sway-run}}

== Troubleshooting ==

If you encounter any issues, try running <Code>sway -Vc /etc/sway/config</Code>. It will run <Code>sway</Code> with the default config file and set the output to be more verbose. It is generally a good idea to track your configuration files with ''git'' (if and when you use a remote repository for them, keep it private, for security reasons).

To capture the Sway error log in a file for troubleshooting, replace <code>sway</code> in your startup file by:

sway -d 2> ~/sway_error.log

Alternatively, you can also issue the below command from TTY.

{{Cmd|$ sway -d 2> ~/sway_error.log}}

=== Video Driver Issues ===

After installing Sway, and while launching it for the first time, a lack of appropriate [[#Install Graphics Drivers|video drivers]] may cause various error messages such as:

* "unable to create backend"
* "Failed to create renderer"

Install the necessary drivers in order for your [[#Install Graphics Drivers|graphics card]] to work with Sway.

=== XDG_RUNTIME_DIR is not set in the environment. Aborting ===

If [[seatd]] is used instead of [[elogind]], the error message '''XDG_RUNTIME_DIR is not set in the environment. Aborting''' might be encountered.

Ensure that the mandatory steps outlined in the [[Seatd]] wiki page are completed in order to set the [[XDG_RUNTIME_DIR]] variable.

=== No backend was able to open a seat ===

If no [[seat manager]] is available, then the error below will appear.

<Pre>
[libseat] [libseat/libseat.c:73] libseat_open_seat : No backend was able to open a seat
[backend/session/libseat.c:102] Unable to create seat : Function not implemented
[backend/backend.c:303] Failed to open any DRM device
[sway/server.c:49] Unable to create backend
</Pre>

Ensure that either [[Elogind]] or [[Seatd]] is properly configured and running.

=== Firefox (Flatpak) and/or GTK Apps ===

==== Disappearing Cursor ====

You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively, one could install an [https://pkgs.alpinelinux.org/packages?name=*-icon-theme&branch=edge&repo=&arch=x86_64&origin=&flagged=&maintainer= icon theme] package for all users.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Nvidia Issues ===

{{Draft|This section is partly outdated and could benefit from contributions in view of Nvidia's [https://docs.nvidia.com/drive/drive-os-5.2.3.0L/drive-os/index.html#page/DRIVE_OS_Linux_SDK_Development_Guide/Windows%20Systems/window_system_wayland.html current support] of Wayland. Help is encouraged.}}
{{Main|NVIDIA}}
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your <Code>WLR_BACKENDS</Code> environmental variables to <code>drm,libinput</code> or <code>x11</code> (add {{Pkg|libinput}} here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install {{Pkg|libinput}} first''').

== See also ==

* [https://github.com/swaywm/sway/wiki/ Sway Wiki]
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]

[[Category:Compositor]]

APKBUILD examples:Rust

2025-10-05T09:36:06Z

WhyNotHugo: Document fetching of deps

== Considerations ==

Use <code>cargo-auditable</code> to encode dependency information into binaries.

Most Rust projects use <code>cargo</code> to fetch Rust library dependencies. The current convention it to use <code>options="net"</code> fetch these during the <code>prepare()</code> phase. Use the <code>--locked</code> flag to ensure that the exact same versions of dependencies are fetched on each rebuild. If a package is missing a lockfile, include one with the aport and attempt to recommend upstream to include one.

== Examples ==

=== Basic example ===

<pre>
maintainer="Hugo Osvaldo Barrera <hugo@whynothugo.nl>"
pkgname=harper
pkgver=0.59.0
pkgrel=0
pkgdesc="Grammar checker that respects your privacy"
url="https://github.com/elijah-potter/harper"
arch="all"
license="Apache-2.0"
makedepends="cargo-auditable rust"
source="harper-$pkgver.tar.gz::https://github.com/elijah-potter/harper/archive/v$pkgver/harper-$pkgver.tar.gz"
options="net"

prepare() {
default_prepare

cargo fetch --target="$CTARGET" --locked
}

build() {
cargo auditable build --release --frozen
}

check() {
cargo test --frozen
}

package() {
install -Dm755 target/release/harper-cli "$pkgdir"/usr/bin/harper-cli
install -Dm755 target/release/harper-ls "$pkgdir"/usr/bin/harper-ls
}

sha512sums="
e5be781b33ba624e2447464a51ff8c0b565a42d7bf957c2fd6655f4bf312211fcf669bbb152b62a57494f89fd7fbee7eda37bbbaf7a61c5d4c8c9684ffe687bd harper-0.48.0.tar.gz
"
</pre>

== See also ==

* [[APKBUILD examples]]
* [[Creating an Alpine package]]

[[Category:Development]] [[Category:Rust]]

OpenRC

2025-09-05T16:14:20Z

WhyNotHugo: /* PAM support */ remove mistaken warning

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. <code>$XDG_CONFIG_HOME</code>, the fallback {{path|~/.config}} is used. is unset.

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-05T12:54:13Z

WhyNotHugo: /* Config files for user services */ hint on .profile

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. <code>$XDG_CONFIG_HOME</code>, the fallback {{path|~/.config}} is used. is unset.

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

{{Warning|Starting services via PAM will start them before the user session initialises, which can lead them to fail in unexpected way due to missing preconditions. E.g.: because the [[XDG_RUNTIME_DIR]] is not yet initialised.}}

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

Writing Init Scripts

2025-09-05T12:52:41Z

WhyNotHugo: /* Things to avoid */ this advice runs contrary to upstream advise, and users can still disable this by using 'unset' in conf.d

{{Draft}}

== Introduction ==

Alpine Linux uses the [https://github.com/OpenRC/openrc OpenRC] init system to start services. Don't confuse OpenRC init with our system init (the first process that is executed aka pid 1). Many of the current init.d script found in Alpine Linux are taken from Gentoo. If you want to save time you could search [https://packages.gentoo.org/categories Gentoo's repository] for an existing initscript for your service. You can also check [https://wiki.gentoo.org/wiki/Handbook:X86/Working/Initscripts#Writing_initscripts Gentoo's wiki] for some additional OpenRC information.

NOTE: OpenRC recently added [https://github.com/OpenRC/openrc/blob/master/service-script-guide.md documentation] on how to write proper Init scripts. Make sure you read it!

If you cannot find an init.d script from Gentoo, or you just want to start to write your own init.d scripts, we provide you with some basic information on how to write simple OpenRC init scripts.

Primary information about the OpenRC format can be found in the [https://manpages.org/openrc-run/8 OpenRC man page openrc-run].

<pre>
apk add openrc-doc
man openrc-run
</pre>

== Things to avoid ==

* Prefer standard OpenRC variables such as <code>command_args</code>, <code>command_user</code> etc. (see [https://www.mankier.com/8/openrc-run openrc-run(8)]); do not create unnecessary config variables like <code>FOO_OPTS</code>, <code>FOO_USER</code> etc. If you want to predefine the default value in init.d script, use common idiom <code>: ${command_user=foo}</code>.

* Use snake_case for naming extra configuration variables (to be consistent with the OpenRC variables and other init scripts in Alpine). Do not prefix them with the service name, try to be consistent with existing init scripts (e.g. <code>cfgfile</code>, <code>cfgdir</code>, <code>logfile</code>, <code>cachedir</code>, <code>listen_on</code>, <code>start_wait</code>, …).

== Minimal Templates ==

Every init.d script you write needs to start with a [https://en.wikipedia.org/wiki/Shebang_(Unix) shebang] like:

<code>#!/sbin/openrc-run</code>

=== Services relying on OpenRC exclusively ===

<pre>
#!/sbin/openrc-run

command=/path/to/command
</pre>

=== Services supervised by [https://www.skarnet.org/software/s6/ s6] ===

Notes:

* Install and configure the <code>s6-scan</code> service to start on system boot
* Exclude <code>start()</code>, <code>stop()</code> and <code>status()</code> functions in order for s6 supervision to work reliably. OpenRC has built-in equivalent functions which invoke the necessary s6 commands.
* Include a <code>depend()</code> stanza to ensure that the <code>s6-svscan</code> service is already running.
* Add a <code>start_pre()</code> stanza to symlink the service directory into the scan directory, because the <code>/etc/init.d/bootmisc</code> scripts cleans out the <code>/run</code> directory on system boot.

<pre>
#!/sbin/openrc-run

name="foo"
supervisor="s6"
s6_service_path="${RC_SVCDIR}/s6-scan/${name}"

depend() {
need s6-svscan
}

start_pre() {
if [ ! -L "${RC_SVC_DIR}/s6-scan/${name}" ]; then
ln -s "/path/to/${name}/service/dir" "${RC_SVCDIR}/s6-scan/${name}"
fi
}
</pre>

The rest of the below basic example could be omitted, but that would most probably leave you with an non working initd script.

== Basic example ==

<pre>
#!/sbin/openrc-run

name=$RC_SVCNAME
cfgfile="/etc/$RC_SVCNAME/$RC_SVCNAME.conf"
command="/usr/bin/my_daemon"
command_args="--my-daemon-args"
command_user="my_system_user"
pidfile="/run/$RC_SVCNAME/$RC_SVCNAME.pid"
start_stop_daemon_args="--args-for-start-stop-daemon"
command_background="yes"

depend() {
need net
}

start_pre() {
checkpath --directory --owner $command_user:$command_user --mode 0775 \
/run/$RC_SVCNAME /var/log/$RC_SVCNAME
}
</pre>

== start, stop, restart functions ==

OpenRC defined a few basic functions ie: start, stop, restart. These functions are defined by default but can be overwritten by defining your own set of functions.
This is generally only necessary if you want to do something special which is not provided by the default start/stop/restart implementations.

=== start ===

<pre>
start() {
ebegin "Starting mydaemon"
start-stop-daemon --start \
--exec /usr/sbin/mydaemon \
--pidfile /var/run/mydaemon.pid \
-- \
--args-for-mydaemon
eend $?
}
</pre>

=== stop ===

=== restart ===

== Daemon, Forking, Logging ==

TODO...

[[Category:Booting]]

OpenRC

2025-09-05T12:50:57Z

WhyNotHugo: /* PAM support */ warn about pam initialising services

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. <code>$XDG_CONFIG_HOME</code>, the fallback {{path|~/.config}} is used. is unset.

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

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

{{Warning|Starting services via PAM will start them before the user session initialises, which can lead them to fail in unexpected way due to missing preconditions. E.g.: because the [[XDG_RUNTIME_DIR]] is not yet initialised.}}

== 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-05T12:44:50Z

WhyNotHugo: /* Runlevels */ also refer to pam as an option

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. <code>$XDG_CONFIG_HOME</code>, the fallback {{path|~/.config}} is used. is unset.

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

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-05T12:43:20Z

WhyNotHugo: /* User services */ Fix improperly closed tag

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. <code>$XDG_CONFIG_HOME</code>, the fallback {{path|~/.config}} is used. is unset.

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

==== 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-05T12:42:47Z

WhyNotHugo: /* Config files for user services */ describe runlevels

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. <code>$XDG_CONFIG_HOME<code>, the fallback {{path|~/.config}} is used. is unset.

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

==== 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-05T12:34:55Z

WhyNotHugo: /* Configure environment variables */ 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|~/.config}}, if $XDG_CONFIG_HOME is unset. Adjust below instructions, if $XDG_CONFIG_HOME differs. The main configuration file for OpenRC User services is {{path|~/.config/rc/rc.conf}} and {{Path|~/.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 {{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-05T12:34:00Z

WhyNotHugo: /* PAM support */ clarify that this is not mandatory

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|~/.config}}, if $XDG_CONFIG_HOME is unset. Adjust below instructions, if $XDG_CONFIG_HOME differs. The main configuration file for OpenRC User services is {{path|~/.config/rc/rc.conf}} and {{Path|~/.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 {{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. Eventhough [[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]]

Logbookd

2025-09-03T12:56:09Z

WhyNotHugo: /* See also */ Link to Syslog

[https://sr.ht/~martijnbraam/logbookd/ logbookd] is a syslogd implementation that uses an sqlite database as a backend.

The default mode of operation uses a reduced write mode, where lots are written to memory and only flushed to disk when the service is interrupted or receives SIGUSR1.

== Setup ==

Logbook is provided via the {{pkg|logbookd}} package.

Setting it up is quite straightforward:

apk add logbookd

# Disable and stop the default syslog.
rc-update del syslog boot
service syslog stop

# Enable and start logbookd
rc-update add logbookd boot
service logbookd start

After the next reboot, you may want to review previous log files in <code>/var/log</code>, which will remain unused and stale. Only the sqlite database should remain relevant.

= See also =

* [https://blog.brixit.nl/looking-closer-at-the-syslog/ Looking closer at the syslog]: an introductory article to syslog and logbookd.
* [[Syslog]]

[[Category:Services]]

Syslog

2025-09-03T12:55:36Z

WhyNotHugo: Mention s6-socklog

{{TOC right}}

Syslog collects log data from multiple programs either to RAM or to a file, and handles log rotation (similar to <code>journald</code> on systemd-based systems). Alpine installs <code>syslog</code> as provided by {{pkg|busybox}} per default, but it also packages [https://pkgs.alpinelinux.org/packages?name=*syslog* other implementations], such as {{pkg|rsyslog}}, {{pkg|syslog-ng}}, [https://skarnet.org/software/s6/s6-socklog.html s6-socklog] (from {{pkg|s6}}) and [[logbookd]].

== busybox syslog ==
=== Running syslogd ===
Depending on how you have installed Alpine, it is already running (check with <code>ps a | grep syslogd</code>). Otherwise enable it at boot and start it with the following commands:

{{cmd|<nowiki># rc-update add syslog boot
# rc-service syslog start
</nowiki>}}

=== Configuration ===
Edit {{path|/etc/conf.d/syslog}} to change the options used when running <code>syslogd</code>. All available options can be looked up with <code>syslogd --help</code>.

=== Reading logs ===
{{cmd|<nowiki># tail -f /var/log/messages
Shows all messages and follows the log
# tail -f /var/log/messages | grep ssh
Only shows SSH related messages, also follows the log
</nowiki>}}

When <code>-C</code> is enabled in the configuration:
{{cmd|<nowiki># logread -f
# logread -f | grep ssh
</nowiki>}}

== Writing logs ==
Many applications are able to write to the syslog by default (e.g. <code>sshd</code>). If you wish to write manually to it, use the <code>logger</code> program.

{{cmd|$ logger "hello world"}}

== See also ==
* [https://wiki.gentoo.org/wiki/Logging Gentoo Wiki - Logging]

[[category:System Administration]]

Steam

2025-09-02T22:05:05Z

WhyNotHugo: /* Installation */ -> Installation via Flatpak

This page explains how to run [https://store.steampowered.com/about/ Steam], a popular game distribution platform by Valve on Alpine Linux. Steam requires glibc to run, and thus won't run natively on Alpine Linux. The simplest approach is to run it as [[Flatpak]]. Other workarounds involve using a virtual machine, a chroot or a container. It is theoretically possible to run the windows version of Steam using {{Pkg|wine}}.

== Installation via Flatpak ==

# Follow the [[Flatpak#Installing_Flatpak|Flatpak]] wiki page and ensure that [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.
# Install the Steam flatpak package from Flathub.{{Cmd|$ flatpak --user install com.valvesoftware.Steam}}
# After installation Steam can be started either using it's .desktop file or from the command line: {{Cmd|$ flatpak run com.valvesoftware.Steam}}

== Troubleshooting ==

=== My controllers aren't detected ===

By default Steam doesn't have permission to read your controllers.
This can be fixed by installing an [[udev]] rule from the official Steam package, but the udev rules are also available as an Alpine package.

# apk add {{pkg|steam-devices|arch=x86_64}}

These udev rules rely on the <code>TAG+="uaccess"</code>, and are therefore only expected to work reliably when using [[Elogind]].

=== SteamVR won't launch ===

Out of the box SteamVR might not be able to launch and give you various errors. Steam tries to fix this itself by setting the right capabilities on the SteamVR binary, but this doesn't work in the Flatpak. Instead we'll have do it manually.

# setcap CAP_SYS_NICE+ep ~/.var/app/com.valvesoftware.Steam/data/Steam/steamapps/common/SteamVR/bin/linux64/vrcompositor-launcher

Then restart Steam.

There is an issue for this [https://github.com/flathub/com.valvesoftware.Steam/issues/636#issuecomment-779763326 on the Flathub repository].

=== Steam - Error: OpenGL GLX extension not supported by display ===

Add the Mesa gallium driver and reboot your system.

# apk add {{pkg|mesa-dri-gallium|arch=x86_64}}

=== eventfd: Too many open files ===

Due to a low amount of allowed open file descriptors, Proton games may crash shortly after launching. This can be worked around by disabling esync but many games will perform measurably worse without it. Instead, user limits should be increased. In order to do this, you will need [[PAM]] and a PAM enabled login.

Add the following to <code>/etc/security/limits.conf</code>:
@users hard nofile 524288

{{Note|Although you should already belong to the users group, you can run <code>groups</code> to check.}}

Reboot and run <code>ulimit -Hn</code> to verify the new limits are applied.

=== dbus-launch: no such file or directory ===

Set up [[D-Bus|dbus]] for your session.

=== Steam games launched via Proton crash before creating a window ===

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.

As your last resort, you can try installing [https://github.com/GloriousEggroll/proton-ge-custom proton-ge-custom], but please note that in order for this to be even detected by Steam, you will need to install Steam via Nix due to high level of isolation that Flatpaks utilize. This can however come at the expense of your [https://tosdr.org/en/service/180 privacy].

=== Steam spams dmesg with x86/split lock detection entries ===

Add the below line to {{path|/etc/sysctl.conf}}:
kernel.split_lock_mitigate = 0

=== Steam hangs on start with a steamwebhelper popup ===

If this happens and {{path|~/.var/app/com.valvesoftware.Steam/.local/share/Steam/logs/steamwebhelper.log}} says that you are missing X server or <var>DISPLAY</var>, it means your <var>DISPLAY</var> is not present in the activation environment. For more information please see https://github.com/ValveSoftware/steam-for-linux/issues/10554

'''[[Sway]]''': go into your sway config file and add <var>DISPLAY</var> to the following line, then restart:
<pre>exec dbus-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway</pre>
For more information about this line, please see the Alpine Wiki's entry on Sway

'''Hyprland''': add an exec-once to the configuration file at {{path|~/.config/hypr/hyprland}} to set <var>DISPLAY</var>. Similarly to Sway you may already have a line that sets other variables. If so, add <var>DISPLAY</var> to the line. The line should look similar to this:

<pre>exec-once = dbus-update-activation-environment DISPLAY</pre>

== See Also ==
* [[Gaming on Alpine|Gaming on Alpine Linux]]
* [[Flatpak]]
* [https://wiki.postmarketos.org/wiki/Steam Steam on postmarketOS]

[[category:Gaming]]

Steam

2025-09-02T22:04:46Z

WhyNotHugo: Mention other alternatives to flatpak

This page explains how to run [https://store.steampowered.com/about/ Steam], a popular game distribution platform by Valve on Alpine Linux. Steam requires glibc to run, and thus won't run natively on Alpine Linux. The simplest approach is to run it as [[Flatpak]]. Other workarounds involve using a virtual machine, a chroot or a container. It is theoretically possible to run the windows version of Steam using {{Pkg|wine}}.

== Installation ==

# Follow the [[Flatpak#Installing_Flatpak|Flatpak]] wiki page and ensure that [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.
# Install the Steam flatpak package from Flathub.{{Cmd|$ flatpak --user install com.valvesoftware.Steam}}
# After installation Steam can be started either using it's .desktop file or from the command line: {{Cmd|$ flatpak run com.valvesoftware.Steam}}

== Troubleshooting ==

=== My controllers aren't detected ===

By default Steam doesn't have permission to read your controllers.
This can be fixed by installing an [[udev]] rule from the official Steam package, but the udev rules are also available as an Alpine package.

# apk add {{pkg|steam-devices|arch=x86_64}}

These udev rules rely on the <code>TAG+="uaccess"</code>, and are therefore only expected to work reliably when using [[Elogind]].

=== SteamVR won't launch ===

Out of the box SteamVR might not be able to launch and give you various errors. Steam tries to fix this itself by setting the right capabilities on the SteamVR binary, but this doesn't work in the Flatpak. Instead we'll have do it manually.

# setcap CAP_SYS_NICE+ep ~/.var/app/com.valvesoftware.Steam/data/Steam/steamapps/common/SteamVR/bin/linux64/vrcompositor-launcher

Then restart Steam.

There is an issue for this [https://github.com/flathub/com.valvesoftware.Steam/issues/636#issuecomment-779763326 on the Flathub repository].

=== Steam - Error: OpenGL GLX extension not supported by display ===

Add the Mesa gallium driver and reboot your system.

# apk add {{pkg|mesa-dri-gallium|arch=x86_64}}

=== eventfd: Too many open files ===

Due to a low amount of allowed open file descriptors, Proton games may crash shortly after launching. This can be worked around by disabling esync but many games will perform measurably worse without it. Instead, user limits should be increased. In order to do this, you will need [[PAM]] and a PAM enabled login.

Add the following to <code>/etc/security/limits.conf</code>:
@users hard nofile 524288

{{Note|Although you should already belong to the users group, you can run <code>groups</code> to check.}}

Reboot and run <code>ulimit -Hn</code> to verify the new limits are applied.

=== dbus-launch: no such file or directory ===

Set up [[D-Bus|dbus]] for your session.

=== Steam games launched via Proton crash before creating a window ===

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.

As your last resort, you can try installing [https://github.com/GloriousEggroll/proton-ge-custom proton-ge-custom], but please note that in order for this to be even detected by Steam, you will need to install Steam via Nix due to high level of isolation that Flatpaks utilize. This can however come at the expense of your [https://tosdr.org/en/service/180 privacy].

=== Steam spams dmesg with x86/split lock detection entries ===

Add the below line to {{path|/etc/sysctl.conf}}:
kernel.split_lock_mitigate = 0

=== Steam hangs on start with a steamwebhelper popup ===

If this happens and {{path|~/.var/app/com.valvesoftware.Steam/.local/share/Steam/logs/steamwebhelper.log}} says that you are missing X server or <var>DISPLAY</var>, it means your <var>DISPLAY</var> is not present in the activation environment. For more information please see https://github.com/ValveSoftware/steam-for-linux/issues/10554

'''[[Sway]]''': go into your sway config file and add <var>DISPLAY</var> to the following line, then restart:
<pre>exec dbus-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway</pre>
For more information about this line, please see the Alpine Wiki's entry on Sway

'''Hyprland''': add an exec-once to the configuration file at {{path|~/.config/hypr/hyprland}} to set <var>DISPLAY</var>. Similarly to Sway you may already have a line that sets other variables. If so, add <var>DISPLAY</var> to the line. The line should look similar to this:

<pre>exec-once = dbus-update-activation-environment DISPLAY</pre>

== See Also ==
* [[Gaming on Alpine|Gaming on Alpine Linux]]
* [[Flatpak]]
* [https://wiki.postmarketos.org/wiki/Steam Steam on postmarketOS]

[[category:Gaming]]