Alpine Linux - User contributions [en]

KDE

2025-11-21T05:28:35Z

Encode: /* Prerequisites */ Change wording

[[File:KDEScreenshot.png|thumb|KDE Plasma screenshot.]]

[https://kde.org/plasma-desktop/ Plasma] is the desktop environment from [https://kde.org/ KDE], a software project comprising of a collection of libraries known as [https://develop.kde.org/products/frameworks/ KDE Frameworks], and several applications known as [https://apps.kde.org/ KDE Applications]. Their [https://userbase.kde.org/Welcome_to_KDE_UserBase UserBase wiki] has detailed information about most KDE Applications.

== Prerequisites ==

{{Tip|Everything but the first two and last two, are automatically handled if Plasma desktop is installed using [[#setup-desktop|setup-desktop]].}}

{{:Include:Desktop prerequisites}}
* Enable [[Elogind]] service
* If you need Xwayland and [[Xorg]], run [[Alpine_setup_scripts#setup-xorg-base|setup-xorg-base]].
* Wayland users: Install package {{pkg|xf86-input-libinput|arch=}}

== Installation ==

{{Note|The {{Pkg|plasma-desktop-meta|arch=}} package, which is used by {{Ic|setup-desktop}}, isn't available for the {{Ic|armhf}} or {{Ic|s390x}} [[Alpine_Linux:Overview#Architectures|architectures]]. However, the rest of Plasma may be installed separately to potentially get a functional desktop.}}

=== setup-desktop ===

{{:Include:Setup-desktop}}
When Plasma is chosen, the above script additionally installs [[PipeWire]] for audio and [[SDDM]] as display manager.

=== Manual ===

The following command will install the Plasma desktop as specified by the plasma metapackage, including the {{Pkg|sddm|arch=}} display manager and other assorted niceties. {{Cmd|# apk add {{pkg|plasma-desktop-meta|arch=}}}}
{{Note|'''polkit''' and '''udev''' are optional services for authentication and device management respectively. While KDE will function without these services enabled, some functionality may be missing or incomplete.}}

== KDE Applications ==

To install the full set of KDE Applications, install {{Pkg|kde-applications}}. You can also choose to install a smaller set of applications by installing any of the subpackages:

{{Note|{{Pkg|kde-applications-edu|arch=}}, {{Pkg|kde-applications-network|arch=}} and {{Pkg|kde-applications-pim|arch=}} are not available on the {{Ic|ppc64le}} or {{Ic|s390x}} [[Alpine_Linux:Overview#Architectures|architectures]].}}

* {{Pkg|kde-applications-accessibility|arch=}}
* {{Pkg|kde-applications-admin|arch=}}
* {{Pkg|kde-applications-base|arch=}}
* {{Pkg|kde-applications-edu|arch=}}
* {{Pkg|kde-applications-games|arch=}}
* {{Pkg|kde-applications-graphics|arch=}}
* {{Pkg|kde-applications-multimedia|arch=}}
* {{Pkg|kde-applications-network|arch=}}
* {{Pkg|kde-applications-pim|arch=}}
* {{Pkg|kde-applications-sdk|arch=}}
* {{Pkg|kde-applications-utils|arch=}}
* {{Pkg|kde-applications-webdev|arch=}}

== Starting Plasma ==

Plasma can be started using a display manager or from the console.

=== Using a display manager ===

When Plasma is installed via the plasma meta-package, the display manager is set up using sddm.

Make sure you enable and start the SDDM service.

{{Cmd|<nowiki># rc-update add sddm
# rc-service sddm start </nowiki>}}

* Select ''Plasma'' to launch a new session in Wayland
* Select ''Plasma (X11)'' to launch a new session in Xorg

=== From the console ===

For the Wayland session run:

{{Cmd|$ XDG_SESSION_TYPE{{=}}wayland dbus-run-session startplasma-wayland}}

The Xorg session can be launched by installing {{Pkg|xinit|arch=}} and appending {{Ic|exec startplasma-x11}} to your {{Path|.xinitrc}} file. To start X:

{{Cmd|$ xinit}}

== Discover ==

[https://userbase.kde.org/Discover Discover] is the application installer from KDE. The alpine linux package {{pkg|discover}} is automatically installed if {{pkg|plasma-desktop-meta|arch=}} package is installed or if [[#setup-desktop|setup-desktop]] is used to install Plasma.

Install the packages {{pkg|discover-backend-apk}} and {{pkg|discover-backend-flatpak}} to use Discover as a graphical interface to [[Alpine Package Keeper]] and [[Flatpak]] respectively.

== Troubleshooting ==

=== HiDPI Scaling ===

When using high resolution screens, e.g. 4K, you might need to apply scaling so the fonts and windows are not too small.

In order to achieve this you can open {{Ic|Settings -> Display and Monitor}} and change the slider under ''Global Scale'' to an appropriate value.

You can also change the mouse cursor and icon size under {{Ic|Settings -> Appearance}}.

If your taskbar and window decorations are still too small, you might want to create the file {{path|~/.xprofile}} to define the ''PLASMA_USE_QT_SCALING'' environment variable:{{Cmd|export PLASMA_USE_QT_SCALING{{=}}1}}

After creating this file, you may need to restart your session to apply this modification.

== See also ==

* [[Installation#Post-Installation|Post installation]]
* [[Flatpak]]
* [https://wiki.archlinux.org/title/KDE KDE - Archwiki]

[[Category:Desktop Environments]]

KDE

2025-11-21T03:42:26Z

Encode: General wiki style

[[File:KDEScreenshot.png|thumb|KDE Plasma screenshot.]]

[https://kde.org/plasma-desktop/ Plasma] is the desktop environment from [https://kde.org/ KDE], a software project comprising of a collection of libraries known as [https://develop.kde.org/products/frameworks/ KDE Frameworks], and several applications known as [https://apps.kde.org/ KDE Applications]. Their [https://userbase.kde.org/Welcome_to_KDE_UserBase UserBase wiki] has detailed information about most KDE Applications.

== Prerequisites ==

{{Tip|Except for the first two ''Prerequisites'', all the others are automatically handled if Plasma desktop is installed using [[#setup-desktop|setup-desktop]] script.}}

{{:Include:Desktop prerequisites}}
* Enable [[Elogind]] service
* For users interested in Xorg as opposed to Wayland, install the [[Alpine_setup_scripts#setup-xorg-base|Xorg base packages]]
* Wayland users: Install package {{pkg|xf86-input-libinput|arch=}}

== Installation ==

{{Note|The {{Pkg|plasma-desktop-meta|arch=}} package, which is used by {{Ic|setup-desktop}}, isn't available for the {{Ic|armhf}} or {{Ic|s390x}} [[Alpine_Linux:Overview#Architectures|architectures]]. However, the rest of Plasma may be installed separately to potentially get a functional desktop.}}

=== setup-desktop ===

{{:Include:Setup-desktop}}
When Plasma is chosen, the above script additionally installs [[PipeWire]] for audio and [[SDDM]] as display manager.

=== Manual ===

The following command will install the Plasma desktop as specified by the plasma metapackage, including the {{Pkg|sddm|arch=}} display manager and other assorted niceties. {{Cmd|# apk add {{pkg|plasma-desktop-meta|arch=}}}}
{{Note|'''polkit''' and '''udev''' are optional services for authentication and device management respectively. While KDE will function without these services enabled, some functionality may be missing or incomplete.}}

== KDE Applications ==

To install the full set of KDE Applications, install {{Pkg|kde-applications}}. You can also choose to install a smaller set of applications by installing any of the subpackages:

{{Note|{{Pkg|kde-applications-edu|arch=}}, {{Pkg|kde-applications-network|arch=}} and {{Pkg|kde-applications-pim|arch=}} are not available on the {{Ic|ppc64le}} or {{Ic|s390x}} [[Alpine_Linux:Overview#Architectures|architectures]].}}

* {{Pkg|kde-applications-accessibility|arch=}}
* {{Pkg|kde-applications-admin|arch=}}
* {{Pkg|kde-applications-base|arch=}}
* {{Pkg|kde-applications-edu|arch=}}
* {{Pkg|kde-applications-games|arch=}}
* {{Pkg|kde-applications-graphics|arch=}}
* {{Pkg|kde-applications-multimedia|arch=}}
* {{Pkg|kde-applications-network|arch=}}
* {{Pkg|kde-applications-pim|arch=}}
* {{Pkg|kde-applications-sdk|arch=}}
* {{Pkg|kde-applications-utils|arch=}}
* {{Pkg|kde-applications-webdev|arch=}}

== Starting Plasma ==

Plasma can be started using a display manager or from the console.

=== Using a display manager ===

When Plasma is installed via the plasma meta-package, the display manager is set up using sddm.

Make sure you enable and start the SDDM service.

{{Cmd|<nowiki># rc-update add sddm
# rc-service sddm start </nowiki>}}

* Select ''Plasma'' to launch a new session in Wayland
* Select ''Plasma (X11)'' to launch a new session in Xorg

=== From the console ===

For the Wayland session run:

{{Cmd|$ XDG_SESSION_TYPE{{=}}wayland dbus-run-session startplasma-wayland}}

The Xorg session can be launched by installing {{Pkg|xinit|arch=}} and appending {{Ic|exec startplasma-x11}} to your {{Path|.xinitrc}} file. To start X:

{{Cmd|$ xinit}}

== Discover ==

[https://userbase.kde.org/Discover Discover] is the application installer from KDE. The alpine linux package {{pkg|discover}} is automatically installed if {{pkg|plasma-desktop-meta|arch=}} package is installed or if [[#setup-desktop|setup-desktop]] is used to install Plasma.

Install the packages {{pkg|discover-backend-apk}} and {{pkg|discover-backend-flatpak}} to use Discover as a graphical interface to [[Alpine Package Keeper]] and [[Flatpak]] respectively.

== Troubleshooting ==

=== HiDPI Scaling ===

When using high resolution screens, e.g. 4K, you might need to apply scaling so the fonts and windows are not too small.

In order to achieve this you can open {{Ic|Settings -> Display and Monitor}} and change the slider under ''Global Scale'' to an appropriate value.

You can also change the mouse cursor and icon size under {{Ic|Settings -> Appearance}}.

If your taskbar and window decorations are still too small, you might want to create the file {{path|~/.xprofile}} to define the ''PLASMA_USE_QT_SCALING'' environment variable:{{Cmd|export PLASMA_USE_QT_SCALING{{=}}1}}

After creating this file, you may need to restart your session to apply this modification.

== See also ==

* [[Installation#Post-Installation|Post installation]]
* [[Flatpak]]
* [https://wiki.archlinux.org/title/KDE KDE - Archwiki]

[[Category:Desktop Environments]]

Talk:KDE

2025-11-20T21:05:12Z

Encode: /* When is {{Ic|xf86-input-libinput}} needed? */ new section

==Note on reversion of edit id 26401==
Romw314, I reverted your edit because apk template does not allow a display string different from the package being linked to, the apk command as written int the article {{ic|# apk add plasma}} is correct; the actual package name though is {{pkg|plasma-desktop-meta|arch=}}. It might be possible to change the command to the latter in order to have the display string and the package name match though... Will look into it shortly.
–[[User:zcrayfish|zcrayfish]] ([[User talk:zcrayfish|talk]]•[[Special:Contributions/zcrayfish|contribs]]•[[Special:EmailUser/zcrayfish|send email]]) 04:29, 17 February 2024 (UTC)

== Should this page be renamed to Plasma ==

Since KDE has adopted Plasma as the name of the Desktop, should we change the page name from KDE to Plasma. I don't see this wiki page has any relevance to KDE project and instead it's all about Plasma Desktop and KDE Addons and KDE Applications.
[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 09:10, 11 August 2024 (UTC)

== When is {{Ic|xf86-input-libinput}} needed? ==

What situation is this needed for? It was added in [https://wiki.alpinelinux.org/w/index.php?title=KDE&diff=prev&oldid=26364 26364] because of {{Issue|15006#note_317477}}, updated in [https://wiki.alpinelinux.org/w/index.php?title=KDE&diff=prev&oldid=26391 26391] and changed to say it's only for Wayland users because {{Ic|setup-xorg-base}} would already install this. I have KDE installed and inputs work without this. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 21:05, 20 November 2025 (UTC)

KDE

2025-11-20T20:43:30Z

Encode: Update supported architectures

[[File:KDEScreenshot.png |thumb |KDE Plasma screenshot.]]

[https://kde.org/plasma-desktop/ Plasma] is the desktop environment from [https://kde.org/ KDE], a software project comprising of a collection of libraries known as [https://develop.kde.org/products/frameworks/ KDE Frameworks], and several applications known as [https://apps.kde.org/ KDE Applications]. Their [https://userbase.kde.org/Welcome_to_KDE_UserBase UserBase wiki] has detailed information about most KDE Applications.

== Prerequisites ==
{{:Include:Desktop prerequisites}}
* For users interested in Xorg as opposed to Wayland, install the [[Alpine_setup_scripts#setup-xorg-base|Xorg base packages]]
* Enable [[Elogind]] service
* Wayland users: Install package {{pkg|xf86-input-libinput|arch=}}
{{Tip|Except for the first two [[#Prerequisites|Prerequisites]], all the others are automatically handled if Plasma desktop is [[#Installation using setup-desktop|installed using setup-desktop]] script.}}

== Installation ==

{{Note|The {{Pkg|plasma-desktop-meta|arch=}} package, which is used by {{Ic|setup-desktop}}, isn't available for the {{Ic|armhf}} or {{Ic|s390x}} architectures. However, the rest of Plasma may be installed separately to potentially get a functional desktop.}}

=== setup-desktop ===

{{:Include:Setup-desktop}}
When Plasma is chosen, the above script additionally installs [[PipeWire]] for audio and [[SDDM]] as display manager.

=== Manual ===

The following command will install the Plasma desktop as specified by the plasma metapackage, including the {{Pkg|sddm|arch=}} display manager and other assorted niceties. {{Cmd|# apk add {{pkg|plasma-desktop-meta|arch=}}}}
{{Note|'''polkit''' and '''udev''' are optional services for authentication and device management respectively. While KDE will function without these services enabled, some functionality may be missing or incomplete.}}

== KDE Applications ==

To install the full set of KDE Applications, install {{Pkg|kde-applications}}. You can also choose to install a smaller set of applications by installing any of the subpackages:

{{Note|{{Pkg|kde-applications-edu|arch=}}, {{Pkg|kde-applications-network|arch=}} and {{Pkg|kde-applications-pim|arch=}} are not available on {{Ic|ppc64le}} or {{Ic|s390x}}.}}

* {{Pkg|kde-applications-accessibility|arch=}}
* {{Pkg|kde-applications-admin|arch=}}
* {{Pkg|kde-applications-base|arch=}}
* {{Pkg|kde-applications-edu|arch=}}
* {{Pkg|kde-applications-games|arch=}}
* {{Pkg|kde-applications-graphics|arch=}}
* {{Pkg|kde-applications-multimedia|arch=}}
* {{Pkg|kde-applications-network|arch=}}
* {{Pkg|kde-applications-pim|arch=}}
* {{Pkg|kde-applications-sdk|arch=}}
* {{Pkg|kde-applications-utils|arch=}}
* {{Pkg|kde-applications-webdev|arch=}}

== Starting Plasma ==

Plasma can be started using a display manager or from the console.

=== Using a display manager ===

When Plasma is installed via the plasma meta-package, the display manager is set up using sddm.

Make sure you enable and start the SDDM service.

{{Cmd|rc-update add sddm
rc-service sddm start
}}

* Select ''Plasma'' to launch a new session in Wayland
* Select ''Plasma (X11)'' to launch a new session in Xorg

=== From the console ===

The Xorg session can be launched by installing {{Pkg|xinit|arch=}} and appending <code>exec startplasma-x11</code> to your <code>.xinitrc</code> file. To start X:
{{Cmd|xinit}}

For the Wayland session run
{{Cmd|XDG_SESSION_TYPE{{=}}wayland dbus-run-session startplasma-wayland}}

== Discover ==

[https://userbase.kde.org/Discover Discover] is the application installer from KDE. The alpine linux package {{pkg|discover}} is automatically installed if {{pkg|plasma-desktop-meta|arch=}} package is installed or if [[#setup-desktop|setup-desktop]] is used to install Plasma.

Install the packages {{pkg|discover-backend-apk}} and {{pkg|discover-backend-flatpak}} to use Discover as a graphical interface to [[Alpine Package Keeper]] and [[Flatpak]] respectively.

== Troubleshooting ==

=== HiDPI Scaling ===

When using high resolution screens, e.g. 4K, you might need to apply scaling so the fonts and windows are not too small.

In order to achieve this you can open <code>Settings -> Display and Monitor</code> and change the slider under ''Global Scale'' to an appropriate value.

You can also change the mouse cursor and icon size under <code>Settings -> Appearance</code>.

If your taskbar and window decorations are still too small, you might want to create the file {{path|~/.xprofile}} to define the ''PLASMA_USE_QT_SCALING'' environment variable:{{Cmd|export PLASMA_USE_QT_SCALING{{=}}1}}

After creating this file, you may need to restart your session to apply this modification.

== See also ==

* [[Installation#Post-Installation|Post installation]]
* [[Flatpak]]
* [https://wiki.archlinux.org/title/KDE KDE - Archwiki]

[[Category:Desktop Environments]]

KDE

2025-11-20T20:07:44Z

Encode: Put ‘setup-desktop’ and ‘Manual’ under ‘Installation’

[[File:KDEScreenshot.png |thumb |KDE Plasma screenshot.]]

[https://kde.org/plasma-desktop/ Plasma] is the desktop environment from [https://kde.org/ KDE], a software project comprising of a collection of libraries known as [https://develop.kde.org/products/frameworks/ KDE Frameworks], and several applications known as [https://apps.kde.org/ KDE Applications]. Their [https://userbase.kde.org/Welcome_to_KDE_UserBase UserBase wiki] has detailed information about most KDE Applications.

{{Note|the {{Pkg|plasma-desktop-meta|arch=}} package isn't available for the <code>ppc64le</code>, <code>s390x</code>, <code>armhf</code>, or <code>riscv64</code> architectures due to the {{Pkg|kdeplasma-addons|arch=}} dependency not being available there. However, the rest of Plasma may be installed separately to potentially get a functional desktop.}}

== Prerequisites ==
{{:Include:Desktop prerequisites}}
* For users interested in Xorg as opposed to Wayland, install the [[Alpine_setup_scripts#setup-xorg-base|Xorg base packages]]
* Enable [[Elogind]] service
* Wayland users: Install package {{pkg|xf86-input-libinput|arch=}}
{{Tip|Except for the first two [[#Prerequisites|Prerequisites]], all the others are automatically handled if Plasma desktop is [[#Installation using setup-desktop|installed using setup-desktop]] script.}}

== Installation ==

=== setup-desktop ===

{{:Include:Setup-desktop}}
When Plasma is chosen, the above script additionally installs [[PipeWire]] for audio and [[SDDM]] as display manager.

=== Manual ===

The following command will install the Plasma desktop as specified by the plasma metapackage, including the {{Pkg|sddm|arch=}} display manager and other assorted niceties. {{Cmd|# apk add {{pkg|plasma-desktop-meta|arch=}}}}
{{Note|'''polkit''' and '''udev''' are optional services for authentication and device management respectively. While KDE will function without these services enabled, some functionality may be missing or incomplete.}}

== KDE Applications ==

To install the full set of KDE Applications, install {{Pkg|kde-applications}}. You can also choose to install a smaller set of applications by installing any of the subpackages:

{{Note|Most of these are not available on <code>ppc64le</code> or <code>s390x</code>.}}
* {{Pkg|kde-applications-accessibility|arch=}}
* {{Pkg|kde-applications-admin|arch=}}
* {{Pkg|kde-applications-base|arch=}}
* {{Pkg|kde-applications-edu|arch=}}
* {{Pkg|kde-applications-games|arch=}}
* {{Pkg|kde-applications-graphics|arch=}}
* {{Pkg|kde-applications-multimedia|arch=}}
* {{Pkg|kde-applications-network|arch=}}
* {{Pkg|kde-applications-pim|arch=}}
* {{Pkg|kde-applications-sdk|arch=}}
* {{Pkg|kde-applications-utils|arch=}}
* {{Pkg|kde-applications-webdev|arch=}}

== Starting Plasma ==

Plasma can be started using a display manager or from the console.

=== Using a display manager ===

When Plasma is installed via the plasma meta-package, the display manager is set up using sddm.

Make sure you enable and start the SDDM service.

{{Cmd|rc-update add sddm
rc-service sddm start
}}

* Select ''Plasma'' to launch a new session in Wayland
* Select ''Plasma (X11)'' to launch a new session in Xorg

=== From the console ===

The Xorg session can be launched by installing {{Pkg|xinit|arch=}} and appending <code>exec startplasma-x11</code> to your <code>.xinitrc</code> file. To start X:
{{Cmd|xinit}}

For the Wayland session run
{{Cmd|XDG_SESSION_TYPE{{=}}wayland dbus-run-session startplasma-wayland}}

== Discover ==

[https://userbase.kde.org/Discover Discover] is the application installer from KDE. The alpine linux package {{pkg|discover}} is automatically installed if {{pkg|plasma-desktop-meta|arch=}} package is installed or if [[#setup-desktop|setup-desktop]] is used to install Plasma.

Install the packages {{pkg|discover-backend-apk}} and {{pkg|discover-backend-flatpak}} to use Discover as a graphical interface to [[Alpine Package Keeper]] and [[Flatpak]] respectively.

== Troubleshooting ==

=== HiDPI Scaling ===

When using high resolution screens, e.g. 4K, you might need to apply scaling so the fonts and windows are not too small.

In order to achieve this you can open <code>Settings -> Display and Monitor</code> and change the slider under ''Global Scale'' to an appropriate value.

You can also change the mouse cursor and icon size under <code>Settings -> Appearance</code>.

If your taskbar and window decorations are still too small, you might want to create the file {{path|~/.xprofile}} to define the ''PLASMA_USE_QT_SCALING'' environment variable:{{Cmd|export PLASMA_USE_QT_SCALING{{=}}1}}

After creating this file, you may need to restart your session to apply this modification.

== See also ==

* [[Installation#Post-Installation|Post installation]]
* [[Flatpak]]
* [https://wiki.archlinux.org/title/KDE KDE - Archwiki]

[[Category:Desktop Environments]]

Template talk:Issue

2025-11-20T09:36:19Z

Encode: /* {{Ic|Issue}} should work for other projects under the Alpine umbrella */ Possible fix

== Update URL to {{Ic|gitlab.alpinelinux.org}} ==

{{Done}}

<s>Please update the URL used in the template to https://gitlab.alpinelinux.org/alpine/aports/-/issues/</s>
[[User:Zcrayfish|zcrayfish]] ([[User talk:Zcrayfish|talk]]) 04:02, 31 July 2023 (UTC)

== {{Ic|Issue}} should work for other projects under the Alpine umbrella ==

This template refers only to aports. If the issue was filed against other subprojects like, alpine-conf, there is no way to use this template. Please fix this.
The below issue number cannot be referred in the current template. Please use aports as default argument, but allow users to choose other components like alpine-conf to refer bug reports.
https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10473
[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 08:55, 29 October 2024 (UTC)
: I don't know MediaWiki but I played around on [[Template:Sandbox]] and [https://wiki.alpinelinux.org/w/index.php?title=Template:Sandbox&oldid=31513 this] seems to work --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 09:36, 20 November 2025 (UTC)

Template:Sandbox

2025-11-20T09:33:15Z

Encode: Testing ‘Issue’ template

<noinclude>

{{Template}}

Link to issues under the [https://gitlab.alpinelinux.org/alpine/ Alpine gitlab umbrella].

== Usage ==

<nowiki>{{Issue|number|project=|description=}}</nowiki>

{{Define|number|Issue number.
:This argument is '''required'''.}}
{{Define|project{{=}}|Project under {{Ic|https://gitlab.alpinelinux.org/alpine/}} to which the issue belongs.
:This argument is '''optional''', defaults to {{Ic|aports}}.}}
{{Define|description{{=}}|Description for the issue, for example, what the issue title is.
:This argument is '''optional'''.}}

== Examples ==

<nowiki>{{Issue|10516}}</nowiki>

Produces: {{Issue|10516}}

<nowiki>{{Issue|5|project=docs/user-handbook}}</nowiki>

Produces: {{Issue|5|project=docs/user-handbook}}

<nowiki>{{Issue|10516|description=libreoffice is built without Wayland support}}</nowiki>

Produces: {{Issue|10516|description=libreoffice is built without Wayland support}}

<nowiki>{{Issue|10516|project=alpine-conf|description=Boot partition only has enough space for one kernel}}</nowiki>

Produces: {{Issue|10516|project=alpine-conf|description=Boot partition only has enough space for one kernel}}

</noinclude>
<includeonly>
[https://gitlab.alpinelinux.org/alpine/{{#if: {{{project|}}} | {{{project}}} | aports}}/-/issues/{{{1}}} {{{project|}}} #{{{1}}}{{#if: {{{description|}}} |<nowiki>:</nowiki> {{{description}}}}}]
</includeonly>

Template talk:Issue

2025-11-20T09:28:37Z

Encode: Put headings and mark that one is done

Talk:PipeWire

2025-11-18T20:35:59Z

Encode: /* Is {{Ic|rtkit}} still recommended for Realtime scheduling? */ Add the ‘Done’ template

== Revert edit about considering two options to launch PipeWire ==

Dear [[User:John3-16|John3-16]], This [https://wiki.alpinelinux.org/w/index.php?title=PipeWire&oldid=30543 edit] is being reverted because Pipewire user service is the recommended method going forward and the pipewire-launcher will be removed at some point. When a recommended method is available, listing them on par with bespoke methods will confuse new users. We can always list such methods under a heading like ''Custom configuration''. Our [https://wiki.alpinelinux.org/w/index.php?title=Installation&oldid=26677 installation page] was a perfect example for listing a lot of options, but frustrating for new users. Thanks for you contributions to Wiki and it is highly appreciated and i hope you understand and agree with the reasoning for this revert. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 03:49, 22 July 2025 (UTC)

: Agreed that Pipewire user service is the recommended method; and that the pipewire-launcher method is expected to be sunsetted; this was respected in my edit. The Note was preserved which stated that the second option would be deprecated. My impression is that enough readers may not stop and realize that these are mutually exclusive methods, if they implement the passages in this guide one after another in a rush.
: I concur with you too that other, bespoke methods would be superfluous on the wiki; their existence was only being acknowledged in the edit's Summary. Thank you for your extensive wiki help also; please continue!
:[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 04:26, 22 July 2025 (UTC)
:: Thanks for you reply. Understood the reasoning and added the suggested changes. - [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 05:22, 22 July 2025 (UTC)

== Is {{Ic|rtkit}} still recommended for [[PipeWire#Realtime_scheduling|Realtime scheduling]]? ==

{{Done}}

[https://github.com/heftig/rtkit rtkit's] repository hasn't been updated since 2020-04-05 and the open [https://github.com/heftig/rtkit/issues issues] seem to list some problems. [https://wiki.gentoo.org/wiki/PipeWire#Audio_Groups Gentoo PipeWire#Audio Groups] implies rtkit is the fallback and {{Ic|pipewire}} group is the recommeneded path. {{Path|/etc/security/limits.d/25-pw-rlimits.conf}} (which is shipped from [https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/src/modules/module-rt/25-pw-rlimits.conf.in upstream]) also seems to imply that the {{Ic|pipewire}} group is preferred. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 07:48, 17 November 2025 (UTC)
: Made changes to wiki section. Please feel to make necessary changes to fix any remaining inaccuracies, and to remove the Accuracy template. Thanks. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 10:54, 17 November 2025 (UTC)
:: I changed the wording slightly and removed ‘glitch-free’ because I feel that is too strong. Everything looks good. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 20:13, 18 November 2025 (UTC)

Template talk:Accuracy

2025-11-18T20:34:56Z

Encode: /* A space should be added after {{Ic|Reason:}} */ Add the ‘Done’ template

== A space should be added after {{Ic|Reason:}} ==

{{Done}}

Between {{Ic|Reason:}} and the reason you put, a space should be added. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 07:58, 17 November 2025 (UTC)
: Hi [[User:Encode|Encode]], Thanks for the feedback and my sincere appreciation for all your past contributiions to improve Alpine Wiki. I copied many content from your user pages and used them in various pages of Alpine wiki. I tried making the change, but doesn't seem to make any difference. Please go ahead and make the necessary change. I copied this template from Archwiki and made minor changes to follow Alpine wiki template conventions. - [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 10:23, 17 November 2025 (UTC)
:: Just doing my part to improve the wiki. I went ahead and added the space. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 09:26, 18 November 2025 (UTC)

Polkit

2025-11-18T20:23:40Z

Encode: /* Authentication agents */ Correct KDE agent package name

[https://polkit.pages.freedesktop.org/polkit/polkit.8.html Polkit] is an authorization manager which is used for allowing unprivileged processes to speak to privileged processes through some form of inter-process communication mechanism like [[D-Bus]].

== Prerequisites ==

* Install and configure [[D-Bus#Installation|D-Bus]].

== Installation ==

For graphical applications, polkit relies on [[Elogind|elogind]] or [[Seatd]] to determine the identity of the user making a request. To use the full features of polkit, [[#Using polkit with elogind|using polkit with elogind]] is recommended.

=== Using polkit with elogind ===

For a feature-rich [[Desktop environments and Window managers|desktop]] experience, use polkit with [[Elogind|elogind]]. Features like [[#Authentication agents|authentication agents]] can be used only with elogind. Install the {{Pkg|polkit-elogind}} package and enable the {{ic|polkit}} service using [[OpenRC]].

{{Cmd|<nowiki># apk add polkit-elogind
# rc-update add polkit
# rc-service polkit start </nowiki>}}

Proceed to configure [[Elogind|elogind]], if not done already.

=== Using polkit with seatd ===

For a minimal desktop like [[Sway]], polkit can be used with [[Seatd#Polkit|seatd with certain limitations]]. With Seatd, polkit rules can only evaluate group membership, resulting in a 'yes' or 'no' decision. Graphical, session aware [[#Authentication agents|authentication agents]] are not supported.

To proceed to use polkit with seatd, install the {{Pkg|polkit}} package and enable the {{ic|polkit}} service using [[OpenRC]]: {{Cmd|<nowiki># apk add polkit
# rc-update add polkit
# rc-service polkit start </nowiki>}}

== Authentication agents ==

Polkit authentication agent integration helps coordinate the display of a password prompt to the active and local users.
When an unprivileged user attempts to access a privileged location (such as by typing admin:// in the address bar of a [[File_management#File_managers|File Manager]]), when the appropriate polkit policy requires administrative authentication, a password dialogue will typically appear.

{{Warning|Authentication agents will work only when [[PAM]] is properly set up and [[#Using polkit with elogind|polkit is used with elogind]].}}

Some of the authentication agents available in Alpine linux is listed below:

* {{Pkg|xfce-polkit}}
* {{Pkg|mate-polkit}}
* {{Pkg|polkit-gnome}}
* {{Pkg|polkit-kde-agent-1}}

For [[Xfce]], install {{Pkg|xfce-polkit}} as follows:

{{Cmd|# apk add xfce-polkit}}

== Polkit rule files ==

The following example rule files have been provided to show the limitations of [[#Using polkit with seatd|seatd]].

Ensure that correct permissions are set for the rule files. For example, for the rule file {{Path|/etc/polkit-1/rules.d/50-udisks.rules}}:{{Cmd|<nowiki># chown root:root /etc/polkit-1/rules.d/50-udisks.rules
# chmod 644 /etc/polkit-1/rules.d/50-udisks.rules</nowiki>}}

=== Example1 ===

A sample polkit rule file {{Path|/etc/polkit-1/rules.d/50-udisks.rules}} which allow [[File_management#Automounting_removable_storage|automatic mounting of removable storage]] based on being a member of '''disk''' or '''storage''' group. This rule depends only on group membership which works with seatd: {{cat|/etc/polkit-1/rules.d/50-udisks.rules|<nowiki>
polkit.addRule(function(action, subject) {
if (subject.isInGroup("disk") || subject.isInGroup("storage")) &&
(action.id == "org.freedesktop.udisks2.filesystem-mount" ||
action.id == "org.freedesktop.udisks2.filesystem-mount-system" ||
action.id == "org.freedesktop.udisks2.filesystem-unmount-others" ||
action.id == "org.freedesktop.udisks2.drive-eject" ||
action.id == "org.freedesktop.udisks2.encrypted-unlock" ||
action.id == "org.freedesktop.udisks2.power-off-drive")) {
return polkit.Result.YES; //
}
});
</nowiki>}}

The above polkit rule file is fully supported when used with both [[#Using polkit with seatd|seatd]] and [[#Using polkit with elogind|Elogind]].

=== Example2 ===

[[elogind|Elogind]] is required for "subject.active" rules and no AUTH_ADMIN, since polkit agents need POLKIT_IS_SUBJECT. Given below is a sample polkit rule file {{Path|/etc/polkit-1/rules.d/51-require-active-session.rules}} which allow only active local sessions to suspend:{{Cat|/etc/polkit-1/rules.d/51-require-active-session.rules|<nowiki>
polkit.addRule(function(action, subject) {
if (action.id == "org.freedesktop.login1.suspend" &&
subject.active) {
return polkit.Result.YES;
} else if (action.id == "org.freedesktop.login1.suspend") {
return polkit.Result.NO; // Or polkit.Result.AUTH_ADMIN to prompt for password
}
});
</nowiki>}}

The above rule file depends on ''subject.active'' which is supported only when [[#Using polkit with elogind|polkit is used with Elogind]].

== See also ==
* [https://polkit.pages.freedesktop.org/polkit/polkit.8.html polkit Architecture]
* [https://github.com/polkit-org/polkit polkit github page]
* [https://wiki.archlinux.org/title/Polkit Arch wiki Polkit page]
* [https://wiki.archlinux.org/title/Running_GUI_applications_as_root Arch wiki Running GUI applications as root]

[[Category:Authentication]]

Talk:PipeWire

2025-11-18T20:13:08Z

Encode: /* Is {{Ic|rtkit}} still recommended for Realtime scheduling? */ Everything looks good

== Revert edit about considering two options to launch PipeWire ==

Dear [[User:John3-16|John3-16]], This [https://wiki.alpinelinux.org/w/index.php?title=PipeWire&oldid=30543 edit] is being reverted because Pipewire user service is the recommended method going forward and the pipewire-launcher will be removed at some point. When a recommended method is available, listing them on par with bespoke methods will confuse new users. We can always list such methods under a heading like ''Custom configuration''. Our [https://wiki.alpinelinux.org/w/index.php?title=Installation&oldid=26677 installation page] was a perfect example for listing a lot of options, but frustrating for new users. Thanks for you contributions to Wiki and it is highly appreciated and i hope you understand and agree with the reasoning for this revert. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 03:49, 22 July 2025 (UTC)

: Agreed that Pipewire user service is the recommended method; and that the pipewire-launcher method is expected to be sunsetted; this was respected in my edit. The Note was preserved which stated that the second option would be deprecated. My impression is that enough readers may not stop and realize that these are mutually exclusive methods, if they implement the passages in this guide one after another in a rush.
: I concur with you too that other, bespoke methods would be superfluous on the wiki; their existence was only being acknowledged in the edit's Summary. Thank you for your extensive wiki help also; please continue!
:[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 04:26, 22 July 2025 (UTC)
:: Thanks for you reply. Understood the reasoning and added the suggested changes. - [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 05:22, 22 July 2025 (UTC)

== Is {{Ic|rtkit}} still recommended for [[PipeWire#Realtime_scheduling|Realtime scheduling]]? ==

[https://github.com/heftig/rtkit rtkit's] repository hasn't been updated since 2020-04-05 and the open [https://github.com/heftig/rtkit/issues issues] seem to list some problems. [https://wiki.gentoo.org/wiki/PipeWire#Audio_Groups Gentoo PipeWire#Audio Groups] implies rtkit is the fallback and {{Ic|pipewire}} group is the recommeneded path. {{Path|/etc/security/limits.d/25-pw-rlimits.conf}} (which is shipped from [https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/src/modules/module-rt/25-pw-rlimits.conf.in upstream]) also seems to imply that the {{Ic|pipewire}} group is preferred. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 07:48, 17 November 2025 (UTC)
: Made changes to wiki section. Please feel to make necessary changes to fix any remaining inaccuracies, and to remove the Accuracy template. Thanks. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 10:54, 17 November 2025 (UTC)
:: I changed the wording slightly and removed ‘glitch-free’ because I feel that is too strong. Everything looks good. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 20:13, 18 November 2025 (UTC)

PipeWire

2025-11-18T20:06:46Z

Encode: /* Realtime scheduling */ Rewording

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

* PipeWire requires [[D-Bus#D-Bus_session_bus|D-Bus session bus]] for most of its functionality.
* Ensure that your [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]] has 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]].
* 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].

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.

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

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.

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

Template talk:Accuracy

2025-11-18T09:26:44Z

Encode: /* A space should be added after {{Ic|Reason:}} */ Respond that it is done

== A space should be added after {{Ic|Reason:}} ==

Between {{Ic|Reason:}} and the reason you put, a space should be added. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 07:58, 17 November 2025 (UTC)
: Hi [[User:Encode|Encode]], Thanks for the feedback and my sincere appreciation for all your past contributiions to improve Alpine Wiki. I copied many content from your user pages and used them in various pages of Alpine wiki. I tried making the change, but doesn't seem to make any difference. Please go ahead and make the necessary change. I copied this template from Archwiki and made minor changes to follow Alpine wiki template conventions. - [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 10:23, 17 November 2025 (UTC)
:: Just doing my part to improve the wiki. I went ahead and added the space. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 09:26, 18 November 2025 (UTC)

Template:Accuracy

2025-11-18T09:21:16Z

Encode: Add a space after ‘Reason:’

<noinclude>{{Template}}

'''This "accuracy dispute" flag template must be used to indicate inaccurate content.'''

=== Usage ===

This template should be added at the beginning of articles or sections suspected of incorrect, misleading, or confusing content. Ensure to cite specific concerns with the first argument and possibly also on the flagged article's discussion page.

<nowiki>{{Accuracy|reason}}</nowiki>

You can override the default discussion page with a second optional argument:

<nowiki>{{Accuracy|reason|Talk:Alternative Page}}</nowiki>

Alternatively you can point to a specific section in the default talk page with the named {{ic|section}} parameter:

<nowiki>{{Accuracy|reason|section=Section name}}</nowiki>

Flagged pages can be found in [[Special:WhatLinksHere/Template:Accuracy]] or in [[:Category:Pages or sections flagged with Template:Accuracy]]. If knowledgeable in a subject, users are encouraged to participate to resolve the issue. The {{Ic|<nowiki>{{Accuracy}}</nowiki>}} flag should be removed after verification/correction/removal of disputed facts.

{{Note|The talk page is linked through an external link: this is to avoid polluting [[Special:WantedPages]] when the talk page does not exist.}}

=== Examples ===

<pre>{{Accuracy|Briefly provide a note on what is not correct. Feel free to help us make an up-to-date version.}}</pre>

will produce:
{|style="width: 60vw; padding:2px; margin:0; margin-bottom:10px; background-color:#f1f1de; border:1px solid #cc9; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.0em; font-weight:bold; text-align:center;"> [[Image:Inaccurate.svg|54px|left|link=]] The factual accuracy of this article or section is disputed. </div>'''Reason:''' Briefly provide a note on what is not correct. Feel free to help us make an up-to-date version.
([[{{TALKPAGENAME}}|Discuss]])
|}

<hr>

</noinclude><includeonly><center>
{|style="width: 60vw; padding:2px; margin:0; margin-bottom:10px; background-color:#f1f1de; border:1px solid #cc9; -moz-border-radius-bottomright: 0.5em; -moz-border-radius-bottomleft: 1em; border-radius-bottomright: 0.5em; border-radius-bottomleft: 1em; -webkit-border-bottom-right-radius: 0.5em; -webkit-border-bottom-left-radius: 1em;"
|<div style="font-size: 1.0em; font-weight:bold; text-align:center;"> [[Image:Inaccurate.svg|54px|left|link=]] The factual accuracy of this article or section is disputed. </div>'''Reason:''' {{{reason|{{{1|}}}}}}
(Discuss in {{#if:{{{talk|{{{2|}}}}}}{{{section|}}}|[[{{{talk|{{{2|{{TALKPAGENAME}}#{{{section|}}}}}}}}}]]|[{{fullurl:{{TALKPAGENAME}}}} {{TALKPAGENAME}}]}})
|}</center>[[Category:Pages or sections flagged with Template:Accuracy]]</includeonly>

Template talk:Accuracy

2025-11-17T07:58:04Z

Encode: A space should be added after {{Ic|Reason:}}

PipeWire

2025-11-17T07:52:02Z

Encode: Question accuracy of ‘Realtime scheduling’ section.

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

* PipeWire requires [[D-Bus#D-Bus_session_bus|D-Bus session bus]] for most of its functionality.
* Ensure that your [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]] has 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]].
* 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 ===

{{Accuracy|Is rtkit still recommended?|section=Is rtkit still recommended for Realtime scheduling?}}

For realtime scheduling, it is recommended to use {{Pkg|rtkit}} package. Add your user to the <code>rtkit</code> group.

Alternatively, ensure your user has the right ulimit permissions. Since PipeWire 0.3.66, you can add yourself to the <code>pipewire</code> group. You generally need (e.g. in {{Path|/etc/security/limits.conf}}):

<pre>
@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95
</pre>

This allows a member of the pipewire group to have the right permissions for PipeWire to use realtime scheduling without rtkit. This same snippet comes with PipeWire since 0.3.66, so if you have a [[PAM]] login session and add yourself to the pipewire group, you don't have to do anything else. Note that the above {{Path|/etc/security/limits.conf}} will only work if your session is using [[PAM]].

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

Installing the {{pkg|rtkit}} package as mentioned in [[#Realtime scheduling|Realtime scheduling]] section resolves the above error message.

== See also ==

* [[Bluetooth]]
* [https://gitlab.freedesktop.org/pipewire/pipewire PipeWire source repository]
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home PipeWire Wiki]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/PipeWire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

Talk:PipeWire

2025-11-17T07:48:42Z

Encode: Is rtkit still recommended for Realtime scheduling?

== Revert edit about considering two options to launch PipeWire ==

Dear [[User:John3-16|John3-16]], This [https://wiki.alpinelinux.org/w/index.php?title=PipeWire&oldid=30543 edit] is being reverted because Pipewire user service is the recommended method going forward and the pipewire-launcher will be removed at some point. When a recommended method is available, listing them on par with bespoke methods will confuse new users. We can always list such methods under a heading like ''Custom configuration''. Our [https://wiki.alpinelinux.org/w/index.php?title=Installation&oldid=26677 installation page] was a perfect example for listing a lot of options, but frustrating for new users. Thanks for you contributions to Wiki and it is highly appreciated and i hope you understand and agree with the reasoning for this revert. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 03:49, 22 July 2025 (UTC)

: Agreed that Pipewire user service is the recommended method; and that the pipewire-launcher method is expected to be sunsetted; this was respected in my edit. The Note was preserved which stated that the second option would be deprecated. My impression is that enough readers may not stop and realize that these are mutually exclusive methods, if they implement the passages in this guide one after another in a rush.
: I concur with you too that other, bespoke methods would be superfluous on the wiki; their existence was only being acknowledged in the edit's Summary. Thank you for your extensive wiki help also; please continue!
:[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 04:26, 22 July 2025 (UTC)
:: Thanks for you reply. Understood the reasoning and added the suggested changes. - [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 05:22, 22 July 2025 (UTC)

== Is {{Ic|rtkit}} still recommended for [[PipeWire#Realtime_scheduling|Realtime scheduling]]? ==

[https://github.com/heftig/rtkit rtkit's] repository hasn't been updated since 2020-04-05 and the open [https://github.com/heftig/rtkit/issues issues] seem to list some problems. [https://wiki.gentoo.org/wiki/PipeWire#Audio_Groups Gentoo PipeWire#Audio Groups] implies rtkit is the fallback and {{Ic|pipewire}} group is the recommeneded path. {{Path|/etc/security/limits.d/25-pw-rlimits.conf}} (which is shipped from [https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/src/modules/module-rt/25-pw-rlimits.conf.in upstream]) also seems to imply that the {{Ic|pipewire}} group is preferred. --[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 07:48, 17 November 2025 (UTC)

PipeWire

2025-11-17T00:05:02Z

Encode: Misc styling

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

* PipeWire requires [[D-Bus#D-Bus_session_bus|D-Bus session bus]] for most of its functionality.
* Ensure that your [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]] has 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]].
* 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 ===

For realtime scheduling, it is recommended to use {{Pkg|rtkit}} package. Add your user to the <code>rtkit</code> group.

Alternatively, ensure your user has the right ulimit permissions. Since PipeWire 0.3.66, you can add yourself to the <code>pipewire</code> group. You generally need (e.g. in {{Path|/etc/security/limits.conf}}):

<pre>
@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95
</pre>

This allows a member of the pipewire group to have the right permissions for PipeWire to use realtime scheduling without rtkit. This same snippet comes with PipeWire since 0.3.66, so if you have a [[PAM]] login session and add yourself to the pipewire group, you don't have to do anything else. Note that the above {{Path|/etc/security/limits.conf}} will only work if your session is using [[PAM]].

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

Installing the {{pkg|rtkit}} package as mentioned in [[#Realtime scheduling|Realtime scheduling]] section resolves the above error message.

== See also ==

* [[Bluetooth]]
* [https://gitlab.freedesktop.org/pipewire/pipewire PipeWire source repository]
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home PipeWire Wiki]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/PipeWire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

PipeWire

2025-11-16T21:28:41Z

Encode: Use ‘_’ (low lines) when linking, have ‘{{Cmd|...}}’ on its own line, misc styling

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

* PipeWire requires [[D-Bus#D-Bus_session_bus|D-Bus session bus]] for most of its functionality.
* Ensure that your [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]] has 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]].
* 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:
<pre>
$ rc-service -U pipewire start
$ rc-service -U wireplumber start
</pre>
To enable the {{Ic|pipewire}} and {{Ic|wireplumber}} user services in [[Wayland]], issue the following commands; omit the term {{ic|gui}}/swap it for {{ic|default}} for [[Xorg]] sessions:
<pre>
$ rc-update -U add pipewire gui
$ rc-update -U add wireplumber gui
</pre>

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

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

For realtime scheduling, it is recommended to use {{Pkg|rtkit}} package. Add your user to the <code>rtkit</code> group.

Alternatively, ensure your user has the right ulimit permissions. Since PipeWire 0.3.66, you can add yourself to the <code>pipewire</code> group. You generally need (e.g. in {{Path|/etc/security/limits.conf}}):

<pre>
@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95
</pre>

This allows a member of the pipewire group to have the right permissions for PipeWire to use realtime scheduling without rtkit. This same snippet comes with PipeWire since 0.3.66, so if you have a [[PAM]] login session and add yourself to the pipewire group, you don't have to do anything else. Note that the above {{Path|/etc/security/limits.conf}} will only work if your session is using [[PAM]].

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

<pre>
$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused
</pre>

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}}. If you see something like this:
<pre>
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
</pre>

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

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

Installing the {{pkg|rtkit}} package as mentioned in [[#Realtime scheduling|Realtime scheduling]] section resolves the above error message.

== See also ==

* [[Bluetooth]]
* [https://gitlab.freedesktop.org/pipewire/pipewire PipeWire source repository]
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home PipeWire Wiki]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/PipeWire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

Bluetooth

2025-11-16T20:04:01Z

Encode: ‘pipewire’ → ‘PipeWire’, to match upstream

[https://en.wikipedia.org/wiki/Bluetooth Bluetooth] is a standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices. [https://www.bluez.org/ BlueZ] is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the {{Pkg|bluez}} package.

This article describes the basic installation of Bluetooth controllers and devices.

== Prerequisites ==

* Set up [[Include:Setup Device Manager|eudev]]

== Installation ==

Basic installation requires the Installation of {{Pkg|bluez}} package as follows:{{Cmd|# apk add {{Pkg|bluez}}}}

Optionally install {{Pkg|bluez-deprecated}} if you need deprecated tools like <code>hcitool</code>

=== File transfer ===

To enable bluetooth file transfer, [[Install]] the {{Pkg|openobex}} package.

=== Front-ends ===

There are several front-ends available:

* The {{Pkg|bluez}} comes with the <code>bluetoothctl</code> front-end
* {{Pkg|blueman}}: a full-featured Bluetooth manager
* {{Pkg|bluedevil}}: the [[KDE]] Bluetooth manager
* {{Pkg|bluetuith}}: simple text-based bluetooth management user interface
* {{Pkg|gnome-bluetooth}}: the [[GNOME]] Bluetooth manager

== Configuration ==

Set up the bluetooth hardware first before connecting it to other devices. The steps involved are as follows:

Load the <code>btusb</code> kernel module: {{Cmd|# modprobe btusb}}
Add user <username> to the <code>lp</code> group: {{Cmd|# adduser <username> lp}}

=== Service configuration ===

It is necessary to set up the {{ic|bluetooth}} service before proceeding further.

Use standard '''start|stop|restart''' [[OpenRC]] command to start the {{ic|bluetooth}} service immediately: {{Cmd|# rc-service bluetooth start}}
Add the {{ic|bluetooth}} service to start during every boot: {{Cmd|# rc-update add bluetooth default}}

=== Verify the hardware ===

Now, check the state of the Bluetooth radio transmitter using <code>rfkill</code>: {{Cmd|$ rfkill list bluetooth}}

It should return something similar to:

0: hci0: Bluetooth
Soft blocked: no
Hard blocked: no

If the device is listed as blocked, it can be unblocked using the same tool: {{Cmd|# rfkill unblock bluetooth}}

{{Note|It may be necessary to [[OpenRC|restart]] the Bluetooth service before continuing.}}

=== Pairing with <code>bluetoothctl</code> ===

<code>bluetoothctl</code> tool can be run both in interactive and non-interactive mode. The non-interactive commands can be issued from the shell by suffixing <Code>bluetoothctl</Code> like {{ic|$ bluetoothctl list}} or {{ic|$ bluetoothctl power on}}.

The example below shows step-by-step procedure to configure a bluetooth adapter in interactive mode. Begin by starting <code>bluetoothctl</code> and follow these basic steps:

{{Cmd|$ bluetoothctl}}

The prompt should display:

[bluetooth]#

List the available controllers:

[bluetooth]# list

Display information about a controller:

[bluetooth]# show ''controller_mac_address''

Set the default controller:

[bluetooth]# select ''controller_mac_address''

Power on the controller:

[bluetooth]# power on

Enable the agent and set it as default:

[bluetooth]# agent on
[bluetooth]# default-agent

Set the controller as discoverable (temporarily for 3 minutes) and pairable:

[bluetooth]# discoverable on
[bluetooth]# pairable on

Scan for devices:

[bluetooth]# scan on

Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.

Discover the device MAC address:

[bluetooth]# devices

Pair with the device:

[bluetooth]# pair ''device_mac_address''

Enter the PIN if prompted:

[agent] PIN code: ####

Trust the device:

[bluetooth]# trust ''device_mac_address''

Connect to the device:

[bluetooth]# connect ''device_mac_address''

Display information about the device:

[bluetooth]# info ''device_mac_address''

The device is now paired:

[bluetooth]# quit

=== Set adapter power state ===

If you would like the adapter to not be automatically enabled (e.g. on a portable device where you wish to save battery), set <code>AutoEnable=false</code> in <code>/etc/bluetooth/main.conf</code> in the <code>[Policy]</code> section: {{Cat|/etc/bluetooth/main.conf|[Policy]
...
AutoEnable=false
...}}

=== Battery Reporting ===

An experimental feature can be enabled in order to report device battery level: {{Cat|/etc/bluetooth/main.conf|[General]
...
Experimental=true
...}}

== Troubleshooting ==

Due to the variety of available Bluetooth hardware it is possible that you receive errors while attempting to install, activate, or find your Bluetooth device.

=== "No default controller available" error ===

After having followed these instructions, or others, you run <code>bluetoothctl</code> and encounter the following scenario:

[bluetooth]# list
[bluetooth]# show
No default controller available

One possible solution is that you are missing firmware drivers.

Try running the following command to discover the source of the issue: {{Cmd|# dmesg | grep -i bluetooth | grep -i firmware}}

There are many firmware packages available that could likely solve the this problem (see {{Pkg|linux-firmware-*}}).

Another possible solution is to install {{Pkg|hidapi}} and add load the module: {{Cmd|# apk add hidapi
# modprobe uhid}}

It may also be necessary to create configuration to load the uhid and btusb kernel modules on boot: {{Cmd|cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF}}

{{Cmd|cat <<EOF > /etc/modules-load.d/btusb.conf
#Load btusb kernel module:
btusb
EOF}}

=== "org.bluez.Error.NotAvailable br-connection-profile-unavailable" ===

The error <code>br-connection-profile-unavailable</code> is sometimes produced when trying to connect a Bluetooth HID device but the <code>uhid</code> kernel module is not loaded. HID devices include keyboards and the volume buttons on headphones (which are sometimes presented to the OS as a keyboard), mice, game controllers, alphanumeric displays, etc.

The <code>uhid</code> kernel module is required for USB HID devices with drivers that are implemented in userspace, when userspace HID support is enabled.

Loading <code>uhid</code> with <code>modprobe</code> after encountering this error does not always fix the problem.

Try setting up <code>uhid</code> to load at boot, and then rebooting: {{Cmd|# cat <<EOF > /etc/modules-load.d/uhid.conf
#Load uhid kernel module:
uhid
EOF
# reboot}}

Alternatively, the userspace HID feature can be disabled entirely in favour of kernel HIDP drivers in <code>/etc/bluetooth/input.conf</code>: {{Cmd|1=UserspaceHID=false}}

If running [[PipeWire]], you may also try installing {{Pkg|pipewire-spa-bluez}} to see if that solves the issue.

=== Unable to control Bluetooth speaker volume / Bluetooth output is muted (Pulseaudio) ===

It is possible to automatically switch audio output and volume control to last connected device.

This can solve the problem of controlling the speaker volume when switching between Bluetooth devices.

Append the following lines at the end of the {{Path|/etc/pulse/default.pa}}: {{Cat|/etc/pulse/default.pa|...
###Automatically switch audio to the most recently connected device (Bluetooth, HDMI, USB)
load-module module-switch-on-connect}}

=== Failed to connect: org.bluez.Error.NotReady br-connection-adapter-not-powered ===

The error code <code>Failed to connect: org.bluez.Error.NotReady br-connection-adapter-not-powered</code> may appear after resuming from suspend. This error can be resolved by issuing the command:{{Cmd|$ bluetoothctl power on}}

=== Failed to connect: org.bluez.Error.Failed br-connection-unknown ===

When trying to connect to a bluetooth speaker, If you receive the following error message {{Cmd|$ bluetoothctl connect 88:C6:26:0A:7D:F1
Attempting to connect to 88:C6:26:0A:7D:F1
Failed to connect: org.bluez.Error.Failed br-connection-unknown}}
Check the following {{Cmd|<nowiki>$ bluetoothctl info
Missing device address argument
DeviceSet (null) not available</nowiki>}}

The above errors may appear after resuming from suspend. In such cases, resolve it by restarting {{ic|bluetooth}} service: {{Cmd|$ doas service bluetooth restart}}

=== dbus-daemon[2431]: [system] Rejected send message error name="org.bluez.Profile1.Error.NotImplemented" ===

Jul 19 20:54:59 homepc2 auth.notice dbus-daemon[2431]: [system] Rejected send message, 0 matched rules; type="error", sender=":1.119" (uid=1000 pid=10213 comm="/usr/bin/wireplumber") interface="(unset)" member="(unset)" error name="org.bluez.Profile1.Error.NotImplemented" requested_reply="0" destination=":1.661" (uid=0 pid=11828 comm="/usr/lib/bluetooth/bluetoothd")

To make the above error message in {{path|/var/log/message}} to disappear, enable the following {{Cat|/etc/bluethooth/main.conf|<nowiki>
[General]
...
# Enables D-Bus experimental interfaces
# Possible values: true or false
Experimental = true
...
</nowiki>}}

== See also ==
* [[PulseAudio#Bluetooth|PulseAudio with Bluetooth]]
* [[PipeWire#Bluetooth_audio|PipeWire with Bluetooth]]
* [https://wiki.postmarketos.org/wiki/Bluetooth Bluetooth entry on PostmarketOS Wiki]
* [https://wiki.gentoo.org/wiki/Bluetooth Bluetooth entry on Gentoo Wiki]
* [https://wiki.archlinux.org/title/Bluetooth Bluetooth entry on ArchWiki]

[[Category:Multimedia]]
[[Category:Hardware]]
[[Category:Sound]]
[[Category:Drivers]]

KDE

2025-11-16T20:01:11Z

Encode: ‘Pipewire’ → ‘PipeWire’, to match upstream

[[File:KDEScreenshot.png |thumb |KDE Plasma screenshot.]]

[https://kde.org/plasma-desktop/ Plasma] is the desktop environment from [https://kde.org/ KDE], a software project comprising of a collection of libraries known as [https://develop.kde.org/products/frameworks/ KDE Frameworks], and several applications known as [https://apps.kde.org/ KDE Applications]. Their [https://userbase.kde.org/Welcome_to_KDE_UserBase UserBase wiki] has detailed information about most KDE Applications.

{{Note|the {{Pkg|plasma-desktop-meta|arch=}} package isn't available for the <code>ppc64le</code>, <code>s390x</code>, <code>armhf</code>, or <code>riscv64</code> architectures due to the {{Pkg|kdeplasma-addons|arch=}} dependency not being available there. However, the rest of Plasma may be installed separately to potentially get a functional desktop.}}

== Prerequisites ==
{{:Include:Desktop prerequisites}}
* For users interested in Xorg as opposed to Wayland, install the [[Alpine_setup_scripts#setup-xorg-base|Xorg base packages]]
* Enable [[Elogind]] service
* Wayland users: Install package {{pkg|xf86-input-libinput|arch=}}
{{Tip|Except for the first two [[#Prerequisites|Prerequisites]], all the others are automatically handled if Plasma desktop is [[#Installation using setup-desktop|installed using setup-desktop]] script.}}
== Installation using setup-desktop ==
{{:Include:Setup-desktop}}
When Plasma is chosen, the above script additionally installs [[PipeWire]] for audio and [[SDDM]] as display manager.

== Manual Installation ==

The following command will install the Plasma desktop as specified by the plasma metapackage, including the {{Pkg|sddm|arch=}} display manager and other assorted niceties. {{Cmd|# apk add {{pkg|plasma-desktop-meta|arch=}}}}
{{Note|'''polkit''' and '''udev''' are optional services for authentication and device management respectively. While KDE will function without these services enabled, some functionality may be missing or incomplete.}}

== KDE Applications ==

To install the full set of KDE Applications, install {{Pkg|kde-applications}}. You can also choose to install a smaller set of applications by installing any of the subpackages:

{{Note|Most of these are not available on <code>ppc64le</code> or <code>s390x</code>.}}
* {{Pkg|kde-applications-accessibility|arch=}}
* {{Pkg|kde-applications-admin|arch=}}
* {{Pkg|kde-applications-base|arch=}}
* {{Pkg|kde-applications-edu|arch=}}
* {{Pkg|kde-applications-games|arch=}}
* {{Pkg|kde-applications-graphics|arch=}}
* {{Pkg|kde-applications-multimedia|arch=}}
* {{Pkg|kde-applications-network|arch=}}
* {{Pkg|kde-applications-pim|arch=}}
* {{Pkg|kde-applications-sdk|arch=}}
* {{Pkg|kde-applications-utils|arch=}}
* {{Pkg|kde-applications-webdev|arch=}}

== Starting Plasma ==

Plasma can be started using a display manager or from the console.

=== Using a display manager ===

When Plasma is installed via the plasma meta-package, the display manager is set up using sddm.

Make sure you enable and start the SDDM service.

{{Cmd|rc-update add sddm
rc-service sddm start
}}

* Select ''Plasma'' to launch a new session in Wayland
* Select ''Plasma (X11)'' to launch a new session in Xorg

=== From the console ===

The Xorg session can be launched by installing {{Pkg|xinit|arch=}} and appending <code>exec startplasma-x11</code> to your <code>.xinitrc</code> file. To start X:
{{Cmd|xinit}}

For the Wayland session run
{{Cmd|XDG_SESSION_TYPE{{=}}wayland dbus-run-session startplasma-wayland}}

== Discover ==

[https://userbase.kde.org/Discover Discover] is the application installer from KDE. The alpine linux package {{pkg|discover}} is automatically installed if {{pkg|plasma-desktop-meta|arch=}} package is installed or if [[#Installation using setup-desktop|setup-desktop]] is used to install Plasma.

Install the packages {{pkg|discover-backend-apk}} and {{pkg|discover-backend-flatpak}} to use Discover as a graphical interface to [[Alpine Package Keeper]] and [[Flatpak]] respectively.

== Troubleshooting ==

=== HiDPI Scaling ===

When using high resolution screens, e.g. 4K, you might need to apply scaling so the fonts and windows are not too small.

In order to achieve this you can open <code>Settings -> Display and Monitor</code> and change the slider under ''Global Scale'' to an appropriate value.

You can also change the mouse cursor and icon size under <code>Settings -> Appearance</code>.

If your taskbar and window decorations are still too small, you might want to create the file {{path|~/.xprofile}} to define the ''PLASMA_USE_QT_SCALING'' environment variable:{{Cmd|export PLASMA_USE_QT_SCALING{{=}}1}}

After creating this file, you may need to restart your session to apply this modification.

== See also ==

* [[Installation#Post-Installation|Post installation]]
* [[Flatpak]]
* [https://wiki.archlinux.org/title/KDE KDE - Archwiki]

[[Category:Desktop Environments]]

GNOME

2025-11-16T19:43:42Z

Encode: ‘Pipewire’ → ‘PipeWire’, to match upstream

[https://www.gnome.org/ Gnome Desktop] aims to get things done with ease, comfort, and control.

== Prerequisites ==
{{:Include:Desktop prerequisites}}
{{Tip|Except for the first two [[#Prerequisites|Prerequisites]], all the others are automatically handled by [[#Installation|setup-desktop]] script.}}
== Installation ==
{{:Include:Setup-desktop}}

When gnome is chosen, the above script enables community repository and additionally installs [[D-Bus]], [[eudev]], [[PipeWire]] and {{Pkg|gdm}} as [[Display manager|display manager]] .

== Configuration ==

To manage network through GUI, configure [[NetworkManager]]. You may need to [[Install]] necessary subpackages like {{Pkg|networkmanager-wifi}}.

=== Software ===

GNOME [https://apps.gnome.org/Software/ Software] can be used as GUI front end for [[Alpine Package Keeper]] and [[Flatpak|Flatpak]].
* [[Install]] the packages {{pkg|gnome-software-plugin-apk}} and {{pkg|gnome-software-plugin-flatpak}}, if not already installed.
* Ensure that {{ic|apk-polkit-server}} service from {{pkg|apk-polkit-rs}} package is running:{{cmd|# rc-update add apk-polkit-server default && rc-service apk-polkit-server start}}

== Updating GNOME packages ==

Most GNOME apps and core systems follow a common versioning pattern, and have a similar release cadence. In order to reduce the workload on maintainers, the [https://gitlab.alpinelinux.org/pabloyoyoista/gnome-aports-utils gnome-aports-utils] project exists. It contains a series of scripts that can be used to detect changes on GNOME-related projects, and commit them. When doing major GNOME updates, and doing minor updates on many projects, these scripts can help warranty that no project is forgotten, and reduce the time needed to build and test the upgrades.

We recommend everybody to '''use and contribute''' to that repository instead of pushing updates for every GNOME component individually.

=== Major GNOME upgrade ===

About every half year, GNOME publishes a new major release. These are announced at: https://release.gnome.org/calendar/ (note the dates are the tarball-due-dates and not the actual release drop).

With this release the whole GNOME stack gets upgraded, this includes G-related libraries, the GNOME shell with mutter, [https://apps.gnome.org/ GNOME core apps] and other packages following the same schedule. The [https://matrix.to/#/%23release-team:gnome.org GNOME release engineering team] publishes dates for alpha, beta, release candidates and stable versions for every major version, most GNOME core packages follow their schedules, but not all of them. Announcements of the releng team are posted on the GNOME forum (https://discourse.gnome.org/tag/release-team) and Release Notes for each phase (with it's upgraded packages) are at: https://download.gnome.org/core/

Therefore we should also upgrade along the dependency tree (glib -> gtk4 -> mutter -> gnome-shell -> other apps). Most important libraries are glib, gtk4, libadwaita. These are mostly already released in the alpha-phase and don't contain many breaking changed. To upgrade other GNOME core package to the latest version in a major version, you can use [https://gitlab.alpinelinux.org/pabloyoyoista/gnome-aports-utils gnome-aports-utils] or also check [https://download.gnome.org/sources/?C=M&O=D https://download.gnome.org/sources (sorted by date)] (thats where all GNOME core maintainers upload their tarballs).

Also take a look at Gentoo's upgrading guide: https://wiki.gentoo.org/wiki/Project:GNOME/GNOME_Bumping_Guide

== Troubleshooting ==

If you are unable to log in, check {{Path|/var/log/gdm/greeter.log}}, there may be info there from X that indicates failed modules, etc.

If GNOME Terminal doesn't start, add the following to /etc/profile.d/locale.sh: <code>LANG=en_US.UTF-8</code> and reboot.

If the on-screen keyboard shows up in GDM after installing other UIs such as Phosh, you need to disable it by opening the Accessibility menu (top right) when you are in the GDM login screen. You can disable the on-screen keyboard there. Or set <code>org.gnome.desktop.a11y.applications screen-keyboard-enabled</code> to <code>false</code> for the <code>gdm</code> user with <code>dconf</code>

=== Slow applications or rendering issues ===

Please note that some applications, i.e. Gnome Web (Epiphany), may require the installation of libraries related to hardware acceleration to work correctly.

In quite some cases, this can be solved by installing <code>mesa-gles</code> (OpenGL ES). Check if you you have issues loading the shared library <code>libGLESv2.so.2</code>. If so, you can install it with:{{Cmd|# apk add mesa-gles}}

== See also ==

* [https://wiki.archlinux.org/title/GNOME GNOME - Archwiki]
* [https://wiki.gentoo.org/wiki/GNOME GNOME - Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/GNOME GNOME - PostmarketOS Wiki]
* [https://wiki.postmarketos.org/wiki/GNOME_apps Alpine linux packages available for Gnome]

[[Category:Desktop Environments]]

PipeWire

2025-11-16T09:29:02Z

Encode: Reword ‘GUI tools’

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

* PipeWire requires [[D-Bus#D-Bus session bus|D-Bus session bus]] for most of its functionality.
* Ensure that your [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]] has 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 section below only if PipeWire is [[#Testing|not launched]] after a relogin/reboot.

[[#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|V3.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]].
* 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:
<pre>
$ rc-service -U pipewire start
$ rc-service -U wireplumber start
</pre>
To enable the {{Ic|pipewire}} and {{Ic|wireplumber}} user services in [[Wayland]], issue the following commands; omit the term {{ic|gui}}/swap it for {{ic|default}} for [[Xorg]] sessions:
<pre>
$ rc-update -U add pipewire gui
$ rc-update -U add wireplumber gui
</pre>

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

Note that 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 pipewire-launcher script will be removed in the future to be replaced with [[#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 ===

For realtime scheduling, it is recommended to use {{Pkg|rtkit}} package. Add your user to the <code>rtkit</code> group.

Alternatively, ensure your user has the right ulimit permissions. Since PipeWire 0.3.66, you can add yourself to the <code>pipewire</code> group. You generally need (e.g. in {{Path|/etc/security/limits.conf}}):

<pre>
@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95
</pre>

This allows a member of the pipewire group to have the right permissions for PipeWire to use realtime scheduling without rtkit. This same snippet comes with PipeWire since 0.3.66, so if you have a [[PAM]] login session and add yourself to the pipewire group, you don't have to do anything else. Note that the above {{Path|/etc/security/limits.conf}} will only work if your session is using [[PAM]].

== 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 Pavucontrol or pactl, you will get the following error:

<pre>
$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused
</pre>

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}}. If you see something like this:
<pre>
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
</pre>

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

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

Installing the {{pkg|rtkit}} package as mentioned in [[#Realtime scheduling|Realtime scheduling]] section resolves the above error message.

== See also ==

* [[Bluetooth]]
* [https://gitlab.freedesktop.org/pipewire/pipewire PipeWire source repository]
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home PipeWire Wiki]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/PipeWire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

PipeWire

2025-11-16T08:43:56Z

Encode: Fix links

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

* PipeWire requires [[D-Bus#D-Bus session bus|D-Bus session bus]] for most of its functionality.
* Ensure that your [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]] has 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 ===

[[#Pulseaudio interface|Pulseaudio Interface]] is mandatory for {{ic|pavucontrol}} to work with PipeWire.

<code>pavucontrol</code> tool from {{Pkg|pavucontrol}} provide a simple GUI app for controlling sound, outputs, etc. Consider using {{Pkg|pavucontrol-qt}} for [[KDE|Plasma]], if not installed already.

The XFCE Audio mixer can also be used to help control volume by installing the package {{pkg|xfce4-mixer}} which is currently in available in [[Repositories#Testing|testing]] repository.

''{{Pkg|qpwgraph}}''' is a 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 section below only if PipeWire is [[#Testing|not launched]] after a relogin/reboot.

[[#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|V3.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]].
* 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:
<pre>
$ rc-service -U pipewire start
$ rc-service -U wireplumber start
</pre>
To enable the {{Ic|pipewire}} and {{Ic|wireplumber}} user services in [[Wayland]], issue the following commands; omit the term {{ic|gui}}/swap it for {{ic|default}} for [[Xorg]] sessions:
<pre>
$ rc-update -U add pipewire gui
$ rc-update -U add wireplumber gui
</pre>

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

Note that 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 pipewire-launcher script will be removed in the future to be replaced with [[#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 ===

For realtime scheduling, it is recommended to use {{Pkg|rtkit}} package. Add your user to the <code>rtkit</code> group.

Alternatively, ensure your user has the right ulimit permissions. Since PipeWire 0.3.66, you can add yourself to the <code>pipewire</code> group. You generally need (e.g. in {{Path|/etc/security/limits.conf}}):

<pre>
@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95
</pre>

This allows a member of the pipewire group to have the right permissions for PipeWire to use realtime scheduling without rtkit. This same snippet comes with PipeWire since 0.3.66, so if you have a [[PAM]] login session and add yourself to the pipewire group, you don't have to do anything else. Note that the above {{Path|/etc/security/limits.conf}} will only work if your session is using [[PAM]].

== 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 Pavucontrol or pactl, you will get the following error:

<pre>
$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused
</pre>

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}}. If you see something like this:
<pre>
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
</pre>

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

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

Installing the {{pkg|rtkit}} package as mentioned in [[#Realtime scheduling|Realtime scheduling]] section resolves the above error message.

== See also ==

* [[Bluetooth]]
* [https://gitlab.freedesktop.org/pipewire/pipewire PipeWire source repository]
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home PipeWire Wiki]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/PipeWire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

PipeWire

2025-11-16T05:07:46Z

Encode: Simplify wording

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

* PipeWire requires [[D-Bus#D-Bus session bus|D-Bus session bus]] for most of its functionality.
* Ensure that your [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]] has appropriate [[Setting_up_a_new_user#Groups for desktop usage|groups for desktop usage]].
* WirePlumber requires [[udev]] 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 ===

[[#Pulseaudio interface|Pulseaudio Interface]] is mandatory for {{ic|pavucontrol}} to work with PipeWire.

<code>pavucontrol</code> tool from {{Pkg|pavucontrol}} provide a simple GUI app for controlling sound, outputs, etc. Consider using {{Pkg|pavucontrol-qt}} for [[KDE|Plasma]], if not installed already.

The XFCE Audio mixer can also be used to help control volume by installing the package {{pkg|xfce4-mixer}} which is currently in available in [[Repositories#Testing|testing]] repository.

''{{Pkg|qpwgraph}}''' is a 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 section below only if PipeWire is [[#Testing|not launched]] after a relogin/reboot.

[[#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|V3.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]].
* 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:
<pre>
$ rc-service -U pipewire start
$ rc-service -U wireplumber start
</pre>
To enable the {{Ic|pipewire}} and {{Ic|wireplumber}} user services in [[Wayland]], issue the following commands; omit the term {{ic|gui}}/swap it for {{ic|default}} for [[Xorg]] sessions:
<pre>
$ rc-update -U add pipewire gui
$ rc-update -U add wireplumber gui
</pre>

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

Note that 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 pipewire-launcher script will be removed in the future to be replaced with [[#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 ===

For realtime scheduling, it is recommended to use {{Pkg|rtkit}} package. Add your user to the <code>rtkit</code> group.

Alternatively, ensure your user has the right ulimit permissions. Since PipeWire 0.3.66, you can add yourself to the <code>pipewire</code> group. You generally need (e.g. in {{Path|/etc/security/limits.conf}}):

<pre>
@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95
</pre>

This allows a member of the pipewire group to have the right permissions for PipeWire to use realtime scheduling without rtkit. This same snippet comes with PipeWire since 0.3.66, so if you have a [[PAM]] login session and add yourself to the pipewire group, you don't have to do anything else. Note that the above {{Path|/etc/security/limits.conf}} will only work if your session is using [[PAM]].

== 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 [[udev]] 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 [[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 Pavucontrol or pactl, you will get the following error:

<pre>
$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused
</pre>

If you are running Alpine 3.22+ and continue to experience this error after verifying that [[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}}. If you see something like this:
<pre>
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
</pre>

Then 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#Module_Loading]] for instructions on how to make sure this module is loaded automatically on each startup.

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

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

Installing the {{pkg|rtkit}} package as mentioned in [[#Realtime scheduling|Realtime scheduling]] section resolves the above error message.

== See also ==

* [[Bluetooth]]
* [https://gitlab.freedesktop.org/pipewire/pipewire PipeWire source repository]
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home PipeWire Wiki]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/Pipewire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

PipeWire

2025-11-16T04:36:35Z

Encode: Use ‘PipeWire’ and ‘WirePlumber’ throughout, matching upstream

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

* PipeWire requires [[D-Bus#D-Bus session bus|D-Bus session bus]] for most of its functionality.
* Ensure that your [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]] has appropriate [[Setting_up_a_new_user#Groups for desktop usage|groups for desktop usage]].
* WirePlumber requires [[udev]] for ALSA device discovery.

== Installation ==

The following packages i.e {{Pkg|pipewire}} and {{Pkg|wireplumber}} a session manager are the minimum required packages for getting PipeWire to work.{{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 ===

[[#Pulseaudio interface|Pulseaudio Interface]] is mandatory for {{ic|pavucontrol}} to work with PipeWire.

<code>pavucontrol</code> tool from {{Pkg|pavucontrol}} provide a simple GUI app for controlling sound, outputs, etc. Consider using {{Pkg|pavucontrol-qt}} for [[KDE|Plasma]], if not installed already.

The XFCE Audio mixer can also be used to help control volume by installing the package {{pkg|xfce4-mixer}} which is currently in available in [[Repositories#Testing|testing]] repository.

''{{Pkg|qpwgraph}}''' is a 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 section below only if PipeWire is [[#Testing|not launched]] after a relogin/reboot.

[[#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|V3.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]].
* 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:
<pre>
$ rc-service -U pipewire start
$ rc-service -U wireplumber start
</pre>
To enable the {{Ic|pipewire}} and {{Ic|wireplumber}} user services in [[Wayland]], issue the following commands; omit the term {{ic|gui}}/swap it for {{ic|default}} for [[Xorg]] sessions:
<pre>
$ rc-update -U add pipewire gui
$ rc-update -U add wireplumber gui
</pre>

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

Note that 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 pipewire-launcher script will be removed in the future to be replaced with [[#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 ===

For realtime scheduling, it is recommended to use {{Pkg|rtkit}} package. Add your user to the <code>rtkit</code> group.

Alternatively, ensure your user has the right ulimit permissions. Since PipeWire 0.3.66, you can add yourself to the <code>pipewire</code> group. You generally need (e.g. in {{Path|/etc/security/limits.conf}}):

<pre>
@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95
</pre>

This allows a member of the pipewire group to have the right permissions for PipeWire to use realtime scheduling without rtkit. This same snippet comes with PipeWire since 0.3.66, so if you have a [[PAM]] login session and add yourself to the pipewire group, you don't have to do anything else. Note that the above {{Path|/etc/security/limits.conf}} will only work if your session is using [[PAM]].

== 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 [[udev]] 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 [[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 Pavucontrol or pactl, you will get the following error:

<pre>
$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused
</pre>

If you are running Alpine 3.22+ and continue to experience this error after verifying that [[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 that [[#WirePlumber|Session Manager]] is running.

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

Check {{Path|/var/log/messages}}. If you see something like this:
<pre>
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
</pre>

Then 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#Module_Loading]] for instructions on how to make sure this module is loaded automatically on each startup.

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

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

Installing the {{pkg|rtkit}} package as mentioned in [[#Realtime scheduling|Realtime scheduling]] section resolves the above error message.

== See also ==

* [[Bluetooth]]
* [https://gitlab.freedesktop.org/pipewire/pipewire PipeWire source repository]
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home PipeWire Wiki]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/Pipewire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

Shell management

2025-11-15T23:56:58Z

Encode: Make the warning more prominent

The default shell used by Alpine Linux is the [[BusyBox]] variant of the [[BusyBox#Ash_shell|ash]] shell. This page explains how to use the default shell and various ways to change the default shell in Alpine Linux.

== Ash shell ==

Alpine Linux uses [[Busybox]] Ash shell for its default shell. It is a standard POSIX shell derived from Debian Ash variant.

One's ~/.bashrc file (or, alternatively, a different shell alias file) could be considered as a basis, say, for an {{Path|~/.ashrc}} file, reviewing it carefully for syntax/cli variants against that of Ash shell. For non-login, interactive shells refer to [[#Setting alias|Setting alias]] section.

{{Tip|Use {{pkg|checkbashisms}} script to perform basic checks for the presence of bashisms in scripts and help remove them.}}

=== Setting alias ===

For non-login shells, Busybox Ash and other POSIX shells do NOT automatically read a startup file like {{Path|~/.ashrc}}. To ensure that both login and non-login shells work consistently, use '''ENV''' environment variable in {{Path|~/.profile}} to refer {{Path|~/.ashrc}} file.

# Edit the {{Path|~/.profile}} as follows: {{Cat|~/.profile|<nowiki>...
export ENV="$HOME/.ashrc" </nowiki>}}
# Now aliases can be added in the startup file {{Path|~/.ashrc}} as follows: {{Cat|~/.ashrc|<nowiki># ~/.ashrc: interactive shell configuration for BusyBox Ash

# Custom Aliases
alias ls='ls --color=auto'
alias grep='grep --color=auto'

# You may want to put all your additions into a separate file like
# ~/.ash_aliases, instead of adding them here directly.

if [ -f ~/.ash_aliases ]; then
. ~/.ash_aliases
fi</nowiki>}}

== Available shells ==

Most of the popular shells are available in Alpine Linux repositories as can be seen from the below list.
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
|width="10%" | Name
|width="36%" | URL
|Remarks
|-
|{{Pkg|bash}}|| https://www.gnu.org/software/bash/bash.html||The GNU Bourne Again shell
|-
|{{pkg|dash}} ||http://gondor.apana.org.au/~herbert/dash/||Small and fast POSIX-compliant shell
|-
|{{pkg|elvish}} ||https://elv.sh||Friendly and expressive Unix shell
|-
|{{Pkg|fish}} ||https://fishshell.com/||Modern interactive commandline shell
|-
|{{pkg|loksh}} ||https://github.com/dimkr/loksh||A Linux port of OpenBSD's ksh
|-
|{{pkg|murex}} ||https://murex.rocks/||Intuitive, typed and content aware shell
|-
|{{pkg|nsh}} ||https://github.com/nuta/nsh||A command-line shell like fish, but POSIX compatible
|-
|{{pkg|nushell}} ||https://www.nushell.sh||A new type of shell
|-
|{{pkg|oksh}} ||https://github.com/ibara/oksh||Portable OpenBSD ksh, based on pdksh
|-
|{{pkg|tcsh}} ||https://github.com/tcsh-org/tcsh||extended C-shell
|-
|{{pkg|yash}} ||https://magicant.github.io/yash||Yet another shell
|-
|{{Pkg|zsh}} || https://www.zsh.org/||Very advanced and programmable command interpreter
|}

To install any of the above shells, say for eg: {{pkg|bash}} shell: {{Cmd|# apk add {{pkg|bash}} {{pkg|bash-completion}}}}

== Change default shell ==

There are various ways to change the default user shell in Alpine Linux. You can revert back to [[#ash|ash]] shell at anytime with the same steps.

{{Note|After performing the below step, you need to log out and login again for these changes to take effect.}}

=== By hand ===

{{Warning|Take care not to delete/mangle the line, as it would make you unable to log in again.}}

Edit {{Path|/etc/passwd}} manually using an editor of your choice. An example line for a user named <code>user</code> is: {{Cat|/etc/passwd|...
user:x:1000:1000:user:/home/user:/bin/ash
...
}}

Change {{Path|/bin/ash}} to point to the path of a shell from {{Path|/etc/shells}}. The <code>user</code> should be the user you are changing the default login shell for.

=== Using chsh command ===

To use {{ic|chsh}} command, install the {{pkg|shadow}} package: {{Cmd|# apk add shadow}}
And use chsh: {{Cmd|# chsh username}}
Now enter the path for the shell you want to use (e.g {{Path|/bin/zsh}})
and press {{Key|Enter}} to confirm this change. The shell should exist in {{Path|/etc/shells}}.

== /bin/sh ==

Most applications expect a POSIX-compliant shell to be present in a standard location, {{Path|/bin/sh}}. In Alpine Linux, {{Path|/bin/sh}} is linked to [[#Ash shell|Busybox ash]] by default, but you can change this by installing an alternate {{pkg|*-binsh}} package. Changing {{Path|/bin/sh}} may lead to a difference in script execution speed.

To use {{pkg|dash}} shell as {{Path|/bin/sh}}:{{Cmd|# apk add {{pkg|dash-binsh}}}}

== See also ==

* [https://linux.die.net/man/1/dash dash Manual]
* [https://git.busybox.net/busybox/tree/shell/README Ash README]
* [https://git.busybox.net/busybox/tree/shell Ash source code]
* [https://pubs.opengroup.org/onlinepubs/9799919799/ POSIX standard]
* [https://stackoverflow.com/questions/38024160/how-to-get-etc-profile-to-run-automatically-in-alpine-docker/38025686#38025686 stackoverflow on ash shell]

[[Category:Shell]]
[[Category:System Administration]]

Shell management

2025-11-15T23:53:18Z

Encode: Alphabetize ‘Available shells’ list

The default shell used by Alpine Linux is the [[BusyBox]] variant of the [[BusyBox#Ash_shell|ash]] shell. This page explains how to use the default shell and various ways to change the default shell in Alpine Linux.

== Ash shell ==

Alpine Linux uses [[Busybox]] Ash shell for its default shell. It is a standard POSIX shell derived from Debian Ash variant.

One's ~/.bashrc file (or, alternatively, a different shell alias file) could be considered as a basis, say, for an {{Path|~/.ashrc}} file, reviewing it carefully for syntax/cli variants against that of Ash shell. For non-login, interactive shells refer to [[#Setting alias|Setting alias]] section.

{{Tip|Use {{pkg|checkbashisms}} script to perform basic checks for the presence of bashisms in scripts and help remove them.}}

=== Setting alias ===

For non-login shells, Busybox Ash and other POSIX shells do NOT automatically read a startup file like {{Path|~/.ashrc}}. To ensure that both login and non-login shells work consistently, use '''ENV''' environment variable in {{Path|~/.profile}} to refer {{Path|~/.ashrc}} file.

# Edit the {{Path|~/.profile}} as follows: {{Cat|~/.profile|<nowiki>...
export ENV="$HOME/.ashrc" </nowiki>}}
# Now aliases can be added in the startup file {{Path|~/.ashrc}} as follows: {{Cat|~/.ashrc|<nowiki># ~/.ashrc: interactive shell configuration for BusyBox Ash

# Custom Aliases
alias ls='ls --color=auto'
alias grep='grep --color=auto'

# You may want to put all your additions into a separate file like
# ~/.ash_aliases, instead of adding them here directly.

if [ -f ~/.ash_aliases ]; then
. ~/.ash_aliases
fi</nowiki>}}

== Available shells ==

Most of the popular shells are available in Alpine Linux repositories as can be seen from the below list.
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
|width="10%" | Name
|width="36%" | URL
|Remarks
|-
|{{Pkg|bash}}|| https://www.gnu.org/software/bash/bash.html||The GNU Bourne Again shell
|-
|{{pkg|dash}} ||http://gondor.apana.org.au/~herbert/dash/||Small and fast POSIX-compliant shell
|-
|{{pkg|elvish}} ||https://elv.sh||Friendly and expressive Unix shell
|-
|{{Pkg|fish}} ||https://fishshell.com/||Modern interactive commandline shell
|-
|{{pkg|loksh}} ||https://github.com/dimkr/loksh||A Linux port of OpenBSD's ksh
|-
|{{pkg|murex}} ||https://murex.rocks/||Intuitive, typed and content aware shell
|-
|{{pkg|nsh}} ||https://github.com/nuta/nsh||A command-line shell like fish, but POSIX compatible
|-
|{{pkg|nushell}} ||https://www.nushell.sh||A new type of shell
|-
|{{pkg|oksh}} ||https://github.com/ibara/oksh||Portable OpenBSD ksh, based on pdksh
|-
|{{pkg|tcsh}} ||https://github.com/tcsh-org/tcsh||extended C-shell
|-
|{{pkg|yash}} ||https://magicant.github.io/yash||Yet another shell
|-
|{{Pkg|zsh}} || https://www.zsh.org/||Very advanced and programmable command interpreter
|}

To install any of the above shells, say for eg: {{pkg|bash}} shell: {{Cmd|# apk add {{pkg|bash}} {{pkg|bash-completion}}}}

== Change default shell ==

There are various ways to change the default user shell in Alpine Linux. You can revert back to [[#ash|ash]] shell at anytime with the same steps.

{{Note|After performing the below step, you need to log out and login again for these changes to take effect.}}

=== By hand ===

Edit {{Path|/etc/passwd}} manually using an editor of your choice. An example line for a user named <code>user</code> is: {{Cat|/etc/passwd|...
user:x:1000:1000:user:/home/user:/bin/ash
...
}}

Change {{Path|/bin/ash}} to point to the path of a shell from {{Path|/etc/shells}}. Take care to not delete/mangle the line, as it would make you unable to log in again. The <code>user</code> should be the user you are changing the default login shell for.

=== Using chsh command ===

To use {{ic|chsh}} command, install the {{pkg|shadow}} package: {{Cmd|# apk add shadow}}
And use chsh: {{Cmd|# chsh username}}
Now enter the path for the shell you want to use (e.g {{Path|/bin/zsh}})
and press {{Key|Enter}} to confirm this change. The shell should exist in {{Path|/etc/shells}}.

== /bin/sh ==

Most applications expect a POSIX-compliant shell to be present in a standard location, {{Path|/bin/sh}}. In Alpine Linux, {{Path|/bin/sh}} is linked to [[#Ash shell|Busybox ash]] by default, but you can change this by installing an alternate {{pkg|*-binsh}} package. Changing {{Path|/bin/sh}} may lead to a difference in script execution speed.

To use {{pkg|dash}} shell as {{Path|/bin/sh}}:{{Cmd|# apk add {{pkg|dash-binsh}}}}

== See also ==

* [https://linux.die.net/man/1/dash dash Manual]
* [https://git.busybox.net/busybox/tree/shell/README Ash README]
* [https://git.busybox.net/busybox/tree/shell Ash source code]
* [https://pubs.opengroup.org/onlinepubs/9799919799/ POSIX standard]
* [https://stackoverflow.com/questions/38024160/how-to-get-etc-profile-to-run-automatically-in-alpine-docker/38025686#38025686 stackoverflow on ash shell]

[[Category:Shell]]
[[Category:System Administration]]

Alpine Package Keeper

2025-11-15T23:43:08Z

Encode: Spelling

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode requires additional step i.e running:{{ic|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}} for the changes to take effect on next reboot.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:

{|
| [[#Add a Package|add]]
| Add new packages or upgrade packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| [[#apk fix|fix ]]
| Repair packages or system
|-
| [[#Update Package list|update]]
| Update the index of available packages
|-
| [[#Information on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Local Cache|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|-
| [[#apk dot|dot]]
| Create a [https://graphviz.org/ graphviz] graph description for a given package
|-
| [[#apk_policy|policy]]
| Display the repository that updates a given package, plus repositories that also offer the package
|-
| stats
| Display statistics, including number of packages installed and available, number of directories and files, etc.
|-
| manifest
| Display checksums for files contained in a given package
|}

== Packages and Repositories ==
{{Main|Repositories}}
Software packages for Alpine Linux are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata. They have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file.

=== Subpackages ===

In Alpine Linux, software packages are thinned out and split into subpackages to give more control over what features are installed and keeps the installation as small and efficient as possible.

== World ==

At {{Path|/etc/apk/world}}, apk maintains the world, that is, a list of constraints the package selection needs to fulfill. World describes the desired system state. The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}.

{{Path|/etc/apk/world}} is a plaintext file with one constraint using dependency notation per line. Each line has the format: 
<code>name{@tag}{[<>~=]version}</code>

apk will by default only use the untagged repositories, but adding a package with a @tag will make apk use the [[Repositories#Tagged_repository|tagged repository]] for the named package. It also allows pulling in dependencies for the tagged package from the tagged repository, though it prefers to use untagged repositories to satisfy dependencies if possible.

Every constraint listed in {{Path|/etc/apk/world}} must be solvable in order for the system to be considered correct, and no transaction may be committed that is incorrect. If apk cannot verify the correctness of the requested change, it will back out adding the constraint before attempting to change what packages are actually installed on the system. Thus apk will never [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

== apk fix ==

If a package is specified, the '''fix''' subcommand applies repair strategies to correct errors in the installation of the specified packages. If no packages are specified, this command synchronizes all the installed packages with the desired system state.

{{Tip|If {{Path|/etc/apk/world}} is edited manually, run the command {{ic|'''# apk fix'''}} to apply the changes.}}

== Update Package list ==

Alpine Linux [[Repositories|'''repositories''']] change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. This command downloads the {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/cache/apk/}}, {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}. {{Cmd|# apk update}}

Adding the <code>--update-cache</code>, or for short <code>-U</code> switch to another apk command, as in <code>apk --update-cache upgrade</code> or <code>apk -U add ...</code>, the command has the same effect as first running <code>apk update</code> before the other apk command.

It is a good idea to always do an '''update''' right '''before''' doing an '''upgrade or add''' command. That way the command will install the latest available packages from the repositories.

== Add a Package ==

Use '''add''' to install packages from a [[Repositories|'''repository''']]. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package. {{Cmd|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|held back or pinned]] at a specific level or version.

=== Add a local Package ===

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the '''--allow-untrusted''' flag: {{cmd|# apk add --allow-untrusted /path/to/file.apk}}

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

{{cmd|# apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==

To get the latest security upgrades and bugfixes available for the currently installed packages from the [[Repositories#Release_Branches|release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

{{Tip|Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used to enable unattended, automatic upgrades of packages.}}

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<Pre>
# apk update
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz</nowiki>
v3.6.2-191-gf98d79930f <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/main]</nowiki>
v3.6.2-190-ga5d68c47df <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/community]</nowiki>
v3.6.0-4624-g11f1b9c8ab <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/testing]</nowiki>
OK: 20118 distinct packages available

# apk upgrade
(1/2) Upgrading extra-cmake-modules@testing (5.38.0-r0 -> 5.39.0-r0)
(2/2) Upgrading extra-cmake-modules-doc@testing (5.38.0-r0 -> 5.39.0-r0)
Executing mdocml-apropos-1.14.1-r0.trigger
OK: 2635 MiB in 803 packages
</Pre>

{{Tip|To upgrade Alpine Linux to a newer [[Repositories#Release_Branches|release branch]], refer [[Upgrading_Alpine|Upgrading Alpine]] page.}}

=== Handling changes in configuration files ===

apk avoids overwriting configuration files in the {{path|/etc}} directory. Whenever apk installs a file there, but realizes a potentially edited one is already present, it will write its file to that filename with {{path|.apk-new}} appended. You may handle these by hand, or use [[Alpine configuration management scripts#update-conf|update-conf]] utility.

* To check for changes to configurations from the new packages: {{Cmd|# update-conf -a -l}}
* Simply invoking it will present you with the difference between the two files, and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages followed by running {{ic|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}} in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

== Search for Packages ==

{{Tip|Alpine Linux provides a specialized [https://pkgs.alpinelinux.org web interface] dedicated to looking through various available packages.}}

The '''search''' command searches the repository Index files for installable packages.

The return format is '''Package'''-'''Version'''. Omit '''Version''' for ''apk add '''Package'''''

Examples:
* To list all packages available, along with their descriptions: {{cmd|$ apk search -v}}
* To list all packages are part of the ACF system: {{cmd|$ apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|$ apk search -v --description 'NTP' }}
* To list all packages that provide the <code>git</code> command: {{cmd|$ apk search -v 'cmd:git'}}

== Information on Packages ==

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information), or all information displayed with the ''-a'' command.

Example: {{cmd|$ apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>https://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

=== Check file ownership ===

The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|$ apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

=== Check Dependencies ===

The '''info''' command specific to check package dependency and reverse dependency is explained below:

The option '''-R''' or '''--depends''' lists the dependencies of the package: {{Cmd|$ apk info --depends pipewire}}
<pre>
pipewire-1.0.6-r1 depends on:
/bin/sh
so:libc.musl-x86_64.so.1
so:libpipewire-0.3.so.0
</pre>

The option '''-r''' or '''--rdepends''' lists the reverse dependencies of the package (all other packages which depend on the package). {{Cmd|$ apk info --rdepends pipewire}}
<pre>
pipewire-1.0.6-r1 is required by:
xdg-desktop-portal-wlr-0.7.1-r0
pipewire-pulse-1.0.6-r1
</pre>

=== Listing installed packages ===

To list all installed packages, use: {{Cmd|$ apk info}}

To list all installed packages in alphabetical order, with a description of each, do:{{Cmd|$ apk -vv info|sort}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ apk list --quiet --origin util-linux}}

The apk tool does not have a subcommand to list manually-installed packages that do not have reverse dependencies. To get this information on a traditional system that is not using [[Alpine local backup|lbu]], try this script. Note that this approach will also list core packages like alpine-base that should not be removed.

<pre>
#!/bin/sh
apk info | grep -ve '-doc$' | sort | while read pkg
do
rdep=`apk info -qr "$pkg"`
[ -z "$rdep" ] && echo $pkg
done
</pre>

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ dot -Tpng seatd_dependencies.dot -o seatd_dependencies.png}}

== apk policy ==

To display the repository a package was installed from and will be updated from, plus any [[#Repository_pinning|tagged]] or enabled repositories where it is also offered, if any, for this architecture - its '''policy''': {{Cmd|$ apk policy ''package''}}

For example:
<pre>
$ apk policy vlc
vlc policy:
2.2.6-r1:
lib/apk/db/installed
https://dl-3.alpinelinux.org/alpine/v3.7/community
3.0.0_rc2-r1:
@edgecommunity https://dl-3.alpinelinux.org/alpine/edge/community
</pre>

== Local Cache ==
{{Main|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|sys mode]] installs don't need an apk cache, it still allows to serve packages over the network, though, e.g. to get installed by other local machines.

{{Note|For [[Diskless Mode|diskless]] installations, [[Local APK cache|local package cache]] is needed to automatically (re-)install packages when booting.}}

When newer packages are added to the cache over time, the older versions of the packages default to remain in the cache directory. The older versions of packages can be removed with the '''clean''' command. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# apk cache download}}

The above two steps can be combined into one with the '''sync''' command - this cleans out old packages and downloads missing packages. {{cmd|# apk cache -v sync}}

== Advanced APK Usage ==

=== Commandline repository options ===

By default, the '''apk''' utility will use the system repositories for all operations. This behavior can be overridden by the following options:
{|
| --repositories-file REPOFILE
| Override the system repositories by specifying a repositories file.
|-
| <nowiki>-X|--repository REPO</nowiki>
| Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.
|}

{{cmd|# apk add cherokee --update-cache --repository https://dl-cdn.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

=== Package pinning ===
{{Seealso|Repositories#Tagged repository}}

In certain cases, you may want to upgrade a system, but keep a specific package at a specific level or version by pinning a Package. It is possible to add "sticky" or versioned dependencies.

{{Warning| If you desire deterministic, repeatable package installation (such as with containerized environments) via package pinning, it is important to understand your package repo's version retention rules. Always pin to a package version that is intended for your [[Repositories#Release_Branches|release branch]]. Pinning to a version on the [[Repositories#Edge|edge]] branch may stop working after the package version is revoked from the repo.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or {{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# apk add 'asterisk>1.6.1'}}

You can also use "fuzzy" version matching to pin the version to a major/minor release. To match any version of asterisk that starts with 1.6 (such as 1.6.0.21-r0 or 1.6.9.31-r9) use the command: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Commit hooks ===

If you'd like to trigger an action or run a certain script on every commit made by apk, there's a built-in method for that. On every commit apk looks for executables located in the "/etc/apk/commit_hooks.d/" directory, and executes them both before and after the commit. To provide some way to selectively run hooks either before or after a change is commited by apk, the scripts are called with "pre-commit" or "post-commit" as argument 1.
This is an example of a hook to do different things before and after commit:

{{cmd|1=#!/bin/sh

if [ "$1" = "pre-commit" ]; then
do_something

elif [ "$1" = "post-commit" ]; then
do_something_else
fi}}

Commit hooks are $PATH-aware, so for the sake of security it's recommended to specify absolute paths to executables.

== Rosetta Stone ==

[[Comparison with other distros#Comparison chart/Rosetta Stone|Rosetta Stone]] or a Comparison chart shows how standard things related to package management are done in Alpine Linux compared to other popular distributions.

== Troubleshooting ==

=== ERROR: unable to select packages ===

This error typically indicates that the package manager cannot find a suitable package to install. On issuing a command to add a package for eg: {{ic|# apk add labwc}}, you may receive below error message:
<Pre>
ERROR: unable to select packages:
labwc (no such package):
required by: world[labwc]
</Pre>

The above error indicates {{pkg|labwc}} does not exist in the [[Repositories|repositories]] currently configured in {{Path|/etc/apk/repositories}}. Ensure that <code>community</code> repository is [[Repositories#Managing_repositories|enabled]], as by default only <code>main</code> repository is enabled. You may also want to check [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and the [[Repositories|repository]] in which the package is available.

<Pre>
ERROR: unable to select packages:
so:libxml2.so.2 (no such package):
required by: llvm19-libs-19.1.7-r1[so:libxml2.so.2]
</Pre>

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ rebuilt]. You may want to wait for some time to try again.

=== ERROR: unsatisfiable constraints ===

This error signifies a dependency conflict. It means that the package you're trying to install has dependencies that cannot be simultaneously satisfied within the current package repository.

You may want to check [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and version and the [[Repositories|repository]] in which the package is available.

=== WARNING: This apk-tools is OLD! ===

'''apk update''', '''apk upgrade''' or '''apk add''' may report the following:
WARNING: This apk-tools is OLD! Some packages might not function properly

This may happen if you are running Alpine Linux stable version with a [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# apk add --upgrade apk-tools@edgemain}}

=== ERROR: UNTRUSTED signature ===

This happens when the release version changes. You need to update the local apk keys.

If you have already updated your repositories, allow them to update without the trusted key:
{{Cmd|# apk update --allow-untrusted}}

Then install the keys upgrade:
{{Cmd|# apk fix --upgrade --allow-untrusted alpine-keys}}

Now updates and upgrades should proceed normally.

Alternative, the updated alpine-keys package may be obtained, verified, installed directly, as covered earlier, prior to a repository update.

=== World updated but the following packages are not removed ===

On issuing a command to remove a package for eg: {{ic|# apk del btrfs-progs}}, you may receive below error message:
<Pre>
World updated, but the following packages are not removed due to:
btrfs-progs: btrbk
</Pre>

Here, the removal of package {{Pkg|btrfs-progs}} affects another package {{Pkg|btrbk}} in the constraints file [[#World|/etc/apk/world]]. So the package {{Pkg|btrfs-progs}} will be removed from the constraints file, but not removed from the system. The {{Pkg|btrfs-progs}} will remain in the system, until the constraint i.e {{Pkg|btrbk}} which depends on {{Pkg|btrfs-progs}} is removed.

If {{ic|apk del btrbk}} is issued, the package {{Pkg|btrfs-progs}} will be automatically removed from system as the constraint {{Pkg|btrfs-progs}} does not exist in {{Path|/etc/apk/world}}.

== See also ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html spelunking through the apk-tools dependency solver]
* [https://whynothugo.nl/journal/2023/02/18/in-praise-of-alpine-and-apk/ In praise of alpine and apk]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Pipewire

2025-11-15T23:37:46Z

Encode: Redirect ‘pipewire’ → ‘PipeWire’

#REDIRECT [[PipeWire]]

Dbus

2025-11-15T23:34:56Z

Encode: Redirect dbus > D-Bus

#REDIRECT [[D-Bus]]

User:Encode

2025-03-19T05:00:52Z

Encode: I don't think this is the right way to do things anymore

[[User:Encode/XDG_package_building]]

User:Encode/Workstation

2025-03-19T05:00:05Z

Encode: Request deletion, I don't think this is the right way to do things anymore

{{Delete|I don't think this is the right way to do things anymore.}}



{{TOC right}}

'''Alpine Linux''' has no official desktop; older versions used [[Xfce]], but now, all GUI and graphical interfaces are optional. This page is an attempt at being a ''jumping off page'' for everything you need to have a decent workstation.

{{Tip|Combine a version control system (like [[:Category:Git|Git]]) and a configuration management/deployment system (like [[Ansible]]) to automate this.}}

== [https://en.wikipedia.org/wiki/Graphical_user_interface Graphical user interfaces (GUI)] ==

=== Display Server ===

* [[Wayland]]
* [[X|X (also called: Xorg, X11)]]

=== Desktop environments ===

* [[GNOME]]
* [[KDE|KDE Plasma]]
* [[LXQt]]
* [[MATE]]
* [[Xfce]]

=== Window managers ===

==== [https://en.wikipedia.org/wiki/Stacking_window_manager Stacking (floating) window managers] ====

* [[Wayland]]:
** [[LabWC]]
** [[Wayfire]]
** [[Weston]]

* [[X]]:
** [[Fluxbox (spanish)]]
** [[Openbox]]

==== [https://en.wikipedia.org/wiki/Tiling_window_manager Tiling (dynamic) window managers] ====

* [[Wayland]]:
** [[River]]
** [[Sway]]

* [[X]]:
** [[AwesomeWM]]
** [[Dwm]]
** [[I3wm]]

== Fonts ==

{{Note|Depending on the Desktop environment/window manager fonts may or may not be installed automatically.}}

* [[Fonts]]

== Networking ==

* [[Tutorials_and_Howtos#Networking_2|Networking]]

== Printer ==

* [[Printer Setup]]

== Sound ==

{{Note|If you are unsure, [[PipeWire]] is recommended.}}

* [[ALSA]]
* [[PipeWire]]
* [[PulseAudio]]

== Laptop ==

{{Expand|To be done.}}

* [[Suspend on LID close]]
* Power management
** Suspend and hibernate
** [[CPU frequency scaling]]

== Miscellaneous ==

* [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|man command/man pages]]
* [[Default applications]] - Changing the default application associated with a filetype.
* [[Bubblewrap]] - Unprivileged sandboxing tool.

== See Also ==

* [[Installation#Post-Installation|Post Install]]

[[Category:Desktop]]

Bubblewrap/Examples

2025-03-18T23:02:27Z

Encode: *: Separate shell command short options that don't take input from ones that do, I think it adds clarity

{{Draft|Someone more experienced needs to look over this.}}

{{Todo|
* Since bubblewrap can make use of [https://en.wikipedia.org/wiki/Seccomp seccomp], restrictive versions should be added.
* {{Ic|imv}}, {{Ic|mpv}} and {{Ic|zathura}} currently only accept 1 mandatory (except {{Ic|imv}}) argument. This should (hopefully) be temporary, until I figure out how to pass multiple arguments (without including everything else).}}

{{Warning|These were found by going backward; start with a complicated program and as restricted as possible sandbox, allowing more till the program appears to work. Because of this, complicated and sensitive programs (for example: {{Pkg|firefox|arch=}} and {{Pkg|keepassxc|arch=}}) may be missing some things they need, which might lead to '''LESS SECURITY''', '''LESS PRIVACY''' and '''DATA LOSS'''.}}

{{Note|
* This page assumes you have already read [[Bubblewrap]].
* To try and avoid duplicates everything will be explained for [[Firefox]] and only when it differs (non obviously) for everything else.
* Where applicable, this assumes: [[Wayland]] only + [[PipeWire]].
: If Wayland is needed, make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

{{TOC right}}

== Firefox ==

{{Cat|~/.local/bin/bwrap-firefox|#!/bin/sh

# Firefox wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"

mkdir -p -m 0700 "${XDG_DATA_HOME}/firefox/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--ro-bind-try /etc/firefox/policies/policies.json /etc/firefox/policies/policies.json \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
--ro-bind /usr/share/icons/ /usr/share/icons/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
/usr/lib/firefox/firefox}}

set -u
If the shell tries to expand an unset parameter, it will error (with a
few exceptions).

XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
Take value if already set, else fallback to the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG] default.

NEW_HOME='/home/user'
User to appear as.

NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
{{Path|"$XDG_CACHE_HOME"}} for the new user.

mkdir -p -m 0700 "${XDG_DATA_HOME}/firefox/"
Make sure the new (real) home for Firefox data exist.

--unshare-all \
Unshare all possible [https://en.wikipedia.org/wiki/Linux_namespaces namespaces].

--share-net \
Retain the network namespace.

--new-session \
New terminal session for the sandbox.

--die-with-parent \
Child process dies when {{Ic|bwrap}} parent dies.

--clearenv \
Unset all environment variables (except for {{Path|"$PWD"}}).

--setenv HOME "$NEW_HOME" \
Pass the path to {{Path|"$NEW_HOME"}} for {{Path|"$HOME"}}.

--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
Specify the Wayland display to run clients on.

--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
User-specific non-essential (cached) data.

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
User-specific non-essential runtime files and other file objects.

--hostname localhost \
Use custom hostname in the sandbox.

--dev /dev/ \
New devtmpfs, access to special or device files.

--ro-bind-try /etc/firefox/policies/policies.json /etc/firefox/policies/policies.json \
Set Firefox [https://mozilla.github.io/policy-templates/ policies], if found.

--ro-bind /etc/fonts/ /etc/fonts/ \
System font configuration directory.

--ro-bind /etc/resolv.conf /etc/resolv.conf \
Needed for DNS resolution.

--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
Per-user Mozilla cache.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:-$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${NEW_XDG_CONFIG_HOME}/fontconfig/" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) Per-user font configuration directory.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:-$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/user-dirs.dirs" "${NEW_XDG_CONFIG_HOME}/user-dirs.dirs" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) If you modify "well known" user directories, like
{{Path|~/Downloads/}}, you need this to have Firefox pick it up.

{{Note|If you use {{Path|"${XDG_CONFIG_HOME}/user-dirs.dirs"}} you should also add the corresponding path(s).
For example if you set {{Path|XDG_DOWNLOAD_DIR}} to
{{Path|"${HOME}/downloads/"}} you would also add:
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--bind-try "${HOME}/downloads/" "${NEW_HOME}/downloads/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
}}

--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
{{Path|"${XDG_DATA_HOME}/firefox/"}} is the location of Firefox data. Shown to Firefox as {{Path|"${NEW_HOME}/.mozilla/"}}.

{{Note|This has the added benefit of getting {{Path|~/.mozilla/}} out of your {{Path|"$HOME"}}, and conforming more to XDG. This may one day not be necessary: [https://bugzilla.mozilla.org/show_bug.cgi?id{{=}}259356 Support for the Freedesktop.org XDG Base Directory Specification (2004-09-14)].}}

...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${NEW_XDG_DATA_HOME}/fonts/" \'''
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
...
(Optional) Per-user directory scanned for font files.

--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Default {{Path|~/Downloads/}} directory.

--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
Shared libraries.

--proc /proc/ \
New procfs, provides information about running processes and the kernel.

--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
Bind the Wayland socket file.

--ro-bind /usr/lib/ /usr/lib/ \
Object files and libraries.

{{Note|It is not worth the time to limit this, the churn is too great.}}

--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
XKB is a keyboard keymap support library.

{{Note|Even tho the path has {{Path|*/X11/*}} Wayland uses it too.}}

--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
Font presets.

--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
Global directory scanned for font files.

--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
Needed for "Save Page As…", "Export|Import Bookmarks File", among others.

--ro-bind /usr/share/icons/ /usr/share/icons/ \
Global icons directory.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
International Components for Unicode (ICU) provides support for Unicode
and globalization.

...
--ro-bind /usr/share/icu/ /usr/share/icu/ \
'''--ro-bind /usr/share/libdrm/ /usr/share/libdrm/ \'''
--ro-bind /usr/share/mime/ /usr/share/mime/ \
...
(Optional) Direct Rendering Manager (DRM), Linux kernel subsystem for
interfacing with GPUs of video cards. Programs can use this to have the
GPU do hardware-accelerated 3D rendering and video decoding.

--ro-bind /usr/share/mime/ /usr/share/mime/ \
Global XDG MIME directory.

/usr/lib/firefox/firefox
Call Firefox.

{{Tip|If you use multiple profiles you can have:
/usr/lib/firefox/firefox -P "$@"
this will allow you to pass a profile name and go into that specific one or not pass anything and get prompted for which to choose.}}

=== PipeWire audio ===

{{Todo|}}

=== Pulse audio ===

...
--proc /proc/ \
'''--ro-bind "${XDG_RUNTIME_DIR}/pulse/" "${XDG_RUNTIME_DIR}/pulse/" \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
(Optional) Pulse audio.

=== Optional(?) stuff ===

{{Draft|Are these needed?}}

...
--proc /proc/ \
'''--ro-bind /sys/bus/pci/ /sys/bus/pci/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Information about PCI bus type.

Without this you get
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: cannot access /sys/bus/pci (t=0.177033) [GFX1-]: glxtest: cannot access /sys/bus/pci
but it still seems to work.

...
--proc /proc/ \
'''--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Contains a filesystem representation of the kernel device tree.

With {{Ic|--ro-bind /sys/bus/pci/ /sys/bus/pci/ \}} but without this you get:
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) [GFX1-]: glxtest: ManageChildProcess failed

Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) |[1][GFX1-]: No GPUs detected via PCI
(t=0.18958) [GFX1-]: No GPUs detected via PCI
but it still seems to work.

== imv ==

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

...

'''XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"'''
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
'''XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \'''
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
'''--ro-bind /etc/fonts/ /etc/fonts/ \'''
'''--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \'''
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \'''
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
'''--ro-bind /usr/share/fonts/ /usr/share/fonts/ \'''
'''--ro-bind /usr/share/icu/ /usr/share/icu/ \'''
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
...
(Optional) To use commands in {{Ic|imv}}.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument. If you don't pass in
anything it will default to {{Path|./}}, the current directory.

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}

== KeePassXC ==

{{Note|I only use the bare minimum functionality, so functionality you need is probably missing. If you use functionality not here, your contribution will be most appreciated. To kick things off: {{Ic|Unable to initialize libusb. USB devices may not be detected properly.}} can be silenced with {{Ic|--dev-bind /dev/bus/usb/ /dev/bus/usb/ \}}.}}

{{Cat|~/.local/bin/bwrap-keepassxc|#!/bin/sh

# keepassxc wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
PASSWORD_DATABASE{{=}}"${HOME}/password database"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_PASSWORD_DATABASE{{=}}"${NEW_HOME}${PASSWORD_DATABASE#"$HOME"}"

mkdir -p -m 0700 "$PASSWORD_DATABASE"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CONFIG_HOME}/keepassxc/" "${NEW_XDG_CONFIG_HOME}/keepassxc/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind /usr/bin/keepassxc /usr/bin/keepassxc \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/ /usr/share/X11/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/keepassxc/ /usr/share/keepassxc/ \
--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
/usr/bin/keepassxc "$@"}}

PASSWORD_DATABASE="${HOME}/password database"
Directory containing your {{Pkg|keepassxc|arch=}} password database.

{{Tip|This is almost certainly not where '''your''' database is located. You will need to change it to where you put your password database.}}

--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
Session type, since we are assuming Wayland only, this will be "wayland".

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
Bind password database.

== mpv ==

{{Cat|~/.local/bin/bwrap-mpv|#!/bin/sh

# mpv wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run mpv wrapped in bwrap.

Usage:
$ bwrap-mpv VIDEO\n'
exit 1
fi

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$1"}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

--player-operation-mode=pseudo-gui \
Because {{Ic|--new-session}} is used, this is needed to have a way to
control {{Ic|mpv}} when it would otherwise not show a GUI.

{{Tip|If you followed [[Bubblewrap#.desktop_integration]], you should remove it from {{Path|"${XDG_DATA_HOME}/applications/bwrap-mpv.desktop"}}.}}

--title='bwrap | ${media-title}' \
Set the window title, showing at a glance that you are using {{Ic|bwrap}}.

=== mpv-net ===

If you want to use {{Ic|mpv}} to stream over the Internet, you will need
a few things more.

{{Tip|You can use both {{Ic|bwrap-mpv}} and {{Ic|bwrap-mpv-net}}. {{Ic|bwrap-mpv}} for local stuff and {{Ic|bwrap-mpv-net}} for watching over the Internet.}}

{{Cat|~/.local/bin/bwrap-mpv-net|#!/bin/sh

# mpv wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv PATH /usr/bin/ \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$@"}}

--setenv PATH /usr/bin/ \
{{Todo|Document why this is needed.}}

--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
Certificate authorities that are ''trusted''.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

"$@"
This is so you can pass more options to {{Ic|bwrap-mpv-net}}, for example:
$ bwrap-mpv-net --video=no --sub=no 'URL1' 'URL2'

=== Pulse audio ===

--ro-bind "${XDG_RUNTIME_DIR}/pulse" "${XDG_RUNTIME_DIR}/pulse" \
Pulse audio.

=== Screenshots ===

The default screenshots directory is {{Path|"$XDG_DESKTOP_DIR"}} (which is
{{Path|"${HOME}/Desktop/"}}, which will fallback to {{Path|"$HOME/"}} if
{{Path|"${HOME}/Desktop/"}} doesn't exist). That means that by default
{{Ic|bwrap-mpv[-net]}} won't allow screenshots unless you change a few things.
Do the following to allow an XDG approved screenshots directory:

...
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
'''XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"'''

...
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

'''mkdir -p -m 0700 "${XDG_DATA_HOME}/mpv/"'''

...
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
'''--bind "${XDG_DATA_HOME}/mpv/" "${NEW_XDG_DATA_HOME}/mpv/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
Now make {{Ic|mpv}} use that directory:

{{Cat|"${XDG_CONFIG_HOME}/mpv/mpv.conf"|<nowiki>...
# Something like this, change to match your "$XDG_DATA_HOME"
screenshot-template="~/.local/share/mpv/screenshots/%F [%p] %02n"
...</nowiki>}}

== yt-dlp ==

{{Cat|~/.local/bin/bwrap-yt-dlp|#!/bin/sh

# yt-dlp wrapped in bwrap with network access.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

mkdir -p -m 0700 "${HOME}/Downloads/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--hostname localhost \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--ro-bind-try "${XDG_CONFIG_HOME}/yt-dlp/config" "${NEW_XDG_CONFIG_HOME}/yt-dlp/config" \
--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/bin/ffmpeg /usr/bin/ffmpeg \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
/usr/bin/yt-dlp "$@"}}

--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Directory for writing the files. This should match {{Ic|--output}} that
is either in {{Path|"${XDG_CONFIG_HOME}/yt-dlp/config"}} or passed on
the command line.

/usr/bin/yt-dlp "$@"
This is so you can pass more options to {{Ic|bwrap-yt-dlp}}, for example:
$ bwrap-yt-dlp --no-playlist 'URL1' 'URL2'

== zathura ==

{{Cat|~/.local/bin/bwrap-zathura|#!/bin/sh

# zathura wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run zathura wrapped in bwrap.

Usage:
$ bwrap-zathura PDF\n'
exit 1
fi

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"

mkdir -p -m 0700 "${XDG_DATA_HOME}/zathura/"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/zathura/zathurarc" "${XDG_CONFIG_HOME}/zathura/zathurarc" \
--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/zathura /usr/bin/zathura \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/zathura "$1"}}

mkdir -p -m 0700 "${XDG_DATA_HOME}/zathura/"
Have to premake the directory for {{Ic|zathura}} data.

--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
Allow writing of: bookmarks, history, input history.

--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
Used for identifying what type a file should be. Read the
{{Ic|file(1)}} man page for more information.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

[[Category:Security]]

Bubblewrap/Examples

2025-03-18T22:50:59Z

Encode: Firefox: allow policies, if found

{{Draft|Someone more experienced needs to look over this.}}

{{Todo|
* Since bubblewrap can make use of [https://en.wikipedia.org/wiki/Seccomp seccomp], restrictive versions should be added.
* {{Ic|imv}}, {{Ic|mpv}} and {{Ic|zathura}} currently only accept 1 mandatory (except {{Ic|imv}}) argument. This should (hopefully) be temporary, until I figure out how to pass multiple arguments (without including everything else).}}

{{Warning|These were found by going backward; start with a complicated program and as restricted as possible sandbox, allowing more till the program appears to work. Because of this, complicated and sensitive programs (for example: {{Pkg|firefox|arch=}} and {{Pkg|keepassxc|arch=}}) may be missing some things they need, which might lead to '''LESS SECURITY''', '''LESS PRIVACY''' and '''DATA LOSS'''.}}

{{Note|
* This page assumes you have already read [[Bubblewrap]].
* To try and avoid duplicates everything will be explained for [[Firefox]] and only when it differs (non obviously) for everything else.
* Where applicable, this assumes: [[Wayland]] only + [[PipeWire]].
: If Wayland is needed, make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

{{TOC right}}

== Firefox ==

{{Cat|~/.local/bin/bwrap-firefox|#!/bin/sh

# Firefox wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--ro-bind-try /etc/firefox/policies/policies.json /etc/firefox/policies/policies.json \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
--ro-bind /usr/share/icons/ /usr/share/icons/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
/usr/lib/firefox/firefox}}

set -u
If the shell tries to expand an unset parameter, it will error (with a
few exceptions).

XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
Take value if already set, else fallback to the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG] default.

NEW_HOME='/home/user'
User to appear as.

NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
{{Path|"$XDG_CACHE_HOME"}} for the new user.

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"
Make sure the new (real) home for Firefox data exist.

--unshare-all \
Unshare all possible [https://en.wikipedia.org/wiki/Linux_namespaces namespaces].

--share-net \
Retain the network namespace.

--new-session \
New terminal session for the sandbox.

--die-with-parent \
Child process dies when {{Ic|bwrap}} parent dies.

--clearenv \
Unset all environment variables (except for {{Path|"$PWD"}}).

--setenv HOME "$NEW_HOME" \
Pass the path to {{Path|"$NEW_HOME"}} for {{Path|"$HOME"}}.

--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
Specify the Wayland display to run clients on.

--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
User-specific non-essential (cached) data.

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
User-specific non-essential runtime files and other file objects.

--hostname localhost \
Use custom hostname in the sandbox.

--dev /dev/ \
New devtmpfs, access to special or device files.

--ro-bind-try /etc/firefox/policies/policies.json /etc/firefox/policies/policies.json \
Set Firefox [https://mozilla.github.io/policy-templates/ policies], if found.

--ro-bind /etc/fonts/ /etc/fonts/ \
System font configuration directory.

--ro-bind /etc/resolv.conf /etc/resolv.conf \
Needed for DNS resolution.

--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
Per-user Mozilla cache.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:-$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${NEW_XDG_CONFIG_HOME}/fontconfig/" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) Per-user font configuration directory.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:-$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/user-dirs.dirs" "${NEW_XDG_CONFIG_HOME}/user-dirs.dirs" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) If you modify "well known" user directories, like
{{Path|~/Downloads/}}, you need this to have Firefox pick it up.

{{Note|If you use {{Path|"${XDG_CONFIG_HOME}/user-dirs.dirs"}} you should also add the corresponding path(s).
For example if you set {{Path|XDG_DOWNLOAD_DIR}} to
{{Path|"${HOME}/downloads/"}} you would also add:
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--bind-try "${HOME}/downloads/" "${NEW_HOME}/downloads/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
}}

--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
{{Path|"${XDG_DATA_HOME}/firefox/"}} is the location of Firefox data. Shown to Firefox as {{Path|"${NEW_HOME}/.mozilla/"}}.

{{Note|This has the added benefit of getting {{Path|~/.mozilla/}} out of your {{Path|"$HOME"}}, and conforming more to XDG. This may one day not be necessary: [https://bugzilla.mozilla.org/show_bug.cgi?id{{=}}259356 Support for the Freedesktop.org XDG Base Directory Specification (2004-09-14)].}}

...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${NEW_XDG_DATA_HOME}/fonts/" \'''
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
...
(Optional) Per-user directory scanned for font files.

--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Default {{Path|~/Downloads/}} directory.

--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
Shared libraries.

--proc /proc/ \
New procfs, provides information about running processes and the kernel.

--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
Bind the Wayland socket file.

--ro-bind /usr/lib/ /usr/lib/ \
Object files and libraries.

{{Note|It is not worth the time to limit this, the churn is too great.}}

--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
XKB is a keyboard keymap support library.

{{Note|Even tho the path has {{Path|*/X11/*}} Wayland uses it too.}}

--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
Font presets.

--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
Global directory scanned for font files.

--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
Needed for "Save Page As…", "Export|Import Bookmarks File", among others.

--ro-bind /usr/share/icons/ /usr/share/icons/ \
Global icons directory.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
International Components for Unicode (ICU) provides support for Unicode
and globalization.

...
--ro-bind /usr/share/icu/ /usr/share/icu/ \
'''--ro-bind /usr/share/libdrm/ /usr/share/libdrm/ \'''
--ro-bind /usr/share/mime/ /usr/share/mime/ \
...
(Optional) Direct Rendering Manager (DRM), Linux kernel subsystem for
interfacing with GPUs of video cards. Programs can use this to have the
GPU do hardware-accelerated 3D rendering and video decoding.

--ro-bind /usr/share/mime/ /usr/share/mime/ \
Global XDG MIME directory.

/usr/lib/firefox/firefox
Call Firefox.

{{Tip|If you use multiple profiles you can have:
/usr/lib/firefox/firefox -P "$@"
this will allow you to pass a profile name and go into that specific one or not pass anything and get prompted for which to choose.}}

=== PipeWire audio ===

{{Todo|}}

=== Pulse audio ===

...
--proc /proc/ \
'''--ro-bind "${XDG_RUNTIME_DIR}/pulse/" "${XDG_RUNTIME_DIR}/pulse/" \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
(Optional) Pulse audio.

=== Optional(?) stuff ===

{{Draft|Are these needed?}}

...
--proc /proc/ \
'''--ro-bind /sys/bus/pci/ /sys/bus/pci/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Information about PCI bus type.

Without this you get
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: cannot access /sys/bus/pci (t=0.177033) [GFX1-]: glxtest: cannot access /sys/bus/pci
but it still seems to work.

...
--proc /proc/ \
'''--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Contains a filesystem representation of the kernel device tree.

With {{Ic|--ro-bind /sys/bus/pci/ /sys/bus/pci/ \}} but without this you get:
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) [GFX1-]: glxtest: ManageChildProcess failed

Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) |[1][GFX1-]: No GPUs detected via PCI
(t=0.18958) [GFX1-]: No GPUs detected via PCI
but it still seems to work.

== imv ==

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

...

'''XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"'''
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
'''XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \'''
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
'''--ro-bind /etc/fonts/ /etc/fonts/ \'''
'''--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \'''
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \'''
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
'''--ro-bind /usr/share/fonts/ /usr/share/fonts/ \'''
'''--ro-bind /usr/share/icu/ /usr/share/icu/ \'''
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
...
(Optional) To use commands in {{Ic|imv}}.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument. If you don't pass in
anything it will default to {{Path|./}}, the current directory.

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}

== KeePassXC ==

{{Note|I only use the bare minimum functionality, so functionality you need is probably missing. If you use functionality not here, your contribution will be most appreciated. To kick things off: {{Ic|Unable to initialize libusb. USB devices may not be detected properly.}} can be silenced with {{Ic|--dev-bind /dev/bus/usb/ /dev/bus/usb/ \}}.}}

{{Cat|~/.local/bin/bwrap-keepassxc|#!/bin/sh

# keepassxc wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
PASSWORD_DATABASE{{=}}"${HOME}/password database"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_PASSWORD_DATABASE{{=}}"${NEW_HOME}${PASSWORD_DATABASE#"$HOME"}"

mkdir -pm 0700 "$PASSWORD_DATABASE"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CONFIG_HOME}/keepassxc/" "${NEW_XDG_CONFIG_HOME}/keepassxc/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind /usr/bin/keepassxc /usr/bin/keepassxc \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/ /usr/share/X11/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/keepassxc/ /usr/share/keepassxc/ \
--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
/usr/bin/keepassxc "$@"}}

PASSWORD_DATABASE="${HOME}/password database"
Directory containing your {{Pkg|keepassxc|arch=}} password database.

{{Tip|This is almost certainly not where '''your''' database is located. You will need to change it to where you put your password database.}}

--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
Session type, since we are assuming Wayland only, this will be "wayland".

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
Bind password database.

== mpv ==

{{Cat|~/.local/bin/bwrap-mpv|#!/bin/sh

# mpv wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run mpv wrapped in bwrap.

Usage:
$ bwrap-mpv VIDEO\n'
exit 1
fi

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$1"}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

--player-operation-mode=pseudo-gui \
Because {{Ic|--new-session}} is used, this is needed to have a way to
control {{Ic|mpv}} when it would otherwise not show a GUI.

{{Tip|If you followed [[Bubblewrap#.desktop_integration]], you should remove it from {{Path|"${XDG_DATA_HOME}/applications/bwrap-mpv.desktop"}}.}}

--title='bwrap | ${media-title}' \
Set the window title, showing at a glance that you are using {{Ic|bwrap}}.

=== mpv-net ===

If you want to use {{Ic|mpv}} to stream over the Internet, you will need
a few things more.

{{Tip|You can use both {{Ic|bwrap-mpv}} and {{Ic|bwrap-mpv-net}}. {{Ic|bwrap-mpv}} for local stuff and {{Ic|bwrap-mpv-net}} for watching over the Internet.}}

{{Cat|~/.local/bin/bwrap-mpv-net|#!/bin/sh

# mpv wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv PATH /usr/bin/ \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$@"}}

--setenv PATH /usr/bin/ \
{{Todo|Document why this is needed.}}

--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
Certificate authorities that are ''trusted''.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

"$@"
This is so you can pass more options to {{Ic|bwrap-mpv-net}}, for example:
$ bwrap-mpv-net --video=no --sub=no 'URL1' 'URL2'

=== Pulse audio ===

--ro-bind "${XDG_RUNTIME_DIR}/pulse" "${XDG_RUNTIME_DIR}/pulse" \
Pulse audio.

=== Screenshots ===

The default screenshots directory is {{Path|"$XDG_DESKTOP_DIR"}} (which is
{{Path|"${HOME}/Desktop/"}}, which will fallback to {{Path|"$HOME/"}} if
{{Path|"${HOME}/Desktop/"}} doesn't exist). That means that by default
{{Ic|bwrap-mpv[-net]}} won't allow screenshots unless you change a few things.
Do the following to allow an XDG approved screenshots directory:

...
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
'''XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"'''

...
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

'''mkdir -pm 0700 "${XDG_DATA_HOME}/mpv/"'''

...
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
'''--bind "${XDG_DATA_HOME}/mpv/" "${NEW_XDG_DATA_HOME}/mpv/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
Now make {{Ic|mpv}} use that directory:

{{Cat|"${XDG_CONFIG_HOME}/mpv/mpv.conf"|<nowiki>...
# Something like this, change to match "$XDG_DATA_HOME"
screenshot-template="~/.local/share/mpv/screenshots/%F [%p] %02n"
...</nowiki>}}

== yt-dlp ==

{{Cat|~/.local/bin/bwrap-yt-dlp|#!/bin/sh

# yt-dlp wrapped in bwrap with network access.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

mkdir -pm 0700 "${HOME}/Downloads/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--hostname localhost \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--ro-bind-try "${XDG_CONFIG_HOME}/yt-dlp/config" "${NEW_XDG_CONFIG_HOME}/yt-dlp/config" \
--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/bin/ffmpeg /usr/bin/ffmpeg \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
/usr/bin/yt-dlp "$@"}}

--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Directory for writing the files. This should match {{Ic|--output}} that
is either in {{Path|"${XDG_CONFIG_HOME}/yt-dlp/config"}} or passed on
the command line.

/usr/bin/yt-dlp "$@"
This is so you can pass more options to {{Ic|bwrap-yt-dlp}}, for example:
$ bwrap-yt-dlp --no-playlist 'URL1' 'URL2'

== zathura ==

{{Cat|~/.local/bin/bwrap-zathura|#!/bin/sh

# zathura wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run zathura wrapped in bwrap.

Usage:
$ bwrap-zathura PDF\n'
exit 1
fi

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/zathura/zathurarc" "${XDG_CONFIG_HOME}/zathura/zathurarc" \
--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/zathura /usr/bin/zathura \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/zathura "$1"}}

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"
Have to premake the directory for {{Ic|zathura}} data.

--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
Allow writing of: bookmarks, history, input history.

--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
Used for identifying what type a file should be. Read the
{{Ic|file(1)}} man page for more information.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

[[Category:Security]]

Gaming on Alpine

2025-03-18T07:02:27Z

Encode: Xonotic: Mention clients and server

This page documents the various game related packages available in Alpine Linux and lists alternate ways to game. If you are interested in developing games on Alpine Linux visit [[Game development on Alpine Linux]].

== Installing Games ==

Like with installing any other package, run the following:

{{Cmd|# apk add [game]}}

Where <code>[game]</code> is the name of the package containing the game, like <code>micro-tetris</code> from among the [[#List of games|available games]].

== Steam ==
{{Main|Steam}}
Steam, a popular game distribution platform by Valve can be run on Alpine Linux through [[Flatpak]].

== Wine ==

{{Pkg|wine}} allows you to run some Windows software, including games, under Linux. A 32-bit Alpine chroot/multiboot might be required to use 32 bit Windows games under Wine. If you use x86_64, 32-bit applications will run in Wine's experimental WoW64 mode, which may not be compatible with all software.

To run windows app/games inside a [https://www.reddit.com/r/linux4noobs/comments/1fegh0i/winealpine/ docker container] with alpine Linux, {{pkg|libcap}} is required to fix issues related to [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ#failed-to-use-icmp-network-ping-this-requires-special-permissions raw sockets]

<Pre>
RUN apk add --no-cache libcap
RUN setcap cap_net_raw+epi /usr/bin/wine-preloader
</Pre>

== Permissions ==

To make sure your account is in the "games" group, run the following:

{{Cmd|# adduser youruser games}}

Log-off and then log back on in order for the changes to take effect. Most games don't require this in order to work.

== List of games ==

Below is the list of games packages available in Alpine Linux:
{|class="wikitable" 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="20%" |Game
|width="20%" | Package name
|| Description
|-
| [https://www.advancemame.it/ AdvanceMAME] || {{Pkg|advancemame}} || Arcade simulator.
|-
| [https://gitlab.gnome.org/GNOME/aisleriot Aisleriot] || {{Pkg|aisleriot}} || Solitaire card games.
|-
|[https://www.chocolate-doom.org/wiki/index.php/Chocolate_Doom Chocolate Doom] || {{Pkg|chocolate-doom}} || Portable release of Doom, Heretic, Hexen, and Strife
|-
| [https://www.dosbox-staging.org/ DOSBox Staging] || {{Pkg|dosbox-staging}} || DOS-emulator that uses SDL.
|-
| [https://www.flightgear.org/ FlightGear]|| {{Pkg|flightgear}} || Flight simulator.
|-
| [https://www.freeciv.org Freeciv]|| {{Pkg|freeciv}} || Free and Open Source empire-building strategy game.
|-
|[https://freedoom.github.io/ Freedoom]|| {{Pkg|freedoom}} || an entirely free software game running on a Doom engine.
|-
| [https://davidgriffith.gitlab.io/frotz/ Frotz] || {{Pkg|frotz}} || Z machine (Infocom interactive fiction) Interpreter.
|-
| [https://gcompris.net/index-en.html GCompris] || {{Pkg|gcompris-qt}} || Educational software suite comprising of numerous activities for children aged 2 to 10.
|-
| [https://www.gnu.org/software/chess/ GNU Chess]|| {{Pkg|gnuchess}} || Play chess against the computer.
|-
|[https://zdoom.org/index GZDoom] || {{Pkg|gzdoom}} || Modern game engine resembling modern FPSes compatible with Doom WADs
|-
| [https://lgames.sourceforge.io/LBreakout2/ LBreakout2]|| {{Pkg|lbreakout2}} || Ball-and-paddle game.
|-
| [https://lgames.sourceforge.io/LBreakoutHD LBreakoutHD] || {{Pkg|lbreakouthd}} || {{Note|No level editor available.}}
The successor to LBreakout2.
{{Pkg|lbreakout2}} is needed for level creation.
|-
| [https://lgames.sourceforge.io/LPairs LPairs]|| {{Pkg|lpairs2}} || Classical memory game.
|-
| [https://www.luanti.org/ Luanti] || {{Pkg|luanti}} || An open source voxel game engine.
|-
| [https://github.com/troglobit/tetris Micro Tetris] || {{Pkg|micro-tetris}} || A version of Tetris that uses ANSI escape sequences and can fit in embedded devices.
|-
| [https://www.nethack.org NetHack] || {{Pkg|nethack}} || A single player Rogue-like dungeon crawler or dungeon exploration game
|-
| [https://openrct2.io/ OpenRCT2] || {{Pkg|openrct2}} || {{Note| Requires original files of “RollerCoaster Tycoon 2” to play.}}
A free and open-source reimplementation of “RollerCoaster Tycoon 2”.
|-
| [https://www.openttd.org/ OpenTTD]|| {{Pkg|openttd}} || A business simulation game.
|-
| [https://www.retroarch.com/ RetroArch] || {{Pkg|retroarch}} || Frontend for emulators, game engines, and media players using libretro.
|-
| [https://www.scummvm.org/ ScummVM]|| {{Pkg|scummvm}} || Engine for several graphical adventure games.
|-
| [https://www.supertux.org/ SuperTux] || {{Pkg|supertux}} || Classic 2D jump'n'run side-scroller game in a style similar to the original Super Mario games.
|-
|[https://supertuxkart.net/Main_Page SuperTuxKart] || {{pkg|supertuxkart}} || Kart racing game with OSS mascots.
|-
|[https://www.xonotic.org/ Xonotic] || {{Pkg|xonotic}} || The Free and Fast Arena Shooter.
Clients are: {{Pkg|xonotic-sdl}} or {{Pkg|xonotic-glx}}. Install {{Pkg|xonotic-server}} to run a dedicated server.
|}

== See also ==
* [[Steam|Steam on Alpine Linux]]
* [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ Wine FAQ]
* [https://obsproject.com/ OBS Studio] ({{Pkg|obs-studio}}) - Used by live streamers on streaming platforms such as YouTube and Twitch.
* [https://wine.htmlvalidator.com/install-wine-on-alpine-linux-3.html How to Install Wine on Alpine Linux 3]
[[category:Gaming]]

Gaming on Alpine

2025-03-18T06:50:09Z

Encode: Update game website links

This page documents the various game related packages available in Alpine Linux and lists alternate ways to game. If you are interested in developing games on Alpine Linux visit [[Game development on Alpine Linux]].

== Installing Games ==

Like with installing any other package, run the following:

{{Cmd|# apk add [game]}}

Where <code>[game]</code> is the name of the package containing the game, like <code>micro-tetris</code> from among the [[#List of games|available games]].

== Steam ==
{{Main|Steam}}
Steam, a popular game distribution platform by Valve can be run on Alpine Linux through [[Flatpak]].

== Wine ==

{{Pkg|wine}} allows you to run some Windows software, including games, under Linux. A 32-bit Alpine chroot/multiboot might be required to use 32 bit Windows games under Wine. If you use x86_64, 32-bit applications will run in Wine's experimental WoW64 mode, which may not be compatible with all software.

To run windows app/games inside a [https://www.reddit.com/r/linux4noobs/comments/1fegh0i/winealpine/ docker container] with alpine Linux, {{pkg|libcap}} is required to fix issues related to [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ#failed-to-use-icmp-network-ping-this-requires-special-permissions raw sockets]

<Pre>
RUN apk add --no-cache libcap
RUN setcap cap_net_raw+epi /usr/bin/wine-preloader
</Pre>

== Permissions ==

To make sure your account is in the "games" group, run the following:

{{Cmd|# adduser youruser games}}

Log-off and then log back on in order for the changes to take effect. Most games don't require this in order to work.

== List of games ==

Below is the list of games packages available in Alpine Linux:
{|class="wikitable" 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="20%" |Game
|width="20%" | Package name
|| Description
|-
| [https://www.advancemame.it/ AdvanceMAME] || {{Pkg|advancemame}} || Arcade simulator.
|-
| [https://gitlab.gnome.org/GNOME/aisleriot Aisleriot] || {{Pkg|aisleriot}} || Solitaire card games.
|-
|[https://www.chocolate-doom.org/wiki/index.php/Chocolate_Doom Chocolate Doom] || {{Pkg|chocolate-doom}} || Portable release of Doom, Heretic, Hexen, and Strife
|-
| [https://www.dosbox-staging.org/ DOSBox Staging] || {{Pkg|dosbox-staging}} || DOS-emulator that uses SDL.
|-
| [https://www.flightgear.org/ FlightGear]|| {{Pkg|flightgear}} || Flight simulator.
|-
| [https://www.freeciv.org Freeciv]|| {{Pkg|freeciv}} || Free and Open Source empire-building strategy game.
|-
|[https://freedoom.github.io/ Freedoom]|| {{Pkg|freedoom}} || an entirely free software game running on a Doom engine.
|-
| [https://davidgriffith.gitlab.io/frotz/ Frotz] || {{Pkg|frotz}} || Z machine (Infocom interactive fiction) Interpreter.
|-
| [https://gcompris.net/index-en.html GCompris] || {{Pkg|gcompris-qt}} || Educational software suite comprising of numerous activities for children aged 2 to 10.
|-
| [https://www.gnu.org/software/chess/ GNU Chess]|| {{Pkg|gnuchess}} || Play chess against the computer.
|-
|[https://zdoom.org/index GZDoom] || {{Pkg|gzdoom}} || Modern game engine resembling modern FPSes compatible with Doom WADs
|-
| [https://lgames.sourceforge.io/LBreakout2/ LBreakout2]|| {{Pkg|lbreakout2}} || Ball-and-paddle game.
|-
| [https://lgames.sourceforge.io/LBreakoutHD LBreakoutHD] || {{Pkg|lbreakouthd}} || {{Note|No level editor available.}}
The successor to LBreakout2.
{{Pkg|lbreakout2}} is needed for level creation.
|-
| [https://lgames.sourceforge.io/LPairs LPairs]|| {{Pkg|lpairs2}} || Classical memory game.
|-
| [https://www.luanti.org/ Luanti] || {{Pkg|luanti}} || An open source voxel game engine.
|-
| [https://github.com/troglobit/tetris Micro Tetris] || {{Pkg|micro-tetris}} || A version of Tetris that uses ANSI escape sequences and can fit in embedded devices.
|-
| [https://www.nethack.org NetHack] || {{Pkg|nethack}} || A single player Rogue-like dungeon crawler or dungeon exploration game
|-
| [https://openrct2.io/ OpenRCT2] || {{Pkg|openrct2}} || {{Note| Requires original files of “RollerCoaster Tycoon 2” to play.}}
A free and open-source reimplementation of “RollerCoaster Tycoon 2”.
|-
| [https://www.openttd.org/ OpenTTD]|| {{Pkg|openttd}} || A business simulation game.
|-
| [https://www.retroarch.com/ RetroArch] || {{Pkg|retroarch}} || Frontend for emulators, game engines, and media players using libretro.
|-
| [https://www.scummvm.org/ ScummVM]|| {{Pkg|scummvm}} || Engine for several graphical adventure games.
|-
| [https://www.supertux.org/ SuperTux] || {{Pkg|supertux}} || Classic 2D jump'n'run side-scroller game in a style similar to the original Super Mario games.
|-
|[https://supertuxkart.net/Main_Page SuperTuxKart] || {{pkg|supertuxkart}} || Kart racing game with OSS mascots.
|-
|[https://www.xonotic.org/ Xonotic] || {{Pkg|xonotic}} || A free and open-source FPS.
|}

== See also ==
* [[Steam|Steam on Alpine Linux]]
* [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ Wine FAQ]
* [https://obsproject.com/ OBS Studio] ({{Pkg|obs-studio}}) - Used by live streamers on streaming platforms such as YouTube and Twitch.
* [https://wine.htmlvalidator.com/install-wine-on-alpine-linux-3.html How to Install Wine on Alpine Linux 3]
[[category:Gaming]]

Gaming on Alpine

2025-03-18T06:37:39Z

Encode: Alphabetize list

This page documents the various game related packages available in Alpine Linux and lists alternate ways to game. If you are interested in developing games on Alpine Linux visit [[Game development on Alpine Linux]].

== Installing Games ==

Like with installing any other package, run the following:

{{Cmd|# apk add [game]}}

Where <code>[game]</code> is the name of the package containing the game, like <code>micro-tetris</code> from among the [[#List of games|available games]].

== Steam ==
{{Main|Steam}}
Steam, a popular game distribution platform by Valve can be run on Alpine Linux through [[Flatpak]].

== Wine ==

{{Pkg|wine}} allows you to run some Windows software, including games, under Linux. A 32-bit Alpine chroot/multiboot might be required to use 32 bit Windows games under Wine. If you use x86_64, 32-bit applications will run in Wine's experimental WoW64 mode, which may not be compatible with all software.

To run windows app/games inside a [https://www.reddit.com/r/linux4noobs/comments/1fegh0i/winealpine/ docker container] with alpine Linux, {{pkg|libcap}} is required to fix issues related to [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ#failed-to-use-icmp-network-ping-this-requires-special-permissions raw sockets]

<Pre>
RUN apk add --no-cache libcap
RUN setcap cap_net_raw+epi /usr/bin/wine-preloader
</Pre>

== Permissions ==

To make sure your account is in the "games" group, run the following:

{{Cmd|# adduser youruser games}}

Log-off and then log back on in order for the changes to take effect. Most games don't require this in order to work.

== List of games ==

Below is the list of games packages available in Alpine Linux:
{|class="wikitable" 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="20%" |Game
|width="20%" | Package name
|| Description
|-
| [https://www.advancemame.it/ AdvanceMAME]|| {{Pkg|advancemame}} || Arcade simulator.
|-
| [https://wiki.gnome.org/Apps/Aisleriot Aisleriot]|| {{Pkg|aisleriot}} || Solitaire card games.
|-
|[https://www.chocolate-doom.org/ Chocolate Doom] || {{Pkg|chocolate-doom}}|| Portable release of Doom, Heretic, Hexen, and Strife
|-
| [https://www.dosbox-staging.org/ DOSBox Staging] ||{{Pkg|dosbox-staging}} || DOS-emulator that uses SDL.
|-
| [https://home.flightgear.org FlightGear]|| {{Pkg|flightgear}} || Flight simulator.
|-
| [https://freeciv.fandom.com Freeciv]|| {{Pkg|freeciv}} || Free and Open Source empire-building strategy game.
|-
|[https://freedoom.github.io/ Freedoom]|| {{Pkg|freedoom}}|| an entirely free software game running on a Doom engine.
|-
| [https://frotz.sourceforge.net/ Frotz] || {{Pkg|frotz}} || Z machine (Infocom interactive fiction) Interpreter.
|-
| [https://gcompris.net GCompris] || {{Pkg|gcompris-qt}}|| Educational software suite comprising of numerous activities for children aged 2 to 10.
|-
| [https://en.wikipedia.org/wiki/GNU_Chess GNU Chess]|| {{Pkg|gnuchess}}|| Play chess against the computer.
|-
|[https://zdoom.org GZDoom] || {{Pkg|gzdoom}} || Modern game engine resembling modern FPSes compatible with Doom WADs
|-
| [https://lgames.sourceforge.io/LBreakout2 LBreakout2]|| {{Pkg|lbreakout2}}|| Ball-and-paddle game.
|-
| [https://lgames.sourceforge.io/LBreakoutHD LBreakoutHD] || {{Pkg|lbreakouthd}}|| The successor to LBreakout2. Note: no level editor available.
lbreakout2 is needed for level creation.
|-
| [https://lgames.sourceforge.io/LPairs LPairs]||{{Pkg|lpairs2}}|| Classical memory game.
|-
| [https://www.luanti.org/ Luanti] || {{Pkg|luanti}} || An open source voxel game engine.
|-
| [https://github.com/troglobit/tetris Micro Tetris] ||{{Pkg|micro-tetris}}|| A version of Tetris that uses ANSI escape sequences and can fit in embedded devices.
|-
| [https://www.nethack.org NetHack] ||{{Pkg|netHack}} || A single player Rogue-like dungeon crawler or dungeon exploration game
|-
| [https://openrct2.org/ OpenRCT2] || {{Pkg|openrct2 }}|| A free and open-source reimplementation of RollerCoaster Tycoon 2 but '''requires''' original RollerCoaster Tycoon 2 assets.
|-
| [https://en.wikipedia.org/wiki/OpenTTD OpenTTD]||{{Pkg|openttd}}|| A business simulation game.
|-
| [https://www.retroarch.com RetroArch] ||{{Pkg|retroarch}}|| Frontend for emulators, game engines, and media players using libretro.
|-
| [https://www.scummvm.org/ ScummVM]||{{Pkg|scummvm}}|| Engine for several graphical adventure games.
|-
| [https://www.supertux.org/ SuperTux] ||{{Pkg|supertux}}|| Classic 2D jump'n'run side-scroller game in a style similar to the original Super Mario games.
|-
|[https://supertuxkart.net/Main_Page SuperTuxKart] || {{pkg|supertuxkart}}|| Kart racing game with OSS mascots.
|-
|[https://www.xonotic.org/ Xonotic] ||{{Pkg|xonotic}}|| A free and open-source FPS.
|}

== See also ==
* [[Steam|Steam on Alpine Linux]]
* [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ Wine FAQ]
* [https://obsproject.com/ OBS Studio] ({{Pkg|obs-studio}}) - Used by live streamers on streaming platforms such as YouTube and Twitch.
* [https://wine.htmlvalidator.com/install-wine-on-alpine-linux-3.html How to Install Wine on Alpine Linux 3]
[[category:Gaming]]

Gaming on Alpine

2025-03-18T06:27:12Z

Encode: Minetest → Luanti, https://blog.luanti.org/2024/10/13/Introducing-Our-New-Name/

This page documents the various game related packages available in Alpine Linux and lists alternate ways to game. If you are interested in developing games on Alpine Linux visit [[Game development on Alpine Linux]].

== Installing Games ==

Like with installing any other package, run the following:

{{Cmd|# apk add [game]}}

Where <code>[game]</code> is the name of the package containing the game, like <code>micro-tetris</code> from among the [[#List of games|available games]].

== Steam ==
{{Main|Steam}}
Steam, a popular game distribution platform by Valve can be run on Alpine Linux through [[Flatpak]].

== Wine ==

{{Pkg|wine}} allows you to run some Windows software, including games, under Linux. A 32-bit Alpine chroot/multiboot might be required to use 32 bit Windows games under Wine. If you use x86_64, 32-bit applications will run in Wine's experimental WoW64 mode, which may not be compatible with all software.

To run windows app/games inside a [https://www.reddit.com/r/linux4noobs/comments/1fegh0i/winealpine/ docker container] with alpine Linux, {{pkg|libcap}} is required to fix issues related to [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ#failed-to-use-icmp-network-ping-this-requires-special-permissions raw sockets]

<Pre>
RUN apk add --no-cache libcap
RUN setcap cap_net_raw+epi /usr/bin/wine-preloader
</Pre>

== Permissions ==

To make sure your account is in the "games" group, run the following:

{{Cmd|# adduser youruser games}}

Log-off and then log back on in order for the changes to take effect. Most games don't require this in order to work.

== List of games ==

Below is the list of games packages available in Alpine Linux:
{|class="wikitable" 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="20%" |Game
|width="20%" | Package name
|| Description
|-
| [https://www.advancemame.it/ AdvanceMAME]|| {{Pkg|advancemame}} || Arcade simulator.
|-
| [https://wiki.gnome.org/Apps/Aisleriot Aisleriot]|| {{Pkg|aisleriot}} || Solitaire card games.
|-
| [https://www.dosbox-staging.org/ DOSBox Staging] ||{{Pkg|dosbox-staging}} || DOS-emulator that uses SDL.
|-
| [https://freeciv.fandom.com Freeciv]|| {{Pkg|freeciv}} || Free and Open Source empire-building strategy game.
|-
| [https://frotz.sourceforge.net/ Frotz] || {{Pkg|frotz}} || Z machine (Infocom interactive fiction) Interpreter.
|-
| [https://home.flightgear.org FlightGear]|| {{Pkg|flightgear}} || Flight simulator.
|-
|[https://freedoom.github.io/ Freedoom]|| {{Pkg|freedoom}}|| an entirely free software game running on a Doom engine.
|-
|[https://www.chocolate-doom.org/ Chocolate Doom] || {{Pkg|chocolate-doom}}|| Portable release of Doom, Heretic, Hexen, and Strife
|-
|[https://zdoom.org GZDoom] || {{Pkg|gzdoom}} || Modern game engine resembling modern FPSes compatible with Doom WADs
|-
| [https://gcompris.net GCompris] || {{Pkg|gcompris-qt}}|| Educational software suite comprising of numerous activities for children aged 2 to 10.
|-
| [https://en.wikipedia.org/wiki/GNU_Chess GNU Chess]|| {{Pkg|gnuchess}}|| Play chess against the computer.
|-
| [https://lgames.sourceforge.io/LBreakout2 LBreakout2]|| {{Pkg|lbreakout2}}|| Ball-and-paddle game.
|-
| [https://lgames.sourceforge.io/LBreakoutHD LBreakoutHD] || {{Pkg|lbreakouthd}}|| The successor to LBreakout2. Note: no level editor available.
lbreakout2 is needed for level creation.
|-
| [https://lgames.sourceforge.io/LPairs LPairs]||{{Pkg|lpairs2}}|| Classical memory game.
|-
| [https://github.com/troglobit/tetris Micro Tetris] ||{{Pkg|micro-tetris}}|| A version of Tetris that uses ANSI escape sequences and can fit in embedded devices.
|-
| [https://www.luanti.org/ Luanti] ||{{Pkg|luanti}}|| An open source voxel game engine.
|-
| [https://www.nethack.org NetHack] ||{{Pkg|netHack}} || A single player Rogue-like dungeon crawler or dungeon exploration game
|-
| [https://openrct2.org/ OpenRCT2] || {{Pkg|openrct2 }}|| A free and open-source reimplementation of RollerCoaster Tycoon 2 but '''requires''' original RollerCoaster Tycoon 2 assets.
|-
| [https://en.wikipedia.org/wiki/OpenTTD OpenTTD]||{{Pkg|openttd}}|| A business simulation game.
|-
| [https://www.retroarch.com RetroArch] ||{{Pkg|retroarch}}|| Frontend for emulators, game engines, and media players using libretro.
|-
| [https://www.scummvm.org/ ScummVM]||{{Pkg|scummvm}}|| Engine for several graphical adventure games.
|-
| [https://www.supertux.org/ SuperTux] ||{{Pkg|supertux}}|| Classic 2D jump'n'run side-scroller game in a style similar to the original Super Mario games.
|-
|[https://supertuxkart.net/Main_Page SuperTuxKart] || {{pkg|supertuxkart}}|| Kart racing game with OSS mascots.
|-
|[https://www.xonotic.org/ Xonotic] ||{{Pkg|xonotic}}|| A free and open-source FPS.
|}

== See also ==
* [[Steam|Steam on Alpine Linux]]
* [https://gitlab.winehq.org/wine/wine/-/wikis/FAQ Wine FAQ]
* [https://obsproject.com/ OBS Studio] ({{Pkg|obs-studio}}) - Used by live streamers on streaming platforms such as YouTube and Twitch.
* [https://wine.htmlvalidator.com/install-wine-on-alpine-linux-3.html How to Install Wine on Alpine Linux 3]
[[category:Gaming]]

Bubblewrap/Examples

2024-06-05T03:06:03Z

Encode: Use default values, instead of assign default values. Doesn't matter in this situation, but will lead to surprising results in most situations.

{{Draft|Someone more experienced needs to look over this.}}

{{Todo|
* Since bubblewrap can make use of [https://en.wikipedia.org/wiki/Seccomp seccomp], restrictive versions should be added.
* {{Ic|imv}}, {{Ic|mpv}} and {{Ic|zathura}} currently only accept 1 mandatory (except {{Ic|imv}}) argument. This should (hopefully) be temporary, until I figure out how to pass multiple arguments (without including everything else).}}

{{Warning|These were found by going backward; start with a complicated program and as restricted as possible sandbox, allowing more till the program appears to work. Because of this, complicated and sensitive programs (for example: {{Pkg|firefox|arch=}} and {{Pkg|keepassxc|arch=}}) may be missing some things they need, which might lead to '''LESS SECURITY''', '''LESS PRIVACY''' and '''DATA LOSS'''.}}

{{Note|
* This page assumes you have already read [[Bubblewrap]].
* To try and avoid duplicates everything will be explained for [[Firefox]] and only when it differs (non obviously) for everything else.
* Where applicable, this assumes: [[Wayland]] only + [[PipeWire]].
: If Wayland is needed, make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

{{TOC right}}

== Firefox ==

{{Cat|~/.local/bin/bwrap-firefox|#!/bin/sh

# Firefox wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
--ro-bind /usr/share/icons/ /usr/share/icons/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
/usr/lib/firefox/firefox}}

set -u
If the shell tries to expand an unset parameter, it will error (with a
few exceptions).

XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
Take value if already set, else fallback to the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG] default.

NEW_HOME='/home/user'
User to appear as.

NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
{{Path|"$XDG_CACHE_HOME"}} for the new user.

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"
Make sure the new (real) home for Firefox data exist.

--unshare-all \
Unshare all possible [https://en.wikipedia.org/wiki/Linux_namespaces namespaces].

--share-net \
Retain the network namespace.

--new-session \
New terminal session for the sandbox.

--die-with-parent \
Child process dies when {{Ic|bwrap}} parent dies.

--clearenv \
Unset all environment variables (except for {{Path|"$PWD"}}).

--setenv HOME "$NEW_HOME" \
Pass the path to {{Path|"$NEW_HOME"}} for {{Path|"$HOME"}}.

--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
Specify the Wayland display to run clients on.

--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
User-specific non-essential (cached) data.

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
User-specific non-essential runtime files and other file objects.

--hostname localhost \
Use custom hostname in the sandbox.

--dev /dev/ \
New devtmpfs, access to special or device files.

--ro-bind /etc/fonts/ /etc/fonts/ \
System font configuration directory.

--ro-bind /etc/resolv.conf /etc/resolv.conf \
Needed for DNS resolution.

--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
Per-user Mozilla cache.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:-$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${NEW_XDG_CONFIG_HOME}/fontconfig/" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) Per-user font configuration directory.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:-$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/user-dirs.dirs" "${NEW_XDG_CONFIG_HOME}/user-dirs.dirs" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) If you modify "well known" user directories, like
{{Path|~/Downloads/}}, you need this to have Firefox pick it up.

{{Note|If you use {{Path|"${XDG_CONFIG_HOME}/user-dirs.dirs"}} you should also add the corresponding path(s).
For example if you set {{Path|XDG_DOWNLOAD_DIR}} to
{{Path|"${HOME}/downloads/"}} you would also add:
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--bind-try "${HOME}/downloads/" "${NEW_HOME}/downloads/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
}}

--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
{{Path|"${XDG_DATA_HOME}/firefox/"}} is the location of Firefox data. Shown to Firefox as {{Path|"${NEW_HOME}/.mozilla/"}}.

{{Note|This has the added benefit of getting {{Path|~/.mozilla/}} out of your {{Path|"$HOME"}}, and conforming more to XDG. This may one day not be necessary: [https://bugzilla.mozilla.org/show_bug.cgi?id{{=}}259356 Support for the Freedesktop.org XDG Base Directory Specification (2004-09-14)].}}

...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${NEW_XDG_DATA_HOME}/fonts/" \'''
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
...
(Optional) Per-user directory scanned for font files.

--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Default {{Path|~/Downloads/}} directory.

--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
Shared libraries.

--proc /proc/ \
New procfs, provides information about running processes and the kernel.

--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
Bind the Wayland socket file.

--ro-bind /usr/lib/ /usr/lib/ \
Object files and libraries.

{{Note|It is not worth the time to limit this, the churn is too great.}}

--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
XKB is a keyboard keymap support library.

{{Note|Even tho the path has {{Path|*/X11/*}} Wayland uses it too.}}

--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
Font presets.

--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
Global directory scanned for font files.

--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
Needed for "Save Page As…", "Export|Import Bookmarks File", among others.

--ro-bind /usr/share/icons/ /usr/share/icons/ \
Global icons directory.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
International Components for Unicode (ICU) provides support for Unicode
and globalization.

...
--ro-bind /usr/share/icu/ /usr/share/icu/ \
'''--ro-bind /usr/share/libdrm/ /usr/share/libdrm/ \'''
--ro-bind /usr/share/mime/ /usr/share/mime/ \
...
(Optional) Direct Rendering Manager (DRM), Linux kernel subsystem for
interfacing with GPUs of video cards. Programs can use this to have the
GPU do hardware-accelerated 3D rendering and video decoding.

--ro-bind /usr/share/mime/ /usr/share/mime/ \
Global XDG MIME directory.

/usr/lib/firefox/firefox
Call Firefox.

{{Tip|If you use multiple profiles you can have:
/usr/lib/firefox/firefox -P "$@"
this will allow you to pass a profile name and go into that specific one or not pass anything and get prompted for which to choose.}}

=== PipeWire audio ===

{{Todo|}}

=== Pulse audio ===

...
--proc /proc/ \
'''--ro-bind "${XDG_RUNTIME_DIR}/pulse/" "${XDG_RUNTIME_DIR}/pulse/" \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
(Optional) Pulse audio.

=== Optional(?) stuff ===

{{Draft|Are these needed?}}

...
--proc /proc/ \
'''--ro-bind /sys/bus/pci/ /sys/bus/pci/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Information about PCI bus type.

Without this you get
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: cannot access /sys/bus/pci (t=0.177033) [GFX1-]: glxtest: cannot access /sys/bus/pci
but it still seems to work.

...
--proc /proc/ \
'''--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Contains a filesystem representation of the kernel device tree.

With {{Ic|--ro-bind /sys/bus/pci/ /sys/bus/pci/ \}} but without this you get:
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) [GFX1-]: glxtest: ManageChildProcess failed

Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) |[1][GFX1-]: No GPUs detected via PCI
(t=0.18958) [GFX1-]: No GPUs detected via PCI
but it still seems to work.

== imv ==

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

...

'''XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"'''
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
'''XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \'''
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
'''--ro-bind /etc/fonts/ /etc/fonts/ \'''
'''--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \'''
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \'''
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
'''--ro-bind /usr/share/fonts/ /usr/share/fonts/ \'''
'''--ro-bind /usr/share/icu/ /usr/share/icu/ \'''
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
...
(Optional) To use commands in {{Ic|imv}}.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument. If you don't pass in
anything it will default to {{Path|./}}, the current directory.

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}

== KeePassXC ==

{{Note|I only use the bare minimum functionality, so functionality you need is probably missing. If you use functionality not here, your contribution will be most appreciated. To kick things off: {{Ic|Unable to initialize libusb. USB devices may not be detected properly.}} can be silenced with {{Ic|--dev-bind /dev/bus/usb/ /dev/bus/usb/ \}}.}}

{{Cat|~/.local/bin/bwrap-keepassxc|#!/bin/sh

# keepassxc wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
PASSWORD_DATABASE{{=}}"${HOME}/password database"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_PASSWORD_DATABASE{{=}}"${NEW_HOME}${PASSWORD_DATABASE#"$HOME"}"

mkdir -pm 0700 "$PASSWORD_DATABASE"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CONFIG_HOME}/keepassxc/" "${NEW_XDG_CONFIG_HOME}/keepassxc/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind /usr/bin/keepassxc /usr/bin/keepassxc \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/ /usr/share/X11/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/keepassxc/ /usr/share/keepassxc/ \
--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
/usr/bin/keepassxc "$@"}}

PASSWORD_DATABASE="${HOME}/password database"
Directory containing your {{Pkg|keepassxc|arch=}} password database.

{{Tip|This is almost certainly not where '''your''' database is located. You will need to change it to where you put your password database.}}

--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
Session type, since we are assuming Wayland only, this will be "wayland".

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
Bind password database.

== mpv ==

{{Cat|~/.local/bin/bwrap-mpv|#!/bin/sh

# mpv wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run mpv wrapped in bwrap.

Usage:
$ bwrap-mpv VIDEO\n'
exit 1
fi

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$1"}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

--player-operation-mode=pseudo-gui \
Because {{Ic|--new-session}} is used, this is needed to have a way to
control {{Ic|mpv}} when it would otherwise not show a GUI.

{{Tip|If you followed [[Bubblewrap#.desktop_integration]], you should remove it from {{Path|"${XDG_DATA_HOME}/applications/bwrap-mpv.desktop"}}.}}

--title='bwrap | ${media-title}' \
Set the window title, showing at a glance that you are using {{Ic|bwrap}}.

=== mpv-net ===

If you want to use {{Ic|mpv}} to stream over the Internet, you will need
a few things more.

{{Tip|You can use both {{Ic|bwrap-mpv}} and {{Ic|bwrap-mpv-net}}. {{Ic|bwrap-mpv}} for local stuff and {{Ic|bwrap-mpv-net}} for watching over the Internet.}}

{{Cat|~/.local/bin/bwrap-mpv-net|#!/bin/sh

# mpv wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv PATH /usr/bin/ \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$@"}}

--setenv PATH /usr/bin/ \
{{Todo|Document why this is needed.}}

--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
Certificate authorities that are ''trusted''.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

"$@"
This is so you can pass more options to {{Ic|bwrap-mpv-net}}, for example:
$ bwrap-mpv-net --video=no --sub=no 'URL1' 'URL2'

=== Pulse audio ===

--ro-bind "${XDG_RUNTIME_DIR}/pulse" "${XDG_RUNTIME_DIR}/pulse" \
Pulse audio.

=== Screenshots ===

The default screenshots directory is {{Path|"$XDG_DESKTOP_DIR"}} (which is
{{Path|"${HOME}/Desktop/"}}, which will fallback to {{Path|"$HOME/"}} if
{{Path|"${HOME}/Desktop/"}} doesn't exist). That means that by default
{{Ic|bwrap-mpv[-net]}} won't allow screenshots unless you change a few things.
Do the following to allow an XDG approved screenshots directory:

...
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
'''XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"'''

...
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

'''mkdir -pm 0700 "${XDG_DATA_HOME}/mpv/"'''

...
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
'''--bind "${XDG_DATA_HOME}/mpv/" "${NEW_XDG_DATA_HOME}/mpv/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
Now make {{Ic|mpv}} use that directory:

{{Cat|"${XDG_CONFIG_HOME}/mpv/mpv.conf"|<nowiki>...
# Something like this, change to match "$XDG_DATA_HOME"
screenshot-template="~/.local/share/mpv/screenshots/%F [%p] %02n"
...</nowiki>}}

== yt-dlp ==

{{Cat|~/.local/bin/bwrap-yt-dlp|#!/bin/sh

# yt-dlp wrapped in bwrap with network access.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

mkdir -pm 0700 "${HOME}/Downloads/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--hostname localhost \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--ro-bind-try "${XDG_CONFIG_HOME}/yt-dlp/config" "${NEW_XDG_CONFIG_HOME}/yt-dlp/config" \
--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/bin/ffmpeg /usr/bin/ffmpeg \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
/usr/bin/yt-dlp "$@"}}

--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Directory for writing the files. This should match {{Ic|--output}} that
is either in {{Path|"${XDG_CONFIG_HOME}/yt-dlp/config"}} or passed on
the command line.

/usr/bin/yt-dlp "$@"
This is so you can pass more options to {{Ic|bwrap-yt-dlp}}, for example:
$ bwrap-yt-dlp --no-playlist 'URL1' 'URL2'

== zathura ==

{{Cat|~/.local/bin/bwrap-zathura|#!/bin/sh

# zathura wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run zathura wrapped in bwrap.

Usage:
$ bwrap-zathura PDF\n'
exit 1
fi

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/zathura/zathurarc" "${XDG_CONFIG_HOME}/zathura/zathurarc" \
--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/zathura /usr/bin/zathura \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/zathura "$1"}}

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"
Have to premake the directory for {{Ic|zathura}} data.

--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
Allow writing of: bookmarks, history, input history.

--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
Used for identifying what type a file should be. Read the
{{Ic|file(1)}} man page for more information.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

[[Category:Security]]

Bubblewrap

2024-06-05T02:45:01Z

Encode: Use default values, instead of assign default values. Doesn't matter in this situation, but will lead to surprising results in most situations.

{{Draft|The reasoning is most likely wrong for why to do some stuff. Someone more experienced needs to look it over.}}
{{TOC right}}

[https://github.com/containers/bubblewrap Bubblewrap] is an
unprivileged sandboxing tool. Kernel features it also has:
User/IPC/PID/Network/UTS/cgroup
[https://en.wikipedia.org/wiki/Linux_namespaces namespaces] and
[https://en.wikipedia.org/wiki/Seccomp Seccomp] filters.

How bubblewrap works, as stated in the
[https://github.com/containers/bubblewrap/blob/main/README.md#usage README.md]:
:bubblewrap works by creating a new, completely empty, mount namespace where the root is on a tmpfs that is invisible from the host, and will be automatically cleaned up when the last process exits. You can then use commandline options to construct the root filesystem and process environment and command to run in the namespace.

== Installation ==

Install {{Pkg|bubblewrap|arch=}}:

{{Cmd|# apk add bubblewrap}}

{{Note|The package is {{pkg|bubblewrap|arch=}} but the command to
manage it is {{Ic|bwrap}}.}}

== How to workout what a program needs ==

{{Tip|Look at [[Bubblewrap/Examples]] to see various ways {{Ic|bwrap}} can be used.}}

=== Prerequisites ===

First make sure to have a user editable directory in {{Path|"$PATH"}}.
This page will use {{Path|"${HOME}/.local/bin/"}}, create it if it does
not exist:

{{Cmd|$ mkdir -p ~/.local/bin}}

Add it to {{Path|~/.profile}}:

{{Cat|~/.profile|...<nowiki>
PATH="${PATH}":"${HOME}/.local/bin"
export PATH
</nowiki>...}}

Will need to relog for this to apply.

=== Basic bwrap setup ===

{{Note|With how we will be sandboxing everything that doesn't match our owner/group will show as {{Ic|nobody}}.}}

Lets assume you want to sandbox {{Pkg|imv|arch=}} and are using [[Wayland]]
only. Here is how you might go about that.

Create {{Ic|bwrap-imv}} inside {{Path|"${HOME}/.local/bin/"}} and make it
executable:

{{Cmd|$ touch ~/.local/bin/bwrap-imv
$ chmod 0700 ~/.local/bin/bwrap-imv}}

Use {{Ic|file}} to determine the file type of {{Path|/usr/bin/imv}}:

{{Cmd|$ file /usr/bin/imv
/usr/bin/imv: POSIX shell script, ASCII text executable}}

Since it is just a shell script, we can use {{Ic|less}} to view it:

{{Cmd|$ less /usr/bin/imv}}

{{Cat|/usr/bin/imv|#!/bin/sh
if [ -n "${WAYLAND_DISPLAY}" ]; then
exec /usr/libexec/imv-wayland "$@"
else
exec /usr/libexec/imv-x11 "$@"
fi}}

Since we are assuming Wayland only we can just skip to
{{Path|/usr/libexec/imv-wayland}}. Run {{Ic|file}} on it:

{{Cmd|$ file /usr/libexec/imv-wayland
/usr/libexec/imv-wayland: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-musl-x86_64.so.1, stripped}}

It is an
[https://en.wikipedia.org/wiki/Executable_and_Linkable_Format Executable and Linkable Format (ELF)]
file. So we know we need the ELF interpreter
{{Path|/lib/ld-musl-x86_64.so.1}}. We also know we need
{{Path|/usr/libexec/imv-wayland}}, since it has to know where the command
is located.

As the argument to {{Ic|/usr/libexec/imv-wayland}}, put
{{Ic|"${1:-./}"}}, this will pass '''only''' the first argument and if
there is none, will default to {{Path|./}}, the current directory. We
will also need {{Ic|--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \}},
since we are not passing the whole filesystem. This will get the
absolute pathname using {{Ic|realpath}}, so you can pass a relative
argument and still bind the argument:
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}
{{Todo|How can you pass 2+ arguments?}}

Find necessary shared libraries, except ones loaded at runtime:

{{Cmd|$ ldd /usr/libexec/imv-wayland}}

It outputs a lot of things but we only need a few; the directory path of
the majority {{Path|/usr/lib/*}} and the 4 paths that start with
{{Path|/lib/*}}. Filter the output to see those clearer:

{{Cmd|$ ldd /usr/libexec/imv-wayland {{!}} grep ' /lib/'}}

In total:
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/lib/ /usr/lib/ \

{{Note|It is not worth the time to limit {{Path|/usr/lib/*}}, the churn is too great.}}

{{Warning|The {{Ic|ldd}} manpage talks about some security implications. It may not apply since they seem to be talking about glibc and {{Pkg|musl-utils|arch=}} makes {{Path|/lib/ld-musl-x86_64.so.1}} ldd [https://git.alpinelinux.org/aports/tree/main/musl/APKBUILD#n105]. Is this something to worry about?}}

Since this is a shell script, lets use a helpful command:
set -u
if the shell tries to expand an unset parameter, it will error (with a
few exceptions).

Since this is for a GUI [[Wayland]] program, so lets also add some prerequisites:

{{Note|Make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
for determining the directory for the wayland socket;
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
for determining the socket;
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
mount readonly.

Lets also add some nice to haves:
--unshare-all \
will create a new user/ipc/pid/net/utc namespaces and try to create a
new cgroup namespace if possible;
--new-session
will create a new terminal session for the sandbox, disconnecting from
the controlling terminal so for example it can't inject input into the
terminal;
--die-with-parent
will ensure child process ({{Ic|imv-wayland}} in this case) dies when
{{Ic|bwrap}} parent dies.

We might also have a {{Path|config}} file:
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
this will add your local config to {{Ic|imv}} if you have one and if not
will still continue.

Pass {{Path|"$XDG_CONFIG_HOME"}} to sandbox:
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
but this isn't always defined, so lets fallback to the
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory]
default:
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
this will use {{Path|"$XDG_CONFIG_HOME"}} if it's set, otherwise
fallback to the default of {{Path|"$HOME/.config"}}.

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

{{Path|~/.local/bin/bwrap-imv}} now looks like:

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

Now lets run {{Ic|bwrap-imv}}, go into a directory with an image:

{{Cmd|$ bwrap-imv IMAGE
sh: eval: line 0: can't create /dev/null: nonexistent directory
...
sh: eval: line 0: can't create /dev/null: nonexistent directory
xkbcommon: ERROR: failed to add default include path /usr/share/X11/xkb
Assertion failed: keyboard->context (../src/keyboard.c: imv_keyboard_create: 20)}}

Add:
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
to {{Ic|bwrap-imv}}. [https://en.wikipedia.org/wiki/X_keyboard_extension XKB]
is a keyboard keymap support library.

After adding the above, run it again:

{{Cmd|$ bwrap-imv IMAGE
sh: eval: line 0: can't create /dev/null: nonexistent directory
...
sh: eval: line 0: can't create /dev/null: nonexistent directory
libEGL warning: wayland-egl: could not open /dev/dri/renderD128 (No such file or directory)}}

Add:
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
and run again:

{{Cmd|$ bwrap-imv IMAGE
libEGL warning: wayland-egl: drmGetMagic failed}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

--clearenv \
Finally we can unset all environment variables, except for
{{Path|"$PWD"}} and any we set with {{Ic|--setenv}}.

Now {{Ic|imv}} should show images and your {{Path|config}} file should
work (if you have one). If you do not use commands, the finished
{{Path|~/.local/bin/bwrap-imv}} should look like:

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

If you do use commands however, you will notice it is only showing
[https://en.wikipedia.org/wiki/Substitute_character substitute characters].

{{Tip|Commands in {{Ic|imv}} are entered by pressing {{Ic|:}}.}}

If you try to use a command it will say:

Fontconfig error: Cannot load default config file: No such file: (null)

Look at the {{Ic|fonts-conf}} manpage (which is from
{{Pkg|fontconfig-doc|arch=}}) we see that {{Path|/etc/fonts/}} is the system
font configuration directory and
{{Path|"${XDG_CONFIG_HOME}/fontconfig/"}} is the per-user configuration
directory. {{Path|"${XDG_CONFIG_HOME}/fontconfig/"}} is added with
{{Ic|--ro-bind-try}} so it doesn't have to exist:
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \

The default directories scanned for font files are
{{Path|/usr/share/fonts/}} and {{Path|"${XDG_DATA_HOME}/fonts/"}}.
{{Path|"${XDG_DATA_HOME}/fonts/"}} added with {{Ic|--ro-bind-try}}:
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \

Pass {{Path|"$XDG_DATA_HOME"}} to sandbox:
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
just like for {{Path|"$XDG_CONFIG_HOME"}}, this isn't always defined, so
fallback to
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory]
default:
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
use {{Path|"$XDG_DATA_HOME"}} if set, else use {{Path|"$HOME/.local/share"}}.

The user cache of font information is also needed, by default
{{Path|"${XDG_CACHE_HOME}/fontconfig/"}}:
--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \

Pass {{Path|"$XDG_CACHE_HOME"}} to sandbox:
--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \
just like for {{Path|"$XDG_CONFIG_HOME"}}, this isn't always defined, so
fallback to
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory]
default:
XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
use {{Path|"$XDG_CACHE_HOME"}} if set, else use {{Path|"$HOME/.cache"}}.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
Is also needed or when you do {{Ic|:<backspace>}} it will terminate the
process. ICU provides Unicode and Globalization support.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

The updated {{Path|~/.local/bin/bwrap-imv}} should look like this:

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

==== See what exists in the sandbox ====

Finally test what all is allowed by replacing
{{Ic|/usr/libexec/imv-wayland "${1:-./}"}} with {{Ic|/bin/sh}} and
adding {{Ic|--ro-bind /bin/ /bin/ \}}. Check around and see what the
filesystem is like:

{{Cat|~/.local/bin/bwrap-imv| ...
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
--ro-bind /bin/ /bin/ \
/bin/sh}}

Invoke {{Ic|bwrap-imv}}:

{{Cmd|$ bwrap-imv IMAGE}}

Show what environment variables are active:

{{Cmd|$ printenv}}

See what directories are at root:

{{Cmd|$ ls -la /
... bin
... dev
... etc
... home
... lib
... sys
... tmp
... usr}}

{{Ic|exit}} when done:

{{Cmd|$ exit}}

Do not forget to change it back:

{{Cat|~/.local/bin/bwrap-imv| ...
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

All done with a basic {{Ic|bwrap}} wrapper.

=== Seccomp ===

{{Expand|}}

== .desktop integration ==

{{Obsolete|This should probably be documented in [[Default_applications]] and linked here. Nothing is unique in using with {{Ic|bwrap}}.}}

{{Note|This section is also using {{Pkg|imv|arch=}} as the example.}}

[https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html XDG Desktop Entry Specification]
are a set of standards describing how a particular program is to be
launched, how it appears in menus, etc.

The default ''.desktop'' file for {{Ic|imv}} is at
{{Path|/usr/share/applications/imv.desktop}}. Move it to
{{Path|"${XDG_DATA_HOME}/applications/bwrap-imv.desktop"}}.

Only 3 options will need to be changed: Name/Name[en_US], what shows up
in the application menu in a graphical file manager (if you have one
installed); Exec, program to execute:

{{Cat|"${XDG_DATA_HOME}/applications/bwrap-imv.desktop"|...<nowiki>
Name=bwrap-imv
Name[en_US]=bwrap-imv
Exec=bwrap-imv %F
</nowiki>...}}

The program {{Ic|xdg-open}} (from the {{Pkg|xdg-utils|arch=}} package) can be
used to open files based on the [https://en.wikipedia.org/wiki/MIME MIME]
type + corresponding entry in
{{Path|"${XDG_CONFIG_HOME}/mimeapps.list"}} and
{{Path|"${XDG_DATA_HOME}/applications/mimeinfo.cache"}}.

Install {{Pkg|desktop-file-utils|arch=}} if it is not installed already, it
comes with two commands that are needed {{Ic|desktop-file-validate}} and
{{Ic|update-desktop-database}}:

{{Cmd|# apk add desktop-file-utils}}

=== Validate ===

It is a good idea to validate {{Ic|imv.desktop}} using
{{Ic|desktop-file-validate}}:

{{Cmd|$ desktop-file-validate "${XDG_DATA_HOME}/applications/bwrap-imv.desktop"}}

=== Update database ===

This will make entries in {{Path|"${XDG_DATA_HOME}/applications/"}} take
precedence over system-wide files ({{Path|/usr/share/applications/}}).
However {{Path|"${XDG_CONFIG_HOME}/mimeapps.list"}} has precedence over
both.

Updating the database, will create
{{Path|"${XDG_DATA_HOME}/applications/mimeinfo.cache"}}:

{{Cmd|$ update-desktop-database "${XDG_DATA_HOME}/applications"}}

== Troubleshooting ==

=== Can't find what path is missing ===

If all else fails start broad and work toward narrowing. See if
{{Ic|bwrap}} works with the program at all:

{{Cmd|$ bwrap \
--dev-bind / / PROGRAM}}

If that works start to narrow:

{{Cmd|$ bwrap \
--ro-bind /bin/ /bin/ \
--dev-bind /dev/ /dev/ \
--ro-bind /lib/ /lib/ \
--ro-bind /sys/ /sys/ \
--ro-bind /usr/ /usr/ \
PROGRAM}}

Keep going till you have narrowed as much as possible.

== See also ==

* [[Bubblewrap/Examples]]
* [https://wiki.archlinux.org/title/Bubblewrap ArchWiki: Bubblewrap]
** [https://wiki.archlinux.org/title/Bubblewrap/Examples ArchWiki: Bubblewrap/Examples]
* [https://wiki.archlinux.org/title/Desktop_entries ArchWiki: Desktop entries (*.desktop files)]

[[Category:Desktop]]
[[Category:Security]]

Template talk:Pkg

2024-05-27T00:54:42Z

Encode: 'arch=' default to all architectures

This template should have options to specify the architecture and maybe also the repository. Currently packages which are not available in the x86_64 architecture (eg. `linux-asahi`) can't be linked with this template. [[User:Sertonix|Sertonix]] ([[User talk:Sertonix|talk]]) 22:52, 8 November 2023 (UTC)

<s>:Hey Sertonix, I've been working on this lately, check out the potential new template @ [[Template:Sandbox]], and I'd love for you to add some test cases to @ [[Sandbox]] too just in case I've missed something!
:Thanks –[[User:zcrayfish|zcrayfish]] ([[User talk:zcrayfish|talk]]•[[Special:Contributions/zcrayfish|contribs]]•[[Special:EmailUser/zcrayfish|send email]]) 20:32, 2 January 2024 (UTC)</s>

:{{done}}
:The pkg template has been updated!
:–[[User:zcrayfish|zcrayfish]] ([[User talk:zcrayfish|talk]]•[[Special:Contributions/zcrayfish|contribs]]•[[Special:EmailUser/zcrayfish|send email]]) 21:40, 9 January 2024 (UTC)

::Thanks! [[User:Sertonix|Sertonix]] ([[User talk:Sertonix|talk]]) 14:45, 10 January 2024 (UTC)

= '''arch=''' default to all architectures =

Most of the time what you say will apply regardless of the architecture,
so this will cut down on the amount of text you need for the common
case. 
(The same argument may apply for '''branch=''' too but I have no opinion.)
--[[User:Encode|Encode]] ([[User talk:Encode|talk]]) 00:54, 27 May 2024 (UTC)

Bubblewrap

2024-05-24T07:28:32Z

Encode: Pkg: Search every arch

{{Draft|The reasoning is most likely wrong for why to do some stuff. Someone more experienced needs to look it over.}}
{{TOC right}}

[https://github.com/containers/bubblewrap Bubblewrap] is an
unprivileged sandboxing tool. Kernel features it also has:
User/IPC/PID/Network/UTS/cgroup
[https://en.wikipedia.org/wiki/Linux_namespaces namespaces] and
[https://en.wikipedia.org/wiki/Seccomp Seccomp] filters.

How bubblewrap works, as stated in the
[https://github.com/containers/bubblewrap/blob/main/README.md#usage README.md]:
:bubblewrap works by creating a new, completely empty, mount namespace where the root is on a tmpfs that is invisible from the host, and will be automatically cleaned up when the last process exits. You can then use commandline options to construct the root filesystem and process environment and command to run in the namespace.

== Installation ==

Install {{Pkg|bubblewrap|arch=}}:

{{Cmd|# apk add bubblewrap}}

{{Note|The package is {{pkg|bubblewrap|arch=}} but the command to
manage it is {{Ic|bwrap}}.}}

== How to workout what a program needs ==

{{Tip|Look at [[Bubblewrap/Examples]] to see various ways {{Ic|bwrap}} can be used.}}

=== Prerequisites ===

First make sure to have a user editable directory in {{Path|"$PATH"}}.
This page will use {{Path|"${HOME}/.local/bin/"}}, create it if it does
not exist:

{{Cmd|$ mkdir -p ~/.local/bin}}

Add it to {{Path|~/.profile}}:

{{Cat|~/.profile|...<nowiki>
PATH="${PATH}":"${HOME}/.local/bin"
export PATH
</nowiki>...}}

Will need to relog for this to apply.

=== Basic bwrap setup ===

{{Note|With how we will be sandboxing everything that doesn't match our owner/group will show as {{Ic|nobody}}.}}

Lets assume you want to sandbox {{Pkg|imv|arch=}} and are using [[Wayland]]
only. Here is how you might go about that.

Create {{Ic|bwrap-imv}} inside {{Path|"${HOME}/.local/bin/"}} and make it
executable:

{{Cmd|$ touch ~/.local/bin/bwrap-imv
$ chmod 0700 ~/.local/bin/bwrap-imv}}

Use {{Ic|file}} to determine the file type of {{Path|/usr/bin/imv}}:

{{Cmd|$ file /usr/bin/imv
/usr/bin/imv: POSIX shell script, ASCII text executable}}

Since it is just a shell script, we can use {{Ic|less}} to view it:

{{Cmd|$ less /usr/bin/imv}}

{{Cat|/usr/bin/imv|#!/bin/sh
if [ -n "${WAYLAND_DISPLAY}" ]; then
exec /usr/libexec/imv-wayland "$@"
else
exec /usr/libexec/imv-x11 "$@"
fi}}

Since we are assuming Wayland only we can just skip to
{{Path|/usr/libexec/imv-wayland}}. Run {{Ic|file}} on it:

{{Cmd|$ file /usr/libexec/imv-wayland
/usr/libexec/imv-wayland: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-musl-x86_64.so.1, stripped}}

It is an
[https://en.wikipedia.org/wiki/Executable_and_Linkable_Format Executable and Linkable Format (ELF)]
file. So we know we need the ELF interpreter
{{Path|/lib/ld-musl-x86_64.so.1}}. We also know we need
{{Path|/usr/libexec/imv-wayland}}, since it has to know where the command
is located.

As the argument to {{Ic|/usr/libexec/imv-wayland}}, put
{{Ic|"${1:-./}"}}, this will pass '''only''' the first argument and if
there is none, will default to {{Path|./}}, the current directory. We
will also need {{Ic|--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \}},
since we are not passing the whole filesystem. This will get the
absolute pathname using {{Ic|realpath}}, so you can pass a relative
argument and still bind the argument:
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}
{{Todo|How can you pass 2+ arguments?}}

Find necessary shared libraries, except ones loaded at runtime:

{{Cmd|$ ldd /usr/libexec/imv-wayland}}

It outputs a lot of things but we only need a few; the directory path of
the majority {{Path|/usr/lib/*}} and the 4 paths that start with
{{Path|/lib/*}}. Filter the output to see those clearer:

{{Cmd|$ ldd /usr/libexec/imv-wayland {{!}} grep ' /lib/'}}

In total:
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/lib/ /usr/lib/ \

{{Note|It is not worth the time to limit {{Path|/usr/lib/*}}, the churn is too great.}}

{{Warning|The {{Ic|ldd}} manpage talks about some security implications. It may not apply since they seem to be talking about glibc and {{Pkg|musl-utils|arch=}} makes {{Path|/lib/ld-musl-x86_64.so.1}} ldd [https://git.alpinelinux.org/aports/tree/main/musl/APKBUILD#n105]. Is this something to worry about?}}

Since this is a shell script, lets use a helpful command:
set -u
if the shell tries to expand an unset parameter, it will error (with a
few exceptions).

Since this is for a GUI [[Wayland]] program, so lets also add some prerequisites:

{{Note|Make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
for determining the directory for the wayland socket;
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
for determining the socket;
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
mount readonly.

Lets also add some nice to haves:
--unshare-all \
will create a new user/ipc/pid/net/utc namespaces and try to create a
new cgroup namespace if possible;
--new-session
will create a new terminal session for the sandbox, disconnecting from
the controlling terminal so for example it can't inject input into the
terminal;
--die-with-parent
will ensure child process ({{Ic|imv-wayland}} in this case) dies when
{{Ic|bwrap}} parent dies.

We might also have a {{Path|config}} file:
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
this will add your local config to {{Ic|imv}} if you have one and if not
will still continue.

Pass {{Path|"$XDG_CONFIG_HOME"}} to sandbox:
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
but this isn't always defined, so lets fallback to the
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory]
default:
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
this will use {{Path|"$XDG_CONFIG_HOME"}} if it's set, otherwise
fallback to the default of {{Path|"$HOME/.config"}}.

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

{{Path|~/.local/bin/bwrap-imv}} now looks like:

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

Now lets run {{Ic|bwrap-imv}}; go into a directory with an image:

{{Cmd|$ bwrap-imv IMAGE
sh: eval: line 0: can't create /dev/null: nonexistent directory
...
sh: eval: line 0: can't create /dev/null: nonexistent directory
xkbcommon: ERROR: failed to add default include path /usr/share/X11/xkb
Assertion failed: keyboard->context (../src/keyboard.c: imv_keyboard_create: 20)}}

Add:
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
to {{Ic|bwrap-imv}}. [https://en.wikipedia.org/wiki/X_keyboard_extension XKB]
is a keyboard keymap support library.

After adding the above, run it again:

{{Cmd|$ bwrap-imv IMAGE
sh: eval: line 0: can't create /dev/null: nonexistent directory
...
sh: eval: line 0: can't create /dev/null: nonexistent directory
libEGL warning: wayland-egl: could not open /dev/dri/renderD128 (No such file or directory)}}

Add:
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
and run again:

{{Cmd|$ bwrap-imv IMAGE
libEGL warning: wayland-egl: drmGetMagic failed}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

--clearenv \
Finally we can unset all environment variables, except for
{{Path|"$PWD"}} and any we set with {{Ic|--setenv}}.

Now {{Ic|imv}} should show images and your {{Path|config}} file should
work (if you have one). If you do not use commands, the finished
{{Path|~/.local/bin/bwrap-imv}} should look like:

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

If you do use commands however, you will notice it is only showing
[https://en.wikipedia.org/wiki/Substitute_character substitute characters].

{{Tip|Commands in {{Ic|imv}} are entered by pressing {{Ic|:}}.}}

If you try to use a command it will say:

Fontconfig error: Cannot load default config file: No such file: (null)

Look at the {{Ic|fonts-conf}} manpage (which is from
{{Pkg|fontconfig-doc|arch=}}) we see that {{Path|/etc/fonts/}} is the system
font configuration directory and
{{Path|"${XDG_CONFIG_HOME}/fontconfig/"}} is the per-user configuration
directory. {{Path|"${XDG_CONFIG_HOME}/fontconfig/"}} is added with
{{Ic|--ro-bind-try}} so it doesn't have to exist:
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \

The default directories scanned for font files are
{{Path|/usr/share/fonts/}} and {{Path|"${XDG_DATA_HOME}/fonts/"}}.
{{Path|"${XDG_DATA_HOME}/fonts/"}} added with {{Ic|--ro-bind-try}}:
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \

Pass {{Path|"$XDG_DATA_HOME"}} to sandbox:
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
just like for {{Path|"$XDG_CONFIG_HOME"}}, this isn't always defined, so
fallback to
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory]
default:
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
use {{Path|"$XDG_DATA_HOME"}} if set, else use {{Path|"$HOME/.local/share"}}.

The user cache of font information is also needed, by default
{{Path|"${XDG_CACHE_HOME}/fontconfig/"}}:
--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \

Pass {{Path|"$XDG_CACHE_HOME"}} to sandbox:
--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \
just like for {{Path|"$XDG_CONFIG_HOME"}}, this isn't always defined; so
fallback to
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory]
default:
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
use {{Path|"$XDG_CACHE_HOME"}} if set, else use {{Path|"$HOME/.cache"}}.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
Is also needed or when you do {{Ic|:<backspace>}} it will terminate the
process. ICU provides Unicode and Globalization support.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

The updated {{Path|~/.local/bin/bwrap-imv}} should look like this:

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

==== See what exists in the sandbox ====

Finally test what all is allowed by replacing
{{Ic|/usr/libexec/imv-wayland "${1:-./}"}} with {{Ic|/bin/sh}} and
adding {{Ic|--ro-bind /bin/ /bin/ \}}. Check around and see what the
filesystem is like:

{{Cat|~/.local/bin/bwrap-imv| ...
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
--ro-bind /bin/ /bin/ \
/bin/sh}}

Invoke {{Ic|bwrap-imv}}:

{{Cmd|$ bwrap-imv IMAGE}}

Show what environment variables are active:

{{Cmd|$ printenv}}

See what directories are at root:

{{Cmd|$ ls -la /
... bin
... dev
... etc
... home
... lib
... sys
... tmp
... usr}}

{{Ic|exit}} when done:

{{Cmd|$ exit}}

Do not forget to change it back:

{{Cat|~/.local/bin/bwrap-imv| ...
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

All done with a basic {{Ic|bwrap}} wrapper.

=== Seccomp ===

{{Expand|}}

== .desktop integration ==

{{Obsolete|This should probably be documented in [[Default_applications]] and linked here. Nothing is unique in using with {{Ic|bwrap}}.}}

{{Note|This section is also using {{Pkg|imv|arch=}} as the example.}}

[https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html XDG Desktop Entry Specification]
are a set of standards describing how a particular program is to be
launched, how it appears in menus, etc.

The default ''.desktop'' file for {{Ic|imv}} is at
{{Path|/usr/share/applications/imv.desktop}}. Move it to
{{Path|"${XDG_DATA_HOME}/applications/bwrap-imv.desktop"}}.

Only 3 options will need to be changed: Name/Name[en_US], what shows up
in the application menu in a graphical file manager (if you have one
installed); Exec, program to execute:

{{Cat|"${XDG_DATA_HOME}/applications/bwrap-imv.desktop"|...<nowiki>
Name=bwrap-imv
Name[en_US]=bwrap-imv
Exec=bwrap-imv %F
</nowiki>...}}

The program {{Ic|xdg-open}} (from the {{Pkg|xdg-utils|arch=}} package) can be
used to open files based on the [https://en.wikipedia.org/wiki/MIME MIME]
type + corresponding entry in
{{Path|"${XDG_CONFIG_HOME}/mimeapps.list"}} and
{{Path|"${XDG_DATA_HOME}/applications/mimeinfo.cache"}}.

Install {{Pkg|desktop-file-utils|arch=}} if it is not installed already, it
comes with two commands that are needed {{Ic|desktop-file-validate}} and
{{Ic|update-desktop-database}}:

{{Cmd|# apk add desktop-file-utils}}

=== Validate ===

It is a good idea to validate {{Ic|imv.desktop}} using
{{Ic|desktop-file-validate}}:

{{Cmd|$ desktop-file-validate "${XDG_DATA_HOME}/applications/bwrap-imv.desktop"}}

=== Update database ===

This will make entries in {{Path|"${XDG_DATA_HOME}/applications/"}} take
precedence over system-wide files ({{Path|/usr/share/applications/}}).
However {{Path|"${XDG_CONFIG_HOME}/mimeapps.list"}} has precedence over
both.

Updating the database, will create
{{Path|"${XDG_DATA_HOME}/applications/mimeinfo.cache"}}:

{{Cmd|$ update-desktop-database "${XDG_DATA_HOME}/applications"}}

== Troubleshooting ==

=== Can't find what path is missing ===

If all else fails start broad and work toward narrowing. See if
{{Ic|bwrap}} works with the program at all:

{{Cmd|$ bwrap \
--dev-bind / / PROGRAM}}

If that works start to narrow:

{{Cmd|$ bwrap \
--ro-bind /bin/ /bin/ \
--dev-bind /dev/ /dev/ \
--ro-bind /lib/ /lib/ \
--ro-bind /sys/ /sys/ \
--ro-bind /usr/ /usr/ \
PROGRAM}}

Keep going till you have narrowed as much as possible.

== See also ==

* [[Bubblewrap/Examples]]
* [https://wiki.archlinux.org/title/Bubblewrap ArchWiki: Bubblewrap]
** [https://wiki.archlinux.org/title/Bubblewrap/Examples ArchWiki: Bubblewrap/Examples]
* [https://wiki.archlinux.org/title/Desktop_entries ArchWiki: Desktop entries (*.desktop files)]

[[Category:Desktop]]
[[Category:Security]]

Bubblewrap/Examples

2024-05-24T07:24:12Z

Encode: Pkg: Search every arch

{{Draft|Someone more experienced needs to look over this.}}

{{Todo|
* Since bubblewrap can make use of [https://en.wikipedia.org/wiki/Seccomp seccomp], restrictive versions should be added.
* {{Ic|imv}}, {{Ic|mpv}} and {{Ic|zathura}} currently only accept 1 mandatory (except {{Ic|imv}}) argument. This should (hopefully) be temporary, until I figure out how to pass multiple arguments (without including everything else).}}

{{Warning|These were found by going backward; start with a complicated program and as restricted as possible sandbox, allowing more till the program appears to work. Because of this, complicated and sensitive programs (for example: {{Pkg|firefox|arch=}} and {{Pkg|keepassxc|arch=}}) may be missing some things they need, which might lead to '''LESS SECURITY''', '''LESS PRIVACY''' and '''DATA LOSS'''.}}

{{Note|
* This page assumes you have already read [[Bubblewrap]].
* To try and avoid duplicates everything will be explained for [[Firefox]] and only when it differs (non obviously) for everything else.
* Where applicable, this assumes: [[Wayland]] only + [[PipeWire]].
: If Wayland is needed, make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

{{TOC right}}

== Firefox ==

{{Cat|~/.local/bin/bwrap-firefox|#!/bin/sh

# Firefox wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
--ro-bind /usr/share/icons/ /usr/share/icons/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
/usr/lib/firefox/firefox}}

set -u
If the shell tries to expand an unset parameter, it will error (with a
few exceptions).

XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
Take value if already set, else fallback to the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG] default.

NEW_HOME='/home/user'
User to appear as.

NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
{{Path|"$XDG_CACHE_HOME"}} for the new user.

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"
Make sure the new (real) home for Firefox data exist.

--unshare-all \
Unshare all possible [https://en.wikipedia.org/wiki/Linux_namespaces namespaces].

--share-net \
Retain the network namespace.

--new-session \
New terminal session for the sandbox.

--die-with-parent \
Child process dies when {{Ic|bwrap}} parent dies.

--clearenv \
Unset all environment variables (except for {{Path|"$PWD"}}).

--setenv HOME "$NEW_HOME" \
Pass the path to {{Path|"$NEW_HOME"}} for {{Path|"$HOME"}}.

--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
Specify the Wayland display to run clients on.

--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
User-specific non-essential (cached) data.

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
User-specific non-essential runtime files and other file objects.

--hostname localhost \
Use custom hostname in the sandbox.

--dev /dev/ \
New devtmpfs, access to special or device files.

--ro-bind /etc/fonts/ /etc/fonts/ \
System font configuration directory.

--ro-bind /etc/resolv.conf /etc/resolv.conf \
Needed for DNS resolution.

--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
Per-user Mozilla cache.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${NEW_XDG_CONFIG_HOME}/fontconfig/" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) Per-user font configuration directory.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/user-dirs.dirs" "${NEW_XDG_CONFIG_HOME}/user-dirs.dirs" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) If you modify "well known" user directories, like
{{Path|~/Downloads/}}, you need this to have Firefox pick it up.

{{Note|If you use {{Path|"${XDG_CONFIG_HOME}/user-dirs.dirs"}} you should also add the corresponding path(s).
For example if you set {{Path|XDG_DOWNLOAD_DIR}} to
{{Path|"${HOME}/downloads/"}} you would also add:
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--bind-try "${HOME}/downloads/" "${NEW_HOME}/downloads/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
}}

--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
{{Path|"${XDG_DATA_HOME}/firefox/"}} is the location of Firefox data. Shown to Firefox as {{Path|"${NEW_HOME}/.mozilla/"}}.

{{Note|This has the added benefit of getting {{Path|~/.mozilla/}} out of your {{Path|"$HOME"}}, and conforming more to XDG. This may one day not be necessary: [https://bugzilla.mozilla.org/show_bug.cgi?id{{=}}259356 Support for the Freedesktop.org XDG Base Directory Specification (2004-09-14)].}}

...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${NEW_XDG_DATA_HOME}/fonts/" \'''
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
...
(Optional) Per-user directory scanned for font files.

--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Default {{Path|~/Downloads/}} directory.

--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
Shared libraries.

--proc /proc/ \
New procfs, provides information about running processes and the kernel.

--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
Bind the Wayland socket file.

--ro-bind /usr/lib/ /usr/lib/ \
Object files and libraries.

{{Note|It is not worth the time to limit this, the churn is too great.}}

--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
XKB is a keyboard keymap support library.

{{Note|Even tho the path has {{Path|*/X11/*}} Wayland uses it too.}}

--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
Font presets.

--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
Global directory scanned for font files.

--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
Needed for "Save Page As…", "Export|Import Bookmarks File", among others.

--ro-bind /usr/share/icons/ /usr/share/icons/ \
Global icons directory.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
International Components for Unicode (ICU) provides support for Unicode
and globalization.

...
--ro-bind /usr/share/icu/ /usr/share/icu/ \
'''--ro-bind /usr/share/libdrm/ /usr/share/libdrm/ \'''
--ro-bind /usr/share/mime/ /usr/share/mime/ \
...
(Optional) Direct Rendering Manager (DRM), Linux kernel subsystem for
interfacing with GPUs of video cards. Programs can use this to have the
GPU do hardware-accelerated 3D rendering and video decoding.

--ro-bind /usr/share/mime/ /usr/share/mime/ \
Global XDG MIME directory.

/usr/lib/firefox/firefox
Call Firefox.

{{Tip|If you use multiple profiles you can have:
/usr/lib/firefox/firefox -P "$@"
this will allow you to pass a profile name and go into that specific one or not pass anything and get prompted for which to choose.}}

=== PipeWire audio ===

{{Todo|}}

=== Pulse audio ===

...
--proc /proc/ \
'''--ro-bind "${XDG_RUNTIME_DIR}/pulse/" "${XDG_RUNTIME_DIR}/pulse/" \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
(Optional) Pulse audio.

=== Optional(?) stuff ===

{{Draft|Are these needed?}}

...
--proc /proc/ \
'''--ro-bind /sys/bus/pci/ /sys/bus/pci/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Information about PCI bus type.

Without this you get
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: cannot access /sys/bus/pci (t=0.177033) [GFX1-]: glxtest: cannot access /sys/bus/pci
but it still seems to work.

...
--proc /proc/ \
'''--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Contains a filesystem representation of the kernel device tree.

With {{Ic|--ro-bind /sys/bus/pci/ /sys/bus/pci/ \}} but without this you get:
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) [GFX1-]: glxtest: ManageChildProcess failed

Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) |[1][GFX1-]: No GPUs detected via PCI
(t=0.18958) [GFX1-]: No GPUs detected via PCI
but it still seems to work.

== imv ==

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

...

'''XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"'''
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
'''XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \'''
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
'''--ro-bind /etc/fonts/ /etc/fonts/ \'''
'''--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \'''
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \'''
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
'''--ro-bind /usr/share/fonts/ /usr/share/fonts/ \'''
'''--ro-bind /usr/share/icu/ /usr/share/icu/ \'''
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
...
(Optional) To use commands in {{Ic|imv}}.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument. If you don't pass in
anything it will default to {{Path|./}}, the current directory.

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}

== KeePassXC ==

{{Note|I only use the bare minimum functionality, so functionality you need is probably missing. If you use functionality not here, your contribution will be most appreciated. To kick things off: {{Ic|Unable to initialize libusb. USB devices may not be detected properly.}} can be silenced with {{Ic|--dev-bind /dev/bus/usb/ /dev/bus/usb/ \}}.}}

{{Cat|~/.local/bin/bwrap-keepassxc|#!/bin/sh

# keepassxc wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
PASSWORD_DATABASE{{=}}"${HOME}/password database"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_PASSWORD_DATABASE{{=}}"${NEW_HOME}${PASSWORD_DATABASE#"$HOME"}"

mkdir -pm 0700 "$PASSWORD_DATABASE"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CONFIG_HOME}/keepassxc/" "${NEW_XDG_CONFIG_HOME}/keepassxc/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind /usr/bin/keepassxc /usr/bin/keepassxc \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/ /usr/share/X11/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/keepassxc/ /usr/share/keepassxc/ \
--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
/usr/bin/keepassxc "$@"}}

PASSWORD_DATABASE="${HOME}/password database"
Directory containing your {{Pkg|keepassxc|arch=}} password database.

{{Tip|This is almost certainly not where '''your''' database is located. You will need to change it to where you put your password database.}}

--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
Session type, since we are assuming Wayland only, this will be "wayland".

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
Bind password database.

== mpv ==

{{Cat|~/.local/bin/bwrap-mpv|#!/bin/sh

# mpv wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run mpv wrapped in bwrap.

Usage:
$ bwrap-mpv VIDEO\n'
exit 1
fi

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$1"}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

--player-operation-mode=pseudo-gui \
Because {{Ic|--new-session}} is used, this is needed to have a way to
control {{Ic|mpv}} when it would otherwise not show a GUI.

{{Tip|If you followed [[Bubblewrap#.desktop_integration]], you should remove it from {{Path|"${XDG_DATA_HOME}/applications/bwrap-mpv.desktop"}}.}}

--title='bwrap | ${media-title}' \
Set the window title, showing at a glance that you are using {{Ic|bwrap}}.

=== mpv-net ===

If you want to use {{Ic|mpv}} to stream over the Internet, you will need
a few things more.

{{Tip|You can use both {{Ic|bwrap-mpv}} and {{Ic|bwrap-mpv-net}}. {{Ic|bwrap-mpv}} for local stuff and {{Ic|bwrap-mpv-net}} for watching over the Internet.}}

{{Cat|~/.local/bin/bwrap-mpv-net|#!/bin/sh

# mpv wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv PATH /usr/bin/ \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$@"}}

--setenv PATH /usr/bin/ \
{{Todo|Document why this is needed.}}

--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
Certificate authorities that are ''trusted''.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

"$@"
This is so you can pass more options to {{Ic|bwrap-mpv-net}}, for example:
$ bwrap-mpv-net --video=no --sub=no 'URL1' 'URL2'

=== Pulse audio ===

--ro-bind "${XDG_RUNTIME_DIR}/pulse" "${XDG_RUNTIME_DIR}/pulse" \
Pulse audio.

=== Screenshots ===

The default screenshots directory is {{Path|"$XDG_DESKTOP_DIR"}} (which is
{{Path|"${HOME}/Desktop/"}}, which will fallback to {{Path|"$HOME/"}} if
{{Path|"${HOME}/Desktop/"}} doesn't exist). That means that by default
{{Ic|bwrap-mpv[-net]}} won't allow screenshots unless you change a few things.
Do the following to allow an XDG approved screenshots directory:

...
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
'''XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"'''

...
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

'''mkdir -pm 0700 "${XDG_DATA_HOME}/mpv/"'''

...
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
'''--bind "${XDG_DATA_HOME}/mpv/" "${NEW_XDG_DATA_HOME}/mpv/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
Now make {{Ic|mpv}} use that directory:

{{Cat|"${XDG_CONFIG_HOME}/mpv/mpv.conf"|<nowiki>...
# Something like this, change to match "$XDG_DATA_HOME"
screenshot-template="~/.local/share/mpv/screenshots/%F [%p] %02n"
...</nowiki>}}

== yt-dlp ==

{{Cat|~/.local/bin/bwrap-yt-dlp|#!/bin/sh

# yt-dlp wrapped in bwrap with network access.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

mkdir -pm 0700 "${HOME}/Downloads/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--hostname localhost \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--ro-bind-try "${XDG_CONFIG_HOME}/yt-dlp/config" "${NEW_XDG_CONFIG_HOME}/yt-dlp/config" \
--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/bin/ffmpeg /usr/bin/ffmpeg \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
/usr/bin/yt-dlp "$@"}}

--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Directory for writing the files. This should match {{Ic|--output}} that
is either in {{Path|"${XDG_CONFIG_HOME}/yt-dlp/config"}} or passed on
the command line.

/usr/bin/yt-dlp "$@"
This is so you can pass more options to {{Ic|bwrap-yt-dlp}}, for example:
$ bwrap-yt-dlp --no-playlist 'URL1' 'URL2'

== zathura ==

{{Cat|~/.local/bin/bwrap-zathura|#!/bin/sh

# zathura wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run zathura wrapped in bwrap.

Usage:
$ bwrap-zathura PDF\n'
exit 1
fi

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/zathura/zathurarc" "${XDG_CONFIG_HOME}/zathura/zathurarc" \
--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/zathura /usr/bin/zathura \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/zathura "$1"}}

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"
Have to premake the directory for {{Ic|zathura}} data.

--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
Allow writing of: bookmarks, history, input history.

--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
Used for identifying what type a file should be. Read the
{{Ic|file(1)}} man page for more information.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

[[Category:Security]]

Bubblewrap/Examples

2024-05-24T07:09:55Z

Encode: Update formatting

{{Draft|Someone more experienced needs to look over this.}}

{{Todo|
* Since bubblewrap can make use of [https://en.wikipedia.org/wiki/Seccomp seccomp], restrictive versions should be added.
* {{Ic|imv}}, {{Ic|mpv}} and {{Ic|zathura}} currently only accept 1 mandatory (except {{Ic|imv}}) argument. This should (hopefully) be temporary, until I figure out how to pass multiple arguments (without including everything else).}}

{{Warning|These were found by going backward; start with a complicated program and as restricted as possible sandbox, allowing more till the program appears to work. Because of this, complicated and sensitive programs (for example: {{Pkg|firefox}} and {{Pkg|keepassxc}}) may be missing some things they need, which might lead to '''LESS SECURITY''', '''LESS PRIVACY''' and '''DATA LOSS'''.}}

{{Note|
* This page assumes you have already read [[Bubblewrap]].
* To try and avoid duplicates everything will be explained for [[Firefox]] and only when it differs (non obviously) for everything else.
* Where applicable, this assumes: [[Wayland]] only + [[PipeWire]].
: If Wayland is needed, make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

{{TOC right}}

== Firefox ==

{{Cat|~/.local/bin/bwrap-firefox|#!/bin/sh

# Firefox wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
--ro-bind /usr/share/icons/ /usr/share/icons/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
/usr/lib/firefox/firefox}}

set -u
If the shell tries to expand an unset parameter, it will error (with a
few exceptions).

XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
Take value if already set, else fallback to the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG] default.

NEW_HOME='/home/user'
User to appear as.

NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
{{Path|"$XDG_CACHE_HOME"}} for the new user.

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"
Make sure the new (real) home for Firefox data exist.

--unshare-all \
Unshare all possible [https://en.wikipedia.org/wiki/Linux_namespaces namespaces].

--share-net \
Retain the network namespace.

--new-session \
New terminal session for the sandbox.

--die-with-parent \
Child process dies when {{Ic|bwrap}} parent dies.

--clearenv \
Unset all environment variables (except for {{Path|"$PWD"}}).

--setenv HOME "$NEW_HOME" \
Pass the path to {{Path|"$NEW_HOME"}} for {{Path|"$HOME"}}.

--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
Specify the Wayland display to run clients on.

--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
User-specific non-essential (cached) data.

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
User-specific non-essential runtime files and other file objects.

--hostname localhost \
Use custom hostname in the sandbox.

--dev /dev/ \
New devtmpfs, access to special or device files.

--ro-bind /etc/fonts/ /etc/fonts/ \
System font configuration directory.

--ro-bind /etc/resolv.conf /etc/resolv.conf \
Needed for DNS resolution.

--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
Per-user Mozilla cache.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${NEW_XDG_CONFIG_HOME}/fontconfig/" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) Per-user font configuration directory.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
'''XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"'''
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${XDG_CACHE_HOME}/mozilla/" \
'''--ro-bind-try "${XDG_CONFIG_HOME}/user-dirs.dirs" "${NEW_XDG_CONFIG_HOME}/user-dirs.dirs" \'''
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) If you modify "well known" user directories, like
{{Path|~/Downloads/}}, you need this to have Firefox pick it up.

{{Note|If you use {{Path|"${XDG_CONFIG_HOME}/user-dirs.dirs"}} you should also add the corresponding path(s).
For example if you set {{Path|XDG_DOWNLOAD_DIR}} to
{{Path|"${HOME}/downloads/"}} you would also add:
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--bind-try "${HOME}/downloads/" "${NEW_HOME}/downloads/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
}}

--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
{{Path|"${XDG_DATA_HOME}/firefox/"}} is the location of Firefox data. Shown to Firefox as {{Path|"${NEW_HOME}/.mozilla/"}}.

{{Note|This has the added benefit of getting {{Path|~/.mozilla/}} out of your {{Path|"$HOME"}}, and conforming more to XDG. This may one day not be necessary: [https://bugzilla.mozilla.org/show_bug.cgi?id{{=}}259356 Support for the Freedesktop.org XDG Base Directory Specification (2004-09-14)].}}

...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${NEW_XDG_DATA_HOME}/fonts/" \'''
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
...
(Optional) Per-user directory scanned for font files.

--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Default {{Path|~/Downloads/}} directory.

--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
Shared libraries.

--proc /proc/ \
New procfs, provides information about running processes and the kernel.

--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
Bind the Wayland socket file.

--ro-bind /usr/lib/ /usr/lib/ \
Object files and libraries.

{{Note|It is not worth the time to limit this, the churn is too great.}}

--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
XKB is a keyboard keymap support library.

{{Note|Even tho the path has {{Path|*/X11/*}} Wayland uses it too.}}

--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
Font presets.

--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
Global directory scanned for font files.

--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
Needed for "Save Page As…", "Export|Import Bookmarks File", among others.

--ro-bind /usr/share/icons/ /usr/share/icons/ \
Global icons directory.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
International Components for Unicode (ICU) provides support for Unicode
and globalization.

...
--ro-bind /usr/share/icu/ /usr/share/icu/ \
'''--ro-bind /usr/share/libdrm/ /usr/share/libdrm/ \'''
--ro-bind /usr/share/mime/ /usr/share/mime/ \
...
(Optional) Direct Rendering Manager (DRM), Linux kernel subsystem for
interfacing with GPUs of video cards. Programs can use this to have the
GPU do hardware-accelerated 3D rendering and video decoding.

--ro-bind /usr/share/mime/ /usr/share/mime/ \
Global XDG MIME directory.

/usr/lib/firefox/firefox
Call Firefox.

{{Tip|If you use multiple profiles you can have:
/usr/lib/firefox/firefox -P "$@"
this will allow you to pass a profile name and go into that specific one or not pass anything and get prompted for which to choose.}}

=== PipeWire audio ===

{{Todo|}}

=== Pulse audio ===

...
--proc /proc/ \
'''--ro-bind "${XDG_RUNTIME_DIR}/pulse/" "${XDG_RUNTIME_DIR}/pulse/" \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
(Optional) Pulse audio.

=== Optional(?) stuff ===

{{Draft|Are these needed?}}

...
--proc /proc/ \
'''--ro-bind /sys/bus/pci/ /sys/bus/pci/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Information about PCI bus type.

Without this you get
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: cannot access /sys/bus/pci (t=0.177033) [GFX1-]: glxtest: cannot access /sys/bus/pci
but it still seems to work.

...
--proc /proc/ \
'''--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \'''
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Contains a filesystem representation of the kernel device tree.

With {{Ic|--ro-bind /sys/bus/pci/ /sys/bus/pci/ \}} but without this you get:
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) [GFX1-]: glxtest: ManageChildProcess failed

Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) |[1][GFX1-]: No GPUs detected via PCI
(t=0.18958) [GFX1-]: No GPUs detected via PCI
but it still seems to work.

== imv ==

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

...

'''XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"'''
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
'''XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"'''

...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
'''--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \'''
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
'''--ro-bind /etc/fonts/ /etc/fonts/ \'''
'''--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \'''
'''--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \'''
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
'''--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
'''--ro-bind /usr/share/fonts/ /usr/share/fonts/ \'''
'''--ro-bind /usr/share/icu/ /usr/share/icu/ \'''
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
...
(Optional) To use commands in {{Ic|imv}}.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument. If you don't pass in
anything it will default to {{Path|./}}, the current directory.

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}

== KeePassXC ==

{{Note|I only use the bare minimum functionality, so functionality you need is probably missing. If you use functionality not here, your contribution will be most appreciated. To kick things off: {{Ic|Unable to initialize libusb. USB devices may not be detected properly.}} can be silenced with {{Ic|--dev-bind /dev/bus/usb/ /dev/bus/usb/ \}}.}}

{{Cat|~/.local/bin/bwrap-keepassxc|#!/bin/sh

# keepassxc wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
PASSWORD_DATABASE{{=}}"${HOME}/password database"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_PASSWORD_DATABASE{{=}}"${NEW_HOME}${PASSWORD_DATABASE#"$HOME"}"

mkdir -pm 0700 "$PASSWORD_DATABASE"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CONFIG_HOME}/keepassxc/" "${NEW_XDG_CONFIG_HOME}/keepassxc/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind /usr/bin/keepassxc /usr/bin/keepassxc \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/ /usr/share/X11/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/keepassxc/ /usr/share/keepassxc/ \
--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
/usr/bin/keepassxc "$@"}}

PASSWORD_DATABASE="${HOME}/password database"
Directory containing your {{Pkg|keepassxc}} password database.

{{Tip|This is almost certainly not where '''your''' database is located. You will need to change it to where you put your password database.}}

--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
Session type, since we are assuming Wayland only, this will be "wayland".

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
Bind password database.

== mpv ==

{{Cat|~/.local/bin/bwrap-mpv|#!/bin/sh

# mpv wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run mpv wrapped in bwrap.

Usage:
$ bwrap-mpv VIDEO\n'
exit 1
fi

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$1"}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

--player-operation-mode=pseudo-gui \
Because {{Ic|--new-session}} is used, this is needed to have a way to
control {{Ic|mpv}} when it would otherwise not show a GUI.

{{Tip|If you followed [[Bubblewrap#.desktop_integration]], you should remove it from {{Path|"${XDG_DATA_HOME}/applications/bwrap-mpv.desktop"}}.}}

--title='bwrap | ${media-title}' \
Set the window title, showing at a glance that you are using {{Ic|bwrap}}.

=== mpv-net ===

If you want to use {{Ic|mpv}} to stream over the Internet, you will need
a few things more.

{{Tip|You can use both {{Ic|bwrap-mpv}} and {{Ic|bwrap-mpv-net}}. {{Ic|bwrap-mpv}} for local stuff and {{Ic|bwrap-mpv-net}} for watching over the Internet.}}

{{Cat|~/.local/bin/bwrap-mpv-net|#!/bin/sh

# mpv wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv PATH /usr/bin/ \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$@"}}

--setenv PATH /usr/bin/ \
{{Todo|Document why this is needed.}}

--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
Certificate authorities that are ''trusted''.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

"$@"
This is so you can pass more options to {{Ic|bwrap-mpv-net}}, for example:
$ bwrap-mpv-net --video=no --sub=no 'URL1' 'URL2'

=== Pulse audio ===

--ro-bind "${XDG_RUNTIME_DIR}/pulse" "${XDG_RUNTIME_DIR}/pulse" \
Pulse audio.

=== Screenshots ===

The default screenshots directory is {{Path|"$XDG_DESKTOP_DIR"}} (which is
{{Path|"${HOME}/Desktop/"}}, which will fallback to {{Path|"$HOME/"}} if
{{Path|"${HOME}/Desktop/"}} doesn't exist). That means that by default
{{Ic|bwrap-mpv[-net]}} won't allow screenshots unless you change a few things.
Do the following to allow an XDG approved screenshots directory:

...
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
'''XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"'''

...
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
'''NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"'''

'''mkdir -pm 0700 "${XDG_DATA_HOME}/mpv/"'''

...
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
'''--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \'''
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
'''--bind "${XDG_DATA_HOME}/mpv/" "${NEW_XDG_DATA_HOME}/mpv/" \'''
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
Now make {{Ic|mpv}} use that directory:

{{Cat|"${XDG_CONFIG_HOME}/mpv/mpv.conf"|<nowiki>...
# Something like this, change to match "$XDG_DATA_HOME"
screenshot-template="~/.local/share/mpv/screenshots/%F [%p] %02n"
...</nowiki>}}

== yt-dlp ==

{{Cat|~/.local/bin/bwrap-yt-dlp|#!/bin/sh

# yt-dlp wrapped in bwrap with network access.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

mkdir -pm 0700 "${HOME}/Downloads/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--hostname localhost \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--ro-bind-try "${XDG_CONFIG_HOME}/yt-dlp/config" "${NEW_XDG_CONFIG_HOME}/yt-dlp/config" \
--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/bin/ffmpeg /usr/bin/ffmpeg \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
/usr/bin/yt-dlp "$@"}}

--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Directory for writing the files. This should match {{Ic|--output}} that
is either in {{Path|"${XDG_CONFIG_HOME}/yt-dlp/config"}} or passed on
the command line.

/usr/bin/yt-dlp "$@"
This is so you can pass more options to {{Ic|bwrap-yt-dlp}}, for example:
$ bwrap-yt-dlp --no-playlist 'URL1' 'URL2'

== zathura ==

{{Cat|~/.local/bin/bwrap-zathura|#!/bin/sh

# zathura wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run zathura wrapped in bwrap.

Usage:
$ bwrap-zathura PDF\n'
exit 1
fi

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/zathura/zathurarc" "${XDG_CONFIG_HOME}/zathura/zathurarc" \
--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/zathura /usr/bin/zathura \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/zathura "$1"}}

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"
Have to premake the directory for {{Ic|zathura}} data.

--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
Allow writing of: bookmarks, history, input history.

--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
Used for identifying what type a file should be. Read the
{{Ic|file(1)}} man page for more information.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

[[Category:Security]]

Release Notes for Alpine 3.20.0

2024-05-24T05:06:51Z

Encode: Added page to Category:News

== Base System ==

=== grub 2.12 ===

When upgrading existing installations using grub on UEFI systems, make sure to update the installed bootloader before rebooting otherwise your machine might not boot.

The problem is that grub added a new configuration that executes <code>fwsetup --is-supported</code>, but grub 2.06 does not support the <code>--is-supported</code> argument yet, causing grub to try to reboot into firmware unconditionally.

Here is an example assuming the default setup. Don't blindly copy this example, but verify what's applicable to your system.

==== EFI ====

{{Cmd|
# grub-install --target{{=}}<var>$target</var> --efi-directory{{=}}<var>$efi_directory</var> \
--bootloader-id{{=}}alpine --boot-directory{{=}}/boot --no-nvram
# install -D <var>$efi_directory</var>/EFI/alpine/grub<var>$fwa</var>.efi <var>$efi_directory</var>/EFI/boot/boot<var>$fwa</var>.efi

}}

; target : The relevant [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/blob/master/setup-disk.in#L320-324 target] for your system
; efi_directory : Either {{Path|/boot/efi}} or {{Path|/boot}}. Run <code>awk '$2 ~ /boot/ && $3 ~ /fat|msdos/ { print $2 }' /proc/mounts</code> to confirm.
; fwa : The respective [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/blob/master/setup-disk.in#L320-324 firmware architecture] for your system

==== Short-term workaround ====

A short-term workaround to get the system bootable again is to restore the backup configuration:

{{Cmd|cp /boot/grub/grub.cfg.backup /boot/grub.cfg }}

This should allow you to boot the system again in order to fix it permanently. This will be reverted when either grub or the kernel is updated again.

This will only work if <code>update-grub</code> has not been executed any more since the upgrade to grub 2.12.

== Others ==

=== Redis ===
Due to [https://github.com/redis/redis/pull/13157 the relicensing of Redis] to [https://redis.io/legal/rsalv2-agreement/ RSALv2]+[https://redis.io/legal/server-side-public-license-sspl/ SSPLv1], a non-free license model, the [https://spdx.org/licenses/BSD-3-Clause.html BSD-3-Clause] licensed fork [https://valkey.io/ Valkey] has replaced Redis in the main package repository.

A {{#ifexpr: {{AlpineLatest}} >= 3.20 |{{pkg|valkey-compat|branch=v3.20|arch=}}|{{pkg|valkey-compat|branch=edge|arch=}}}} package is provided with symlinks and group for easy Redis replacement.

The {{#ifexpr: {{AlpineLatest}} >= 3.20 |{{pkg|redis|branch=v3.20|arch=}}|{{pkg|redis|branch=edge|arch=}}}} aport has been moved to the community repository, with a shorter support cycle, and will not be upgraded past 7.2.x due to the license change.

Another replacement alternative, the [https://spdx.org/licenses/LGPL-3.0-only.html LGPL-3.0-only] licensed fork [https://redict.io/ Redict] is also available in the community repository.

=== yq ===
yq was renamed to yq-go. [https://gitlab.alpinelinux.org/alpine/aports/-/issues/16052 #16052]

=== aws-cli ===
Due to incompatibility issues with Python 3.12, aws-cli has been temporarily disabled until the issue is resolved by upstream. See the corresponding problem upstream: [https://github.com/aws/aws-cli/issues/8342 #8342]

=== GNOME 46 ===

New upstream release of GNOME.

Depending on how you installed GNOME, you may have to manually add <code>gcr-ssh-agent</code> after upgrading to retain GNOME Keyring ssh integration.

=== KDE 6 ===

KDE Plasma has been upgraded to Plasma 6, bringing the major update to Qt6 with it. This also includes applications from KDE Gear although some individual applications remain on Qt5 for now. The update makes the Wayland session the default and this Alpine release is the last one to support the X11 session.

=== podman [https://github.com/containers/podman/releases/tag/v5.0.0 5.x] ===

The default tool for rootless networking has been swapped from <code>slirp4netns</code> to
<code>pasta</code> (<code>passt</code>) for improved performance. As a result, networks named pasta are
no longer supported.

== Upgrades ==

* Crystal 1.12
* LLVM 18
* nginx 1.26
* .NET 8
* Nim 2.0
* OpenJDK 22
* Python 3.12
* Racket 8.13
* Ruby 3.3
* Rust 1.78
* R 4.4
* Sway 1.9

[[Category:News]]

Bubblewrap/Examples

2024-05-21T06:34:52Z

Encode: Add a general warning about potential problems from using stuff from here

{{Draft|Someone more experienced needs to look over this.}}

{{Todo|Since bubblewrap can make use of [https://en.wikipedia.org/wiki/Seccomp seccomp], restrictive versions should be added. {{Ic|imv}}, {{Ic|mpv}} and {{Ic|zathura}} currently only accept 1 mandatory (except {{Ic|imv}}) argument. This should (hopefully) be temporary, until I figure out how to pass multiple arguments (without including everything else).}}

{{Warning|These were found by going backward; start with a complicated program and as restricted as possible sandbox, allowing more till the program appears to work. Because of this, complicated and sensitive programs (for example: {{Pkg|firefox}} and {{Pkg|keepassxc}}) may be missing some things they need, which might lead to '''LESS SECURITY''', '''LESS PRIVACY''' and '''DATA LOSS'''.}}

{{Note|This page assumes you have already read over [[Bubblewrap]]. To try and avoid duplicates, everything will be explained for [[Firefox]] and only when it differs (non obviously) for everything else. Where applicable this also assumes: [[Wayland]] only + [[PipeWire]]. If you use Wayland, make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

{{TOC right}}

== Firefox ==

{{Cat|~/.local/bin/bwrap-firefox|#!/bin/sh

# Firefox wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
--ro-bind /usr/share/icons/ /usr/share/icons/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
/usr/lib/firefox/firefox}}

set -u
If the shell tries to expand an unset parameter, it will error (with a
few exceptions).

XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
Take value if already set, else fallback to the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG] default.

NEW_HOME='/home/user'
User to appear as.

NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
{{Path|"$XDG_CACHE_HOME"}} for the new user.

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"
Make sure the new (real) home for Firefox data exist.

--unshare-all \
Unshare all possible [https://en.wikipedia.org/wiki/Linux_namespaces namespaces].

--share-net \
Retain the network namespace.

--new-session \
New terminal session for the sandbox.

--die-with-parent \
Child process dies when {{Ic|bwrap}} parent dies.

--clearenv \
Unset all environment variables (except for {{Path|"$PWD"}}).

--setenv HOME "$NEW_HOME" \
Pass the path to {{Path|"$NEW_HOME"}} for {{Path|"$HOME"}}.

--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
Specify the Wayland display to run clients on.

--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
User-specific non-essential (cached) data.

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
User-specific non-essential runtime files and other file objects.

--hostname localhost \
Use custom hostname in the sandbox.

--dev /dev/ \
New devtmpfs, access to special or device files.

--ro-bind /etc/fonts/ /etc/fonts/ \
System font configuration directory.

--ro-bind /etc/resolv.conf /etc/resolv.conf \
Needed for DNS resolution.

--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
Per-user Mozilla cache.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${NEW_XDG_CONFIG_HOME}/fontconfig/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) Per-user font configuration directory.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${XDG_CACHE_HOME}/mozilla/" \
--ro-bind-try "${XDG_CONFIG_HOME}/user-dirs.dirs" "${NEW_XDG_CONFIG_HOME}/user-dirs.dirs" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) If you modify "well known" user directories, like
{{Path|~/Downloads/}}, you need this to have Firefox pick it up.

{{Note|If you use {{Path|"${XDG_CONFIG_HOME}/user-dirs.dirs"}} you should also add the corresponding path(s).
For example if you set {{Path|XDG_DOWNLOAD_DIR}} to
{{Path|"${HOME}/downloads/"}} you would also add:
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/downloads/" "${NEW_HOME}/downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
}}

--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
{{Path|"${XDG_DATA_HOME}/firefox/"}} is the location of Firefox data. Shown to Firefox as {{Path|"${NEW_HOME}/.mozilla/"}}.

{{Note|This has the added benefit of getting {{Path|~/.mozilla/}} out of your {{Path|"$HOME"}}, and conforming more to XDG. This may one day not be necessary: [https://bugzilla.mozilla.org/show_bug.cgi?id{{=}}259356 Support for the Freedesktop.org XDG Base Directory Specification (2004-09-14)].}}

...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${NEW_XDG_DATA_HOME}/fonts/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
...
(Optional) Per-user directory scanned for font files.

--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Default {{Path|~/Downloads/}} directory.

--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
Shared libraries.

--proc /proc/ \
New procfs, provides information about running processes and the kernel.

--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
Bind the Wayland socket file.

--ro-bind /usr/lib/ /usr/lib/ \
Object files and libraries.

{{Note|It is not worth the time to limit this, the churn is too great.}}

--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
XKB is a keyboard keymap support library.

{{Note|Even tho the path has {{Path|*/X11/*}} Wayland uses it too.}}

--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
Font presets.

--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
Global directory scanned for font files.

--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
Needed for "Save Page As…", "Export|Import Bookmarks File", among others.

--ro-bind /usr/share/icons/ /usr/share/icons/ \
Global icons directory.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
International Components for Unicode (ICU) provides support for Unicode
and globalization.

...
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/libdrm/ /usr/share/libdrm/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
...
(Optional) Direct Rendering Manager (DRM), Linux kernel subsystem for
interfacing with GPUs of video cards. Programs can use this to have the
GPU do hardware-accelerated 3D rendering and video decoding.

--ro-bind /usr/share/mime/ /usr/share/mime/ \
Global XDG MIME directory.

/usr/lib/firefox/firefox
Call Firefox.

{{Tip|If you use multiple profiles you can have:
/usr/lib/firefox/firefox -P "$@"
this will allow you to pass a profile name and go into that specific one or not pass anything and get prompted for which to choose.}}

=== PipeWire audio ===

{{Todo|}}

=== Pulse audio ===

...
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/pulse/" "${XDG_RUNTIME_DIR}/pulse/" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
(Optional) Pulse audio.

=== Optional(?) stuff ===

{{Draft|Are these needed?}}

...
--proc /proc/ \
--ro-bind /sys/bus/pci/ /sys/bus/pci/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Information about PCI bus type.

Without this you get
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: cannot access /sys/bus/pci (t=0.177033) [GFX1-]: glxtest: cannot access /sys/bus/pci
but it still seems to work.

...
--proc /proc/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Contains a filesystem representation of the kernel device tree.

With {{Ic|--ro-bind /sys/bus/pci/ /sys/bus/pci/ \}} but without this you get:
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) [GFX1-]: glxtest: ManageChildProcess failed

Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) |[1][GFX1-]: No GPUs detected via PCI
(t=0.18958) [GFX1-]: No GPUs detected via PCI
but it still seems to work.

== imv ==

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

...
XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
...
(Optional) To use commands in {{Ic|imv}}.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument. If you don't pass in
anything it will default to {{Path|./}}, the current directory.

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}

== KeePassXC ==

{{Note|I only use the bare minimum functionality, so functionality you need is probably missing. If you use functionality not here, your contribution will be most appreciated. To kick things off: {{Ic|Unable to initialize libusb. USB devices may not be detected properly.}} can be silenced with {{Ic|--dev-bind /dev/bus/usb/ /dev/bus/usb/ \}}.}}

{{Cat|~/.local/bin/bwrap-keepassxc|#!/bin/sh

# keepassxc wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
PASSWORD_DATABASE{{=}}"${HOME}/password database"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_PASSWORD_DATABASE{{=}}"${NEW_HOME}${PASSWORD_DATABASE#"$HOME"}"

mkdir -pm 0700 "$PASSWORD_DATABASE"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CONFIG_HOME}/keepassxc/" "${NEW_XDG_CONFIG_HOME}/keepassxc/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind /usr/bin/keepassxc /usr/bin/keepassxc \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/ /usr/share/X11/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/keepassxc/ /usr/share/keepassxc/ \
--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
/usr/bin/keepassxc "$@"}}

PASSWORD_DATABASE="${HOME}/password database"
Directory containing your {{Pkg|keepassxc}} password database.

{{Tip|This is almost certainly not where '''your''' database is located. You will need to change it to where you put your password database.}}

--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
Session type, since we are assuming Wayland only, this will be "wayland".

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
Bind password database.

== mpv ==

{{Cat|~/.local/bin/bwrap-mpv|#!/bin/sh

# mpv wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run mpv wrapped in bwrap.

Usage:
$ bwrap-mpv VIDEO\n'
exit 1
fi

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$1"}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

--player-operation-mode=pseudo-gui \
Because {{Ic|--new-session}} is used, this is needed to have a way to
control {{Ic|mpv}} when it would otherwise not show a GUI.

{{Tip|If you followed [[Bubblewrap#.desktop_integration]], you should remove it from {{Path|"${XDG_DATA_HOME}/applications/bwrap-mpv.desktop"}}.}}

--title='bwrap | ${media-title}' \
Set the window title, showing at a glance that you are using {{Ic|bwrap}}.

=== mpv-net ===

If you want to use {{Ic|mpv}} to stream over the Internet, you will need
a few things more.

{{Tip|You can use both {{Ic|bwrap-mpv}} and {{Ic|bwrap-mpv-net}}. {{Ic|bwrap-mpv}} for local stuff and {{Ic|bwrap-mpv-net}} for watching over the Internet.}}

{{Cat|~/.local/bin/bwrap-mpv-net|#!/bin/sh

# mpv wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv PATH /usr/bin/ \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$@"}}

--setenv PATH /usr/bin/ \
{{Todo|Document why this is needed.}}

--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
Certificate authorities that are ''trusted''.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

"$@"
This is so you can pass more options to {{Ic|bwrap-mpv-net}}, for example:
$ bwrap-mpv-net --video=no --sub=no 'URL1' 'URL2'

=== Pulse audio ===

--ro-bind "${XDG_RUNTIME_DIR}/pulse" "${XDG_RUNTIME_DIR}/pulse" \
Pulse audio.

=== Screenshots ===

The default screenshots directory is {{Path|"$XDG_DESKTOP_DIR"}} (which is
{{Path|"${HOME}/Desktop/"}}, which will fallback to {{Path|"$HOME/"}} if
{{Path|"${HOME}/Desktop/"}} doesn't exist). That means that by default
{{Ic|bwrap-mpv[-net]}} won't allow screenshots unless you change a few things.
Do the following to allow an XDG approved screenshots directory:

...
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/mpv/"
...
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--bind "${XDG_DATA_HOME}/mpv/" "${NEW_XDG_DATA_HOME}/mpv/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
Now make {{Ic|mpv}} use that directory:

{{Cat|"${XDG_CONFIG_HOME}/mpv/mpv.conf"|<nowiki>...
# Something like this, change to match "$XDG_DATA_HOME"
screenshot-template="~/.local/share/mpv/screenshots/%F [%p] %02n"
...</nowiki>}}

== yt-dlp ==

{{Cat|~/.local/bin/bwrap-yt-dlp|#!/bin/sh

# yt-dlp wrapped in bwrap with network access.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

mkdir -pm 0700 "${HOME}/Downloads/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--hostname localhost \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--ro-bind-try "${XDG_CONFIG_HOME}/yt-dlp/config" "${NEW_XDG_CONFIG_HOME}/yt-dlp/config" \
--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/bin/ffmpeg /usr/bin/ffmpeg \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
/usr/bin/yt-dlp "$@"}}

--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Directory for writing the files. This should match {{Ic|--output}} that
is either in {{Path|"${XDG_CONFIG_HOME}/yt-dlp/config"}} or passed on
the command line.

/usr/bin/yt-dlp "$@"
This is so you can pass more options to {{Ic|bwrap-yt-dlp}}, for example:
$ bwrap-yt-dlp --no-playlist 'URL1' 'URL2'

== zathura ==

{{Cat|~/.local/bin/bwrap-zathura|#!/bin/sh

# zathura wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run zathura wrapped in bwrap.

Usage:
$ bwrap-zathura PDF\n'
exit 1
fi

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/zathura/zathurarc" "${XDG_CONFIG_HOME}/zathura/zathurarc" \
--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/zathura /usr/bin/zathura \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/zathura "$1"}}

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"
Have to premake the directory for {{Ic|zathura}} data.

--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
Allow writing of: bookmarks, history, input history.

--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
Used for identifying what type a file should be. Read the
{{Ic|file(1)}} man page for more information.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

[[Category:Security]]

Bubblewrap/Examples

2024-05-21T05:19:22Z

Encode: KeePassXC example

{{Draft|Someone more experienced needs to look over this.}}

{{Todo|Since bubblewrap can make use of [https://en.wikipedia.org/wiki/Seccomp seccomp], restrictive versions should be added. {{Ic|imv}}, {{Ic|mpv}} and {{Ic|zathura}} currently only accept 1 mandatory (except {{Ic|imv}}) argument. This should (hopefully) be temporary, until I figure out how to pass multiple arguments (without including everything else).}}

{{Note|This page assumes you have already read over [[Bubblewrap]]. To try and avoid duplicates, everything will be explained for [[Firefox]] and only when it differs (non obviously) for everything else. Where applicable this also assumes: [[Wayland]] only + [[PipeWire]]. If you use Wayland, make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

{{TOC right}}

== Firefox ==

{{Cat|~/.local/bin/bwrap-firefox|#!/bin/sh

# Firefox wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
--ro-bind /usr/share/icons/ /usr/share/icons/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
/usr/lib/firefox/firefox}}

set -u
If the shell tries to expand an unset parameter, it will error (with a
few exceptions).

XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
Take value if already set, else fallback to the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG] default.

NEW_HOME='/home/user'
User to appear as.

NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
{{Path|"$XDG_CACHE_HOME"}} for the new user.

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"
Make sure the new (real) home for Firefox data exist.

--unshare-all \
Unshare all possible [https://en.wikipedia.org/wiki/Linux_namespaces namespaces].

--share-net \
Retain the network namespace.

--new-session \
New terminal session for the sandbox.

--die-with-parent \
Child process dies when {{Ic|bwrap}} parent dies.

--clearenv \
Unset all environment variables (except for {{Path|"$PWD"}}).

--setenv HOME "$NEW_HOME" \
Pass the path to {{Path|"$NEW_HOME"}} for {{Path|"$HOME"}}.

--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
Specify the Wayland display to run clients on.

--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
User-specific non-essential (cached) data.

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
User-specific non-essential runtime files and other file objects.

--hostname localhost \
Use custom hostname in the sandbox.

--dev /dev/ \
New devtmpfs, access to special or device files.

--ro-bind /etc/fonts/ /etc/fonts/ \
System font configuration directory.

--ro-bind /etc/resolv.conf /etc/resolv.conf \
Needed for DNS resolution.

--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
Per-user Mozilla cache.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${NEW_XDG_CONFIG_HOME}/fontconfig/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) Per-user font configuration directory.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${XDG_CACHE_HOME}/mozilla/" \
--ro-bind-try "${XDG_CONFIG_HOME}/user-dirs.dirs" "${NEW_XDG_CONFIG_HOME}/user-dirs.dirs" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) If you modify "well known" user directories, like
{{Path|~/Downloads/}}, you need this to have Firefox pick it up.

{{Note|If you use {{Path|"${XDG_CONFIG_HOME}/user-dirs.dirs"}} you should also add the corresponding path(s).
For example if you set {{Path|XDG_DOWNLOAD_DIR}} to
{{Path|"${HOME}/downloads/"}} you would also add:
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/downloads/" "${NEW_HOME}/downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
}}

--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
{{Path|"${XDG_DATA_HOME}/firefox/"}} is the location of Firefox data. Shown to Firefox as {{Path|"${NEW_HOME}/.mozilla/"}}.

{{Note|This has the added benefit of getting {{Path|~/.mozilla/}} out of your {{Path|"$HOME"}}, and conforming more to XDG. This may one day not be necessary: [https://bugzilla.mozilla.org/show_bug.cgi?id{{=}}259356 Support for the Freedesktop.org XDG Base Directory Specification (2004-09-14)].}}

...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${NEW_XDG_DATA_HOME}/fonts/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
...
(Optional) Per-user directory scanned for font files.

--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Default {{Path|~/Downloads/}} directory.

--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
Shared libraries.

--proc /proc/ \
New procfs, provides information about running processes and the kernel.

--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
Bind the Wayland socket file.

--ro-bind /usr/lib/ /usr/lib/ \
Object files and libraries.

{{Note|It is not worth the time to limit this, the churn is too great.}}

--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
XKB is a keyboard keymap support library.

{{Note|Even tho the path has {{Path|*/X11/*}} Wayland uses it too.}}

--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
Font presets.

--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
Global directory scanned for font files.

--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
Needed for "Save Page As…", "Export|Import Bookmarks File", among others.

--ro-bind /usr/share/icons/ /usr/share/icons/ \
Global icons directory.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
International Components for Unicode (ICU) provides support for Unicode
and globalization.

...
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/libdrm/ /usr/share/libdrm/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
...
(Optional) Direct Rendering Manager (DRM), Linux kernel subsystem for
interfacing with GPUs of video cards. Programs can use this to have the
GPU do hardware-accelerated 3D rendering and video decoding.

--ro-bind /usr/share/mime/ /usr/share/mime/ \
Global XDG MIME directory.

/usr/lib/firefox/firefox
Call Firefox.

{{Tip|If you use multiple profiles you can have:
/usr/lib/firefox/firefox -P "$@"
this will allow you to pass a profile name and go into that specific one or not pass anything and get prompted for which to choose.}}

=== PipeWire audio ===

{{Todo|}}

=== Pulse audio ===

...
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/pulse/" "${XDG_RUNTIME_DIR}/pulse/" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
(Optional) Pulse audio.

=== Optional(?) stuff ===

{{Draft|Are these needed?}}

...
--proc /proc/ \
--ro-bind /sys/bus/pci/ /sys/bus/pci/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Information about PCI bus type.

Without this you get
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: cannot access /sys/bus/pci (t=0.177033) [GFX1-]: glxtest: cannot access /sys/bus/pci
but it still seems to work.

...
--proc /proc/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Contains a filesystem representation of the kernel device tree.

With {{Ic|--ro-bind /sys/bus/pci/ /sys/bus/pci/ \}} but without this you get:
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) [GFX1-]: glxtest: ManageChildProcess failed

Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) |[1][GFX1-]: No GPUs detected via PCI
(t=0.18958) [GFX1-]: No GPUs detected via PCI
but it still seems to work.

== imv ==

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

...
XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
...
(Optional) To use commands in {{Ic|imv}}.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument. If you don't pass in
anything it will default to {{Path|./}}, the current directory.

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}

== KeePassXC ==

{{Note|I only use the bare minimum functionality, so functionality you need is probably missing. If you use functionality not here, your contribution will be most appreciated. To kick things off: {{Ic|Unable to initialize libusb. USB devices may not be detected properly.}} can be silenced with {{Ic|--dev-bind /dev/bus/usb/ /dev/bus/usb/ \}}.}}

{{Cat|~/.local/bin/bwrap-keepassxc|#!/bin/sh

# keepassxc wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
PASSWORD_DATABASE{{=}}"${HOME}/password database"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_PASSWORD_DATABASE{{=}}"${NEW_HOME}${PASSWORD_DATABASE#"$HOME"}"

mkdir -pm 0700 "$PASSWORD_DATABASE"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CONFIG_HOME}/keepassxc/" "${NEW_XDG_CONFIG_HOME}/keepassxc/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind /usr/bin/keepassxc /usr/bin/keepassxc \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/ /usr/share/X11/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/keepassxc/ /usr/share/keepassxc/ \
--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
/usr/bin/keepassxc "$@"}}

PASSWORD_DATABASE="${HOME}/password database"
Directory containing your {{Pkg|keepassxc}} password database.

{{Tip|This is almost certainly not where '''your''' database is located. You will need to change it to where you put your password database.}}

--setenv XDG_SESSION_TYPE "$XDG_SESSION_TYPE" \
Session type, since we are assuming Wayland only, this will be "wayland".

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--bind "$PASSWORD_DATABASE/" "$NEW_PASSWORD_DATABASE/" \
Bind password database.

== mpv ==

{{Cat|~/.local/bin/bwrap-mpv|#!/bin/sh

# mpv wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run mpv wrapped in bwrap.

Usage:
$ bwrap-mpv VIDEO\n'
exit 1
fi

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$1"}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

--player-operation-mode=pseudo-gui \
Because {{Ic|--new-session}} is used, this is needed to have a way to
control {{Ic|mpv}} when it would otherwise not show a GUI.

{{Tip|If you followed [[Bubblewrap#.desktop_integration]], you should remove it from {{Path|"${XDG_DATA_HOME}/applications/bwrap-mpv.desktop"}}.}}

--title='bwrap | ${media-title}' \
Set the window title, showing at a glance that you are using {{Ic|bwrap}}.

=== mpv-net ===

If you want to use {{Ic|mpv}} to stream over the Internet, you will need
a few things more.

{{Tip|You can use both {{Ic|bwrap-mpv}} and {{Ic|bwrap-mpv-net}}. {{Ic|bwrap-mpv}} for local stuff and {{Ic|bwrap-mpv-net}} for watching over the Internet.}}

{{Cat|~/.local/bin/bwrap-mpv-net|#!/bin/sh

# mpv wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv PATH /usr/bin/ \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$@"}}

--setenv PATH /usr/bin/ \
{{Todo|Document why this is needed.}}

--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
Certificate authorities that are ''trusted''.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

"$@"
This is so you can pass more options to {{Ic|bwrap-mpv-net}}, for example:
$ bwrap-mpv-net --video=no --sub=no 'URL1' 'URL2'

=== Pulse audio ===

--ro-bind "${XDG_RUNTIME_DIR}/pulse" "${XDG_RUNTIME_DIR}/pulse" \
Pulse audio.

=== Screenshots ===

The default screenshots directory is {{Path|"$XDG_DESKTOP_DIR"}} (which is
{{Path|"${HOME}/Desktop/"}}, which will fallback to {{Path|"$HOME/"}} if
{{Path|"${HOME}/Desktop/"}} doesn't exist). That means that by default
{{Ic|bwrap-mpv[-net]}} won't allow screenshots unless you change a few things.
Do the following to allow an XDG approved screenshots directory:

...
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/mpv/"
...
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--bind "${XDG_DATA_HOME}/mpv/" "${NEW_XDG_DATA_HOME}/mpv/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
Now make {{Ic|mpv}} use that directory:

{{Cat|"${XDG_CONFIG_HOME}/mpv/mpv.conf"|<nowiki>...
# Something like this, change to match "$XDG_DATA_HOME"
screenshot-template="~/.local/share/mpv/screenshots/%F [%p] %02n"
...</nowiki>}}

== yt-dlp ==

{{Cat|~/.local/bin/bwrap-yt-dlp|#!/bin/sh

# yt-dlp wrapped in bwrap with network access.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

mkdir -pm 0700 "${HOME}/Downloads/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--hostname localhost \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--ro-bind-try "${XDG_CONFIG_HOME}/yt-dlp/config" "${NEW_XDG_CONFIG_HOME}/yt-dlp/config" \
--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/bin/ffmpeg /usr/bin/ffmpeg \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
/usr/bin/yt-dlp "$@"}}

--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Directory for writing the files. This should match {{Ic|--output}} that
is either in {{Path|"${XDG_CONFIG_HOME}/yt-dlp/config"}} or passed on
the command line.

/usr/bin/yt-dlp "$@"
This is so you can pass more options to {{Ic|bwrap-yt-dlp}}, for example:
$ bwrap-yt-dlp --no-playlist 'URL1' 'URL2'

== zathura ==

{{Cat|~/.local/bin/bwrap-zathura|#!/bin/sh

# zathura wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run zathura wrapped in bwrap.

Usage:
$ bwrap-zathura PDF\n'
exit 1
fi

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/zathura/zathurarc" "${XDG_CONFIG_HOME}/zathura/zathurarc" \
--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/zathura /usr/bin/zathura \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/zathura "$1"}}

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"
Have to premake the directory for {{Ic|zathura}} data.

--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
Allow writing of: bookmarks, history, input history.

--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
Used for identifying what type a file should be. Read the
{{Ic|file(1)}} man page for more information.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

[[Category:Security]]

Bubblewrap/Examples

2024-05-20T23:02:53Z

Encode: env isn't necessary

{{Draft|Someone more experienced needs to look over this.}}

{{Todo|Since bubblewrap can make use of [https://en.wikipedia.org/wiki/Seccomp seccomp], restrictive versions should be added. {{Ic|imv}}, {{Ic|mpv}} and {{Ic|zathura}} currently only accept 1 mandatory (except {{Ic|imv}}) argument. This should (hopefully) be temporary, until I figure out how to pass multiple arguments (without including everything else).}}

{{Note|This page assumes you have already read over [[Bubblewrap]]. To try and avoid duplicates, everything will be explained for [[Firefox]] and only when it differs (non obviously) for everything else. Where applicable this also assumes: [[Wayland]] only + [[PipeWire]]. If you use Wayland, make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

{{TOC right}}

== Firefox ==

{{Cat|~/.local/bin/bwrap-firefox|#!/bin/sh

# Firefox wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
--ro-bind /usr/share/icons/ /usr/share/icons/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
/usr/lib/firefox/firefox}}

set -u
If the shell tries to expand an unset parameter, it will error (with a
few exceptions).

XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
Take value if already set, else fallback to the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG] default.

NEW_HOME='/home/user'
User to appear as.

NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
{{Path|"$XDG_CACHE_HOME"}} for the new user.

mkdir -pm 0700 "${XDG_DATA_HOME}/firefox/"
Make sure the new (real) home for Firefox data exist.

--unshare-all \
Unshare all possible [https://en.wikipedia.org/wiki/Linux_namespaces namespaces].

--share-net \
Retain the network namespace.

--new-session \
New terminal session for the sandbox.

--die-with-parent \
Child process dies when {{Ic|bwrap}} parent dies.

--clearenv \
Unset all environment variables (except for {{Path|"$PWD"}}).

--setenv HOME "$NEW_HOME" \
Pass the path to {{Path|"$NEW_HOME"}} for {{Path|"$HOME"}}.

--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
Specify the Wayland display to run clients on.

--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
User-specific non-essential (cached) data.

--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
User-specific non-essential runtime files and other file objects.

--hostname localhost \
Use custom hostname in the sandbox.

--dev /dev/ \
New devtmpfs, access to special or device files.

--ro-bind /etc/fonts/ /etc/fonts/ \
System font configuration directory.

--ro-bind /etc/resolv.conf /etc/resolv.conf \
Needed for DNS resolution.

--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
Per-user Mozilla cache.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${NEW_XDG_CACHE_HOME}/mozilla/" \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${NEW_XDG_CONFIG_HOME}/fontconfig/" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) Per-user font configuration directory.

...
XDG_CACHE_HOME="${XDG_CACHE_HOME:=$HOME/.cache}"
XDG_CONFIG_HOME "${XDG_CONFIG_HOME:=$HOME/.config}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind-try "${XDG_CACHE_HOME}/mozilla/" "${XDG_CACHE_HOME}/mozilla/" \
--ro-bind-try "${XDG_CONFIG_HOME}/user-dirs.dirs" "${NEW_XDG_CONFIG_HOME}/user-dirs.dirs" \
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
...
(Optional) If you modify "well known" user directories, like
{{Path|~/Downloads/}}, you need this to have Firefox pick it up.

{{Note|If you use {{Path|"${XDG_CONFIG_HOME}/user-dirs.dirs"}} you should also add the corresponding path(s).
For example if you set {{Path|XDG_DOWNLOAD_DIR}} to
{{Path|"${HOME}/downloads/"}} you would also add:
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--bind-try "${HOME}/downloads/" "${NEW_HOME}/downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
}}

--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
{{Path|"${XDG_DATA_HOME}/firefox/"}} is the location of Firefox data. Shown to Firefox as {{Path|"${NEW_HOME}/.mozilla/"}}.

{{Note|This has the added benefit of getting {{Path|~/.mozilla/}} out of your {{Path|"$HOME"}}, and conforming more to XDG. This may one day not be necessary: [https://bugzilla.mozilla.org/show_bug.cgi?id{{=}}259356 Support for the Freedesktop.org XDG Base Directory Specification (2004-09-14)].}}

...
NEW_XDG_CACHE_HOME="${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--bind "${XDG_DATA_HOME}/firefox/" "${NEW_HOME}/.mozilla/" \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${NEW_XDG_DATA_HOME}/fonts/" \
--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
...
(Optional) Per-user directory scanned for font files.

--bind-try "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Default {{Path|~/Downloads/}} directory.

--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
Shared libraries.

--proc /proc/ \
New procfs, provides information about running processes and the kernel.

--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
Bind the Wayland socket file.

--ro-bind /usr/lib/ /usr/lib/ \
Object files and libraries.

{{Note|It is not worth the time to limit this, the churn is too great.}}

--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
XKB is a keyboard keymap support library.

{{Note|Even tho the path has {{Path|*/X11/*}} Wayland uses it too.}}

--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
Font presets.

--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
Global directory scanned for font files.

--ro-bind /usr/share/glib-2.0/ /usr/share/glib-2.0/ \
Needed for "Save Page As…", "Export|Import Bookmarks File", among others.

--ro-bind /usr/share/icons/ /usr/share/icons/ \
Global icons directory.

--ro-bind /usr/share/icu/ /usr/share/icu/ \
International Components for Unicode (ICU) provides support for Unicode
and globalization.

...
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind /usr/share/libdrm/ /usr/share/libdrm/ \
--ro-bind /usr/share/mime/ /usr/share/mime/ \
...
(Optional) Direct Rendering Manager (DRM), Linux kernel subsystem for
interfacing with GPUs of video cards. Programs can use this to have the
GPU do hardware-accelerated 3D rendering and video decoding.

--ro-bind /usr/share/mime/ /usr/share/mime/ \
Global XDG MIME directory.

/usr/lib/firefox/firefox
Call Firefox.

{{Tip|If you use multiple profiles you can have:
/usr/lib/firefox/firefox -P "$@"
this will allow you to pass a profile name and go into that specific one or not pass anything and get prompted for which to choose.}}

=== PipeWire audio ===

{{Todo|}}

=== Pulse audio ===

...
--proc /proc/ \
--ro-bind "${XDG_RUNTIME_DIR}/pulse/" "${XDG_RUNTIME_DIR}/pulse/" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
(Optional) Pulse audio.

=== Optional(?) stuff ===

{{Draft|Are these needed?}}

...
--proc /proc/ \
--ro-bind /sys/bus/pci/ /sys/bus/pci/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Information about PCI bus type.

Without this you get
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: cannot access /sys/bus/pci (t=0.177033) [GFX1-]: glxtest: cannot access /sys/bus/pci
but it still seems to work.

...
--proc /proc/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
...
Contains a filesystem representation of the kernel device tree.

With {{Ic|--ro-bind /sys/bus/pci/ /sys/bus/pci/ \}} but without this you get:
Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) [GFX1-]: glxtest: ManageChildProcess failed

Crash Annotation GraphicsCriticalError: |[0][GFX1-]: glxtest: ManageChildProcess failed
(t=0.189558) |[1][GFX1-]: No GPUs detected via PCI
(t=0.18958) [GFX1-]: No GPUs detected via PCI
but it still seems to work.

== imv ==

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /bin/sh /bin/sh \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
/usr/libexec/imv-wayland "${1:-./}"}}

--ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

...
XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"
...
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \
--ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
--ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/icu/ /usr/share/icu/ \
--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
...
(Optional) To use commands in {{Ic|imv}}.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument. If you don't pass in
anything it will default to {{Path|./}}, the current directory.

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}

== mpv ==

{{Cat|~/.local/bin/bwrap-mpv|#!/bin/sh

# mpv wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run mpv wrapped in bwrap.

Usage:
$ bwrap-mpv VIDEO\n'
exit 1
fi

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$1"}}

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

--player-operation-mode=pseudo-gui \
Because {{Ic|--new-session}} is used, this is needed to have a way to
control {{Ic|mpv}} when it would otherwise not show a GUI.

{{Tip|If you followed [[Bubblewrap#.desktop_integration]], you should remove it from {{Path|"${XDG_DATA_HOME}/applications/bwrap-mpv.desktop"}}.}}

--title='bwrap | ${media-title}' \
Set the window title, showing at a glance that you are using {{Ic|bwrap}}.

=== mpv-net ===

If you want to use {{Ic|mpv}} to stream over the Internet, you will need
a few things more.

{{Tip|You can use both {{Ic|bwrap-mpv}} and {{Ic|bwrap-mpv-net}}. {{Ic|bwrap-mpv}} for local stuff and {{Ic|bwrap-mpv-net}} for watching over the Internet.}}

{{Cat|~/.local/bin/bwrap-mpv-net|#!/bin/sh

# mpv wrapped in bwrap with network access.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:{{=}}$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CACHE_HOME{{=}}"${NEW_HOME}${XDG_CACHE_HOME#"$HOME"}"
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv PATH /usr/bin/ \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CACHE_HOME "$NEW_XDG_CACHE_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--hostname localhost \
--dev /dev/ \
--dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind /etc/mpv/ /etc/mpv/ \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--bind-try "${XDG_CACHE_HOME}/mesa_shader_cache/" "${NEW_XDG_CACHE_HOME}/mesa_shader_cache/" \
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libacl.so.1 /lib/libacl.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--proc /proc/ \
--ro-bind /sys/dev/char/ /sys/dev/char/ \
--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
--ro-bind "${XDG_RUNTIME_DIR}/pipewire-0" "${XDG_RUNTIME_DIR}/pipewire-0" \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/mpv /usr/bin/mpv \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fontconfig/ /usr/share/fontconfig/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/pipewire/ /usr/share/pipewire/ \
/usr/bin/mpv \
--player-operation-mode{{=}}pseudo-gui \
--title{{=}}'bwrap {{!}} ${media-title}' \
"$@"}}

--setenv PATH /usr/bin/ \
{{Todo|Document why this is needed.}}

--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
Certificate authorities that are ''trusted''.

--ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

--ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

"$@"
This is so you can pass more options to {{Ic|bwrap-mpv-net}}, for example:
$ bwrap-mpv-net --video=no --sub=no 'URL1' 'URL2'

=== Pulse audio ===

--ro-bind "${XDG_RUNTIME_DIR}/pulse" "${XDG_RUNTIME_DIR}/pulse" \
Pulse audio.

=== Screenshots ===

The default screenshots directory is {{Path|"$XDG_DESKTOP_DIR"}} (which is
{{Path|"${HOME}/Desktop/"}}, which will fallback to {{Path|"$HOME/"}} if
{{Path|"${HOME}/Desktop/"}} doesn't exist). That means that by default
{{Ic|bwrap-mpv[-net]}} won't allow screenshots unless you change a few things.
Do the following to allow an XDG approved screenshots directory:

...
XDG_CONFIG_HOME="${XDG_CONFIG_HOME:=$HOME/.config}"
XDG_DATA_HOME="${XDG_DATA_HOME:=$HOME/.local/share}"
...
NEW_XDG_CONFIG_HOME="${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"
NEW_XDG_DATA_HOME="${NEW_HOME}${XDG_DATA_HOME#"$HOME"}"

mkdir -pm 0700 "${XDG_DATA_HOME}/mpv/"
...
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$NEW_XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
...
--ro-bind-try "${XDG_CONFIG_HOME}/mpv/mpv.conf" "${NEW_XDG_CONFIG_HOME}/mpv/mpv.conf" \
--bind "${XDG_DATA_HOME}/mpv/" "${NEW_XDG_DATA_HOME}/mpv/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
...
Now make {{Ic|mpv}} use that directory:

{{Cat|"${XDG_CONFIG_HOME}/mpv/mpv.conf"|<nowiki>...
# Something like this, change to match "$XDG_DATA_HOME"
screenshot-template="~/.local/share/mpv/screenshots/%F [%p] %02n"
...</nowiki>}}

== yt-dlp ==

{{Cat|~/.local/bin/bwrap-yt-dlp|#!/bin/sh

# yt-dlp wrapped in bwrap with network access.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"

NEW_HOME{{=}}'/home/user'
NEW_XDG_CONFIG_HOME{{=}}"${NEW_HOME}${XDG_CONFIG_HOME#"$HOME"}"

mkdir -pm 0700 "${HOME}/Downloads/"

/usr/bin/bwrap \
--unshare-all \
--share-net \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$NEW_HOME" \
--setenv XDG_CONFIG_HOME "$NEW_XDG_CONFIG_HOME" \
--hostname localhost \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/ssl/certs/ /etc/ssl/certs/ \
--ro-bind-try "${XDG_CONFIG_HOME}/yt-dlp/config" "${NEW_XDG_CONFIG_HOME}/yt-dlp/config" \
--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libcrypto.so.3 /lib/libcrypto.so.3 \
--ro-bind /lib/libssl.so.3 /lib/libssl.so.3 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind /usr/bin/ffmpeg /usr/bin/ffmpeg \
--ro-bind /usr/bin/python3 /usr/bin/python3 \
--ro-bind /usr/bin/yt-dlp /usr/bin/yt-dlp \
--ro-bind /usr/lib/ /usr/lib/ \
/usr/bin/yt-dlp "$@"}}

--bind "${HOME}/Downloads/" "${NEW_HOME}/Downloads/" \
Directory for writing the files. This should match {{Ic|--output}} that
is either in {{Path|"${XDG_CONFIG_HOME}/yt-dlp/config"}} or passed on
the command line.

/usr/bin/yt-dlp "$@"
This is so you can pass more options to {{Ic|bwrap-yt-dlp}}, for example:
$ bwrap-yt-dlp --no-playlist 'URL1' 'URL2'

== zathura ==

{{Cat|~/.local/bin/bwrap-zathura|#!/bin/sh

# zathura wrapped in bwrap.

set -u

if [ "$#" !{{=}} 1 ]
then
printf 'Run zathura wrapped in bwrap.

Usage:
$ bwrap-zathura PDF\n'
exit 1
fi

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:{{=}}$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:{{=}}$HOME/.local/share}"

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"

/usr/bin/bwrap \
--unshare-all \
--new-session \
--die-with-parent \
--clearenv \
--setenv HOME "$HOME" \
--setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
--setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
--setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
--setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
--ro-bind /etc/fonts/ /etc/fonts/ \
--ro-bind-try "${XDG_CONFIG_HOME}/zathura/zathurarc" "${XDG_CONFIG_HOME}/zathura/zathurarc" \
--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
--ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
--ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
--ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
--ro-bind /lib/libz.so.1 /lib/libz.so.1 \
--ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
--ro-bind /usr/bin/zathura /usr/bin/zathura \
--ro-bind /usr/lib/ /usr/lib/ \
--ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
--ro-bind /usr/share/fonts/ /usr/share/fonts/ \
--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
--ro-bind "$1" "$(realpath "$1")" \
/usr/bin/zathura "$1"}}

mkdir -pm 0700 "${XDG_DATA_HOME}/zathura/"
Have to premake the directory for {{Ic|zathura}} data.

--bind "${XDG_DATA_HOME}/zathura/" "${XDG_DATA_HOME}/zathura/" \
Allow writing of: bookmarks, history, input history.

--ro-bind /usr/share/misc/magic.mgc /usr/share/misc/magic.mgc \
Used for identifying what type a file should be. Read the
{{Ic|file(1)}} man page for more information.

--ro-bind "$1" "$(realpath "$1")" \
Get the absolute pathname using {{Ic|realpath}}, so you can pass a
relative argument and still bind the argument.

[[Category:Security]]