Alpine Linux - User contributions [en]

Proton VPN

2024-05-13T02:43:44Z

Quill: Added a troubleshooting with solution for error

Proton VPN is an open-source VPN service by the non-profit Swiss company Proton AG. It utilizes the OpenVPN protocol. Because Alpine Linux does not currently have a release for Proton VPN, using it requires connecting via either OpenVPN or Wireguard. Using Wireguard is recommended due to Proton AG's own stated preference for the service as well as Wireguard's lighter and more modern build. Setting up for Wireguard is relatively simpler because NetworkManager has native support for it, requiring fewer installations and setups.

 

== Installation ==

{{Cmd|# apk add {{Pkg|wireguard-tools}}}}

 

== Configuring ==

Login to Proton VPN and download the Wireguard config file. More information on this can be found at [https://protonvpn.com/support/wireguard-configurations/ Proton VPN's support page]. Note that the private key will only be available from the site if you download immediately after making the config file, after which the private key is replaced with asterisks. Rename the file "wg0.conf" and move it somewhere safe in your file system.

 

== Running ==

To connect, run the following command. Substitute path_to_file with the full path to wherever you moved the config file.

{{Cmd|# wg-quick up /path_to_file/wg0.conf}}

 

To enable Wireguard connecting to Proton VPN on boot, open your /etc/network/interfaces using a text editor like nano. Add this information after your other interface sections:

<pre>
auto wg0
iface wg0 inet static
pre-up wg-quick up /path_to_file/wg0.conf
</pre>

 

Again, substitute path_to_file with your own relevant information.

== Troubleshooting ==

If trying to turn the VPN on fails and you see the following error:
<pre>
/usr/bin/wg-quick: line 32: iptables-restore: command not found
</pre>
You need to manually install iptables (apk add iptables) so wg-quick can use the command 'iptables-restore'

[[Category:VPN]]

Steam

2024-02-29T21:41:56Z

Quill: /* Steam hangs on start with a steamwebhelper popup */

[https://store.steampowered.com/about/ Steam] is a popular game distribution platform by Valve.

{{Note|Steam for Linux only supports Ubuntu LTS. Thus, do not turn to Valve for support for issues with Steam on Alpine Linux.}}

== Installation ==

Steam requires glibc to run, and thus doesn't straight up run on Alpine Linux.
To work around this problem, we'll use [https://wiki.alpinelinux.org/wiki/Flatpak Flatpak].
Make sure you have the Flathub repository installed.

{{Note| commands prefixed with # are run as root, commands prefixed with $ are run as a regular user}}

# apk add {{pkg|flatpak|arch=x86_64}}
$ flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
$ flatpak --user install com.valvesoftware.Steam

After installation Steam can be started using it's .desktop file or on the command line:

$ flatpak run com.valvesoftware.Steam

== Troubleshooting ==

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

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

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

=== SteamVR won't launch ===

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

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

Then restart Steam.

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

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

Add the Mesa gallium driver and reboot your system.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sway: go into your sway config file and add DISPLAY to the following line, then restart:
<pre>exec dbus-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway</pre>
For more information about this line, please see the Alpine Wiki's entry on Sway

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

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

Steam

2024-02-29T21:41:44Z

Quill: Added a troubleshoot for Steam to address the steamwebhelper hang

[https://store.steampowered.com/about/ Steam] is a popular game distribution platform by Valve.

{{Note|Steam for Linux only supports Ubuntu LTS. Thus, do not turn to Valve for support for issues with Steam on Alpine Linux.}}

== Installation ==

Steam requires glibc to run, and thus doesn't straight up run on Alpine Linux.
To work around this problem, we'll use [https://wiki.alpinelinux.org/wiki/Flatpak Flatpak].
Make sure you have the Flathub repository installed.

{{Note| commands prefixed with # are run as root, commands prefixed with $ are run as a regular user}}

# apk add {{pkg|flatpak|arch=x86_64}}
$ flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
$ flatpak --user install com.valvesoftware.Steam

After installation Steam can be started using it's .desktop file or on the command line:

$ flatpak run com.valvesoftware.Steam

== Troubleshooting ==

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

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

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

=== SteamVR won't launch ===

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

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

Then restart Steam.

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

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

Add the Mesa gallium driver and reboot your system.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sway: go into your sway config file and add DISPLAY to the following line, then restart:
<pre>exec dbus-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway</pre>
For more information about this line, please see the Alpine Wiki's entry on Sway

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

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

Flatpak

2024-02-26T22:19:21Z

Quill: Added a flatpak troubleshooting for an error

Flatpak is a technology for building and distributing applications with the goal of having a universal package format for all Linux distributions, it is similar to [https://en.wikipedia.org/wiki/Snap_(software) Snap],

== Setup / Installation ==

=== Runtime dependencies ===

* {{Pkg|dbus}}
* {{Pkg|polkit}}
* {{Pkg|xdg-desktop-portal}}
* an implementation of <code>xdg-desktop-portal</code>, e.g. {{Pkg|xdg-desktop-portal-gtk}}

{{Note|If you are running a window manager from {{Path|.xinitrc}}, make sure you are running a <code>dbus</code> session explicitly, i.e.:

{{Cmd|# exec dbus-launch --exit-with-session your_favourite_wm}}}}

=== Installing Flatpak Itself ===

''From: https://flatpak.org/setup/Alpine/''

{{Note|To install Flatpak you will need to enable the Community repository, See: [[Repositories#Managing_repositories|Repositories - Managing repositories]]}}

To install Flatpak run:

{{cmd|# apk add {{Pkg|flatpak}}}}

Next you need to add a repository, for this guide we will use the recommended repository, [https://flathub.org Flathub].

{{cmd|$ flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo}}

Flatpak is now ready to use immediately, however flatpak desktop entries will not appear until you restart your desktop session (i.e. by logging out and then logging back in)

== Usage ==

To get all of the available options to use with the '''flatpak''' command run: '''flatpak --help''' or '''flatpak -h''',

=== Search ===

To search for applications run '''flatpak --user search <appplicationname>'''

Example:

~'''$''' flatpak --user search chromium

Name Description Application ID Version Branch Remotes
Chromium Web Browser The web browser from Chromium project org.chromium.Chromium 96.0.4664.93 stable flathub
Chromium B.S.U. Fast paced, arcade-style, top-scrolling space shooter net.sourceforge.chromium-bsu 0.9.16.1 stable flathub
ungoogled-chromium A lightweight approach to removing Google web service dependency com.github.Eloston.UngoogledChromium 96.0.4664.45 stable flathub


 

=== Install ===

To install a package run '''flatpak --user install <applicationname>'''

~'''$''' flatpak --user install com.github.Eloston.UngoogledChromium

Looking for matches…

com.github.Eloston.UngoogledChromium permissions:
ipc network cups pulseaudio wayland x11
devices file access [1] dbus access [2] bus ownership [3] system dbus access [4]

[1] /run/.heim_org.h5l.kcm-socket, home, xdg-run/pipewire-0
[2] org.freedesktop.FileManager1, org.freedesktop.Notifications, org.freedesktop.secrets, org.gnome.SessionManager
[3] org.mpris.MediaPlayer2.chromium.*
[4] org.freedesktop.Avahi, org.freedesktop.UPower

ID Branch Op Remote Download
1. com.github.Eloston.UngoogledChromium.Codecs stable i flathub < 1.1 MB
2. com.github.Eloston.UngoogledChromium.Locale stable i flathub < 112.8 kB
3. com.github.Eloston.UngoogledChromium stable i flathub < 119.0 MB

Proceed with these changes to the system installation? [Y/n]:


or if you don't know or don't want to type the exact package name:

~'''$''' flatpak --user install chromium

Looking for matches…
Similar refs found for ‘chromium’ in remote ‘flathub’ (system):

1) app/net.sourceforge.chromium-bsu/x86_64/stable
2) runtime/com.github.Eloston.UngoogledChromium.Codecs/x86_64/stable
3) runtime/org.chromium.Chromium.Codecs/x86_64/stable
4) app/org.chromium.Chromium/x86_64/stable
5) app/com.github.Eloston.UngoogledChromium/x86_64/stable

Which do you want to use (0 to abort)? [0-5]:


=== Remove ===

To remove a package run: '''flatpak --user remove <applicationname>'''

~'''$''' flatpak --user remove com.github.Eloston.UngoogledChromium

ID Branch Op
1. com.github.Eloston.UngoogledChromium stable r
2. com.github.Eloston.UngoogledChromium.Codecs stable r
3. com.github.Eloston.UngoogledChromium.Locale stable r

Proceed with these changes to the system installation? [Y/n]:


or if you don't know or don't want to type the exact package name:

~'''$''' flatpak --user remove chromium

Similar installed refs found for ‘chromium’:

1) app/com.github.Eloston.UngoogledChromium/x86_64/stable (system)
2) runtime/com.github.Eloston.UngoogledChromium.Codecs/x86_64/stable (system)
3) All of the above

Which do you want to use (0 to abort)? [0-3]:


== Developers ==

* [https://docs.flatpak.org/en/latest/available-runtimes.html Flatpak - available runtimes]

These are all hosted on [https://flathub.org/ Flathub.org].

== Troubleshooting ==
{{Draft|More documentation and testing is needed, but everything currently here should be safe to follow.}}

=== Permission errors ===

If you receive errors about permissions then you may need to add your user to the '''flatpak''' group.

{{Note|You need to log out and log back in or reboot for the group change(s) to take effect}}

=== Fixing audio issues ===

If you have a minimal setup and don't have access to audio devices you will need to set the XDG_RUNTIME_DIR variable. Save the following script in {{Path|/etc/profile.d/xdg_runtime_dir.sh}} and re-login to have it set up properly.

if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)
fi

When you launch a Flatpak you will need to start pulseaudio as well:

{{Cmd|$ pulseaudio --start && flatpak run com.example.Example}}

=== Unable to upload files ===

If you are unable to upload files from the host, this maybe due to [https://docs.flatpak.org/en/latest/sandbox-permissions.html Flatpak sandbox] and you may have to manually add the authorization.

This can be done with the following commands:

{{Cmd|<nowiki>$ flatpak override ApplicationID --filesystem=/home/user/Downloads</nowiki>}}

Where ''ApplicationID'' is given by:

{{Cmd|$ flatpak list}}

For example:

{{Cmd|<nowiki>$ flatpak override org.signal.Signal --filesystem=/home/user/Downloads</nowiki>}}

=== Error while opening repository ===

There is a current issue where sometimes flatpak will try to read the system-wide repository even if your install is with --user. This will result in failure to launch a flatpak application with the terminal reading ""error: While opening repository /var/lib/flatpak/repo: opening repo: opendir(/var/lib/flatpak/repo): No such file or directory". An alpine user has posted more information, as well as a workaround, at https://github.com/flatpak/flatpak/issues/5488

== Links ==
* [https://flatpak.org/ Flatpak]
* [https://flathub.org/ Flathub]
* [https://winepak.github.io/ Winepak]

[[Category:Package Manager]]
[[Category: Desktop]]

Tmux

2023-04-08T15:20:39Z

Quill: removed the troubleshooting section I added as I have found gpm introduces more issues regarding compatibility with tmux within tty and do not want to lead users astray

{{pkg|tmux}} is a terminal multiplexer. It's a good tool for e.g. remote support. It can also be used to start a command you want to keep running after you close your console session (you can later on attach to your running session).

= Install =
In order to use {{pkg|tmux}} you will have to install it:
{{cmd|apk add tmux}}

= Usage =

== Start a new session ==
To create a {{pkg|tmux}} session you just enter:
{{cmd|tmux}}

== List existing sessions ==
When you have started some session(s) you can list them:
{{cmd|tmux ls}}
{{tip|Above command can also be run as <code>tmux list-sessions</code>}}
You might get a list that looks like this:
<pre>
0: 1 windows (created Wed Oct 24 15:12:12 2012) [126x35]
1: 1 windows (created Wed Oct 24 15:14:44 2012) [126x35]
</pre>

== Attach to a existing session ==
Lets say you want to attach to a existing session (e.g. the above <code>1: 1 windows</code> session).
{{cmd|tmux attach -t 1}}
{{tip|If you only have one session you don't need to specify session. Just run <code>tmux attach</code>}}

== Controlling a session ==
While inside a {{pkg|tmux}} session, you can control it using keyboard shortcuts. We will only describe some of those alternatives.

{{tip|To enter a keyboard shortcut that controls the current {{pkg|tmux}} session, you should click {{key|B}} while holding down {{key|CTRL}} In the below examples this procedure is described as <code>C-b</code>}}
=== Get help ===
One of the most useful commands is the one that gives you 'help'. 
While in your {{pkg|tmux}} session, click:
{{cmd|C-b ?}}
''(Do not press/hold {{key|CTRL}} when clicking {{key|?}})''

=== Detach from a session ===
Sometimes it's useful to just detach from a session without killing it. 
{{cmd|C-b d}}
{{tip|Try starting <code>ping 127.0.0.1</code> while inside a session and then detach from the session. After some while re-connect to the session using <code>tmux attach</code>. Note that the "seq" value indicates that ping had continued running while you where detached from the session.}}

=== Close or kill a session ===
To 'kill' a session:
{{cmd|C-b &}}
Confirm by clicking {{key|y}} when prompted.

You can also 'kill' your session by entering:
{{cmd|exit}}

= Other terminal multiplexers =
A similar tool is {{pkg|screen}} which is documented [[Screen_on_console|here]].

[[Category:Shell]]

Tmux

2023-04-08T14:27:13Z

Quill: Added a troubleshooting section that included information on extra steps I had to take for mouse support in a TTY -Quillith

{{pkg|tmux}} is a terminal multiplexer. It's a good tool for e.g. remote support. It can also be used to start a command you want to keep running after you close your console session (you can later on attach to your running session).

= Install =
In order to use {{pkg|tmux}} you will have to install it:
{{cmd|apk add tmux}}

= Usage =

== Start a new session ==
To create a {{pkg|tmux}} session you just enter:
{{cmd|tmux}}

== List existing sessions ==
When you have started some session(s) you can list them:
{{cmd|tmux ls}}
{{tip|Above command can also be run as <code>tmux list-sessions</code>}}
You might get a list that looks like this:
<pre>
0: 1 windows (created Wed Oct 24 15:12:12 2012) [126x35]
1: 1 windows (created Wed Oct 24 15:14:44 2012) [126x35]
</pre>

== Attach to a existing session ==
Lets say you want to attach to a existing session (e.g. the above <code>1: 1 windows</code> session).
{{cmd|tmux attach -t 1}}
{{tip|If you only have one session you don't need to specify session. Just run <code>tmux attach</code>}}

== Controlling a session ==
While inside a {{pkg|tmux}} session, you can control it using keyboard shortcuts. We will only describe some of those alternatives.

{{tip|To enter a keyboard shortcut that controls the current {{pkg|tmux}} session, you should click {{key|B}} while holding down {{key|CTRL}} In the below examples this procedure is described as <code>C-b</code>}}
=== Get help ===
One of the most useful commands is the one that gives you 'help'. 
While in your {{pkg|tmux}} session, click:
{{cmd|C-b ?}}
''(Do not press/hold {{key|CTRL}} when clicking {{key|?}})''

=== Detach from a session ===
Sometimes it's useful to just detach from a session without killing it. 
{{cmd|C-b d}}
{{tip|Try starting <code>ping 127.0.0.1</code> while inside a session and then detach from the session. After some while re-connect to the session using <code>tmux attach</code>. Note that the "seq" value indicates that ping had continued running while you where detached from the session.}}

=== Close or kill a session ===
To 'kill' a session:
{{cmd|C-b &}}
Confirm by clicking {{key|y}} when prompted.

You can also 'kill' your session by entering:
{{cmd|exit}}

=== Troubleshooting ===
If you are aiming to use tmux on your TTY and want to enable mouse service, you may need to take an extra step. First, ensure that your tmux config file has mouse support enabled by adding this to the ~/.tmux.conf file. Make this file if it does not already exist.
<pre>
set -g mouse on
</pre>
Refresh your tmux session to see if that step was enough.
<pre>
tmux source-file ~/.tmux.conf
</pre>
If your mouse does not appear, install the following package:
{{pkg|gpm}}

Enable and start gpm's service
<pre>
rc-update add gpm
rc-service gpm start
</pre>

= Other terminal multiplexers =
A similar tool is {{pkg|screen}} which is documented [[Screen_on_console|here]].

[[Category:Shell]]

Sway

2023-02-24T23:44:00Z

Quill: Added a section to troubleshooting about a possible fix for Proton games crashing on Sway. This solution was only necessary for my Alpine system after switching to Sway

[http://swaywm.org Sway] is a tiling [[Wayland]] compositor. It's a drop-in replacement for the i3 window manager.

== Installation ==

eudev:

<pre>
# apk add eudev
# setup-devd udev
</pre>

Graphics drivers:

* [[Intel Video]]
* [[Radeon Video]]
* [[Nvidia Video]]
Add user to the input and video groups:

<pre>
# adduser $USER input
# adduser $USER video
</pre>

Install some TTF fonts:

<pre>
# apk add ttf-dejavu
</pre>

seatd daemon:

<pre>
# apk add seatd
# rc-update add seatd
# rc-service seatd start
# adduser $USER seat
</pre>

Install sway:

<pre>
# apk add sway sway-doc
# apk add \ # Install optional dependencies:
xwayland \ # recommended for compatibility reasons
foot \ # default terminal emulator. Modify $term in config for a different one.
bemenu \ # wayland menu
swaylock swaylockd \ # lockscreen tool
swaybg \ # wallpaper daemon
swayidle # idle management (DPMS) daemon
</pre>

Configure [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].

== Usage ==

For inter-program communication and functionality such as screensharing, install and enable dbus and PipeWire, see [[PipeWire]] and set <code>SWAYSOCK</code> environmental variable to the value exported by <code>sway</code>. In order to ensure that Pipewire and related services inherit the right environment variables, it is recommended to start these services via a process that is a direct descendant of sway itself.

Launch Sway with a D-Bus server available, use:

<pre>
dbus-run-session -- sway #prepend with exec in your login shell init script
</pre>

== Configuration ==

An example config is provided at <code>/etc/sway/config</code>. Copy it to <code>~/.config/sway/config</code> and read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

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

=== Firefox screensharing ===

For some programs, additional configuration is needed to launch them natively under Wayland and to support special features such as screen sharing.

To launch Firefox natively under Wayland and to enable support for screensharing, you need:

* Install and configure [[PipeWire]]
* Install xdg-desktop-portal and xdg-desktop-portal-wlr package
* Install wofi for screen selection
* Launch support programs on sway startup:
<pre>
exec /usr/libexec/pipewire-launcher #pipewire must be launched first
exec /usr/libexec/xdg-desktop-portal-wlr
</pre>
* Export the following variables:

<pre>
export MOZ_ENABLE_WAYLAND="1"
export XDG_CURRENT_DESKTOP=sway
export QT_QPA_PLATFORM="wayland-egl"
</pre>

=== Flatpaks ===

Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>

This is only needed if they are not started automatically via other means.

=== Scaling for high resolution screens ===

Without further configuration, program interfaces might be too small to use on high resolution screens.

==== Via sway ====

Sway supports the per-display configuration of

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

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

To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

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

to ~/.config/sway/config.

==== Via GTK/Qt ====

<pre>
# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE=2

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

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

Install clipman from test repo and add the following to sway config:

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

=== Firefox picture-in-picture mode/floating windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Screenshots ===
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

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

=== Start with NumLock enabled ===
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>

=== Change cursor theme and size ===
Add to your sway config:
<pre>
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
</pre>
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.
{{Note|Wayland uses client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Start as a service ===
Although this is not necessary, you may write an init script like the following:
<pre>
{{/etc/init.d/sway|
#!/sbin/openrc-run

description="Sway Compositor"

command="/usr/bin/sway"
command_args=""

pidfile="/run/sway.pid"

start_stop_daemon_args="--background --pidfile ${pidfile}"

depend() {
need localmount
after elogind
use seatd dbus
}
</pre>
Then as a root run <code>chmod +x /etc/init.d/seat</code> and <code>rc-update add sway default</code>. Make sure you have elogind installed or specify another service, like your display/login manager after which the sway service will run.

=== Custom keyboard layout ===

Since wayland does not support setxkbmap, you will also need to add similar content to your ''/usr/share/X11/xkb/rules/evdev.xml'', after <code></modelList></code> and after <code><layoutList></code>:
<pre>
<layout>
<configItem>
<name>[the name of your layout, same as the name of the file in /usr/share/X11/xkb/symbols]</name>
<shortDescription>[usually just two letters]</shortDescription>
<description>[description of your layout]</description>
<countryList>
<iso3166Id>US</iso3166Id>
<iso3166Id>NO</iso3166Id>
</countryList>
<languageList>
<iso639Id>eng</iso639Id>
</languageList>
</configItem>
</layout>

</pre>
Then, to enable for all keyboards, navigate to the input section of ''~/.config/sway/config'' and modify it to
<pre>
input * {
xkb_layout "my_layout"
}
</pre>
If you have enabled <code>xkb_numlock</code>, include this setting inside those braces as well.

== Troubleshooting ==

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

=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').

=== Sway socket not detected ===

See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[Tmux terminal multiplexer|tmux]]

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

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

Sway

2023-01-19T15:21:23Z

Quill: Added a section to "Flatpak" that instructed users how to incorporate flatpaks to their bemenu/dmenu results with $PATH

[http://swaywm.org Sway] is a tiling [[Wayland]] compositor. It's a drop-in replacement for the i3 window manager.

== Installation ==

eudev:

<pre>
# apk add eudev
# setup-devd udev
</pre>

Graphics drivers:

* [[Intel Video]]
* [[Radeon Video]]
* [[Nvidia Video]]
Add user to the input and video groups:

<pre>
# adduser $USER input
# adduser $USER video
</pre>

Install some TTF fonts:

<pre>
# apk add ttf-dejavu
</pre>

seatd daemon:

<pre>
# apk add seatd
# rc-update add seatd
# rc-service seatd start
# adduser $USER seat
</pre>

[[elogind]], optional for suspending with a key (otherwise you can run <code>echo mem > /sys/power/state as a root</code>), or lid close support {{Note|Even though elogind may be installed and the service running, you may still need to configure some values. Otherwise you may for example be able to suspend with a key, but encounter a freeze upon waking. It is always vital to verify it is set up correctly with <code>loginctl list-sessions</code>}}

Install sway:

<pre>
# apk add sway sway-doc
# apk add \ # Install optional dependencies:
xwayland \ # recommended for compatibility reasons
foot \ # default terminal emulator. Modify $term in config for a different one.
bemenu \ # wayland menu
swaylock swaylockd \ # lockscreen tool
swaybg \ # wallpaper daemon
swayidle # idle management (DPMS) daemon
</pre>

Configure [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]]. If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the <code>XDG_RUNTIME_DIR</code> code with
<pre>
export XDG_SEAT=seat0
export XDG_SESSION_CLASS=user
</pre>

For inter-program communication and functionality such as screensharing, install and enable dbus and PipeWire, see [[PipeWire]] and set <code>SWAYSOCK</code> environmental variable to
<code>/tmp/$(id -u)-runtime-dir/sway-ipc.1000.$(pgrep -x sway).sock</code> in your login shell's init script.
Note that it has to be set after the line responsible for launching Sway.

Re-login or reboot to allow above modifications to take effect.

Launch Sway with dbus support:

<pre>
dbus-run-session -- sway #prepend with exec in your login shell init script
</pre>

== Configuration ==

An example config is provided at <code>/etc/sway/config</code>. Copy it to <code>~/.config/sway/config</code> and read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

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

=== Firefox screensharing ===

For some programs, additional configuration is needed to launch them natively under Wayland and to support special features such as screen sharing.

To launch Firefox natively under Wayland and to enable support for screensharing, you need:

* Install and configure [[PipeWire]]
* Install xdg-desktop-portal and xdg-desktop-portal-wlr package
* Install wofi for screen selection
* Launch support programs on sway startup:
<pre>
exec /usr/libexec/pipewire-launcher #pipewire must be launched first
exec /usr/libexec/xdg-desktop-portal-wlr
</pre>
* Export the following variables:

<pre>
export MOZ_ENABLE_WAYLAND="1"
export XDG_CURRENT_DESKTOP=sway
export XDG_SESSION_TYPE=wayland
export QT_QPA_PLATFORM="wayland-egl"
</pre>

=== Flatpaks ===

Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>

This is only needed if they are not started automatically via other means.

If you are using bemenu or dmenu and want flatpaks to be included in their search, you need to add the executables for the flatpaks to your $PATH for these launchers to find. To do so in Alpine Linux, open /etc/profile and add a new line to the list of append_path to include the flatpaks. For example, but with your username instead of USERNAME:
<pre>
append_path "/usr/local/sbin"
append_path "/usr/local/bin"
append_path "/usr/sbin"
append_path "/usr/bin"
append_path "/sbin"
append_path "/bin"
append_path "/home/USERNAME/.local/share/flatpak/exports/bin"
</pre>

=== Scaling for high resolution screens ===

Without further configuration, program interfaces might be too small to use on high resolution screens.

==== Via sway ====

Sway supports the per-display configuration of

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

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

To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

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

to ~/.config/sway/config.

==== Via GTK/Qt ====

<pre>
# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE=2

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

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

Install clipman from test repo and add the following to sway config:

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

=== Firefox picture-in-picture mode/floating windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Screenshots ===
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

=== Start with NumLock enabled ===
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>

=== Change cursor theme and size ===
Add to your sway config:
<pre>
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
</pre>
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.
{{Note|Wayland uses client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Start as a service ===
Although this is not necessary, you may write an init script like the following:
<pre>
{{/etc/init.d/sway|
#!/sbin/openrc-run

description="Sway Compositor"

command="/usr/bin/sway"
command_args=""

pidfile="/run/sway.pid"

start_stop_daemon_args="--background --pidfile ${pidfile}"

depend() {
need localmount
after elogind
use seatd dbus
}
</pre>
Then as a root run <code>chmod +x /etc/init.d/seat</code> and <code>rc-update add sway default</code>. Make sure you have elogind installed or specify another service, like your display/login manager after which the sway service will run.

=== Custom keyboard layout ===

Since wayland does not support setxkbmap, you will also need to add similar content to your ''/usr/share/X11/xkb/rules/evdev.xml'', after <code></modelList></code> and after <code><layoutList></code>:
<pre>
<layout>
<configItem>
<name>[the name of your layout, same as the name of the file in /usr/share/X11/xkb/symbols]</name>
<shortDescription>[usually just two letters]</shortDescription>
<description>[description of your layout]</description>
<countryList>
<iso3166Id>US</iso3166Id>
<iso3166Id>NO</iso3166Id>
</countryList>
<languageList>
<iso639Id>eng</iso639Id>
</languageList>
</configItem>
</layout>

</pre>
Then, to enable for all keyboards, navigate to the input section of ''~/.config/sway/config'' and modify it to
<pre>
input * {
xkb_layout "my_layout"
}
</pre>
If you have enabled <code>xkb_numlock</code>, include this setting inside those braces as well.

== Troubleshooting ==

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

=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').

=== Sway socket not detected ===

See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[Tmux terminal multiplexer|tmux]]

[[Category:Desktop]]

Sway

2023-01-10T01:39:29Z

Quill: Added a "Flatpak" section to address an issue I've encountered when switching from Gnome->Sway. Flatpaks were unable to interface with the portals until I started them in my sway config file.

[http://swaywm.org Sway] is a tiling [[Wayland]] compositor. It's a drop-in replacement for the i3 window manager.

== Installation ==

eudev:

<pre>
# apk add eudev
# setup-devd udev
</pre>

Graphics drivers:

* [[Intel Video]]
* [[Radeon Video]]
* [[Nvidia Video]]
Add user to the input and video groups:

<pre>
# adduser $USER input
# adduser $USER video
</pre>

Install some TTF fonts:

<pre>
# apk add ttf-dejavu
</pre>

seatd daemon:

<pre>
# apk add seatd
# rc-update add seatd
# rc-service seatd start
# adduser $USER seat
</pre>

[[elogind]], optional for suspending with a key (otherwise you can run <code>echo mem > /sys/power/state as a root</code>), or lid close support {{Note|Even though elogind may be installed and the service running, you may still need to configure some values. Otherwise you may for example be able to suspend with a key, but encounter a freeze upon waking. It is always vital to verify it is set up correctly with <code>loginctl list-sessions</code>}}

Install sway:

<pre>
# apk add sway sway-doc
# apk add \ # Install optional dependencies:
xwayland \ # recommended for compatibility reasons
foot \ # default terminal emulator. Modify $term in config for a different one.
bemenu \ # wayland menu
swaylock swaylockd \ # lockscreen tool
swaybg \ # wallpaper daemon
swayidle # idle management (DPMS) daemon
</pre>

Configure [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]]. If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the <code>XDG_RUNTIME_DIR</code> code with
<pre>
export XDG_SEAT=seat0
export XDG_SESSION_CLASS=user
</pre>

For inter-program communication and functionality such as screensharing, install and enable dbus and PipeWire, see [[PipeWire]] and set <code>SWAYSOCK</code> environmental variable to
<code>/tmp/$(id -u)-runtime-dir/sway-ipc.1000.$(pgrep -x sway).sock</code> in your login shell's init script.
Note that it has to be set after the line responsible for launching Sway.

Re-login or reboot to allow above modifications to take effect.

Launch Sway with dbus support:

<pre>
dbus-run-session -- sway #prepend with exec in your login shell init script
</pre>

== Configuration ==

An example config is provided at <code>/etc/sway/config</code>. Copy it to <code>~/.config/sway/config</code> and read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

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

=== Firefox screensharing ===

For some programs, additional configuration is needed to launch them natively under Wayland and to support special features such as screen sharing.

To launch Firefox natively under Wayland and to enable support for screensharing, you need:

* Install and configure [[PipeWire]]
* Install xdg-desktop-portal and xdg-desktop-portal-wlr package
* Install wofi for screen selection
* Launch support programs on sway startup:
<pre>
exec /usr/libexec/pipewire-launcher #pipewire must be launched first
exec /usr/libexec/xdg-desktop-portal-wlr
</pre>
* Export the following variables:

<pre>
export MOZ_ENABLE_WAYLAND="1"
export XDG_CURRENT_DESKTOP=sway
export XDG_SESSION_TYPE=wayland
export QT_QPA_PLATFORM="wayland-egl"
</pre>

=== Flatpaks ===

Due to their sandboxing, flatpaks require the use of portals (xdg-desktop-portal) and frontends (such as xdg-desktop-portal-wlr or xdg-desktop-portal-gnome). Different frontends are used by different applications depending on their needs; when in doubt, install multiple frontends. For more information on frontends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional frontends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different frontends, add the relevant frontends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/pipewire-launcher #pipewire must be launched first
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
exec /usr/libexec/xdg-desktop-portal-kde
</pre>

=== Scaling for high resolution screens ===

Without further configuration, program interfaces might be too small to use on high resolution screens.

==== Via sway ====

Sway supports the per-display configuration of

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

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

To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

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

to ~/.config/sway/config.

==== Via GTK/Qt ====

<pre>
# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE=2

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

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

Install clipman from test repo and add the following to sway config:

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

=== Firefox picture-in-picture mode/floating windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Screenshots ===
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

=== Start with NumLock enabled ===
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>

=== Change cursor theme and size ===
Add to your sway config:
<pre>
seat seat0 xcursor_theme my_cursor_theme my_cursor_size
</pre>
You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.
{{Note|Wayland uses client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Start as a service ===
Although this is not necessary, you may write an init script like the following:
<pre>
{{/etc/init.d/sway|
#!/sbin/openrc-run

description="Sway Compositor"

command="/usr/bin/sway"
command_args=""

pidfile="/run/sway.pid"

start_stop_daemon_args="--background --pidfile ${pidfile}"

depend() {
need localmount
after elogind
use seatd dbus
}
</pre>
Then as a root run <code>chmod +x /etc/init.d/seat</code> and <code>rc-update add sway default</code>. Make sure you have elogind installed or specify another service, like your display/login manager after which the sway service will run.

=== Custom keyboard layout ===

Since wayland does not support setxkbmap, you will also need to add similar content to your ''/usr/share/X11/xkb/rules/evdev.xml'', after <code></modelList></code> and after <code><layoutList></code>:
<pre>
<layout>
<configItem>
<name>[the name of your layout, same as the name of the file in /usr/share/X11/xkb/symbols]</name>
<shortDescription>[usually just two letters]</shortDescription>
<description>[description of your layout]</description>
<countryList>
<iso3166Id>US</iso3166Id>
<iso3166Id>NO</iso3166Id>
</countryList>
<languageList>
<iso639Id>eng</iso639Id>
</languageList>
</configItem>
</layout>

</pre>
Then, to enable for all keyboards, navigate to the input section of ''~/.config/sway/config'' and modify it to
<pre>
input * {
xkb_layout "my_layout"
}
</pre>
If you have enabled <code>xkb_numlock</code>, include this setting inside those braces as well.

== Troubleshooting ==

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

=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').

=== Sway socket not detected ===

See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[Tmux terminal multiplexer|tmux]]

[[Category:Desktop]]

AppArmor

2022-10-19T14:49:54Z

Quill: Added a Troubleshooting section with an issue and solution I've run into. Also made the rc-update add apparmor command include boot for the sake of clarity

AppArmor is a kernel security module that restricts individual programs' capabilities. This can allow administrators to prevent programs accessing system resources in malicious ways according to per-applications specifications. AppArmor works by following profiles, which dictate what each application is and is not allowed to do.

 

== Installation ==

{{Cmd|# apk add {{Pkg|apparmor}}}}

 

You should also install apparmor-utils if you want to use the aa command to interact with AppArmor.

{{Cmd|# apk add {{Pkg|apparmor-utils}}}}

 

==Setup==

Run the command {{Cmd|# cat /sys/kernel/security/lsm}} to see what linux security modules are currently setup.

 

Use a text editor like nano to edit <pre>/boot/extlinux.conf</pre> such that the APPEND line ends with the following:

<pre>
lsm=landlock,yama,apparmor
</pre>

Note that because you're including lsm in this .conf file you are overriding the default lsm. Thus, you should include any lsm that you saw previously running in the above cat command. Additionally, lsm initializes these modules in order, so their position is important in regards to major/minor modules. Ensure that apparmor is placed first among major modules. Note for convenience that yama, capability, and landlock, which come with Alpine Linux, are not major modules, and apparmor can be placed after them. The module called capability is automatically included and does not need to be written in.

 

Next, start AppArmor and tell openrc to start it on boot.

{{Cmd|# rc-service apparmor start}}
{{Cmd|# rc-update add apparmor boot}}

 

You can check if AppArmor is running with the command aa-enabled

{{Cmd|# aa-enabled}}

 

==Configuration==

AppArmor works using rules established in profiles. A set of pre-made profiles is available for ease of use:

{{Cmd|# apk add {{Pkg|apparmor-profiles}}}}

Reboot.

 

==Use==

View AppArmor's report with the command aa-status

{{Cmd|# aa-status}}

This details how many and what profiles are in use as well as relevant findings, such as how many profiles are in complain mode or in kill mode.

==Troubleshoot==

If you notice a bunch of AppArmor errors on boot, try running aa-status and aa-enabled in the terminal. If the output mentions AppArmor being disabled at boot, re-open your /boot/extlinux.conf file and make sure the APPEND line still ends with lsm=landlock,yama,apparmor

AppArmor

2022-10-09T00:20:20Z

Quill: consolidated information where it was more relevant

AppArmor is a kernel security module that restricts individual programs' capabilities. This can allow administrators to prevent programs accessing system resources in malicious ways according to per-applications specifications. AppArmor works by following profiles, which dictate what each application is and is not allowed to do.

 

== Installation ==

{{Cmd|# apk add {{Pkg|apparmor}}}}

 

You should also install apparmor-utils if you want to use the aa command to interact with AppArmor.

{{Cmd|# apk add {{Pkg|apparmor-utils}}}}

 

==Setup==

Run the command {{Cmd|# cat /sys/kernel/security/lsm}} to see what linux security modules are currently setup.

 

Use a text editor like nano to edit <pre>/boot/extlinux.conf</pre> such that the APPEND line ends with the following:

<pre>
lsm=landlock,yama,apparmor
</pre>

Note that because you're including lsm in this .conf file you are overriding the default lsm. Thus, you should include any lsm that you saw previously running in the above cat command. Additionally, lsm initializes these modules in order, so their position is important in regards to major/minor modules. Ensure that apparmor is placed first among major modules. Note for convenience that yama, capability, and landlock, which come with Alpine Linux, are not major modules, and apparmor can be placed after them. The module called capability is automatically included and does not need to be written in.

 

Next, start AppArmor and tell openrc to start it on boot.

{{Cmd|# rc-service apparmor start}}
{{Cmd|# rc-update add apparmor}}

 

You can check if AppArmor is running with the command aa-enabled

{{Cmd|# aa-enabled}}

 

==Configuration==

AppArmor works using rules established in profiles. A set of pre-made profiles is available for ease of use:

{{Cmd|# apk add {{Pkg|apparmor-profiles}}}}

Reboot.

 

==Use==

View AppArmor's report with the command aa-status

{{Cmd|# aa-status}}

This details how many and what profiles are in use as well as relevant findings, such as how many profiles are in complain mode or in kill mode.

AppArmor

2022-10-09T00:16:25Z

Quill: Information and instruction on how to install, setup, and use AppArmor

AppArmor is a kernel security module that restricts individual programs' capabilities. This can allow administrators to prevent programs accessing system resources in malicious ways according to per-applications specifications. AppArmor works by following profiles, which dictate what each application is and is not allowed to do.

 

== Installation ==

{{Cmd|# apk add {{Pkg|apparmor}}}}

 

You should also install apparmor-utils if you want to use the aa command to interact with AppArmor.

{{Cmd|# apk add {{Pkg|apparmor-utils}}}}

 

==Setup==

Run the command {{Cmd|# cat /sys/kernel/security/lsm}} to see what linux security modules are currently setup. Note that lsm initializes these modules in order, so their position is important in regards to major/minor modules. Ensure that apparmor is placed first among major modules. Note for convenience that yama, capability, and landlock, which come with Alpine Linux, are not major modules, and apparmor can be placed after them.

 

Use a text editor like nano to edit <pre>/boot/extlinux.conf</pre> such that the APPEND line ends with the following:

<pre>
lsm=landlock,yama,apparmor
</pre>

Note that because you're including lsm in this .conf file you are overriding the default lsm. Thus, you should include any lsm that you saw previously running in the above cat command. The module called capability is automatically included and does not need to be written in.

 

Next, start AppArmor and tell openrc to start it on boot.

{{Cmd|# rc-service apparmor start}}
{{Cmd|# rc-update add apparmor}}

 

You can check if AppArmor is running with the command aa-enabled

{{Cmd|# aa-enabled}}

 

==Configuration==

AppArmor works using rules established in profiles. A set of pre-made profiles is available for ease of use:

{{Cmd|# apk add {{Pkg|apparmor-profiles}}}}

Reboot.

 

==Use==

View AppArmor's report with the command aa-status

{{Cmd|# aa-status}}

This details how many and what profiles are in use as well as relevant findings, such as how many profiles are in complain mode or in kill mode.

Proton VPN

2022-10-05T23:38:57Z

Quill: removed doas from the cmd under "running" section

Proton VPN is an open-source VPN service by the non-profit Swiss company Proton AG. It utilizes the OpenVPN protocol. Because Alpine Linux does not currently have a release for Proton VPN, using it requires connecting via either OpenVPN or Wireguard. Using Wireguard is recommended due to Proton AG's own stated preference for the service as well as Wireguard's lighter and more modern build. Setting up for Wireguard is relatively simpler because NetworkManager has native support for it, requiring fewer installations and setups.

 

== Installation ==

{{Cmd|# apk add {{Pkg|wireguard-tools}}}}

 

== Configuring ==

Login to Proton VPN and download the Wireguard config file. More information on this can be found at [https://protonvpn.com/support/wireguard-configurations/ Proton VPN's support page]. Note that the private key will only be available from the site if you download immediately after making the config file, after which the private key is replaced with asterisks. Rename the file "wg0.conf" and move it somewhere safe in your file system.

 

== Running ==

To connect, run the following command. Substitute path_to_file with the full path to wherever you moved the config file.

{{Cmd|# wg-quick up /path_to_file/wg0.conf}}

 

To enable Wireguard connecting to Proton VPN on boot, open your /etc/network/interfaces using a text editor like nano. Add this information after your auto wlan0 section:

<pre>
auto wg0
iface wg0 inet static
pre-up wg-quick up /path_to_file/wg0.conf
</pre>

 

Again, substitute path_to_file with your own relevant information.

Proton VPN

2022-10-05T03:15:53Z

Quill: How to setup Proton VPN using Wireguard

Proton VPN is an open-source VPN service by the non-profit Swiss company Proton AG. It utilizes the OpenVPN protocol. Because Alpine Linux does not currently have a release for Proton VPN, using it requires connecting via either OpenVPN or Wireguard. Using Wireguard is recommended due to Proton AG's own stated preference for the service as well as Wireguard's lighter and more modern build. Setting up for Wireguard is relatively simpler because NetworkManager has native support for it, requiring fewer installations and setups.

 

== Installation ==

{{Cmd|# apk add {{Pkg|wireguard-tools}}}}

 

== Configuring ==

Login to Proton VPN and download the Wireguard config file. More information on this can be found at [https://protonvpn.com/support/wireguard-configurations/ Proton VPN's support page]. Note that the private key will only be available from the site if you download immediately after making the config file, after which the private key is replaced with asterisks. Rename the file "wg0.conf" and move it somewhere safe in your file system.

 

== Running ==

To connect, run the following command. Substitute path_to_file with the full path to wherever you moved the config file.

{{Cmd|# doas wg-quick up /path_to_file/wg0.conf}}

 

To enable Wireguard connecting to Proton VPN on boot, open your /etc/network/interfaces using a text editor like nano. Add this information after your auto wlan0 section:

<pre>
auto wg0
iface wg0 inet static
pre-up wg-quick up /path_to_file/wg0.conf
</pre>

 

Again, substitute path_to_file with your own relevant information.

NetworkManager

2022-10-04T02:36:30Z

Quill: added 2 lines under "Installation" to indicate the need for networkmanager-wifi

[https://networkmanager.dev/ NetworkManager] is a program that provides automatic detection and configuration for systems to connect to networks.

== Installation ==

{{Cmd|# apk add {{Pkg|networkmanager}}}}

 

NetworkManager comes with a command line interface and a curses-based interface, <code>nmcli</code> and <code>nmtui</code> respectively or you can use a additional gui interface:

* {{Pkg|plasma-nm}} for Plasma integration and applet
* {{Pkg|network-manager-applet}} for a GTK system tray applet

 

You will need to install an additional package if you want NetworkManager to connect to wifi:
{{Cmd|# apk add {{Pkg|networkmanager-wifi}}}}

 

After installation start NetworkManager:
{{Cmd|# rc-service networkmanager start}}

 

Also your user needs to be in the <code>plugdev</code> group:
{{Cmd|# adduser <YourUsername> plugdev}}

{{Note|you will need to log out for the new group to take effect}}

 

== Wireless networks ==

==== wpa_supplicant backend ====

{{Todo|([[KDE|KDE Plasma]] Desktop) find out if it is possible to prevent requesting the password for '''KDE Wallet''' on login}}

* Follow: [[Wi-Fi#wpa_supplicant]] and [[Wi-Fi#Automatic_Configuration_on_System_Boot]]
{{Note|{{Pkg|wpa_supplicant}} configuration might not be required, if it isnt it may be a good idea to have it setup just as a fallback}}

 

Now open <code>/etc/NetworkManager/NetworkManager.conf</code> in a text editor and change it to something like this:

{{Cat|/etc/NetworkManager/NetworkManager.conf|<nowiki>[main]
dhcp=internal
plugins=ifupdown,keyfile

[ifupdown]
managed=true

[device]
wifi.scan-rand-mac-address=yes
wifi.backend=wpa_supplicant</nowiki>}}

{{Note|if these options dont work on your system you can change them as necessary}}

 

Now you need to stop conflicting services:

{{Cmd|# rc-service networking stop}}
{{Cmd|# rc-service wpa_supplicant stop}}

 

Now restart NetworkManager:

{{Cmd|# rc-service networkmanager restart}}

 

Now connect to a network using one of the interfaces mentioned in [[NetworkManager#Installation|Installation]]

 

If that connects and stays connected with no issues enable the <code>networkmanager</code> service and disable the <code>networking</code> and <code>wpa_supplicant</code> boot services:

{{Cmd|# rc-update add networkmanager}}
{{Cmd|# rc-update del networking boot}}
{{Cmd|# rc-update del wpa_supplicant boot}}

 

==== iwd backend ====

NetworkManager supports wireless networks through {{Pkg|iwd}}, however, consider [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues?scope=all&utf8=%E2%9C%93&state=opened&search=iwd existing issues] before using it. After installation, enable the server and restart NetworkManager:
<pre>
rc-service iwd start
rc-service networkmanager restart
</pre>

To use {{Pkg|iwd}} though, you've have to edit NetworkManager's configuration because it still defaults to {{Pkg|wpa_supplicant}} instead. Add the following to {{Path|/etc/NetworkManager/NetworkManager.conf}}:

<pre>
[device]
wifi.backend=iwd
</pre>

 

== VPN support ==
Since version 1.16, NetworkManager has support for Wireguard[https://cgit.freedesktop.org/NetworkManager/NetworkManager/tree/NEWS?id=1.16.0].

Support for other VPN types is provided by plugins. They are provided in the following packages:
* {{Pkg|networkmanager-openvpn}} for OpenVPN

== nm-applet ==
=== not authorized to control networking ===

You can enable all users to edit connections without adding polkit.
First, make the <code>conf.d</code> directory for networkmanager:

{{Cmd|# mkdir -p /etc/NetworkManager/conf.d}}

Then, add following content to <code>/etc/NetworkManager/conf.d/any-user.conf</code>:

<pre>
[main]
auth-polkit=false
</pre>

Finally, restart networkmanager:

{{Cmd|# /etc/init.d/networkmanager restart}}

[[Category:Networking]]