Alpine Linux - User contributions [en]

Configure a Wireguard interface (wg)

2026-02-27T19:10:54Z

154pinkchairs: Undo revision 32094 by 154pinkchairs (talk)

{{TOC right}}

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

== Installation ==

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

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

== Configuration ==

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

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

Remove any permissions on the file for users and groups other than the root user to ensure that only it can access the private key: {{Cmd|<nowiki># chmod go= server.privatekey</nowiki>}}

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

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

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

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

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

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

=== Use with network interfaces ===

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

=== Service configuration ===

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

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

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

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

=== Enable IP Forwarding ===

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

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

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

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

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

== Running with modloop ==

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

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

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

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

== Preventing leaks ==

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

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

#!/usr/sbin/nft -f

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

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

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

== Alternative Integrations into the Network Stack ==
{{Expand|Contributions welcome. Thank you!}}

=== ConnMan Wireguard ===

'''{{Pkg|connman-wireguard}}''': An integration plugin enabling ConnMan management of WireGuard interfaces.

=== ifupdown-ng-wireguard ===

'''{{Pkg|ifupdown-ng-wireguard}}''': Supplies a declarative WireGuard interface for '''ifupdown-ng'''.

=== wireguard-go ===

'''{{Pkg|wireguard-go}}''': A userspace implementation of WireGuard in '''go''', not used by default in Alpine Linux except in containerized or restricted environments where kernel module loading is not possible. It can be used as a fallback on older kernels that do not offer WireGuard support.

== Tools ==
{{Expand|Contributions are encouraged.}}

=== Tailscale and NetBird ===

'''{{Pkg|tailscale}}''', '''{{Pkg|netbird}}''': Mesh VPNs built over WireGuard that streamline peer discovery and access control.

=== Rosenpass ===

'''{{Pkg|rosenpass}}''': Verified, post-quantum key exchange tool.

=== Innernet ===

'''{{Pkg|innernet}}''': A private network based on WireGuard using centralized key management. Currently in testing repository as of February 2026: test by [[Repositories#Using_testing_repository|enabling and tagging the testing repository]] and installing as {{ic|innernet@testing}}.

=== py3-wgconfig ===

'''{{Pkg|py3-wgconfig}}''': Python library to parse and modify WireGuard config files that preserves comments. Currently in testing repository as of February 2026: ensure that the [[Repositories#Using_testing_repository|the testing repo is enabled and tagged]], and install as {{ic|py3-wgconfig@testing}}.

=== WireGuard Bash Completion ===

'''{{Pkg|wireguard-tools-bash-completion}}''': Enables tab completion in bash for {{Pkg|wg}} and {{Pkg|wg-quick}}.

== WireGuard Monitoring and Management ==
{{Expand|Contributions are encouraged.}}

=== Prometheus Wireguard Exporter ===

'''{{Pkg|prometheus-wireguard-exporter}}''': To monitor active peers, traffic. Rust-based, and must run with root privileges or with {{ic|CAP_NET_ADMIN}}.

== See also ==

* [https://github.com/pirate/wireguard-docs WireGuard documentation]
* [https://medium.com/nerd-for-tech/wireguard-vpn-monitoring-alerting-e1e1d1eaaa4e Setting up Prometheus WireGuard exporter, Grafana Dashboard, Alerts Manager.]

[[Category:Networking]]

Configure a Wireguard interface (wg)

2026-02-27T19:07:44Z

154pinkchairs: /* Installation */ legacy iptables -> nftables

{{TOC right}}

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

== Installation ==

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

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

== Configuration ==

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

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

Remove any permissions on the file for users and groups other than the root user to ensure that only it can access the private key: {{Cmd|<nowiki># chmod go= server.privatekey</nowiki>}}

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

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

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

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

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

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

=== Use with network interfaces ===

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

=== Service configuration ===

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

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

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

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

=== Enable IP Forwarding ===

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

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

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

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

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

== Running with modloop ==

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

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

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

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

== Preventing leaks ==

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

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

#!/usr/sbin/nft -f

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

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

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

== Alternative Integrations into the Network Stack ==
{{Expand|Contributions welcome. Thank you!}}

=== ConnMan Wireguard ===

'''{{Pkg|connman-wireguard}}''': An integration plugin enabling ConnMan management of WireGuard interfaces.

=== ifupdown-ng-wireguard ===

'''{{Pkg|ifupdown-ng-wireguard}}''': Supplies a declarative WireGuard interface for '''ifupdown-ng'''.

=== wireguard-go ===

'''{{Pkg|wireguard-go}}''': A userspace implementation of WireGuard in '''go''', not used by default in Alpine Linux except in containerized or restricted environments where kernel module loading is not possible. It can be used as a fallback on older kernels that do not offer WireGuard support.

== Tools ==
{{Expand|Contributions are encouraged.}}

=== Tailscale and NetBird ===

'''{{Pkg|tailscale}}''', '''{{Pkg|netbird}}''': Mesh VPNs built over WireGuard that streamline peer discovery and access control.

=== Rosenpass ===

'''{{Pkg|rosenpass}}''': Verified, post-quantum key exchange tool.

=== Innernet ===

'''{{Pkg|innernet}}''': A private network based on WireGuard using centralized key management. Currently in testing repository as of February 2026: test by [[Repositories#Using_testing_repository|enabling and tagging the testing repository]] and installing as {{ic|innernet@testing}}.

=== py3-wgconfig ===

'''{{Pkg|py3-wgconfig}}''': Python library to parse and modify WireGuard config files that preserves comments. Currently in testing repository as of February 2026: ensure that the [[Repositories#Using_testing_repository|the testing repo is enabled and tagged]], and install as {{ic|py3-wgconfig@testing}}.

=== WireGuard Bash Completion ===

'''{{Pkg|wireguard-tools-bash-completion}}''': Enables tab completion in bash for {{Pkg|wg}} and {{Pkg|wg-quick}}.

== WireGuard Monitoring and Management ==
{{Expand|Contributions are encouraged.}}

=== Prometheus Wireguard Exporter ===

'''{{Pkg|prometheus-wireguard-exporter}}''': To monitor active peers, traffic. Rust-based, and must run with root privileges or with {{ic|CAP_NET_ADMIN}}.

== See also ==

* [https://github.com/pirate/wireguard-docs WireGuard documentation]
* [https://medium.com/nerd-for-tech/wireguard-vpn-monitoring-alerting-e1e1d1eaaa4e Setting up Prometheus WireGuard exporter, Grafana Dashboard, Alerts Manager.]

[[Category:Networking]]

Setting up a laptop

2026-02-18T15:17:04Z

154pinkchairs: /* Improved method with plausible deniability */ obtaining key file path

This guide is about a project to create a '''secured laptop'''. For this project we take in consideration ways to extend battery life. It covers tools and daemons that are must haves for a laptop setup.
{{Todo|Instructions given in the page needs testing. Please help test section by section or the entire page. If individual sections have been tested, please update the Talkpage or please move/place this notice in the untested section(s) alone.}}

== Guide features ==

*Deniable full disk encryption
*Two factor authentication (physical object (USB key), mind)
*Encrypted swap and hibernation
*Encrypted home on top of encrypted drive
*Memory sanitation
*Dynamic power modes
*Feature keys support

== Rubberhose Attack ==

Just a reminder that all attacks are subjected to the Rubberhose Attack dilemma, you either give up your encryption keys or be tortured with a rubberhose with the possibly of death. See [https://en.wikipedia.org/wiki/Rubber-hose_cryptanalysis Wikipedia article]. We try to present [https://en.wikipedia.org/wiki/Deniable_encryption deniable encryption (Wikipedia)] to avoid a rubberhose attack scenario. In this article we use the words plausible deniability interchangeably with deniable encryption. To achieve this we use a facade and require no metadata fingerprints to expose or hint of encrypted or hidden containers or hint as in detect of existence of an encrypted disk. The keys should be stored using steganography where we dilute the randomness into the facade. It also requires you not to brag about encryption or mention it because that is an invitation for the attacker to torture the victim. Deniable encryption requires you not put encrypted as an entry title to your bootloader. There shouldn't be an entry for your facade bootloader to the encrypted drive.

== Why full disk? ==

The full disk encryption provides sort of some plausible deniability or a valid alibi that you didn't encrypt it. Is the drive just random noise, broken, or is it really encrypted? The other reason is that it implies that everything is protected.

But there could be problems if not done right. For example, cryptsetup does leave a plaintext marking or some hints by default that it has been encrypted when using luks/luks2 mode if a detached header with option <code>--header <path></code> is not presented.[https://www.lisenet.com/2013/luks-add-keys-backup-and-restore-volume-header/][https://man7.org/linux/man-pages/man8/cryptsetup.8.html] To gain credibility that we didn't really do the encryption, you have to wipe the +3 MiB region based on the number of key slots used; or store the headers on an external device.

If you did deniable encryption incorrectly, it is possible to erase and restore the header. This presents an opportunity to improve obfuscation. When you pull out the USB key, it should erase the header but store it on the USB key atomically as in completely. If you plug in the USB key, it will restore back the header. cryptsetup has luks actions luksHeaderBackup and luksHeaderRestore to do this.

== Starting at the beginning ==

Grab a USB thumb drive with Alpine. Set it up as usual but don't let it touch your drive yet. Then, install all the tools into memory ramdisk but not in the hard drive yet. The hard drive will be obliterated.

You will then install Alpine using the steps:

First you need WiFi, to get it run do the command below but say no or skip the hard drive setup stuff:

setup-alpine

Then, you need to install some tools into RAM temporarly:
apk add e2fsprogs grub grub-bios grub-efi mkinitfs nano

== Randomizing the drive with pseudorandom urandom entropy ==

The first part is to erase the drive with random noise but in practical time. There are many techniques to do this but should be done in one day or two minimum.

You can use shred or dd to accomplish this depending on your needs and the availability of entropy. Some techniques take longer. Cryptologist Bruce Schneier recommended 7 times with specified pattern. See [https://en.wikipedia.org/wiki/Data_erasure Wikipedia Article]. For practical purposes, we just do it random in one pass. It should be random so that the facade of random noise hides the encrypted data which resembles noise.

To list the drives on the system do <code>fdisk -l</code>.

'''IMPORTANT: make sure you wipe the right specific drive.'''

To wipe the disk with random entropy do:

dd if=/dev/urandom of=/dev/sda

== Creating GPG keys ==

'''As of this time, Alpine's mkinitfs does only one factor authentication with passphrase.''' You need to manually edit the initramfs-init.in in mkinitfs to support two factor authentication using cryptsetup.

After you have scrambled the drive, you want to create your GPG keys. You will use these keys to set the password(s) for your cryptsetup-luks partitions. These keys should be stored on a USB thumb drive or other memory device but should not be on the USB boot thumb drive or on the encrypted drive. The key should be a random 128 bit key wrapped in GPG and protected with a password.

If you are using x, you need to do <code>sudo apk add pinentry-gtk</code> to display password prompt properly for the next step.

To install openssl and gpg do:

apk add openssl gnupg

Then, to generate a key:

export GPG_TTY=$(tty) && openssl rand -base64 512 | gpg --symmetric --cipher-algo aes --armor > /mnt/usb/$(openssl rand -hex 12)

(Make sure your usb is mounted on /mnt/usb first.)

The long file name comes from <code>openssl rand -hex 12</code> so that we enhance plausible deniability. The attacker cannot determine the purpose of the key. Is it used for GitHub? for Email?

The first part will produce 512 random bytes in wrap it in base64. The random data will be piped to gpg which will wrap it in AES as ciphertext which again gets wrapped in base64 ascii armor. For every partition including swap in some cases, you should create more gpg keys and store them in your USB thumb drives. After you have produced your gpg keys, you will then use them as a password for cryptsetup/luks.

You can replace aes above with the ones listed in <code>gpg --version</code>.

There should be a password generated for the swap. This is to resume for your hibernate. If you don't want to hibernate, then password is not required and all you need to do is to create/format the partition each time you boot without a password or with a one time random password.

== Hiding the keys using steganography ==

''WARNING:'' This section is considered experimental. It requires the tool and the dependencies to be placed on another USB separate from the key files, the bootloaders, and encrypted disks. The tool and dependencies need to be packaged together. We decentralize these components so that the attacker doesn't connect the dots easily or immediately jumps to the conclusion for the requirements to decrypt. Steghide automatically uses 128-bit AES in CBC mode to encrypt data. This can be change if you don't like or trust AES with the -e option. Use <code>steghide encinfo</code> for other ciphers and modes.

Fortunately, Alpine has a package for steganography called steghide (in the optional edge/testing repository as of February 2026). To install steghide do:

echo "http://dl-cdn.alpinelinux.org/alpine/edge/testing" >> /etc/apk/repositories
apk add steghide

You will place the keyfile in an image file. The facade image file should be large enough that there is no apparent discernible difference between the original and the modified. Do not use a small image with a small filesize.

As mentioned previously luks headers could be 3MB large or more and an jpeg image file is not suitable. Use another format like .au/.wav or another steganography utility that handles mp3s. The mp3/wav should be fairly large enough to dilute the header. So, something with long content is suitable.

There are two basic commands to use with steghide embed and extract,

To embed do:

steghide embed -ef key.gpg -cf image.jpg

To extract do:

steghide extract -xf key.gpg -sf image.jpg

To get a file list of files to ship out, use:

apk info -L libgcc libmcrypt libmhash libstdc++ libjpeg-turbo steghide

== Full disk encryption with with cryptsetup-luks volumes ==

=== Partitioning scheme ===

This section presents a conceptual layout. It should not be a knee-jerk approval to automatically use the partition tool which would compromise your plausible deniability.

For the facade, we use an Ubuntu Live CD (or less skilled distro) to present the impression that we are not sophisticated or tech savvy enough to implement encryption. Windows is also acceptable even better. The immutable Live CD and immutable partition ensures that you are not compromised by a third party attacker that implants evidence.

There could be possibly two bootloaders, one for the facade and the other to the encrypted drive stored on an external device.

==== Luks ====

Plausible deniability only works if you can demonstrate no existence of partitions 2, 3, 4 and no fingerprints/plaintext introduced by cfdisk and cryptsetup-luks. Use something like TestDisk, fdisk -l, or gparted and a disk editor (hex editor for disks).

{| cellpadding="5" border="1" class="wikitable"
!#
!Name
!Mount point
!Notes
|-
| 1
| facade
| /
| (optional) The facade partition contains a pristine normal operating system or Ubuntu Live CD image to lure the attacker in attempt to boost the confidence of the attacker convincing them that there is no encryption on the device.
|-
| 2
| swap
|
| It should be the same size as your ram for x86_64. Rationale: it should contain the whole ram image.
|-
| 3
| root
| /
|
|-
| 4
| rescue
| /
| This should contain the Alpine image.
|-
|}

==== Plain dm-crypt ====

Plausible deniability only works if you are able to present #2 as being unused space or untampered. To check use something like TestDisk, gparted and a disk editor (hex editor for disks).

{| cellpadding="5" border="1" class="wikitable"
!#
!Name
!Mount point
!Notes
|-
| 1
| facade
| /
| (optional) The facade partition contains a pristine normal operating system or Ubuntu Live CD image to lure the attacker in attempt to boost the confidence of the attacker convincing them that there is no encryption on the device.
|-
| 2
| vgroot
|
|
|-
| 2_1
| vgroot-root
| /
|
|-
| 2_2
| vgroot-swap
|
| It should be the same size as your ram for x86_64. Rationale: it should contain the whole ram image.
|-
| 2_3
| vgroot-rescue
| /
| This should contain the Alpine image.
|-
|}

=== Installing cryptsetup ===

To install cryptsetup you need the package below

apk add cryptsetup

=== Choosing ciphers ===

When you create your luks drives, you need to decide on the type of ciphers and hashing techniques to use. The ciphers that you want to use are ones are up to you, but it should be one that is hasn't been cracked yet or has not suffered a lot of cryptanalysis attacks. The ones that you might want to use is AES which is hardware accelerated in some Intel CPUs that have the AES-NI cpuflag which you can check by <code>cat /proc/cpuinfo</code>. Also consider the ciphers that are SIMD optimized such as serpent and twofish that are available in the Linux kernel. Also consider ciphers that are unpopular but known to be secure such as Blowfish (which Wikipedia claims to be attacked and the author recommended Twofish).[https://en.wikipedia.org/wiki/Cipher_security_summary] If it is hardware accelerated, it will save battery life and minimize CPU usage.

For some ciphers weakness also see [https://en.wikipedia.org/wiki/Cipher_security_summary Cipher security summary (Wikipedia)].

For some hash function weaknesses also see [https://en.wikipedia.org/wiki/Hash_function_security_summary Hash function security summary (Wikipedia)].

Generally speaking, the swap partition should use a fast cipher. You want to lower the latency or delay of the memory subsystem as a consequence of being encrypted.

'''IMPORTANT:''' Please read the [[Setting_up_a_laptop#Important_notes | Important notes]] section for details about the problems with AES encryption.

If you don't trust AES shills and it's NSA endorsement, you can try another different one. Another advantage of using a public vetted cipher is that it provides confidence that it works.

Something like KHAZAD wouldn't work on <code>cryptsetup benchmark</code>. KHAZAD itself is insecure. Wikipedia reported 5 out of 8 rounds been cracked.[https://en.wikipedia.org/wiki/KHAZAD]

For AES-128 7 out of 10, AES-192 8 out of 12, AES-256-bit 9 out 14 rounds have been cracked according to Wikipedia.[https://en.wikipedia.org/wiki/Advanced_Encryption_Standard]

'''IMPORTANT: Do not use sha1 as the hashing algorithm.''' It already has been compromised.

=== Getting the available ciphers ===

To check the availability of a cipher or hash function use:
find /lib/modules/* -type f -path "*/crypto/*.ko" -exec basename {} \; | sort

To check if a cipher is loaded and passed its own tests use:
cat /proc/crypto

To test some popular ciphers and hashes do:

cryptsetup benchmark

The top set is associated with the hashing algorithms. The bottom set are the ciphers. Use the commands below but replace the cipher and/or hash algorithm with your preferences.

<code>cryptsetup benchmark</code> actually doesn't show all the ciphers like Anubis. The cipher should also have CBC and/or XTS block cipher mode of operation to encrypt larger block sizes. AES for example has a block size of 128.

To test if the unpopular but uncracked cipher works use sometime like:
cryptsetup benchmark --cipher anubis

=== General steps for cryptsetup ===

==== Original method with fdisk with no plausible deniability ====

In this method <code>--type luks</code> is implied which generates metadata.

If you want plausible deniability for luks, you need to pass <code>--header <path></code> to all the luks commands, where <code><path></code> is a unix path like /mnt/usb/d6ae10eda66704c8. The random name comes from <code>openssl rand -hex 8</code>. The header is transferred to the external device (but no mention of the key slot area but ciphertext being transferred) in the man page. The information in that file should be obfuscated with encryption if there is plaintext or fingerprint in it just in case. Then, it should be decrypted when reused.

You need to install cfdisk if you prefer the interactive ncurses console method:

apk add cfdisk

{|| cellpadding="5" border="1" class="wikitable"
!#
!Step
!Command
|-
| 1
| Use cfdisk to create partitions. Make two partitions--a system partition and a swap partition
| <code><nowiki>cfdisk</nowiki></code>
|-
| 2
| Create and format the luks device
| <code><nowiki>cryptsetup --cipher aes-cbc-essiv:sha256 --key-size 256 luksFormat /dev/sda1 /mnt/usb/$(ls)</nowiki></code>
|-
| 3
| Open the luks device
| <code><nowiki>cryptsetup --key-file /mnt/usb/$(ls) luksOpen /dev/sda1 root</nowiki></code>
|-
| 4
| Format the decrypted drive with filesystem
| <code>mkfs.ext4 /dev/mapper/root</code>
|-
| 5
| Create the mount point
| <code>mkdir -p /mnt/root</code>
|-
| 6
| Mount the root partition
| <code>mount /dev/mapper/root /mnt/root</code>
|-
| 7
| Create swap
| cryptsetup -c blowfish -h sha256 -d /dev/urandom --key-file /mnt/usb/59022506d9f4a714 create swap /dev/sda2
|-
| 8
| Use swap
| mkswap /dev/mapper/swap && swapon /dev/mapper/swap
|}

==== Improved method with plausible deniability ====

This method requires lvm2. To install:

apk add lvm2

{|| cellpadding="5" border="1" class="wikitable"
!#
!Step
!Command
|-
| 1
| Grab the previously generated key file's path. It is the one with non-zero size. Store it in a variable, e.g. <code><nowiki>KEYFILE</nowiki></code>
| <code><nowiki>ls -l /mnt/usb/</nowiki><code>
|-
| 2
| Open the ''plain dm-crypt'' device generating no metadata
| <code><nowiki>cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --key-file /mnt/usb/$KEYFILE /dev/sda pvroot</nowiki></code>
|-
| 3
| Physical volume create with LVM
| <code><nowiki>pvcreate /dev/mapper/pvroot</nowiki></code>
|-
| 4
| Volume group create with LVM
| <code><nowiki>vgcreate vgroot /dev/mapper/pvroot</nowiki></code>
|-
| 5
| Logical volume create the swap volume with LVM. Remember to replace 4G with your actual RAM size.
| <code><nowiki>lvcreate -L 4G vgroot -n swap</nowiki></code>
|-
| 6
| Logical volume create the root volume with LVM. Also replace 2T with your physical volume size.
| <code><nowiki>lvcreate -L 2T vgroot -n root</nowiki></code>
|-
| 7
| Logical volume create the rescue volume with LVM
| <code><nowiki>lvcreate -L 110M vgroot -n rescue</nowiki></code>
|-
| 8
| Format the root volume with filesystem
| <code>mkfs.ext4 /dev/mapper/vgroot-root</code>
|-
| 9
| Format the swap volume and activate it
| <code>mkswap /dev/mapper/vgroot-swap && swapon /dev/mapper/vgroot-swap</code>
|-
| 10
| Format the rescue volume with filesystem
| <code>mkfs.ext4 /dev/mapper/vgroot-rescue</code>
|-
| 11
| Create mount point for root volume
| <code>mkdir -p /mnt/root</code>
|-
| 12
| Mount the root volume
| <code>mount /dev/mapper/vgroot-root /mnt/root</code>
|-
|}

=== Configuring OpenRC dmcrypt and setting up fstab ===

You need to tell OpenRC init scripts to decrypt the volumes. See <code>/etc/conf.d/dmcrypt</code>.

You need to add the service to boot well because it needs to decrypt the root volume before OpenRC starts running commands from it. So you need to do:

rc-update add dmcrypt boot

==== dmcrypt ====
The dmcrypt OpenRC service will attempt to decrypt the drive using information provided in ''/etc/conf.d/dmcrypt''.

For ''luks'':

{{Cat|/etc/conf.d/dmcrypt|<nowiki>
# Mounting root may not be necessary since it is already mounted.
target=root
source='/dev/sda1'
key='/mnt/usb/2a667ec72774b0d5'

swap=swap
source='/dev/sda2'
key='/mnt/usb/59022506d9f4a714'
</nowiki>}}

For ''plain dm-crypt'':

{{Cat|/etc/conf.d/dmcrypt|<nowiki>
# Mounting root is likely not required since you already mounted it before OpenRC starts to do its thing.
target=root
source='/dev/sda'
key='/mnt/usb/2a667ec72774b0d5'
options='--type plain --cipher aes-cbc-essiv:sha256 --key-size 256'

swap=swap
source='/dev/sda2'
key='/mnt/usb/59022506d9f4a714'
pre_mount='vgchange -ay vgroot ; lvchange -ay vgroot/swap'
</nowiki>}}

dm-crypt will just mount the encrypted ''plain dm-crypt'' drive or the ''luks'' partition. What you need to do next is set up fstab located at /etc/fstab. Examples are shown below.

==== /etc/fstab ====

To mount ''plain dm-crypt'' device with fstab:

{{Cat|/etc/fstab|
/dev/sdb /boot ext4 defaults 0 0
/dev/mapper/root / ext4 defaults 0 1
/dev/mapper/swap none swap sw 0 0
}}

To mount ''lvm'' volumes with fstab:

{{Cat|/etc/fstab|
/dev/sdb /boot ext4 defaults 0 0
/dev/mapper/vgroot-root / ext4 defaults 0 1
/dev/mapper/vgroot-swap none swap sw 0 0
}}

=== How to recover from a bad setup ===

Many times you will not get it right perfectly the first try. To recover from this situation, you need to reopen the ''plain dm-crypt'' drive or the ''luks'' drive and then remount everything back.

To recover from ''luks'':
cryptsetup --key-file /mnt/usb/2a667ec72774b0d5 luksOpen /dev/sda1 root
mkdir -p /mnt/root
mount /dev/mapper/root /mnt/root

To recover from the ''plain dm-crypt'':
cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --key-file /mnt/usb/$(ls) /dev/sda root
vgchange -ay vgroot
lvchange -ay vgroot/root
mkdir -p /mnt/root
mount /dev/mapper/vgroot-swap /mnt/root

== Next step: Full blown Alpine installation ==

We will setup the /mnt/root encrypted partition:
apk add --root=/mnt/root --initdb $(cat /etc/apk/world) --keys-dir /etc/apk/keys --repositories-file /etc/apk/repositories

Then, enable edge repositories in both files including community and testing:
nano /etc/apk/repositories /mnt/root/etc/apk/repositories

Then, copy the necessary files:
cp /etc/resolv.conf /mnt/root/etc

Then, install the basic utils:
apk add --root=/mnt/root dhcpcd chrony networkmanager wireless-tools wpa_supplicant
apk add --root=/mnt/root grub mkinitfs e2fsprogs grub-bios grub-efi
apk add --root=/mnt/root sudo nano
apk add --root=/mnt/root linux-lts

Then, you need to mount your usb on to /boot:
mount /dev/sdb /boot

Edit grub:
nano /boot/grub/grub.cfg

Then, install grub on the usb:
grub-install --force /dev/sdb

Then, prepare chroot:
mount --bind /dev /mnt/root/dev
mount --bind /sys /mnt/root/sys
cp /etc/reslov.conf /mnt/root/etc

Then, chroot:
chroot /mnt/root /bin/sh

Set the root administrator password:
passwd

The root password should be very difficult to deter you from using it and force you to use sudo

Edit sudo so that wheel group has administrative :
EDITOR=nano visudo

Set:
## Uncomment to allow members of group wheel to execute any command
%wheel ALL=(ALL) ALL

Then, add wheel (administrator) user:
useradd -m myname
usermod -a -G video,audio,wheel myname

log in that user:
su myname

Then, update and upgrade it
sudo apk update
sudo apk upgrade

Then, setup xorg:
sudo setup-xorg-base
sudo apk search xf86-video | sort
# pick your xf86 video driver
sudo apk add xf86-video-amdgpu
# install the mesa driver
sudo apk add mesa-dri-gallium

Then, keep piling on:
sudo apk add firefox dwm xfce4-terminal alsa-utils keepassx xfce4 xchat
sudo apk add font-noto-emoji font-terminus leafpad xsetroot # See [[Emojis]] to complete installation
sudo apk add xf86-input-libinput # or -evdev if libinput doesn't work

Then, set the desktop:
nano .xinitrc

Put both but comment with a # one of them if you don't want it,
#while true; do xsetroot -name "$( date +"%a %b %d %I:%M:%S %Y" )" ; sleep 1; done &
#exec dwm
exec xfce4-session

For the above xsetroot statement used to provide information in the statusbar for dwm, consider adding information about the battery level. This information can be found in sysfs at /sys/class/power_supply/BAT0/.

sync
sudo reboot

== Hacking mkinitfs to support cryptsetup with GPG keys ==

This section describes how to assemble a custom initscript chain in multiple parts. It could be extended with three-factor authentication which adds biometrics along side with mind and physical object.

Most entry to secure systems are not fully automated or do not allow things to quickly pass through freely and often guarded. This process may seem like a hassle, but it should dissuade the rubberhosers from jumping to the conclusion of the possibility of the existence of a encrypted drive.

Here is the steps required so that the facade initscripts and dependencies are free from encryption.
* You will separate and archive cryptsetup, ciphers kernel modules, hash function kernel modules, and any additional obfuscation dependencies, and another continuation initscript discussed below. You need to make sure that you copy /etc/mkinitfs/mkinitfs.conf to your home directory and strip out those features without those modules.
* You will hide this archive in a mp3 file with another tool you will package or you can use steghide's .au/.wav support, but .au seems too conspicuous or strange by current trends.

Here we try to clean up the facade so that it presents itself as free without cryptography. You need the following changes to your initramfs to avoid a sensitive rubberhoser:
* You will delete everything in the custom initramfs-init referring to encryption. This includes cryptroot, cryptdm, crypt-anything, etc init options.
* You need to delete references in nlplug-findfs to cryptsetup and recompile the mkinitfs package.
* You could program the init script to boot into a facade partition but drop into sh if a hidden special keypress sequence is met.

You need to create a custom init continuation script:
* Your initscript should drop into single mode which you will mount the encrypted path manually.
* You will manually steg-unhide the encrypted archive hidden in the mp3 file and extract it to the ramdisk.
* You will run the custom init continuation script manually.
* This custom init continuation will automate the process of extracting the gpg keys from another device and image files into the ramdisk. This will then automate the mounting of the encrypted drive. This resume continuation script should handle both cold boot and hibernate.
* You will finish resuming running the other half of mkinitfs-init or specifically where the points after where it typically will mount cryptsetup and hibernate devices.

If you use a USB keyboard, you will unlock the encrypted devices in early userspace. You will need to either compile the USB keyboard drivers in the kernel or you need to add additional modules when generating the mkinitfs. You will need the hid, hid-generic, ehci-hcd, uhci-hcd, usbcore driver and add those paths in a customized <code>/etc/mkinitfs/features.d/usb-keyboard.modules</code>. It should be separate from usb.modules because apk updates may overwrite it. Use the <code>lsmod</code> utility from the kmod package to find what drivers your USB keyboard uses.

You need to generate the final mkinitfs.
First you need the kernelversion to pass into mkinitfs. To obtain that information do <code>ls /lib/modules</code> which will show some folders. Once you found it pass it to mkinitrafs by doing and replacing kernelversion below:

sudo mkinitramfs -i $HOMEDIR/initramfs-init -c "$HOMEDIR"/mkinitfs.conf kernelversion

The $HOMEDIR should be replaced with the full path if you are not root.

== Install the bootloader in the USB thumb drive ==

To install grub, you need to install grub on the ramdisk first on the host.

apk add grub

To get a list of partitions

fdisk -l

Mount the boot partition in /boot

mount /dev/sdb /boot

Make changes to grub's configuration

nano /boot/grub/grub.cfg

'''You need to customize the initramfs in order to use GPG keys since there is no support from it.'''

The steps here below assumes that these custom initramfs features have been implemented.

The following boot loader settings is '''not sufficient''' for deniable encryption because it exposes the fact that an encrypted drive exists because an attacker can discover that encryption was used through the edit option of the grub menu. To protect yourself from a rubberhose attack, you really need to customize the initramfs so that references to anything mentioning encryption, ciphers, hashing are not explicitly mentioned. These configurations should be considered an intermediate form for used in debugging purposes. In addition, the attacker just can inspect grub.cfg files directly.

The following are just examples to just get it working but should be modified so that it doesn't hint to the rubberhoser of a hidden partition or encrypted partitions.

The entry should look like:

For 'luks'

{{cat|/boot/grub/grub.cfg|<nowiki>
default=0
timeout=0

menuentry 'Windows 10' {
set root=(hd0,2)
chainloader +1
}

menuentry 'Alpine Linux' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/root rw modules=sd-mod,usb-storage,ext4,dm-crypt,aes-x86_64,sha256-mb cryptroot=/dev/sda1 cryptdm=root
initrd /initramfs-hardened
}

menuentry 'Alpine Linux (Rescue)' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/root rw modules=sd-mod,usb-storage,ext4,dm-crypt,aes-x86_64,sha256-mb cryptroot=/dev/sda4 cryptdm=root
initrd /initramfs-hardened
}

if keystatus; then
if keystatus --ctrl; then
set timeout=-1
else
set timeout=0
fi
fi
</nowiki>}}

For 'plain dm-crypt':

The stock mkinitfs may not support plain dm-crypt. It looks like it only supports luks. Customization of the initramfs is required.

{{cat|/boot/grub/grub.cfg|<nowiki>
default=0
timeout=0

menuentry 'Windows 10' {
set root=(hd0,2)
chainloader +1
}

menuentry 'Alpine Linux' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/vgroot-root rw modules=sd-mod,usb-storage,ext4,dm-crypt,dm-mod,dm-snapshot,aes-x86_64,sha256-mb cryptroot=/dev/sda cryptdm=root
initrd /initramfs-hardened
}

menuentry 'Alpine Linux (Rescue)' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/vgroot-rescue rw modules=sd-mod,usb-storage,ext4,dm-crypt,dm-mod,dm-snapshot,aes-x86_64,sha256-mb cryptroot=/dev/sda cryptdm=rescue
initrd /initramfs-hardened
}

if keystatus; then
if keystatus --ctrl; then
set timeout=-1
else
set timeout=0
fi
fi
</nowiki>}}

The source code of grub could possibly be modified and recompiled to use other non-standard keys. See [https://github.com/lemenkov/grub2/blob/master/grub-core/commands/keystatus.c]. Ideally, it should be not so obvious or accessible for the attacker.

The above grub.cfg is applied to the USB bootloader. For the facade bootloader, you just want the Windows 10 or Ubuntu entry, nothing more.

For the modules parameter, you need to add your crypto modules.
Use <code>find /lib/modules/ -name "*aes*"</code> where aes is the basename for your cipher or hash algorithm
Use <code>blkid</code> to obtain the UUID of your device

Install it to your USB thumb drive

grub-install /dev/sdb

== Home mounting with eCryptfs ==

We use eCryptfs to encrypt home. The rationale for having another encrypted file system is that if you leave your laptop unattended on break or accidentally leave your USB key in, your data will not be accessible. The other rationale is that if another person wants to use your computer, you can just log off and the data will be kept hidden and encrypted. When you log off due to inactivity, your home directory will be unmounted and encrypted. eCryptfs will encrypt/decrypt the filename and the contents and will sit on top of ext4 which sits on top of luks.

To install ecryptfs-utils:

sudo apk add ecryptfs-utils

This does one factor authentication mostly with just the password, but it should be modified to use the USB key too. You need to reconfigure pam with the pam_usb.so which is not in Alpine aports.

You need to use the pam_ecryptfs PAM module.

== Locking it down ==

Many times you will leave your laptop behind with people you trust. The following tools will help lock down the system.

=== physlock ===

This will auto lock the tty and when you return will prompt for password.

To install physlock:

sudo apk add physlock

It is currently bugged. See [https://bugs.alpinelinux.org/issues/3282]. physlock likely doesn't do two-factor authentication but it should.

You need to create custom script that will monitor idle time in TTY then call physlock. You load this script when you log on.

=== xscreensaver ===

This will lock you out of xserver

To install xscreensaver:

sudo apk add xscreensaver

=== USB key udev rule ===

You need to add a new [[udev]] rule that will suspend-to-ram or hibernate and log off once you pull the USB key. When you come back on, you should do 2 factor authentication to restore back everything. Hibernation and suspend-to-ram might mitigate cold-boot attack (but unlikely see notes at the bottom of the page) to extract plaintext private data and encryption keys in memory.

To find out the details of your USB do:

udevadm monitor --udev -p

The output should look like:

<pre>
UDEV [181762.722853] add /devices/pci0000:00/0000:00:13.2/usb2/2-5/2-5:1.0/host6/target6:0:0/6:0:0:0/block/sdc (block)
ACTION=add
DEVLINKS=/dev/disk/by-id/usb-Kingston_MSFT_NORB_MSFTLAKDA300EB3021790009-0:0 /dev/disk/by-path/pci-0000:00:13.2-usb-0:5:1.0-scsi-0:0:0:0 /dev/disk/by-uuid/5A96-03E4
DEVNAME=/dev/sdc
DEVPATH=/devices/pci0000:00/0000:00:13.2/usb2/2-5/2-5:1.0/host6/target6:0:0/6:0:0:0/block/sdc
DEVTYPE=disk
ID_BUS=usb
ID_FS_TYPE=vfat
ID_FS_USAGE=filesystem
ID_FS_UUID=5A96-03E4
ID_FS_UUID_ENC=5A96-03E4
ID_FS_VERSION=FAT32
ID_INSTANCE=0:0
ID_MODEL=MSFT_NORB
ID_MODEL_ENC=MSFT\x20NORB\x20\x20\x20\x20\x20\x20\x20
ID_MODEL_ID=1645
ID_PATH=pci-0000:00:13.2-usb-0:5:1.0-scsi-0:0:0:0
ID_PATH_TAG=pci-0000_00_13_2-usb-0_5_1_0-scsi-0_0_0_0
ID_REVISION=PMAP
ID_SERIAL=Kingston_MSFT_NORB_MSFTLAKDA300EB3021790009-0:0
ID_SERIAL_SHORT=MSFTLAKDA300EB3021790009
ID_TYPE=disk
ID_USB_DRIVER=usb-storage
ID_USB_INTERFACES=:080650:
ID_USB_INTERFACE_NUM=00
ID_VENDOR=Kingston
ID_VENDOR_ENC=Kingston
ID_VENDOR_ID=0951
MAJOR=8
MINOR=32
SEQNUM=2027
SUBSYSTEM=block
USEC_INITIALIZED=1762722168
</pre>

You want to extract the <code>ID_SERIAL_SHORT=MSFTLAKDA300EB3021790009</code> or whatever is associated with your USB thumb drive.

You need pm-utils for ps-suspend. So to install it do:

sudo apk add pm-utils

You will create a udev rules so that when you pull out the USB, it will suspend-to-ram or you can use your own script. To do that create a file with the following contents:

{{Cat|/etc/udev/rules.d/50-usb-thumb-drive.rules|<nowiki>

ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SERIAL_SHORT}=="MSFTLAKDA300EB3021790009", RUN+="/usr/sbin/pm-suspend"

</nowiki>}}

== Extending battery life ==

'''WARNING: If you do not use the proper mitigation for cold boot attack, you are better off auto-shutdowning the laptop instead of using suspend or hibernate.'''

=== ACPI ===

ACPI is a good daemon to use to execute certain scripts when laptop events are triggered.

To install ACPI do:

apk add acpi

The events to pay attention to are:

{| cellpadding="5" border="1" class="wikitable"
! Event
! ACPI Event
! What your script should do
|-
| lid close
|
| log off ttys and suspend-to-ram. ALSA should either set the volume to 0 for the sound card or the sound driver be unloaded. It might be a good idea to kill or mute any music or movie players if the sound loops loudly after lid open.
|-
| lid open
|
| lock all ttys and all xservers should be locked, possibly reinitialize ALSA and the sound system.
|-
| tapped power button
|
| lock all ttys and suspend-to-ram
|-
| held power button
|
| hibernate
|-
| unplugged power
|
| should switch to 'conservative' cpufreq governor at above 25% power ; 'powersave' governor at 25%. set hdparam spindown rate lower.
|-
| plugged power
|
| should switch to 'performance' governor. disable hdparam spindown.
|}

The purpose of the power governor is to regulate the running frequency (GHz) of the processor.

Certain event handlers are are managed through laptop-mode-tools. If you don't want the dependency, then you could write ACPI handler scripts.

<code>acpi_listen</code> can be used to retrieve the event name.

TODO: put scripts below

=== Adjusting the backlight dynamically ===

The backlight may be controlled using sysfs. The setting is a descendant of <code>/sys/class/backlight/</code>. The feature may allow you to echo a value to it. Use trial and error to discover the values.

The adjustment of the backlight should be function of battery life. So if it is like 33% battery life, you want to run it near lowest settings but readable. For 50 percent battery energy maybe 40% light. For 90% battery maybe 75% light.

=== hdparm ===

To install hdparam do:

sudo apk add hdparm

The settings that laptop-mode-tools messes with is the <code>-S</code> or the spindown timeout. It was also hinted that acoustic setting <code>-M</code> is associated with the speed meaning that louder is faster and quieter is slower which could contribute to the amount of energy used or reduced.

Again you want something like laptop-mode-tools or ACPI to dynamically adjust the settings based on ACPI events.

=== laptop-mode-tools ===

This is currently not in aports but worthy mentioning. It should really be packaged. This is a set of scripts to define a power policies. You can manage all the settings in one place here like the hard drive idle spindown time, CPU governor control, dynamic LCD backlight behavior based on running on battery or AC power supply.

=== cpufreqd ===

This is a useful daemon for regulating power.

To install cpufreqd do:

sudo apk add cpufreqd

Make sure you add the service:

sudo rc-update add cpufreqd

=== LCD screen refresh rate ===

The refresh rate sets the maximum framerate. The more frames pushed the more energy consumed on the battery. You want this adjusted dynamically per certain events. For gaming, you want it to be the highest as possible for the laptop and vsync off. For battery use and traveling, you want it capped at 60 FPS/60 Hz or lower but dynamically adjust when you plug in the AC power supply. You can adjust the framerate with xrandr. For movies and YouTube, you want 60FPS and vsync on.

== Hacking the kernel ==

You should refer to the [[Custom Kernel]] page for details.

== Hibernation ==

See [[Custom_Kernel#Hibernation_to_prevent_data_loss|Hibernation to prevent data loss]].

== WiFi management ==

Since you are using WiFi, you need a better WiFi management to quickly find open access WiFi access points. We don't have all day to debug complexities of WiFi settings while away from home.

To install NetworkManager do:

sudo apk add networkmanager

To find WiFi access points use the <code>nmtui</code> ncurses interface.

You also need other programs so install them as well:

apk add wpa-supplicant dhcpcd chrony macchanger wireless-tools iputils

What these programs do:

* wpa-supplicant -- for WPA encryption
* dhcpcd -- for getting a dynamic IP address
* chrony -- for fixing the time with the atomic clock
* wireless-tools -- for additional information
* macchanger -- for protecting against WiFi access discrimination or increased anonymity. (optional)
* iputils -- for the ping command (optional)

You also need to add those services:

rc-update add chronyd
rc-update add wpa_supplicant
rc-update add dhcpcd
rc-update add networkmanager

To start the services manually (or just reboot):

rc-service chronyd start
rc-service wpa_supplicant start
rc-service dhcpcd start
rc-service networkmanager start

== Additional tools ==

=== actkbd ===

To control the sound with fn function keys, you need this daemon. It is currently not in aports. You could override the design and meaning of those keys with your own scripts and utilities. This daemon gives you that freedom.

If your laptop contains a brightness key, you want to set that up with this program. See also [[Setting_up_a_laptop#Adjusting_the_backlight_dynamically | Adjusting the backlight dynamically]].

=== secure-delete ===

Want to prevent cold-boot attack or decrypted keys in memory falling in the wrong hands? This maybe could work who knows? From research from cold boot attack, the data can actually stay in memory in minutes, just enough time for a hacker to copy the contents of the memory to a USB thumb drive.

To install secure-delete do:

sudo apk add secure-delete

smem only works for unused ram.[https://github.com/gordonrs/thc-secure-delete] If you use the vanilla kernel, this may work. If you use grsecurity, it will automatically sanitize memory if you enable it (but not enabled by default in the Alpine hardened kernel) when the memory page is freed.[https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecurity_and_PaX_Configuration_Options#Sanitize_all_freed_memory]

Close all important programs then call smem.

You call smem in your shutdown script or auto-logoff script.

You can call create a OpenRC shutdown script to run smem when most programs and services are closed. This will erase all your sensitive plaintext private data just in case.

You may want to create a wrapper script to call smem after your program closes.

You need to write a custom script that does the following:
* kill all running processes associated with your user account
* auto logoff terminals
* for the last terminal closed including all idle xservers, unmount your user home
* (optional) use smem to wipe all your plaintext private data in memory after all closed programs in case of cold boot attack

=== Sharing presentations over HDMI ===

If you want to use your laptop to share presentation over HDMI connection, you need libxinerama and xrandr.

To install libxinerama and xrandr do:

sudo apk add libxinerama xrandr

== Important notes ==

If you lose or break your USB key, that is it and you cannot decrypt your drive. It would be wise to make a backup of it.

By default, suspend-to-ram or hibernate will not sufficiently clear the AES encryption keys off ram in those phases which would invite a cold boot attack. This has been covered by the TRESOR kernel patch.[https://en.wikipedia.org/wiki/TRESOR][https://www1.cs.fau.de/tresor] This patch hasn't been updated since the 4.x kernel series.[https://www1.cs.fau.de/tresor]. This patch currently only works on 32-bit x86 Linux with SSE and MMX, and on processors with the AES-NI instruction set for x86_64 Linux. TRESOR doesn't work with DMA attack, but it can be mitigated by disabling DMA.[https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.303.3053&rep=rep1&type=pdf] The 32-bit version of TRESOR has only a key size of 128. The AES-NI version of TRESOR has a largest key size of 256 bit. See [[Setting_up_a_laptop#Choosing_ciphers | Choosing ciphers]] for the number of rounds cracked.

Loop-Amnesia works with LoopAES and is only for 64 bit Linux and only supports 128 bit keys but can result in data loss if their recommendations are not followed. [https://moongate.ydns.eu/amnesia.html]

Please read the Wikipedia article on Cold Boot Attack especially the mitigation section.[https://en.wikipedia.org/wiki/Cold_boot_attack] Full disk encryption will not protect your data especially for older hardware if you do not have the proper mitigation (implying not full proof) prerequisites such as a patched kernel, memory scrambling, permanent memory module mounting for example.

If you have a different but fully encrypted device like iPad, you still can be rubberhosed or interrogated with a perfect deniable encrypted laptop. This guide doesn't protect you from that possibility. If you do not want to be rubberhosed, don't possess those devices.

Additional tips to mitigate against a DMA Attack to exfiltrate encryption keys:

Disable DMA in the BIOS and set the password for the BIOS according to Wikipedia.[https://en.wikipedia.org/wiki/DMA_attack]

Blacklist kernel modules that use DMA and any unused expansion modules (FireWire, CardBus, ExpressCard, Thunderbolt, USB 3.0, PCI Express and hotplug modules) that use DMA.

You may need a custom (or customize a) BIOS or use Intel TXT or TPM which will authenticate the boot devices or boot from specific serial numbers not just any. For cold boot attack, it is not required to remove the RAM but to to slow down the rate of decay of the RAM module with liquid air in addition an USB thumb drive containing an encryption key retriever bypassing the operating system.[https://youtu.be/XfUlRsE3ymQ]

[[Category:Installation]]
[[Category:Security]]
[[category: Desktop]]

Setting up a laptop

2026-02-17T10:16:03Z

154pinkchairs: /* Getting the available ciphers */ cleaner find oneliner

This guide is about a project to create a '''secured laptop'''. For this project we take in consideration ways to extend battery life. It covers tools and daemons that are must haves for a laptop setup.
{{Todo|Instructions given in the page needs testing. Please help test section by section or the entire page. If individual sections have been tested, please update the Talkpage or please move/place this notice in the untested section(s) alone.}}

== Guide features ==

*Deniable full disk encryption
*Two factor authentication (physical object (USB key), mind)
*Encrypted swap and hibernation
*Encrypted home on top of encrypted drive
*Memory sanitation
*Dynamic power modes
*Feature keys support

== Rubberhose Attack ==

Just a reminder that all attacks are subjected to the Rubberhose Attack dilemma, you either give up your encryption keys or be tortured with a rubberhose with the possibly of death. See [https://en.wikipedia.org/wiki/Rubber-hose_cryptanalysis Wikipedia article]. We try to present [https://en.wikipedia.org/wiki/Deniable_encryption deniable encryption (Wikipedia)] to avoid a rubberhose attack scenario. In this article we use the words plausible deniability interchangeably with deniable encryption. To achieve this we use a facade and require no metadata fingerprints to expose or hint of encrypted or hidden containers or hint as in detect of existence of an encrypted disk. The keys should be stored using steganography where we dilute the randomness into the facade. It also requires you not to brag about encryption or mention it because that is an invitation for the attacker to torture the victim. Deniable encryption requires you not put encrypted as an entry title to your bootloader. There shouldn't be an entry for your facade bootloader to the encrypted drive.

== Why full disk? ==

The full disk encryption provides sort of some plausible deniability or a valid alibi that you didn't encrypt it. Is the drive just random noise, broken, or is it really encrypted? The other reason is that it implies that everything is protected.

But there could be problems if not done right. For example, cryptsetup does leave a plaintext marking or some hints by default that it has been encrypted when using luks/luks2 mode if a detached header with option <code>--header <path></code> is not presented.[https://www.lisenet.com/2013/luks-add-keys-backup-and-restore-volume-header/][https://man7.org/linux/man-pages/man8/cryptsetup.8.html] To gain credibility that we didn't really do the encryption, you have to wipe the +3 MiB region based on the number of key slots used; or store the headers on an external device.

If you did deniable encryption incorrectly, it is possible to erase and restore the header. This presents an opportunity to improve obfuscation. When you pull out the USB key, it should erase the header but store it on the USB key atomically as in completely. If you plug in the USB key, it will restore back the header. cryptsetup has luks actions luksHeaderBackup and luksHeaderRestore to do this.

== Starting at the beginning ==

Grab a USB thumb drive with Alpine. Set it up as usual but don't let it touch your drive yet. Then, install all the tools into memory ramdisk but not in the hard drive yet. The hard drive will be obliterated.

You will then install Alpine using the steps:

First you need WiFi, to get it run do the command below but say no or skip the hard drive setup stuff:

setup-alpine

Then, you need to install some tools into RAM temporarly:
apk add e2fsprogs grub grub-bios grub-efi mkinitfs nano

== Randomizing the drive with pseudorandom urandom entropy ==

The first part is to erase the drive with random noise but in practical time. There are many techniques to do this but should be done in one day or two minimum.

You can use shred or dd to accomplish this depending on your needs and the availability of entropy. Some techniques take longer. Cryptologist Bruce Schneier recommended 7 times with specified pattern. See [https://en.wikipedia.org/wiki/Data_erasure Wikipedia Article]. For practical purposes, we just do it random in one pass. It should be random so that the facade of random noise hides the encrypted data which resembles noise.

To list the drives on the system do <code>fdisk -l</code>.

'''IMPORTANT: make sure you wipe the right specific drive.'''

To wipe the disk with random entropy do:

dd if=/dev/urandom of=/dev/sda

== Creating GPG keys ==

'''As of this time, Alpine's mkinitfs does only one factor authentication with passphrase.''' You need to manually edit the initramfs-init.in in mkinitfs to support two factor authentication using cryptsetup.

After you have scrambled the drive, you want to create your GPG keys. You will use these keys to set the password(s) for your cryptsetup-luks partitions. These keys should be stored on a USB thumb drive or other memory device but should not be on the USB boot thumb drive or on the encrypted drive. The key should be a random 128 bit key wrapped in GPG and protected with a password.

If you are using x, you need to do <code>sudo apk add pinentry-gtk</code> to display password prompt properly for the next step.

To install openssl and gpg do:

apk add openssl gnupg

Then, to generate a key:

export GPG_TTY=$(tty) && openssl rand -base64 512 | gpg --symmetric --cipher-algo aes --armor > /mnt/usb/$(openssl rand -hex 12)

(Make sure your usb is mounted on /mnt/usb first.)

The long file name comes from <code>openssl rand -hex 12</code> so that we enhance plausible deniability. The attacker cannot determine the purpose of the key. Is it used for GitHub? for Email?

The first part will produce 512 random bytes in wrap it in base64. The random data will be piped to gpg which will wrap it in AES as ciphertext which again gets wrapped in base64 ascii armor. For every partition including swap in some cases, you should create more gpg keys and store them in your USB thumb drives. After you have produced your gpg keys, you will then use them as a password for cryptsetup/luks.

You can replace aes above with the ones listed in <code>gpg --version</code>.

There should be a password generated for the swap. This is to resume for your hibernate. If you don't want to hibernate, then password is not required and all you need to do is to create/format the partition each time you boot without a password or with a one time random password.

== Hiding the keys using steganography ==

''WARNING:'' This section is considered experimental. It requires the tool and the dependencies to be placed on another USB separate from the key files, the bootloaders, and encrypted disks. The tool and dependencies need to be packaged together. We decentralize these components so that the attacker doesn't connect the dots easily or immediately jumps to the conclusion for the requirements to decrypt. Steghide automatically uses 128-bit AES in CBC mode to encrypt data. This can be change if you don't like or trust AES with the -e option. Use <code>steghide encinfo</code> for other ciphers and modes.

Fortunately, Alpine has a package for steganography called steghide (in the optional edge/testing repository as of February 2026). To install steghide do:

echo "http://dl-cdn.alpinelinux.org/alpine/edge/testing" >> /etc/apk/repositories
apk add steghide

You will place the keyfile in an image file. The facade image file should be large enough that there is no apparent discernible difference between the original and the modified. Do not use a small image with a small filesize.

As mentioned previously luks headers could be 3MB large or more and an jpeg image file is not suitable. Use another format like .au/.wav or another steganography utility that handles mp3s. The mp3/wav should be fairly large enough to dilute the header. So, something with long content is suitable.

There are two basic commands to use with steghide embed and extract,

To embed do:

steghide embed -ef key.gpg -cf image.jpg

To extract do:

steghide extract -xf key.gpg -sf image.jpg

To get a file list of files to ship out, use:

apk info -L libgcc libmcrypt libmhash libstdc++ libjpeg-turbo steghide

== Full disk encryption with with cryptsetup-luks volumes ==

=== Partitioning scheme ===

This section presents a conceptual layout. It should not be a knee-jerk approval to automatically use the partition tool which would compromise your plausible deniability.

For the facade, we use an Ubuntu Live CD (or less skilled distro) to present the impression that we are not sophisticated or tech savvy enough to implement encryption. Windows is also acceptable even better. The immutable Live CD and immutable partition ensures that you are not compromised by a third party attacker that implants evidence.

There could be possibly two bootloaders, one for the facade and the other to the encrypted drive stored on an external device.

==== Luks ====

Plausible deniability only works if you can demonstrate no existence of partitions 2, 3, 4 and no fingerprints/plaintext introduced by cfdisk and cryptsetup-luks. Use something like TestDisk, fdisk -l, or gparted and a disk editor (hex editor for disks).

{| cellpadding="5" border="1" class="wikitable"
!#
!Name
!Mount point
!Notes
|-
| 1
| facade
| /
| (optional) The facade partition contains a pristine normal operating system or Ubuntu Live CD image to lure the attacker in attempt to boost the confidence of the attacker convincing them that there is no encryption on the device.
|-
| 2
| swap
|
| It should be the same size as your ram for x86_64. Rationale: it should contain the whole ram image.
|-
| 3
| root
| /
|
|-
| 4
| rescue
| /
| This should contain the Alpine image.
|-
|}

==== Plain dm-crypt ====

Plausible deniability only works if you are able to present #2 as being unused space or untampered. To check use something like TestDisk, gparted and a disk editor (hex editor for disks).

{| cellpadding="5" border="1" class="wikitable"
!#
!Name
!Mount point
!Notes
|-
| 1
| facade
| /
| (optional) The facade partition contains a pristine normal operating system or Ubuntu Live CD image to lure the attacker in attempt to boost the confidence of the attacker convincing them that there is no encryption on the device.
|-
| 2
| vgroot
|
|
|-
| 2_1
| vgroot-root
| /
|
|-
| 2_2
| vgroot-swap
|
| It should be the same size as your ram for x86_64. Rationale: it should contain the whole ram image.
|-
| 2_3
| vgroot-rescue
| /
| This should contain the Alpine image.
|-
|}

=== Installing cryptsetup ===

To install cryptsetup you need the package below

apk add cryptsetup

=== Choosing ciphers ===

When you create your luks drives, you need to decide on the type of ciphers and hashing techniques to use. The ciphers that you want to use are ones are up to you, but it should be one that is hasn't been cracked yet or has not suffered a lot of cryptanalysis attacks. The ones that you might want to use is AES which is hardware accelerated in some Intel CPUs that have the AES-NI cpuflag which you can check by <code>cat /proc/cpuinfo</code>. Also consider the ciphers that are SIMD optimized such as serpent and twofish that are available in the Linux kernel. Also consider ciphers that are unpopular but known to be secure such as Blowfish (which Wikipedia claims to be attacked and the author recommended Twofish).[https://en.wikipedia.org/wiki/Cipher_security_summary] If it is hardware accelerated, it will save battery life and minimize CPU usage.

For some ciphers weakness also see [https://en.wikipedia.org/wiki/Cipher_security_summary Cipher security summary (Wikipedia)].

For some hash function weaknesses also see [https://en.wikipedia.org/wiki/Hash_function_security_summary Hash function security summary (Wikipedia)].

Generally speaking, the swap partition should use a fast cipher. You want to lower the latency or delay of the memory subsystem as a consequence of being encrypted.

'''IMPORTANT:''' Please read the [[Setting_up_a_laptop#Important_notes | Important notes]] section for details about the problems with AES encryption.

If you don't trust AES shills and it's NSA endorsement, you can try another different one. Another advantage of using a public vetted cipher is that it provides confidence that it works.

Something like KHAZAD wouldn't work on <code>cryptsetup benchmark</code>. KHAZAD itself is insecure. Wikipedia reported 5 out of 8 rounds been cracked.[https://en.wikipedia.org/wiki/KHAZAD]

For AES-128 7 out of 10, AES-192 8 out of 12, AES-256-bit 9 out 14 rounds have been cracked according to Wikipedia.[https://en.wikipedia.org/wiki/Advanced_Encryption_Standard]

'''IMPORTANT: Do not use sha1 as the hashing algorithm.''' It already has been compromised.

=== Getting the available ciphers ===

To check the availability of a cipher or hash function use:
find /lib/modules/* -type f -path "*/crypto/*.ko" -exec basename {} \; | sort

To check if a cipher is loaded and passed its own tests use:
cat /proc/crypto

To test some popular ciphers and hashes do:

cryptsetup benchmark

The top set is associated with the hashing algorithms. The bottom set are the ciphers. Use the commands below but replace the cipher and/or hash algorithm with your preferences.

<code>cryptsetup benchmark</code> actually doesn't show all the ciphers like Anubis. The cipher should also have CBC and/or XTS block cipher mode of operation to encrypt larger block sizes. AES for example has a block size of 128.

To test if the unpopular but uncracked cipher works use sometime like:
cryptsetup benchmark --cipher anubis

=== General steps for cryptsetup ===

==== Original method with fdisk with no plausible deniability ====

In this method <code>--type luks</code> is implied which generates metadata.

If you want plausible deniability for luks, you need to pass <code>--header <path></code> to all the luks commands, where <code><path></code> is a unix path like /mnt/usb/d6ae10eda66704c8. The random name comes from <code>openssl rand -hex 8</code>. The header is transferred to the external device (but no mention of the key slot area but ciphertext being transferred) in the man page. The information in that file should be obfuscated with encryption if there is plaintext or fingerprint in it just in case. Then, it should be decrypted when reused.

You need to install cfdisk if you prefer the interactive ncurses console method:

apk add cfdisk

{|| cellpadding="5" border="1" class="wikitable"
!#
!Step
!Command
|-
| 1
| Use cfdisk to create partitions. Make two partitions--a system partition and a swap partition
| <code><nowiki>cfdisk</nowiki></code>
|-
| 2
| Create and format the luks device
| <code><nowiki>cryptsetup --cipher aes-cbc-essiv:sha256 --key-size 256 luksFormat /dev/sda1 /mnt/usb/$(ls)</nowiki></code>
|-
| 3
| Open the luks device
| <code><nowiki>cryptsetup --key-file /mnt/usb/$(ls) luksOpen /dev/sda1 root</nowiki></code>
|-
| 4
| Format the decrypted drive with filesystem
| <code>mkfs.ext4 /dev/mapper/root</code>
|-
| 5
| Create the mount point
| <code>mkdir -p /mnt/root</code>
|-
| 6
| Mount the root partition
| <code>mount /dev/mapper/root /mnt/root</code>
|-
| 7
| Create swap
| cryptsetup -c blowfish -h sha256 -d /dev/urandom --key-file /mnt/usb/59022506d9f4a714 create swap /dev/sda2
|-
| 8
| Use swap
| mkswap /dev/mapper/swap && swapon /dev/mapper/swap
|}

==== Improved method with plausible deniability ====

This method requires lvm2. To install:

apk add lvm2

{|| cellpadding="5" border="1" class="wikitable"
!#
!Step
!Command
|-
| 1
| Open the ''plain dm-crypt'' device generating no metadata
| <code><nowiki>cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --key-file /mnt/usb/$(ls) /dev/sda pvroot</nowiki></code>
|-
| 2
| Physical volume create with LVM
| <code><nowiki>pvcreate /dev/mapper/pvroot</nowiki></code>
|-
| 3
| Volume group create with LVM
| <code><nowiki>vgcreate vgroot /dev/mapper/pvroot</nowiki></code>
|-
| 4
| Logical volume create the swap volume with LVM
| <code><nowiki>lvcreate -L 4G vgroot -n swap</nowiki></code>
|-
| 5
| Logical volume create the root volume with LVM
| <code><nowiki>lvcreate -L 2T vgroot -n root</nowiki></code>
|-
| 6
| Logical volume create the rescue volume with LVM
| <code><nowiki>lvcreate -L 110M vgroot -n rescue</nowiki></code>
|-
| 7
| Format the root volume with filesystem
| <code>mkfs.ext4 /dev/mapper/vgroot-root</code>
|-
| 8
| Format the swap volume and activate it
| <code>mkswap /dev/mapper/vgroot-swap && swapon /dev/mapper/vgroot-swap</code>
|-
| 9
| Format the rescue volume with filesystem
| <code>mkfs.ext4 /dev/mapper/vgroot-rescue</code>
|-
| 10
| Create mount point for root volume
| <code>mkdir -p /mnt/root</code>
|-
| 11
| Mount the root volume
| <code>mount /dev/mapper/vgroot-root /mnt/root</code>
|-
|}

=== Configuring OpenRC dmcrypt and setting up fstab ===

You need to tell OpenRC init scripts to decrypt the volumes. See <code>/etc/conf.d/dmcrypt</code>.

You need to add the service to boot well because it needs to decrypt the root volume before OpenRC starts running commands from it. So you need to do:

rc-update add dmcrypt boot

==== dmcrypt ====
The dmcrypt OpenRC service will attempt to decrypt the drive using information provided in ''/etc/conf.d/dmcrypt''.

For ''luks'':

{{Cat|/etc/conf.d/dmcrypt|<nowiki>
# Mounting root may not be necessary since it is already mounted.
target=root
source='/dev/sda1'
key='/mnt/usb/2a667ec72774b0d5'

swap=swap
source='/dev/sda2'
key='/mnt/usb/59022506d9f4a714'
</nowiki>}}

For ''plain dm-crypt'':

{{Cat|/etc/conf.d/dmcrypt|<nowiki>
# Mounting root is likely not required since you already mounted it before OpenRC starts to do its thing.
target=root
source='/dev/sda'
key='/mnt/usb/2a667ec72774b0d5'
options='--type plain --cipher aes-cbc-essiv:sha256 --key-size 256'

swap=swap
source='/dev/sda2'
key='/mnt/usb/59022506d9f4a714'
pre_mount='vgchange -ay vgroot ; lvchange -ay vgroot/swap'
</nowiki>}}

dm-crypt will just mount the encrypted ''plain dm-crypt'' drive or the ''luks'' partition. What you need to do next is set up fstab located at /etc/fstab. Examples are shown below.

==== /etc/fstab ====

To mount ''plain dm-crypt'' device with fstab:

{{Cat|/etc/fstab|
/dev/sdb /boot ext4 defaults 0 0
/dev/mapper/root / ext4 defaults 0 1
/dev/mapper/swap none swap sw 0 0
}}

To mount ''lvm'' volumes with fstab:

{{Cat|/etc/fstab|
/dev/sdb /boot ext4 defaults 0 0
/dev/mapper/vgroot-root / ext4 defaults 0 1
/dev/mapper/vgroot-swap none swap sw 0 0
}}

=== How to recover from a bad setup ===

Many times you will not get it right perfectly the first try. To recover from this situation, you need to reopen the ''plain dm-crypt'' drive or the ''luks'' drive and then remount everything back.

To recover from ''luks'':
cryptsetup --key-file /mnt/usb/2a667ec72774b0d5 luksOpen /dev/sda1 root
mkdir -p /mnt/root
mount /dev/mapper/root /mnt/root

To recover from the ''plain dm-crypt'':
cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --key-file /mnt/usb/$(ls) /dev/sda root
vgchange -ay vgroot
lvchange -ay vgroot/root
mkdir -p /mnt/root
mount /dev/mapper/vgroot-swap /mnt/root

== Next step: Full blown Alpine installation ==

We will setup the /mnt/root encrypted partition:
apk add --root=/mnt/root --initdb $(cat /etc/apk/world) --keys-dir /etc/apk/keys --repositories-file /etc/apk/repositories

Then, enable edge repositories in both files including community and testing:
nano /etc/apk/repositories /mnt/root/etc/apk/repositories

Then, copy the necessary files:
cp /etc/resolv.conf /mnt/root/etc

Then, install the basic utils:
apk add --root=/mnt/root dhcpcd chrony networkmanager wireless-tools wpa_supplicant
apk add --root=/mnt/root grub mkinitfs e2fsprogs grub-bios grub-efi
apk add --root=/mnt/root sudo nano
apk add --root=/mnt/root linux-lts

Then, you need to mount your usb on to /boot:
mount /dev/sdb /boot

Edit grub:
nano /boot/grub/grub.cfg

Then, install grub on the usb:
grub-install --force /dev/sdb

Then, prepare chroot:
mount --bind /dev /mnt/root/dev
mount --bind /sys /mnt/root/sys
cp /etc/reslov.conf /mnt/root/etc

Then, chroot:
chroot /mnt/root /bin/sh

Set the root administrator password:
passwd

The root password should be very difficult to deter you from using it and force you to use sudo

Edit sudo so that wheel group has administrative :
EDITOR=nano visudo

Set:
## Uncomment to allow members of group wheel to execute any command
%wheel ALL=(ALL) ALL

Then, add wheel (administrator) user:
useradd -m myname
usermod -a -G video,audio,wheel myname

log in that user:
su myname

Then, update and upgrade it
sudo apk update
sudo apk upgrade

Then, setup xorg:
sudo setup-xorg-base
sudo apk search xf86-video | sort
# pick your xf86 video driver
sudo apk add xf86-video-amdgpu
# install the mesa driver
sudo apk add mesa-dri-gallium

Then, keep piling on:
sudo apk add firefox dwm xfce4-terminal alsa-utils keepassx xfce4 xchat
sudo apk add font-noto-emoji font-terminus leafpad xsetroot # See [[Emojis]] to complete installation
sudo apk add xf86-input-libinput # or -evdev if libinput doesn't work

Then, set the desktop:
nano .xinitrc

Put both but comment with a # one of them if you don't want it,
#while true; do xsetroot -name "$( date +"%a %b %d %I:%M:%S %Y" )" ; sleep 1; done &
#exec dwm
exec xfce4-session

For the above xsetroot statement used to provide information in the statusbar for dwm, consider adding information about the battery level. This information can be found in sysfs at /sys/class/power_supply/BAT0/.

sync
sudo reboot

== Hacking mkinitfs to support cryptsetup with GPG keys ==

This section describes how to assemble a custom initscript chain in multiple parts. It could be extended with three-factor authentication which adds biometrics along side with mind and physical object.

Most entry to secure systems are not fully automated or do not allow things to quickly pass through freely and often guarded. This process may seem like a hassle, but it should dissuade the rubberhosers from jumping to the conclusion of the possibility of the existence of a encrypted drive.

Here is the steps required so that the facade initscripts and dependencies are free from encryption.
* You will separate and archive cryptsetup, ciphers kernel modules, hash function kernel modules, and any additional obfuscation dependencies, and another continuation initscript discussed below. You need to make sure that you copy /etc/mkinitfs/mkinitfs.conf to your home directory and strip out those features without those modules.
* You will hide this archive in a mp3 file with another tool you will package or you can use steghide's .au/.wav support, but .au seems too conspicuous or strange by current trends.

Here we try to clean up the facade so that it presents itself as free without cryptography. You need the following changes to your initramfs to avoid a sensitive rubberhoser:
* You will delete everything in the custom initramfs-init referring to encryption. This includes cryptroot, cryptdm, crypt-anything, etc init options.
* You need to delete references in nlplug-findfs to cryptsetup and recompile the mkinitfs package.
* You could program the init script to boot into a facade partition but drop into sh if a hidden special keypress sequence is met.

You need to create a custom init continuation script:
* Your initscript should drop into single mode which you will mount the encrypted path manually.
* You will manually steg-unhide the encrypted archive hidden in the mp3 file and extract it to the ramdisk.
* You will run the custom init continuation script manually.
* This custom init continuation will automate the process of extracting the gpg keys from another device and image files into the ramdisk. This will then automate the mounting of the encrypted drive. This resume continuation script should handle both cold boot and hibernate.
* You will finish resuming running the other half of mkinitfs-init or specifically where the points after where it typically will mount cryptsetup and hibernate devices.

If you use a USB keyboard, you will unlock the encrypted devices in early userspace. You will need to either compile the USB keyboard drivers in the kernel or you need to add additional modules when generating the mkinitfs. You will need the hid, hid-generic, ehci-hcd, uhci-hcd, usbcore driver and add those paths in a customized <code>/etc/mkinitfs/features.d/usb-keyboard.modules</code>. It should be separate from usb.modules because apk updates may overwrite it. Use the <code>lsmod</code> utility from the kmod package to find what drivers your USB keyboard uses.

You need to generate the final mkinitfs.
First you need the kernelversion to pass into mkinitfs. To obtain that information do <code>ls /lib/modules</code> which will show some folders. Once you found it pass it to mkinitrafs by doing and replacing kernelversion below:

sudo mkinitramfs -i $HOMEDIR/initramfs-init -c "$HOMEDIR"/mkinitfs.conf kernelversion

The $HOMEDIR should be replaced with the full path if you are not root.

== Install the bootloader in the USB thumb drive ==

To install grub, you need to install grub on the ramdisk first on the host.

apk add grub

To get a list of partitions

fdisk -l

Mount the boot partition in /boot

mount /dev/sdb /boot

Make changes to grub's configuration

nano /boot/grub/grub.cfg

'''You need to customize the initramfs in order to use GPG keys since there is no support from it.'''

The steps here below assumes that these custom initramfs features have been implemented.

The following boot loader settings is '''not sufficient''' for deniable encryption because it exposes the fact that an encrypted drive exists because an attacker can discover that encryption was used through the edit option of the grub menu. To protect yourself from a rubberhose attack, you really need to customize the initramfs so that references to anything mentioning encryption, ciphers, hashing are not explicitly mentioned. These configurations should be considered an intermediate form for used in debugging purposes. In addition, the attacker just can inspect grub.cfg files directly.

The following are just examples to just get it working but should be modified so that it doesn't hint to the rubberhoser of a hidden partition or encrypted partitions.

The entry should look like:

For 'luks'

{{cat|/boot/grub/grub.cfg|<nowiki>
default=0
timeout=0

menuentry 'Windows 10' {
set root=(hd0,2)
chainloader +1
}

menuentry 'Alpine Linux' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/root rw modules=sd-mod,usb-storage,ext4,dm-crypt,aes-x86_64,sha256-mb cryptroot=/dev/sda1 cryptdm=root
initrd /initramfs-hardened
}

menuentry 'Alpine Linux (Rescue)' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/root rw modules=sd-mod,usb-storage,ext4,dm-crypt,aes-x86_64,sha256-mb cryptroot=/dev/sda4 cryptdm=root
initrd /initramfs-hardened
}

if keystatus; then
if keystatus --ctrl; then
set timeout=-1
else
set timeout=0
fi
fi
</nowiki>}}

For 'plain dm-crypt':

The stock mkinitfs may not support plain dm-crypt. It looks like it only supports luks. Customization of the initramfs is required.

{{cat|/boot/grub/grub.cfg|<nowiki>
default=0
timeout=0

menuentry 'Windows 10' {
set root=(hd0,2)
chainloader +1
}

menuentry 'Alpine Linux' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/vgroot-root rw modules=sd-mod,usb-storage,ext4,dm-crypt,dm-mod,dm-snapshot,aes-x86_64,sha256-mb cryptroot=/dev/sda cryptdm=root
initrd /initramfs-hardened
}

menuentry 'Alpine Linux (Rescue)' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/vgroot-rescue rw modules=sd-mod,usb-storage,ext4,dm-crypt,dm-mod,dm-snapshot,aes-x86_64,sha256-mb cryptroot=/dev/sda cryptdm=rescue
initrd /initramfs-hardened
}

if keystatus; then
if keystatus --ctrl; then
set timeout=-1
else
set timeout=0
fi
fi
</nowiki>}}

The source code of grub could possibly be modified and recompiled to use other non-standard keys. See [https://github.com/lemenkov/grub2/blob/master/grub-core/commands/keystatus.c]. Ideally, it should be not so obvious or accessible for the attacker.

The above grub.cfg is applied to the USB bootloader. For the facade bootloader, you just want the Windows 10 or Ubuntu entry, nothing more.

For the modules parameter, you need to add your crypto modules.
Use <code>find /lib/modules/ -name "*aes*"</code> where aes is the basename for your cipher or hash algorithm
Use <code>blkid</code> to obtain the UUID of your device

Install it to your USB thumb drive

grub-install /dev/sdb

== Home mounting with eCryptfs ==

We use eCryptfs to encrypt home. The rationale for having another encrypted file system is that if you leave your laptop unattended on break or accidentally leave your USB key in, your data will not be accessible. The other rationale is that if another person wants to use your computer, you can just log off and the data will be kept hidden and encrypted. When you log off due to inactivity, your home directory will be unmounted and encrypted. eCryptfs will encrypt/decrypt the filename and the contents and will sit on top of ext4 which sits on top of luks.

To install ecryptfs-utils:

sudo apk add ecryptfs-utils

This does one factor authentication mostly with just the password, but it should be modified to use the USB key too. You need to reconfigure pam with the pam_usb.so which is not in Alpine aports.

You need to use the pam_ecryptfs PAM module.

== Locking it down ==

Many times you will leave your laptop behind with people you trust. The following tools will help lock down the system.

=== physlock ===

This will auto lock the tty and when you return will prompt for password.

To install physlock:

sudo apk add physlock

It is currently bugged. See [https://bugs.alpinelinux.org/issues/3282]. physlock likely doesn't do two-factor authentication but it should.

You need to create custom script that will monitor idle time in TTY then call physlock. You load this script when you log on.

=== xscreensaver ===

This will lock you out of xserver

To install xscreensaver:

sudo apk add xscreensaver

=== USB key udev rule ===

You need to add a new [[udev]] rule that will suspend-to-ram or hibernate and log off once you pull the USB key. When you come back on, you should do 2 factor authentication to restore back everything. Hibernation and suspend-to-ram might mitigate cold-boot attack (but unlikely see notes at the bottom of the page) to extract plaintext private data and encryption keys in memory.

To find out the details of your USB do:

udevadm monitor --udev -p

The output should look like:

<pre>
UDEV [181762.722853] add /devices/pci0000:00/0000:00:13.2/usb2/2-5/2-5:1.0/host6/target6:0:0/6:0:0:0/block/sdc (block)
ACTION=add
DEVLINKS=/dev/disk/by-id/usb-Kingston_MSFT_NORB_MSFTLAKDA300EB3021790009-0:0 /dev/disk/by-path/pci-0000:00:13.2-usb-0:5:1.0-scsi-0:0:0:0 /dev/disk/by-uuid/5A96-03E4
DEVNAME=/dev/sdc
DEVPATH=/devices/pci0000:00/0000:00:13.2/usb2/2-5/2-5:1.0/host6/target6:0:0/6:0:0:0/block/sdc
DEVTYPE=disk
ID_BUS=usb
ID_FS_TYPE=vfat
ID_FS_USAGE=filesystem
ID_FS_UUID=5A96-03E4
ID_FS_UUID_ENC=5A96-03E4
ID_FS_VERSION=FAT32
ID_INSTANCE=0:0
ID_MODEL=MSFT_NORB
ID_MODEL_ENC=MSFT\x20NORB\x20\x20\x20\x20\x20\x20\x20
ID_MODEL_ID=1645
ID_PATH=pci-0000:00:13.2-usb-0:5:1.0-scsi-0:0:0:0
ID_PATH_TAG=pci-0000_00_13_2-usb-0_5_1_0-scsi-0_0_0_0
ID_REVISION=PMAP
ID_SERIAL=Kingston_MSFT_NORB_MSFTLAKDA300EB3021790009-0:0
ID_SERIAL_SHORT=MSFTLAKDA300EB3021790009
ID_TYPE=disk
ID_USB_DRIVER=usb-storage
ID_USB_INTERFACES=:080650:
ID_USB_INTERFACE_NUM=00
ID_VENDOR=Kingston
ID_VENDOR_ENC=Kingston
ID_VENDOR_ID=0951
MAJOR=8
MINOR=32
SEQNUM=2027
SUBSYSTEM=block
USEC_INITIALIZED=1762722168
</pre>

You want to extract the <code>ID_SERIAL_SHORT=MSFTLAKDA300EB3021790009</code> or whatever is associated with your USB thumb drive.

You need pm-utils for ps-suspend. So to install it do:

sudo apk add pm-utils

You will create a udev rules so that when you pull out the USB, it will suspend-to-ram or you can use your own script. To do that create a file with the following contents:

{{Cat|/etc/udev/rules.d/50-usb-thumb-drive.rules|<nowiki>

ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SERIAL_SHORT}=="MSFTLAKDA300EB3021790009", RUN+="/usr/sbin/pm-suspend"

</nowiki>}}

== Extending battery life ==

'''WARNING: If you do not use the proper mitigation for cold boot attack, you are better off auto-shutdowning the laptop instead of using suspend or hibernate.'''

=== ACPI ===

ACPI is a good daemon to use to execute certain scripts when laptop events are triggered.

To install ACPI do:

apk add acpi

The events to pay attention to are:

{| cellpadding="5" border="1" class="wikitable"
! Event
! ACPI Event
! What your script should do
|-
| lid close
|
| log off ttys and suspend-to-ram. ALSA should either set the volume to 0 for the sound card or the sound driver be unloaded. It might be a good idea to kill or mute any music or movie players if the sound loops loudly after lid open.
|-
| lid open
|
| lock all ttys and all xservers should be locked, possibly reinitialize ALSA and the sound system.
|-
| tapped power button
|
| lock all ttys and suspend-to-ram
|-
| held power button
|
| hibernate
|-
| unplugged power
|
| should switch to 'conservative' cpufreq governor at above 25% power ; 'powersave' governor at 25%. set hdparam spindown rate lower.
|-
| plugged power
|
| should switch to 'performance' governor. disable hdparam spindown.
|}

The purpose of the power governor is to regulate the running frequency (GHz) of the processor.

Certain event handlers are are managed through laptop-mode-tools. If you don't want the dependency, then you could write ACPI handler scripts.

<code>acpi_listen</code> can be used to retrieve the event name.

TODO: put scripts below

=== Adjusting the backlight dynamically ===

The backlight may be controlled using sysfs. The setting is a descendant of <code>/sys/class/backlight/</code>. The feature may allow you to echo a value to it. Use trial and error to discover the values.

The adjustment of the backlight should be function of battery life. So if it is like 33% battery life, you want to run it near lowest settings but readable. For 50 percent battery energy maybe 40% light. For 90% battery maybe 75% light.

=== hdparm ===

To install hdparam do:

sudo apk add hdparm

The settings that laptop-mode-tools messes with is the <code>-S</code> or the spindown timeout. It was also hinted that acoustic setting <code>-M</code> is associated with the speed meaning that louder is faster and quieter is slower which could contribute to the amount of energy used or reduced.

Again you want something like laptop-mode-tools or ACPI to dynamically adjust the settings based on ACPI events.

=== laptop-mode-tools ===

This is currently not in aports but worthy mentioning. It should really be packaged. This is a set of scripts to define a power policies. You can manage all the settings in one place here like the hard drive idle spindown time, CPU governor control, dynamic LCD backlight behavior based on running on battery or AC power supply.

=== cpufreqd ===

This is a useful daemon for regulating power.

To install cpufreqd do:

sudo apk add cpufreqd

Make sure you add the service:

sudo rc-update add cpufreqd

=== LCD screen refresh rate ===

The refresh rate sets the maximum framerate. The more frames pushed the more energy consumed on the battery. You want this adjusted dynamically per certain events. For gaming, you want it to be the highest as possible for the laptop and vsync off. For battery use and traveling, you want it capped at 60 FPS/60 Hz or lower but dynamically adjust when you plug in the AC power supply. You can adjust the framerate with xrandr. For movies and YouTube, you want 60FPS and vsync on.

== Hacking the kernel ==

You should refer to the [[Custom Kernel]] page for details.

== Hibernation ==

See [[Custom_Kernel#Hibernation_to_prevent_data_loss|Hibernation to prevent data loss]].

== WiFi management ==

Since you are using WiFi, you need a better WiFi management to quickly find open access WiFi access points. We don't have all day to debug complexities of WiFi settings while away from home.

To install NetworkManager do:

sudo apk add networkmanager

To find WiFi access points use the <code>nmtui</code> ncurses interface.

You also need other programs so install them as well:

apk add wpa-supplicant dhcpcd chrony macchanger wireless-tools iputils

What these programs do:

* wpa-supplicant -- for WPA encryption
* dhcpcd -- for getting a dynamic IP address
* chrony -- for fixing the time with the atomic clock
* wireless-tools -- for additional information
* macchanger -- for protecting against WiFi access discrimination or increased anonymity. (optional)
* iputils -- for the ping command (optional)

You also need to add those services:

rc-update add chronyd
rc-update add wpa_supplicant
rc-update add dhcpcd
rc-update add networkmanager

To start the services manually (or just reboot):

rc-service chronyd start
rc-service wpa_supplicant start
rc-service dhcpcd start
rc-service networkmanager start

== Additional tools ==

=== actkbd ===

To control the sound with fn function keys, you need this daemon. It is currently not in aports. You could override the design and meaning of those keys with your own scripts and utilities. This daemon gives you that freedom.

If your laptop contains a brightness key, you want to set that up with this program. See also [[Setting_up_a_laptop#Adjusting_the_backlight_dynamically | Adjusting the backlight dynamically]].

=== secure-delete ===

Want to prevent cold-boot attack or decrypted keys in memory falling in the wrong hands? This maybe could work who knows? From research from cold boot attack, the data can actually stay in memory in minutes, just enough time for a hacker to copy the contents of the memory to a USB thumb drive.

To install secure-delete do:

sudo apk add secure-delete

smem only works for unused ram.[https://github.com/gordonrs/thc-secure-delete] If you use the vanilla kernel, this may work. If you use grsecurity, it will automatically sanitize memory if you enable it (but not enabled by default in the Alpine hardened kernel) when the memory page is freed.[https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecurity_and_PaX_Configuration_Options#Sanitize_all_freed_memory]

Close all important programs then call smem.

You call smem in your shutdown script or auto-logoff script.

You can call create a OpenRC shutdown script to run smem when most programs and services are closed. This will erase all your sensitive plaintext private data just in case.

You may want to create a wrapper script to call smem after your program closes.

You need to write a custom script that does the following:
* kill all running processes associated with your user account
* auto logoff terminals
* for the last terminal closed including all idle xservers, unmount your user home
* (optional) use smem to wipe all your plaintext private data in memory after all closed programs in case of cold boot attack

=== Sharing presentations over HDMI ===

If you want to use your laptop to share presentation over HDMI connection, you need libxinerama and xrandr.

To install libxinerama and xrandr do:

sudo apk add libxinerama xrandr

== Important notes ==

If you lose or break your USB key, that is it and you cannot decrypt your drive. It would be wise to make a backup of it.

By default, suspend-to-ram or hibernate will not sufficiently clear the AES encryption keys off ram in those phases which would invite a cold boot attack. This has been covered by the TRESOR kernel patch.[https://en.wikipedia.org/wiki/TRESOR][https://www1.cs.fau.de/tresor] This patch hasn't been updated since the 4.x kernel series.[https://www1.cs.fau.de/tresor]. This patch currently only works on 32-bit x86 Linux with SSE and MMX, and on processors with the AES-NI instruction set for x86_64 Linux. TRESOR doesn't work with DMA attack, but it can be mitigated by disabling DMA.[https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.303.3053&rep=rep1&type=pdf] The 32-bit version of TRESOR has only a key size of 128. The AES-NI version of TRESOR has a largest key size of 256 bit. See [[Setting_up_a_laptop#Choosing_ciphers | Choosing ciphers]] for the number of rounds cracked.

Loop-Amnesia works with LoopAES and is only for 64 bit Linux and only supports 128 bit keys but can result in data loss if their recommendations are not followed. [https://moongate.ydns.eu/amnesia.html]

Please read the Wikipedia article on Cold Boot Attack especially the mitigation section.[https://en.wikipedia.org/wiki/Cold_boot_attack] Full disk encryption will not protect your data especially for older hardware if you do not have the proper mitigation (implying not full proof) prerequisites such as a patched kernel, memory scrambling, permanent memory module mounting for example.

If you have a different but fully encrypted device like iPad, you still can be rubberhosed or interrogated with a perfect deniable encrypted laptop. This guide doesn't protect you from that possibility. If you do not want to be rubberhosed, don't possess those devices.

Additional tips to mitigate against a DMA Attack to exfiltrate encryption keys:

Disable DMA in the BIOS and set the password for the BIOS according to Wikipedia.[https://en.wikipedia.org/wiki/DMA_attack]

Blacklist kernel modules that use DMA and any unused expansion modules (FireWire, CardBus, ExpressCard, Thunderbolt, USB 3.0, PCI Express and hotplug modules) that use DMA.

You may need a custom (or customize a) BIOS or use Intel TXT or TPM which will authenticate the boot devices or boot from specific serial numbers not just any. For cold boot attack, it is not required to remove the RAM but to to slow down the rate of decay of the RAM module with liquid air in addition an USB thumb drive containing an encryption key retriever bypassing the operating system.[https://youtu.be/XfUlRsE3ymQ]

[[Category:Installation]]
[[Category:Security]]
[[category: Desktop]]

Setting up a laptop

2026-02-17T10:03:01Z

154pinkchairs: /* Choosing ciphers */ grammar, duplicate "already"

This guide is about a project to create a '''secured laptop'''. For this project we take in consideration ways to extend battery life. It covers tools and daemons that are must haves for a laptop setup.
{{Todo|Instructions given in the page needs testing. Please help test section by section or the entire page. If individual sections have been tested, please update the Talkpage or please move/place this notice in the untested section(s) alone.}}

== Guide features ==

*Deniable full disk encryption
*Two factor authentication (physical object (USB key), mind)
*Encrypted swap and hibernation
*Encrypted home on top of encrypted drive
*Memory sanitation
*Dynamic power modes
*Feature keys support

== Rubberhose Attack ==

Just a reminder that all attacks are subjected to the Rubberhose Attack dilemma, you either give up your encryption keys or be tortured with a rubberhose with the possibly of death. See [https://en.wikipedia.org/wiki/Rubber-hose_cryptanalysis Wikipedia article]. We try to present [https://en.wikipedia.org/wiki/Deniable_encryption deniable encryption (Wikipedia)] to avoid a rubberhose attack scenario. In this article we use the words plausible deniability interchangeably with deniable encryption. To achieve this we use a facade and require no metadata fingerprints to expose or hint of encrypted or hidden containers or hint as in detect of existence of an encrypted disk. The keys should be stored using steganography where we dilute the randomness into the facade. It also requires you not to brag about encryption or mention it because that is an invitation for the attacker to torture the victim. Deniable encryption requires you not put encrypted as an entry title to your bootloader. There shouldn't be an entry for your facade bootloader to the encrypted drive.

== Why full disk? ==

The full disk encryption provides sort of some plausible deniability or a valid alibi that you didn't encrypt it. Is the drive just random noise, broken, or is it really encrypted? The other reason is that it implies that everything is protected.

But there could be problems if not done right. For example, cryptsetup does leave a plaintext marking or some hints by default that it has been encrypted when using luks/luks2 mode if a detached header with option <code>--header <path></code> is not presented.[https://www.lisenet.com/2013/luks-add-keys-backup-and-restore-volume-header/][https://man7.org/linux/man-pages/man8/cryptsetup.8.html] To gain credibility that we didn't really do the encryption, you have to wipe the +3 MiB region based on the number of key slots used; or store the headers on an external device.

If you did deniable encryption incorrectly, it is possible to erase and restore the header. This presents an opportunity to improve obfuscation. When you pull out the USB key, it should erase the header but store it on the USB key atomically as in completely. If you plug in the USB key, it will restore back the header. cryptsetup has luks actions luksHeaderBackup and luksHeaderRestore to do this.

== Starting at the beginning ==

Grab a USB thumb drive with Alpine. Set it up as usual but don't let it touch your drive yet. Then, install all the tools into memory ramdisk but not in the hard drive yet. The hard drive will be obliterated.

You will then install Alpine using the steps:

First you need WiFi, to get it run do the command below but say no or skip the hard drive setup stuff:

setup-alpine

Then, you need to install some tools into RAM temporarly:
apk add e2fsprogs grub grub-bios grub-efi mkinitfs nano

== Randomizing the drive with pseudorandom urandom entropy ==

The first part is to erase the drive with random noise but in practical time. There are many techniques to do this but should be done in one day or two minimum.

You can use shred or dd to accomplish this depending on your needs and the availability of entropy. Some techniques take longer. Cryptologist Bruce Schneier recommended 7 times with specified pattern. See [https://en.wikipedia.org/wiki/Data_erasure Wikipedia Article]. For practical purposes, we just do it random in one pass. It should be random so that the facade of random noise hides the encrypted data which resembles noise.

To list the drives on the system do <code>fdisk -l</code>.

'''IMPORTANT: make sure you wipe the right specific drive.'''

To wipe the disk with random entropy do:

dd if=/dev/urandom of=/dev/sda

== Creating GPG keys ==

'''As of this time, Alpine's mkinitfs does only one factor authentication with passphrase.''' You need to manually edit the initramfs-init.in in mkinitfs to support two factor authentication using cryptsetup.

After you have scrambled the drive, you want to create your GPG keys. You will use these keys to set the password(s) for your cryptsetup-luks partitions. These keys should be stored on a USB thumb drive or other memory device but should not be on the USB boot thumb drive or on the encrypted drive. The key should be a random 128 bit key wrapped in GPG and protected with a password.

If you are using x, you need to do <code>sudo apk add pinentry-gtk</code> to display password prompt properly for the next step.

To install openssl and gpg do:

apk add openssl gnupg

Then, to generate a key:

export GPG_TTY=$(tty) && openssl rand -base64 512 | gpg --symmetric --cipher-algo aes --armor > /mnt/usb/$(openssl rand -hex 12)

(Make sure your usb is mounted on /mnt/usb first.)

The long file name comes from <code>openssl rand -hex 12</code> so that we enhance plausible deniability. The attacker cannot determine the purpose of the key. Is it used for GitHub? for Email?

The first part will produce 512 random bytes in wrap it in base64. The random data will be piped to gpg which will wrap it in AES as ciphertext which again gets wrapped in base64 ascii armor. For every partition including swap in some cases, you should create more gpg keys and store them in your USB thumb drives. After you have produced your gpg keys, you will then use them as a password for cryptsetup/luks.

You can replace aes above with the ones listed in <code>gpg --version</code>.

There should be a password generated for the swap. This is to resume for your hibernate. If you don't want to hibernate, then password is not required and all you need to do is to create/format the partition each time you boot without a password or with a one time random password.

== Hiding the keys using steganography ==

''WARNING:'' This section is considered experimental. It requires the tool and the dependencies to be placed on another USB separate from the key files, the bootloaders, and encrypted disks. The tool and dependencies need to be packaged together. We decentralize these components so that the attacker doesn't connect the dots easily or immediately jumps to the conclusion for the requirements to decrypt. Steghide automatically uses 128-bit AES in CBC mode to encrypt data. This can be change if you don't like or trust AES with the -e option. Use <code>steghide encinfo</code> for other ciphers and modes.

Fortunately, Alpine has a package for steganography called steghide (in the optional edge/testing repository as of February 2026). To install steghide do:

echo "http://dl-cdn.alpinelinux.org/alpine/edge/testing" >> /etc/apk/repositories
apk add steghide

You will place the keyfile in an image file. The facade image file should be large enough that there is no apparent discernible difference between the original and the modified. Do not use a small image with a small filesize.

As mentioned previously luks headers could be 3MB large or more and an jpeg image file is not suitable. Use another format like .au/.wav or another steganography utility that handles mp3s. The mp3/wav should be fairly large enough to dilute the header. So, something with long content is suitable.

There are two basic commands to use with steghide embed and extract,

To embed do:

steghide embed -ef key.gpg -cf image.jpg

To extract do:

steghide extract -xf key.gpg -sf image.jpg

To get a file list of files to ship out, use:

apk info -L libgcc libmcrypt libmhash libstdc++ libjpeg-turbo steghide

== Full disk encryption with with cryptsetup-luks volumes ==

=== Partitioning scheme ===

This section presents a conceptual layout. It should not be a knee-jerk approval to automatically use the partition tool which would compromise your plausible deniability.

For the facade, we use an Ubuntu Live CD (or less skilled distro) to present the impression that we are not sophisticated or tech savvy enough to implement encryption. Windows is also acceptable even better. The immutable Live CD and immutable partition ensures that you are not compromised by a third party attacker that implants evidence.

There could be possibly two bootloaders, one for the facade and the other to the encrypted drive stored on an external device.

==== Luks ====

Plausible deniability only works if you can demonstrate no existence of partitions 2, 3, 4 and no fingerprints/plaintext introduced by cfdisk and cryptsetup-luks. Use something like TestDisk, fdisk -l, or gparted and a disk editor (hex editor for disks).

{| cellpadding="5" border="1" class="wikitable"
!#
!Name
!Mount point
!Notes
|-
| 1
| facade
| /
| (optional) The facade partition contains a pristine normal operating system or Ubuntu Live CD image to lure the attacker in attempt to boost the confidence of the attacker convincing them that there is no encryption on the device.
|-
| 2
| swap
|
| It should be the same size as your ram for x86_64. Rationale: it should contain the whole ram image.
|-
| 3
| root
| /
|
|-
| 4
| rescue
| /
| This should contain the Alpine image.
|-
|}

==== Plain dm-crypt ====

Plausible deniability only works if you are able to present #2 as being unused space or untampered. To check use something like TestDisk, gparted and a disk editor (hex editor for disks).

{| cellpadding="5" border="1" class="wikitable"
!#
!Name
!Mount point
!Notes
|-
| 1
| facade
| /
| (optional) The facade partition contains a pristine normal operating system or Ubuntu Live CD image to lure the attacker in attempt to boost the confidence of the attacker convincing them that there is no encryption on the device.
|-
| 2
| vgroot
|
|
|-
| 2_1
| vgroot-root
| /
|
|-
| 2_2
| vgroot-swap
|
| It should be the same size as your ram for x86_64. Rationale: it should contain the whole ram image.
|-
| 2_3
| vgroot-rescue
| /
| This should contain the Alpine image.
|-
|}

=== Installing cryptsetup ===

To install cryptsetup you need the package below

apk add cryptsetup

=== Choosing ciphers ===

When you create your luks drives, you need to decide on the type of ciphers and hashing techniques to use. The ciphers that you want to use are ones are up to you, but it should be one that is hasn't been cracked yet or has not suffered a lot of cryptanalysis attacks. The ones that you might want to use is AES which is hardware accelerated in some Intel CPUs that have the AES-NI cpuflag which you can check by <code>cat /proc/cpuinfo</code>. Also consider the ciphers that are SIMD optimized such as serpent and twofish that are available in the Linux kernel. Also consider ciphers that are unpopular but known to be secure such as Blowfish (which Wikipedia claims to be attacked and the author recommended Twofish).[https://en.wikipedia.org/wiki/Cipher_security_summary] If it is hardware accelerated, it will save battery life and minimize CPU usage.

For some ciphers weakness also see [https://en.wikipedia.org/wiki/Cipher_security_summary Cipher security summary (Wikipedia)].

For some hash function weaknesses also see [https://en.wikipedia.org/wiki/Hash_function_security_summary Hash function security summary (Wikipedia)].

Generally speaking, the swap partition should use a fast cipher. You want to lower the latency or delay of the memory subsystem as a consequence of being encrypted.

'''IMPORTANT:''' Please read the [[Setting_up_a_laptop#Important_notes | Important notes]] section for details about the problems with AES encryption.

If you don't trust AES shills and it's NSA endorsement, you can try another different one. Another advantage of using a public vetted cipher is that it provides confidence that it works.

Something like KHAZAD wouldn't work on <code>cryptsetup benchmark</code>. KHAZAD itself is insecure. Wikipedia reported 5 out of 8 rounds been cracked.[https://en.wikipedia.org/wiki/KHAZAD]

For AES-128 7 out of 10, AES-192 8 out of 12, AES-256-bit 9 out 14 rounds have been cracked according to Wikipedia.[https://en.wikipedia.org/wiki/Advanced_Encryption_Standard]

'''IMPORTANT: Do not use sha1 as the hashing algorithm.''' It already has been compromised.

=== Getting the available ciphers ===

To check the availability of a cipher or hash function use:
find $(find /lib/modules -name "crypto" -type d) -type f -name "*.ko" | sort

To check if a cipher is loaded and passed its own tests use:
cat /proc/crypto

To test some popular ciphers and hashes do:

cryptsetup benchmark

The top set is associated with the hashing algorithms. The bottom set are the ciphers. Use the commands below but replace the cipher and/or hash algorithm with your preferences.

<code>cryptsetup benchmark</code> actually doesn't show all the ciphers like Anubis. The cipher should also have CBC and/or XTS block cipher mode of operation to encrypt larger block sizes. AES for example has a block size of 128.

To test if the unpopular but uncracked cipher works use sometime like:
cryptsetup benchmark --cipher anubis

=== General steps for cryptsetup ===

==== Original method with fdisk with no plausible deniability ====

In this method <code>--type luks</code> is implied which generates metadata.

If you want plausible deniability for luks, you need to pass <code>--header <path></code> to all the luks commands, where <code><path></code> is a unix path like /mnt/usb/d6ae10eda66704c8. The random name comes from <code>openssl rand -hex 8</code>. The header is transferred to the external device (but no mention of the key slot area but ciphertext being transferred) in the man page. The information in that file should be obfuscated with encryption if there is plaintext or fingerprint in it just in case. Then, it should be decrypted when reused.

You need to install cfdisk if you prefer the interactive ncurses console method:

apk add cfdisk

{|| cellpadding="5" border="1" class="wikitable"
!#
!Step
!Command
|-
| 1
| Use cfdisk to create partitions. Make two partitions--a system partition and a swap partition
| <code><nowiki>cfdisk</nowiki></code>
|-
| 2
| Create and format the luks device
| <code><nowiki>cryptsetup --cipher aes-cbc-essiv:sha256 --key-size 256 luksFormat /dev/sda1 /mnt/usb/$(ls)</nowiki></code>
|-
| 3
| Open the luks device
| <code><nowiki>cryptsetup --key-file /mnt/usb/$(ls) luksOpen /dev/sda1 root</nowiki></code>
|-
| 4
| Format the decrypted drive with filesystem
| <code>mkfs.ext4 /dev/mapper/root</code>
|-
| 5
| Create the mount point
| <code>mkdir -p /mnt/root</code>
|-
| 6
| Mount the root partition
| <code>mount /dev/mapper/root /mnt/root</code>
|-
| 7
| Create swap
| cryptsetup -c blowfish -h sha256 -d /dev/urandom --key-file /mnt/usb/59022506d9f4a714 create swap /dev/sda2
|-
| 8
| Use swap
| mkswap /dev/mapper/swap && swapon /dev/mapper/swap
|}

==== Improved method with plausible deniability ====

This method requires lvm2. To install:

apk add lvm2

{|| cellpadding="5" border="1" class="wikitable"
!#
!Step
!Command
|-
| 1
| Open the ''plain dm-crypt'' device generating no metadata
| <code><nowiki>cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --key-file /mnt/usb/$(ls) /dev/sda pvroot</nowiki></code>
|-
| 2
| Physical volume create with LVM
| <code><nowiki>pvcreate /dev/mapper/pvroot</nowiki></code>
|-
| 3
| Volume group create with LVM
| <code><nowiki>vgcreate vgroot /dev/mapper/pvroot</nowiki></code>
|-
| 4
| Logical volume create the swap volume with LVM
| <code><nowiki>lvcreate -L 4G vgroot -n swap</nowiki></code>
|-
| 5
| Logical volume create the root volume with LVM
| <code><nowiki>lvcreate -L 2T vgroot -n root</nowiki></code>
|-
| 6
| Logical volume create the rescue volume with LVM
| <code><nowiki>lvcreate -L 110M vgroot -n rescue</nowiki></code>
|-
| 7
| Format the root volume with filesystem
| <code>mkfs.ext4 /dev/mapper/vgroot-root</code>
|-
| 8
| Format the swap volume and activate it
| <code>mkswap /dev/mapper/vgroot-swap && swapon /dev/mapper/vgroot-swap</code>
|-
| 9
| Format the rescue volume with filesystem
| <code>mkfs.ext4 /dev/mapper/vgroot-rescue</code>
|-
| 10
| Create mount point for root volume
| <code>mkdir -p /mnt/root</code>
|-
| 11
| Mount the root volume
| <code>mount /dev/mapper/vgroot-root /mnt/root</code>
|-
|}

=== Configuring OpenRC dmcrypt and setting up fstab ===

You need to tell OpenRC init scripts to decrypt the volumes. See <code>/etc/conf.d/dmcrypt</code>.

You need to add the service to boot well because it needs to decrypt the root volume before OpenRC starts running commands from it. So you need to do:

rc-update add dmcrypt boot

==== dmcrypt ====
The dmcrypt OpenRC service will attempt to decrypt the drive using information provided in ''/etc/conf.d/dmcrypt''.

For ''luks'':

{{Cat|/etc/conf.d/dmcrypt|<nowiki>
# Mounting root may not be necessary since it is already mounted.
target=root
source='/dev/sda1'
key='/mnt/usb/2a667ec72774b0d5'

swap=swap
source='/dev/sda2'
key='/mnt/usb/59022506d9f4a714'
</nowiki>}}

For ''plain dm-crypt'':

{{Cat|/etc/conf.d/dmcrypt|<nowiki>
# Mounting root is likely not required since you already mounted it before OpenRC starts to do its thing.
target=root
source='/dev/sda'
key='/mnt/usb/2a667ec72774b0d5'
options='--type plain --cipher aes-cbc-essiv:sha256 --key-size 256'

swap=swap
source='/dev/sda2'
key='/mnt/usb/59022506d9f4a714'
pre_mount='vgchange -ay vgroot ; lvchange -ay vgroot/swap'
</nowiki>}}

dm-crypt will just mount the encrypted ''plain dm-crypt'' drive or the ''luks'' partition. What you need to do next is set up fstab located at /etc/fstab. Examples are shown below.

==== /etc/fstab ====

To mount ''plain dm-crypt'' device with fstab:

{{Cat|/etc/fstab|
/dev/sdb /boot ext4 defaults 0 0
/dev/mapper/root / ext4 defaults 0 1
/dev/mapper/swap none swap sw 0 0
}}

To mount ''lvm'' volumes with fstab:

{{Cat|/etc/fstab|
/dev/sdb /boot ext4 defaults 0 0
/dev/mapper/vgroot-root / ext4 defaults 0 1
/dev/mapper/vgroot-swap none swap sw 0 0
}}

=== How to recover from a bad setup ===

Many times you will not get it right perfectly the first try. To recover from this situation, you need to reopen the ''plain dm-crypt'' drive or the ''luks'' drive and then remount everything back.

To recover from ''luks'':
cryptsetup --key-file /mnt/usb/2a667ec72774b0d5 luksOpen /dev/sda1 root
mkdir -p /mnt/root
mount /dev/mapper/root /mnt/root

To recover from the ''plain dm-crypt'':
cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --key-file /mnt/usb/$(ls) /dev/sda root
vgchange -ay vgroot
lvchange -ay vgroot/root
mkdir -p /mnt/root
mount /dev/mapper/vgroot-swap /mnt/root

== Next step: Full blown Alpine installation ==

We will setup the /mnt/root encrypted partition:
apk add --root=/mnt/root --initdb $(cat /etc/apk/world) --keys-dir /etc/apk/keys --repositories-file /etc/apk/repositories

Then, enable edge repositories in both files including community and testing:
nano /etc/apk/repositories /mnt/root/etc/apk/repositories

Then, copy the necessary files:
cp /etc/resolv.conf /mnt/root/etc

Then, install the basic utils:
apk add --root=/mnt/root dhcpcd chrony networkmanager wireless-tools wpa_supplicant
apk add --root=/mnt/root grub mkinitfs e2fsprogs grub-bios grub-efi
apk add --root=/mnt/root sudo nano
apk add --root=/mnt/root linux-lts

Then, you need to mount your usb on to /boot:
mount /dev/sdb /boot

Edit grub:
nano /boot/grub/grub.cfg

Then, install grub on the usb:
grub-install --force /dev/sdb

Then, prepare chroot:
mount --bind /dev /mnt/root/dev
mount --bind /sys /mnt/root/sys
cp /etc/reslov.conf /mnt/root/etc

Then, chroot:
chroot /mnt/root /bin/sh

Set the root administrator password:
passwd

The root password should be very difficult to deter you from using it and force you to use sudo

Edit sudo so that wheel group has administrative :
EDITOR=nano visudo

Set:
## Uncomment to allow members of group wheel to execute any command
%wheel ALL=(ALL) ALL

Then, add wheel (administrator) user:
useradd -m myname
usermod -a -G video,audio,wheel myname

log in that user:
su myname

Then, update and upgrade it
sudo apk update
sudo apk upgrade

Then, setup xorg:
sudo setup-xorg-base
sudo apk search xf86-video | sort
# pick your xf86 video driver
sudo apk add xf86-video-amdgpu
# install the mesa driver
sudo apk add mesa-dri-gallium

Then, keep piling on:
sudo apk add firefox dwm xfce4-terminal alsa-utils keepassx xfce4 xchat
sudo apk add font-noto-emoji font-terminus leafpad xsetroot # See [[Emojis]] to complete installation
sudo apk add xf86-input-libinput # or -evdev if libinput doesn't work

Then, set the desktop:
nano .xinitrc

Put both but comment with a # one of them if you don't want it,
#while true; do xsetroot -name "$( date +"%a %b %d %I:%M:%S %Y" )" ; sleep 1; done &
#exec dwm
exec xfce4-session

For the above xsetroot statement used to provide information in the statusbar for dwm, consider adding information about the battery level. This information can be found in sysfs at /sys/class/power_supply/BAT0/.

sync
sudo reboot

== Hacking mkinitfs to support cryptsetup with GPG keys ==

This section describes how to assemble a custom initscript chain in multiple parts. It could be extended with three-factor authentication which adds biometrics along side with mind and physical object.

Most entry to secure systems are not fully automated or do not allow things to quickly pass through freely and often guarded. This process may seem like a hassle, but it should dissuade the rubberhosers from jumping to the conclusion of the possibility of the existence of a encrypted drive.

Here is the steps required so that the facade initscripts and dependencies are free from encryption.
* You will separate and archive cryptsetup, ciphers kernel modules, hash function kernel modules, and any additional obfuscation dependencies, and another continuation initscript discussed below. You need to make sure that you copy /etc/mkinitfs/mkinitfs.conf to your home directory and strip out those features without those modules.
* You will hide this archive in a mp3 file with another tool you will package or you can use steghide's .au/.wav support, but .au seems too conspicuous or strange by current trends.

Here we try to clean up the facade so that it presents itself as free without cryptography. You need the following changes to your initramfs to avoid a sensitive rubberhoser:
* You will delete everything in the custom initramfs-init referring to encryption. This includes cryptroot, cryptdm, crypt-anything, etc init options.
* You need to delete references in nlplug-findfs to cryptsetup and recompile the mkinitfs package.
* You could program the init script to boot into a facade partition but drop into sh if a hidden special keypress sequence is met.

You need to create a custom init continuation script:
* Your initscript should drop into single mode which you will mount the encrypted path manually.
* You will manually steg-unhide the encrypted archive hidden in the mp3 file and extract it to the ramdisk.
* You will run the custom init continuation script manually.
* This custom init continuation will automate the process of extracting the gpg keys from another device and image files into the ramdisk. This will then automate the mounting of the encrypted drive. This resume continuation script should handle both cold boot and hibernate.
* You will finish resuming running the other half of mkinitfs-init or specifically where the points after where it typically will mount cryptsetup and hibernate devices.

If you use a USB keyboard, you will unlock the encrypted devices in early userspace. You will need to either compile the USB keyboard drivers in the kernel or you need to add additional modules when generating the mkinitfs. You will need the hid, hid-generic, ehci-hcd, uhci-hcd, usbcore driver and add those paths in a customized <code>/etc/mkinitfs/features.d/usb-keyboard.modules</code>. It should be separate from usb.modules because apk updates may overwrite it. Use the <code>lsmod</code> utility from the kmod package to find what drivers your USB keyboard uses.

You need to generate the final mkinitfs.
First you need the kernelversion to pass into mkinitfs. To obtain that information do <code>ls /lib/modules</code> which will show some folders. Once you found it pass it to mkinitrafs by doing and replacing kernelversion below:

sudo mkinitramfs -i $HOMEDIR/initramfs-init -c "$HOMEDIR"/mkinitfs.conf kernelversion

The $HOMEDIR should be replaced with the full path if you are not root.

== Install the bootloader in the USB thumb drive ==

To install grub, you need to install grub on the ramdisk first on the host.

apk add grub

To get a list of partitions

fdisk -l

Mount the boot partition in /boot

mount /dev/sdb /boot

Make changes to grub's configuration

nano /boot/grub/grub.cfg

'''You need to customize the initramfs in order to use GPG keys since there is no support from it.'''

The steps here below assumes that these custom initramfs features have been implemented.

The following boot loader settings is '''not sufficient''' for deniable encryption because it exposes the fact that an encrypted drive exists because an attacker can discover that encryption was used through the edit option of the grub menu. To protect yourself from a rubberhose attack, you really need to customize the initramfs so that references to anything mentioning encryption, ciphers, hashing are not explicitly mentioned. These configurations should be considered an intermediate form for used in debugging purposes. In addition, the attacker just can inspect grub.cfg files directly.

The following are just examples to just get it working but should be modified so that it doesn't hint to the rubberhoser of a hidden partition or encrypted partitions.

The entry should look like:

For 'luks'

{{cat|/boot/grub/grub.cfg|<nowiki>
default=0
timeout=0

menuentry 'Windows 10' {
set root=(hd0,2)
chainloader +1
}

menuentry 'Alpine Linux' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/root rw modules=sd-mod,usb-storage,ext4,dm-crypt,aes-x86_64,sha256-mb cryptroot=/dev/sda1 cryptdm=root
initrd /initramfs-hardened
}

menuentry 'Alpine Linux (Rescue)' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/root rw modules=sd-mod,usb-storage,ext4,dm-crypt,aes-x86_64,sha256-mb cryptroot=/dev/sda4 cryptdm=root
initrd /initramfs-hardened
}

if keystatus; then
if keystatus --ctrl; then
set timeout=-1
else
set timeout=0
fi
fi
</nowiki>}}

For 'plain dm-crypt':

The stock mkinitfs may not support plain dm-crypt. It looks like it only supports luks. Customization of the initramfs is required.

{{cat|/boot/grub/grub.cfg|<nowiki>
default=0
timeout=0

menuentry 'Windows 10' {
set root=(hd0,2)
chainloader +1
}

menuentry 'Alpine Linux' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/vgroot-root rw modules=sd-mod,usb-storage,ext4,dm-crypt,dm-mod,dm-snapshot,aes-x86_64,sha256-mb cryptroot=/dev/sda cryptdm=root
initrd /initramfs-hardened
}

menuentry 'Alpine Linux (Rescue)' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/vgroot-rescue rw modules=sd-mod,usb-storage,ext4,dm-crypt,dm-mod,dm-snapshot,aes-x86_64,sha256-mb cryptroot=/dev/sda cryptdm=rescue
initrd /initramfs-hardened
}

if keystatus; then
if keystatus --ctrl; then
set timeout=-1
else
set timeout=0
fi
fi
</nowiki>}}

The source code of grub could possibly be modified and recompiled to use other non-standard keys. See [https://github.com/lemenkov/grub2/blob/master/grub-core/commands/keystatus.c]. Ideally, it should be not so obvious or accessible for the attacker.

The above grub.cfg is applied to the USB bootloader. For the facade bootloader, you just want the Windows 10 or Ubuntu entry, nothing more.

For the modules parameter, you need to add your crypto modules.
Use <code>find /lib/modules/ -name "*aes*"</code> where aes is the basename for your cipher or hash algorithm
Use <code>blkid</code> to obtain the UUID of your device

Install it to your USB thumb drive

grub-install /dev/sdb

== Home mounting with eCryptfs ==

We use eCryptfs to encrypt home. The rationale for having another encrypted file system is that if you leave your laptop unattended on break or accidentally leave your USB key in, your data will not be accessible. The other rationale is that if another person wants to use your computer, you can just log off and the data will be kept hidden and encrypted. When you log off due to inactivity, your home directory will be unmounted and encrypted. eCryptfs will encrypt/decrypt the filename and the contents and will sit on top of ext4 which sits on top of luks.

To install ecryptfs-utils:

sudo apk add ecryptfs-utils

This does one factor authentication mostly with just the password, but it should be modified to use the USB key too. You need to reconfigure pam with the pam_usb.so which is not in Alpine aports.

You need to use the pam_ecryptfs PAM module.

== Locking it down ==

Many times you will leave your laptop behind with people you trust. The following tools will help lock down the system.

=== physlock ===

This will auto lock the tty and when you return will prompt for password.

To install physlock:

sudo apk add physlock

It is currently bugged. See [https://bugs.alpinelinux.org/issues/3282]. physlock likely doesn't do two-factor authentication but it should.

You need to create custom script that will monitor idle time in TTY then call physlock. You load this script when you log on.

=== xscreensaver ===

This will lock you out of xserver

To install xscreensaver:

sudo apk add xscreensaver

=== USB key udev rule ===

You need to add a new [[udev]] rule that will suspend-to-ram or hibernate and log off once you pull the USB key. When you come back on, you should do 2 factor authentication to restore back everything. Hibernation and suspend-to-ram might mitigate cold-boot attack (but unlikely see notes at the bottom of the page) to extract plaintext private data and encryption keys in memory.

To find out the details of your USB do:

udevadm monitor --udev -p

The output should look like:

<pre>
UDEV [181762.722853] add /devices/pci0000:00/0000:00:13.2/usb2/2-5/2-5:1.0/host6/target6:0:0/6:0:0:0/block/sdc (block)
ACTION=add
DEVLINKS=/dev/disk/by-id/usb-Kingston_MSFT_NORB_MSFTLAKDA300EB3021790009-0:0 /dev/disk/by-path/pci-0000:00:13.2-usb-0:5:1.0-scsi-0:0:0:0 /dev/disk/by-uuid/5A96-03E4
DEVNAME=/dev/sdc
DEVPATH=/devices/pci0000:00/0000:00:13.2/usb2/2-5/2-5:1.0/host6/target6:0:0/6:0:0:0/block/sdc
DEVTYPE=disk
ID_BUS=usb
ID_FS_TYPE=vfat
ID_FS_USAGE=filesystem
ID_FS_UUID=5A96-03E4
ID_FS_UUID_ENC=5A96-03E4
ID_FS_VERSION=FAT32
ID_INSTANCE=0:0
ID_MODEL=MSFT_NORB
ID_MODEL_ENC=MSFT\x20NORB\x20\x20\x20\x20\x20\x20\x20
ID_MODEL_ID=1645
ID_PATH=pci-0000:00:13.2-usb-0:5:1.0-scsi-0:0:0:0
ID_PATH_TAG=pci-0000_00_13_2-usb-0_5_1_0-scsi-0_0_0_0
ID_REVISION=PMAP
ID_SERIAL=Kingston_MSFT_NORB_MSFTLAKDA300EB3021790009-0:0
ID_SERIAL_SHORT=MSFTLAKDA300EB3021790009
ID_TYPE=disk
ID_USB_DRIVER=usb-storage
ID_USB_INTERFACES=:080650:
ID_USB_INTERFACE_NUM=00
ID_VENDOR=Kingston
ID_VENDOR_ENC=Kingston
ID_VENDOR_ID=0951
MAJOR=8
MINOR=32
SEQNUM=2027
SUBSYSTEM=block
USEC_INITIALIZED=1762722168
</pre>

You want to extract the <code>ID_SERIAL_SHORT=MSFTLAKDA300EB3021790009</code> or whatever is associated with your USB thumb drive.

You need pm-utils for ps-suspend. So to install it do:

sudo apk add pm-utils

You will create a udev rules so that when you pull out the USB, it will suspend-to-ram or you can use your own script. To do that create a file with the following contents:

{{Cat|/etc/udev/rules.d/50-usb-thumb-drive.rules|<nowiki>

ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SERIAL_SHORT}=="MSFTLAKDA300EB3021790009", RUN+="/usr/sbin/pm-suspend"

</nowiki>}}

== Extending battery life ==

'''WARNING: If you do not use the proper mitigation for cold boot attack, you are better off auto-shutdowning the laptop instead of using suspend or hibernate.'''

=== ACPI ===

ACPI is a good daemon to use to execute certain scripts when laptop events are triggered.

To install ACPI do:

apk add acpi

The events to pay attention to are:

{| cellpadding="5" border="1" class="wikitable"
! Event
! ACPI Event
! What your script should do
|-
| lid close
|
| log off ttys and suspend-to-ram. ALSA should either set the volume to 0 for the sound card or the sound driver be unloaded. It might be a good idea to kill or mute any music or movie players if the sound loops loudly after lid open.
|-
| lid open
|
| lock all ttys and all xservers should be locked, possibly reinitialize ALSA and the sound system.
|-
| tapped power button
|
| lock all ttys and suspend-to-ram
|-
| held power button
|
| hibernate
|-
| unplugged power
|
| should switch to 'conservative' cpufreq governor at above 25% power ; 'powersave' governor at 25%. set hdparam spindown rate lower.
|-
| plugged power
|
| should switch to 'performance' governor. disable hdparam spindown.
|}

The purpose of the power governor is to regulate the running frequency (GHz) of the processor.

Certain event handlers are are managed through laptop-mode-tools. If you don't want the dependency, then you could write ACPI handler scripts.

<code>acpi_listen</code> can be used to retrieve the event name.

TODO: put scripts below

=== Adjusting the backlight dynamically ===

The backlight may be controlled using sysfs. The setting is a descendant of <code>/sys/class/backlight/</code>. The feature may allow you to echo a value to it. Use trial and error to discover the values.

The adjustment of the backlight should be function of battery life. So if it is like 33% battery life, you want to run it near lowest settings but readable. For 50 percent battery energy maybe 40% light. For 90% battery maybe 75% light.

=== hdparm ===

To install hdparam do:

sudo apk add hdparm

The settings that laptop-mode-tools messes with is the <code>-S</code> or the spindown timeout. It was also hinted that acoustic setting <code>-M</code> is associated with the speed meaning that louder is faster and quieter is slower which could contribute to the amount of energy used or reduced.

Again you want something like laptop-mode-tools or ACPI to dynamically adjust the settings based on ACPI events.

=== laptop-mode-tools ===

This is currently not in aports but worthy mentioning. It should really be packaged. This is a set of scripts to define a power policies. You can manage all the settings in one place here like the hard drive idle spindown time, CPU governor control, dynamic LCD backlight behavior based on running on battery or AC power supply.

=== cpufreqd ===

This is a useful daemon for regulating power.

To install cpufreqd do:

sudo apk add cpufreqd

Make sure you add the service:

sudo rc-update add cpufreqd

=== LCD screen refresh rate ===

The refresh rate sets the maximum framerate. The more frames pushed the more energy consumed on the battery. You want this adjusted dynamically per certain events. For gaming, you want it to be the highest as possible for the laptop and vsync off. For battery use and traveling, you want it capped at 60 FPS/60 Hz or lower but dynamically adjust when you plug in the AC power supply. You can adjust the framerate with xrandr. For movies and YouTube, you want 60FPS and vsync on.

== Hacking the kernel ==

You should refer to the [[Custom Kernel]] page for details.

== Hibernation ==

See [[Custom_Kernel#Hibernation_to_prevent_data_loss|Hibernation to prevent data loss]].

== WiFi management ==

Since you are using WiFi, you need a better WiFi management to quickly find open access WiFi access points. We don't have all day to debug complexities of WiFi settings while away from home.

To install NetworkManager do:

sudo apk add networkmanager

To find WiFi access points use the <code>nmtui</code> ncurses interface.

You also need other programs so install them as well:

apk add wpa-supplicant dhcpcd chrony macchanger wireless-tools iputils

What these programs do:

* wpa-supplicant -- for WPA encryption
* dhcpcd -- for getting a dynamic IP address
* chrony -- for fixing the time with the atomic clock
* wireless-tools -- for additional information
* macchanger -- for protecting against WiFi access discrimination or increased anonymity. (optional)
* iputils -- for the ping command (optional)

You also need to add those services:

rc-update add chronyd
rc-update add wpa_supplicant
rc-update add dhcpcd
rc-update add networkmanager

To start the services manually (or just reboot):

rc-service chronyd start
rc-service wpa_supplicant start
rc-service dhcpcd start
rc-service networkmanager start

== Additional tools ==

=== actkbd ===

To control the sound with fn function keys, you need this daemon. It is currently not in aports. You could override the design and meaning of those keys with your own scripts and utilities. This daemon gives you that freedom.

If your laptop contains a brightness key, you want to set that up with this program. See also [[Setting_up_a_laptop#Adjusting_the_backlight_dynamically | Adjusting the backlight dynamically]].

=== secure-delete ===

Want to prevent cold-boot attack or decrypted keys in memory falling in the wrong hands? This maybe could work who knows? From research from cold boot attack, the data can actually stay in memory in minutes, just enough time for a hacker to copy the contents of the memory to a USB thumb drive.

To install secure-delete do:

sudo apk add secure-delete

smem only works for unused ram.[https://github.com/gordonrs/thc-secure-delete] If you use the vanilla kernel, this may work. If you use grsecurity, it will automatically sanitize memory if you enable it (but not enabled by default in the Alpine hardened kernel) when the memory page is freed.[https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecurity_and_PaX_Configuration_Options#Sanitize_all_freed_memory]

Close all important programs then call smem.

You call smem in your shutdown script or auto-logoff script.

You can call create a OpenRC shutdown script to run smem when most programs and services are closed. This will erase all your sensitive plaintext private data just in case.

You may want to create a wrapper script to call smem after your program closes.

You need to write a custom script that does the following:
* kill all running processes associated with your user account
* auto logoff terminals
* for the last terminal closed including all idle xservers, unmount your user home
* (optional) use smem to wipe all your plaintext private data in memory after all closed programs in case of cold boot attack

=== Sharing presentations over HDMI ===

If you want to use your laptop to share presentation over HDMI connection, you need libxinerama and xrandr.

To install libxinerama and xrandr do:

sudo apk add libxinerama xrandr

== Important notes ==

If you lose or break your USB key, that is it and you cannot decrypt your drive. It would be wise to make a backup of it.

By default, suspend-to-ram or hibernate will not sufficiently clear the AES encryption keys off ram in those phases which would invite a cold boot attack. This has been covered by the TRESOR kernel patch.[https://en.wikipedia.org/wiki/TRESOR][https://www1.cs.fau.de/tresor] This patch hasn't been updated since the 4.x kernel series.[https://www1.cs.fau.de/tresor]. This patch currently only works on 32-bit x86 Linux with SSE and MMX, and on processors with the AES-NI instruction set for x86_64 Linux. TRESOR doesn't work with DMA attack, but it can be mitigated by disabling DMA.[https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.303.3053&rep=rep1&type=pdf] The 32-bit version of TRESOR has only a key size of 128. The AES-NI version of TRESOR has a largest key size of 256 bit. See [[Setting_up_a_laptop#Choosing_ciphers | Choosing ciphers]] for the number of rounds cracked.

Loop-Amnesia works with LoopAES and is only for 64 bit Linux and only supports 128 bit keys but can result in data loss if their recommendations are not followed. [https://moongate.ydns.eu/amnesia.html]

Please read the Wikipedia article on Cold Boot Attack especially the mitigation section.[https://en.wikipedia.org/wiki/Cold_boot_attack] Full disk encryption will not protect your data especially for older hardware if you do not have the proper mitigation (implying not full proof) prerequisites such as a patched kernel, memory scrambling, permanent memory module mounting for example.

If you have a different but fully encrypted device like iPad, you still can be rubberhosed or interrogated with a perfect deniable encrypted laptop. This guide doesn't protect you from that possibility. If you do not want to be rubberhosed, don't possess those devices.

Additional tips to mitigate against a DMA Attack to exfiltrate encryption keys:

Disable DMA in the BIOS and set the password for the BIOS according to Wikipedia.[https://en.wikipedia.org/wiki/DMA_attack]

Blacklist kernel modules that use DMA and any unused expansion modules (FireWire, CardBus, ExpressCard, Thunderbolt, USB 3.0, PCI Express and hotplug modules) that use DMA.

You may need a custom (or customize a) BIOS or use Intel TXT or TPM which will authenticate the boot devices or boot from specific serial numbers not just any. For cold boot attack, it is not required to remove the RAM but to to slow down the rate of decay of the RAM module with liquid air in addition an USB thumb drive containing an encryption key retriever bypassing the operating system.[https://youtu.be/XfUlRsE3ymQ]

[[Category:Installation]]
[[Category:Security]]
[[category: Desktop]]

Setting up a laptop

2026-02-17T10:01:12Z

154pinkchairs: /* Hiding the keys using steganography */ mention stedghide being in edge/testing

This guide is about a project to create a '''secured laptop'''. For this project we take in consideration ways to extend battery life. It covers tools and daemons that are must haves for a laptop setup.
{{Todo|Instructions given in the page needs testing. Please help test section by section or the entire page. If individual sections have been tested, please update the Talkpage or please move/place this notice in the untested section(s) alone.}}

== Guide features ==

*Deniable full disk encryption
*Two factor authentication (physical object (USB key), mind)
*Encrypted swap and hibernation
*Encrypted home on top of encrypted drive
*Memory sanitation
*Dynamic power modes
*Feature keys support

== Rubberhose Attack ==

Just a reminder that all attacks are subjected to the Rubberhose Attack dilemma, you either give up your encryption keys or be tortured with a rubberhose with the possibly of death. See [https://en.wikipedia.org/wiki/Rubber-hose_cryptanalysis Wikipedia article]. We try to present [https://en.wikipedia.org/wiki/Deniable_encryption deniable encryption (Wikipedia)] to avoid a rubberhose attack scenario. In this article we use the words plausible deniability interchangeably with deniable encryption. To achieve this we use a facade and require no metadata fingerprints to expose or hint of encrypted or hidden containers or hint as in detect of existence of an encrypted disk. The keys should be stored using steganography where we dilute the randomness into the facade. It also requires you not to brag about encryption or mention it because that is an invitation for the attacker to torture the victim. Deniable encryption requires you not put encrypted as an entry title to your bootloader. There shouldn't be an entry for your facade bootloader to the encrypted drive.

== Why full disk? ==

The full disk encryption provides sort of some plausible deniability or a valid alibi that you didn't encrypt it. Is the drive just random noise, broken, or is it really encrypted? The other reason is that it implies that everything is protected.

But there could be problems if not done right. For example, cryptsetup does leave a plaintext marking or some hints by default that it has been encrypted when using luks/luks2 mode if a detached header with option <code>--header <path></code> is not presented.[https://www.lisenet.com/2013/luks-add-keys-backup-and-restore-volume-header/][https://man7.org/linux/man-pages/man8/cryptsetup.8.html] To gain credibility that we didn't really do the encryption, you have to wipe the +3 MiB region based on the number of key slots used; or store the headers on an external device.

If you did deniable encryption incorrectly, it is possible to erase and restore the header. This presents an opportunity to improve obfuscation. When you pull out the USB key, it should erase the header but store it on the USB key atomically as in completely. If you plug in the USB key, it will restore back the header. cryptsetup has luks actions luksHeaderBackup and luksHeaderRestore to do this.

== Starting at the beginning ==

Grab a USB thumb drive with Alpine. Set it up as usual but don't let it touch your drive yet. Then, install all the tools into memory ramdisk but not in the hard drive yet. The hard drive will be obliterated.

You will then install Alpine using the steps:

First you need WiFi, to get it run do the command below but say no or skip the hard drive setup stuff:

setup-alpine

Then, you need to install some tools into RAM temporarly:
apk add e2fsprogs grub grub-bios grub-efi mkinitfs nano

== Randomizing the drive with pseudorandom urandom entropy ==

The first part is to erase the drive with random noise but in practical time. There are many techniques to do this but should be done in one day or two minimum.

You can use shred or dd to accomplish this depending on your needs and the availability of entropy. Some techniques take longer. Cryptologist Bruce Schneier recommended 7 times with specified pattern. See [https://en.wikipedia.org/wiki/Data_erasure Wikipedia Article]. For practical purposes, we just do it random in one pass. It should be random so that the facade of random noise hides the encrypted data which resembles noise.

To list the drives on the system do <code>fdisk -l</code>.

'''IMPORTANT: make sure you wipe the right specific drive.'''

To wipe the disk with random entropy do:

dd if=/dev/urandom of=/dev/sda

== Creating GPG keys ==

'''As of this time, Alpine's mkinitfs does only one factor authentication with passphrase.''' You need to manually edit the initramfs-init.in in mkinitfs to support two factor authentication using cryptsetup.

After you have scrambled the drive, you want to create your GPG keys. You will use these keys to set the password(s) for your cryptsetup-luks partitions. These keys should be stored on a USB thumb drive or other memory device but should not be on the USB boot thumb drive or on the encrypted drive. The key should be a random 128 bit key wrapped in GPG and protected with a password.

If you are using x, you need to do <code>sudo apk add pinentry-gtk</code> to display password prompt properly for the next step.

To install openssl and gpg do:

apk add openssl gnupg

Then, to generate a key:

export GPG_TTY=$(tty) && openssl rand -base64 512 | gpg --symmetric --cipher-algo aes --armor > /mnt/usb/$(openssl rand -hex 12)

(Make sure your usb is mounted on /mnt/usb first.)

The long file name comes from <code>openssl rand -hex 12</code> so that we enhance plausible deniability. The attacker cannot determine the purpose of the key. Is it used for GitHub? for Email?

The first part will produce 512 random bytes in wrap it in base64. The random data will be piped to gpg which will wrap it in AES as ciphertext which again gets wrapped in base64 ascii armor. For every partition including swap in some cases, you should create more gpg keys and store them in your USB thumb drives. After you have produced your gpg keys, you will then use them as a password for cryptsetup/luks.

You can replace aes above with the ones listed in <code>gpg --version</code>.

There should be a password generated for the swap. This is to resume for your hibernate. If you don't want to hibernate, then password is not required and all you need to do is to create/format the partition each time you boot without a password or with a one time random password.

== Hiding the keys using steganography ==

''WARNING:'' This section is considered experimental. It requires the tool and the dependencies to be placed on another USB separate from the key files, the bootloaders, and encrypted disks. The tool and dependencies need to be packaged together. We decentralize these components so that the attacker doesn't connect the dots easily or immediately jumps to the conclusion for the requirements to decrypt. Steghide automatically uses 128-bit AES in CBC mode to encrypt data. This can be change if you don't like or trust AES with the -e option. Use <code>steghide encinfo</code> for other ciphers and modes.

Fortunately, Alpine has a package for steganography called steghide (in the optional edge/testing repository as of February 2026). To install steghide do:

echo "http://dl-cdn.alpinelinux.org/alpine/edge/testing" >> /etc/apk/repositories
apk add steghide

You will place the keyfile in an image file. The facade image file should be large enough that there is no apparent discernible difference between the original and the modified. Do not use a small image with a small filesize.

As mentioned previously luks headers could be 3MB large or more and an jpeg image file is not suitable. Use another format like .au/.wav or another steganography utility that handles mp3s. The mp3/wav should be fairly large enough to dilute the header. So, something with long content is suitable.

There are two basic commands to use with steghide embed and extract,

To embed do:

steghide embed -ef key.gpg -cf image.jpg

To extract do:

steghide extract -xf key.gpg -sf image.jpg

To get a file list of files to ship out, use:

apk info -L libgcc libmcrypt libmhash libstdc++ libjpeg-turbo steghide

== Full disk encryption with with cryptsetup-luks volumes ==

=== Partitioning scheme ===

This section presents a conceptual layout. It should not be a knee-jerk approval to automatically use the partition tool which would compromise your plausible deniability.

For the facade, we use an Ubuntu Live CD (or less skilled distro) to present the impression that we are not sophisticated or tech savvy enough to implement encryption. Windows is also acceptable even better. The immutable Live CD and immutable partition ensures that you are not compromised by a third party attacker that implants evidence.

There could be possibly two bootloaders, one for the facade and the other to the encrypted drive stored on an external device.

==== Luks ====

Plausible deniability only works if you can demonstrate no existence of partitions 2, 3, 4 and no fingerprints/plaintext introduced by cfdisk and cryptsetup-luks. Use something like TestDisk, fdisk -l, or gparted and a disk editor (hex editor for disks).

{| cellpadding="5" border="1" class="wikitable"
!#
!Name
!Mount point
!Notes
|-
| 1
| facade
| /
| (optional) The facade partition contains a pristine normal operating system or Ubuntu Live CD image to lure the attacker in attempt to boost the confidence of the attacker convincing them that there is no encryption on the device.
|-
| 2
| swap
|
| It should be the same size as your ram for x86_64. Rationale: it should contain the whole ram image.
|-
| 3
| root
| /
|
|-
| 4
| rescue
| /
| This should contain the Alpine image.
|-
|}

==== Plain dm-crypt ====

Plausible deniability only works if you are able to present #2 as being unused space or untampered. To check use something like TestDisk, gparted and a disk editor (hex editor for disks).

{| cellpadding="5" border="1" class="wikitable"
!#
!Name
!Mount point
!Notes
|-
| 1
| facade
| /
| (optional) The facade partition contains a pristine normal operating system or Ubuntu Live CD image to lure the attacker in attempt to boost the confidence of the attacker convincing them that there is no encryption on the device.
|-
| 2
| vgroot
|
|
|-
| 2_1
| vgroot-root
| /
|
|-
| 2_2
| vgroot-swap
|
| It should be the same size as your ram for x86_64. Rationale: it should contain the whole ram image.
|-
| 2_3
| vgroot-rescue
| /
| This should contain the Alpine image.
|-
|}

=== Installing cryptsetup ===

To install cryptsetup you need the package below

apk add cryptsetup

=== Choosing ciphers ===

When you create your luks drives, you need to decide on the type of ciphers and hashing techniques to use. The ciphers that you want to use are ones are up to you, but it should be one that is hasn't been cracked yet or has not suffered a lot of cryptanalysis attacks. The ones that you might want to use is AES which is hardware accelerated in some Intel CPUs that have the AES-NI cpuflag which you can check by <code>cat /proc/cpuinfo</code>. Also consider the ciphers that are SIMD optimized such as serpent and twofish that are available in the Linux kernel. Also consider ciphers that are unpopular but known to be secure such as Blowfish (which Wikipedia claims to be attacked and the author recommended Twofish).[https://en.wikipedia.org/wiki/Cipher_security_summary] If it is hardware accelerated, it will save battery life and minimize CPU usage.

For some ciphers weakness also see [https://en.wikipedia.org/wiki/Cipher_security_summary Cipher security summary (Wikipedia)].

For some hash function weaknesses also see [https://en.wikipedia.org/wiki/Hash_function_security_summary Hash function security summary (Wikipedia)].

Generally speaking, the swap partition should use a fast cipher. You want to lower the latency or delay of the memory subsystem as a consequence of being encrypted.

'''IMPORTANT:''' Please read the [[Setting_up_a_laptop#Important_notes | Important notes]] section for details about the problems with AES encryption.

If you don't trust AES shills and endorsed by the NSA, you can try another different one. Another advantage of using a public vetted cipher is that it provides confidence that it works.

Something like KHAZAD wouldn't work on <code>cryptsetup benchmark</code>. KHAZAD itself is insecure. Wikipedia reported 5 out of 8 rounds been cracked.[https://en.wikipedia.org/wiki/KHAZAD]

For AES-128 7 out of 10, AES-192 8 out of 12, AES-256-bit 9 out 14 rounds have been cracked according to Wikipedia.[https://en.wikipedia.org/wiki/Advanced_Encryption_Standard]

'''IMPORTANT: Do not use sha1 as the hashing algorithm.''' It already has already been compromised.

=== Getting the available ciphers ===

To check the availability of a cipher or hash function use:
find $(find /lib/modules -name "crypto" -type d) -type f -name "*.ko" | sort

To check if a cipher is loaded and passed its own tests use:
cat /proc/crypto

To test some popular ciphers and hashes do:

cryptsetup benchmark

The top set is associated with the hashing algorithms. The bottom set are the ciphers. Use the commands below but replace the cipher and/or hash algorithm with your preferences.

<code>cryptsetup benchmark</code> actually doesn't show all the ciphers like Anubis. The cipher should also have CBC and/or XTS block cipher mode of operation to encrypt larger block sizes. AES for example has a block size of 128.

To test if the unpopular but uncracked cipher works use sometime like:
cryptsetup benchmark --cipher anubis

=== General steps for cryptsetup ===

==== Original method with fdisk with no plausible deniability ====

In this method <code>--type luks</code> is implied which generates metadata.

If you want plausible deniability for luks, you need to pass <code>--header <path></code> to all the luks commands, where <code><path></code> is a unix path like /mnt/usb/d6ae10eda66704c8. The random name comes from <code>openssl rand -hex 8</code>. The header is transferred to the external device (but no mention of the key slot area but ciphertext being transferred) in the man page. The information in that file should be obfuscated with encryption if there is plaintext or fingerprint in it just in case. Then, it should be decrypted when reused.

You need to install cfdisk if you prefer the interactive ncurses console method:

apk add cfdisk

{|| cellpadding="5" border="1" class="wikitable"
!#
!Step
!Command
|-
| 1
| Use cfdisk to create partitions. Make two partitions--a system partition and a swap partition
| <code><nowiki>cfdisk</nowiki></code>
|-
| 2
| Create and format the luks device
| <code><nowiki>cryptsetup --cipher aes-cbc-essiv:sha256 --key-size 256 luksFormat /dev/sda1 /mnt/usb/$(ls)</nowiki></code>
|-
| 3
| Open the luks device
| <code><nowiki>cryptsetup --key-file /mnt/usb/$(ls) luksOpen /dev/sda1 root</nowiki></code>
|-
| 4
| Format the decrypted drive with filesystem
| <code>mkfs.ext4 /dev/mapper/root</code>
|-
| 5
| Create the mount point
| <code>mkdir -p /mnt/root</code>
|-
| 6
| Mount the root partition
| <code>mount /dev/mapper/root /mnt/root</code>
|-
| 7
| Create swap
| cryptsetup -c blowfish -h sha256 -d /dev/urandom --key-file /mnt/usb/59022506d9f4a714 create swap /dev/sda2
|-
| 8
| Use swap
| mkswap /dev/mapper/swap && swapon /dev/mapper/swap
|}

==== Improved method with plausible deniability ====

This method requires lvm2. To install:

apk add lvm2

{|| cellpadding="5" border="1" class="wikitable"
!#
!Step
!Command
|-
| 1
| Open the ''plain dm-crypt'' device generating no metadata
| <code><nowiki>cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --key-file /mnt/usb/$(ls) /dev/sda pvroot</nowiki></code>
|-
| 2
| Physical volume create with LVM
| <code><nowiki>pvcreate /dev/mapper/pvroot</nowiki></code>
|-
| 3
| Volume group create with LVM
| <code><nowiki>vgcreate vgroot /dev/mapper/pvroot</nowiki></code>
|-
| 4
| Logical volume create the swap volume with LVM
| <code><nowiki>lvcreate -L 4G vgroot -n swap</nowiki></code>
|-
| 5
| Logical volume create the root volume with LVM
| <code><nowiki>lvcreate -L 2T vgroot -n root</nowiki></code>
|-
| 6
| Logical volume create the rescue volume with LVM
| <code><nowiki>lvcreate -L 110M vgroot -n rescue</nowiki></code>
|-
| 7
| Format the root volume with filesystem
| <code>mkfs.ext4 /dev/mapper/vgroot-root</code>
|-
| 8
| Format the swap volume and activate it
| <code>mkswap /dev/mapper/vgroot-swap && swapon /dev/mapper/vgroot-swap</code>
|-
| 9
| Format the rescue volume with filesystem
| <code>mkfs.ext4 /dev/mapper/vgroot-rescue</code>
|-
| 10
| Create mount point for root volume
| <code>mkdir -p /mnt/root</code>
|-
| 11
| Mount the root volume
| <code>mount /dev/mapper/vgroot-root /mnt/root</code>
|-
|}

=== Configuring OpenRC dmcrypt and setting up fstab ===

You need to tell OpenRC init scripts to decrypt the volumes. See <code>/etc/conf.d/dmcrypt</code>.

You need to add the service to boot well because it needs to decrypt the root volume before OpenRC starts running commands from it. So you need to do:

rc-update add dmcrypt boot

==== dmcrypt ====
The dmcrypt OpenRC service will attempt to decrypt the drive using information provided in ''/etc/conf.d/dmcrypt''.

For ''luks'':

{{Cat|/etc/conf.d/dmcrypt|<nowiki>
# Mounting root may not be necessary since it is already mounted.
target=root
source='/dev/sda1'
key='/mnt/usb/2a667ec72774b0d5'

swap=swap
source='/dev/sda2'
key='/mnt/usb/59022506d9f4a714'
</nowiki>}}

For ''plain dm-crypt'':

{{Cat|/etc/conf.d/dmcrypt|<nowiki>
# Mounting root is likely not required since you already mounted it before OpenRC starts to do its thing.
target=root
source='/dev/sda'
key='/mnt/usb/2a667ec72774b0d5'
options='--type plain --cipher aes-cbc-essiv:sha256 --key-size 256'

swap=swap
source='/dev/sda2'
key='/mnt/usb/59022506d9f4a714'
pre_mount='vgchange -ay vgroot ; lvchange -ay vgroot/swap'
</nowiki>}}

dm-crypt will just mount the encrypted ''plain dm-crypt'' drive or the ''luks'' partition. What you need to do next is set up fstab located at /etc/fstab. Examples are shown below.

==== /etc/fstab ====

To mount ''plain dm-crypt'' device with fstab:

{{Cat|/etc/fstab|
/dev/sdb /boot ext4 defaults 0 0
/dev/mapper/root / ext4 defaults 0 1
/dev/mapper/swap none swap sw 0 0
}}

To mount ''lvm'' volumes with fstab:

{{Cat|/etc/fstab|
/dev/sdb /boot ext4 defaults 0 0
/dev/mapper/vgroot-root / ext4 defaults 0 1
/dev/mapper/vgroot-swap none swap sw 0 0
}}

=== How to recover from a bad setup ===

Many times you will not get it right perfectly the first try. To recover from this situation, you need to reopen the ''plain dm-crypt'' drive or the ''luks'' drive and then remount everything back.

To recover from ''luks'':
cryptsetup --key-file /mnt/usb/2a667ec72774b0d5 luksOpen /dev/sda1 root
mkdir -p /mnt/root
mount /dev/mapper/root /mnt/root

To recover from the ''plain dm-crypt'':
cryptsetup open --type plain --cipher aes-cbc-essiv:sha256 --key-size 256 --key-file /mnt/usb/$(ls) /dev/sda root
vgchange -ay vgroot
lvchange -ay vgroot/root
mkdir -p /mnt/root
mount /dev/mapper/vgroot-swap /mnt/root

== Next step: Full blown Alpine installation ==

We will setup the /mnt/root encrypted partition:
apk add --root=/mnt/root --initdb $(cat /etc/apk/world) --keys-dir /etc/apk/keys --repositories-file /etc/apk/repositories

Then, enable edge repositories in both files including community and testing:
nano /etc/apk/repositories /mnt/root/etc/apk/repositories

Then, copy the necessary files:
cp /etc/resolv.conf /mnt/root/etc

Then, install the basic utils:
apk add --root=/mnt/root dhcpcd chrony networkmanager wireless-tools wpa_supplicant
apk add --root=/mnt/root grub mkinitfs e2fsprogs grub-bios grub-efi
apk add --root=/mnt/root sudo nano
apk add --root=/mnt/root linux-lts

Then, you need to mount your usb on to /boot:
mount /dev/sdb /boot

Edit grub:
nano /boot/grub/grub.cfg

Then, install grub on the usb:
grub-install --force /dev/sdb

Then, prepare chroot:
mount --bind /dev /mnt/root/dev
mount --bind /sys /mnt/root/sys
cp /etc/reslov.conf /mnt/root/etc

Then, chroot:
chroot /mnt/root /bin/sh

Set the root administrator password:
passwd

The root password should be very difficult to deter you from using it and force you to use sudo

Edit sudo so that wheel group has administrative :
EDITOR=nano visudo

Set:
## Uncomment to allow members of group wheel to execute any command
%wheel ALL=(ALL) ALL

Then, add wheel (administrator) user:
useradd -m myname
usermod -a -G video,audio,wheel myname

log in that user:
su myname

Then, update and upgrade it
sudo apk update
sudo apk upgrade

Then, setup xorg:
sudo setup-xorg-base
sudo apk search xf86-video | sort
# pick your xf86 video driver
sudo apk add xf86-video-amdgpu
# install the mesa driver
sudo apk add mesa-dri-gallium

Then, keep piling on:
sudo apk add firefox dwm xfce4-terminal alsa-utils keepassx xfce4 xchat
sudo apk add font-noto-emoji font-terminus leafpad xsetroot # See [[Emojis]] to complete installation
sudo apk add xf86-input-libinput # or -evdev if libinput doesn't work

Then, set the desktop:
nano .xinitrc

Put both but comment with a # one of them if you don't want it,
#while true; do xsetroot -name "$( date +"%a %b %d %I:%M:%S %Y" )" ; sleep 1; done &
#exec dwm
exec xfce4-session

For the above xsetroot statement used to provide information in the statusbar for dwm, consider adding information about the battery level. This information can be found in sysfs at /sys/class/power_supply/BAT0/.

sync
sudo reboot

== Hacking mkinitfs to support cryptsetup with GPG keys ==

This section describes how to assemble a custom initscript chain in multiple parts. It could be extended with three-factor authentication which adds biometrics along side with mind and physical object.

Most entry to secure systems are not fully automated or do not allow things to quickly pass through freely and often guarded. This process may seem like a hassle, but it should dissuade the rubberhosers from jumping to the conclusion of the possibility of the existence of a encrypted drive.

Here is the steps required so that the facade initscripts and dependencies are free from encryption.
* You will separate and archive cryptsetup, ciphers kernel modules, hash function kernel modules, and any additional obfuscation dependencies, and another continuation initscript discussed below. You need to make sure that you copy /etc/mkinitfs/mkinitfs.conf to your home directory and strip out those features without those modules.
* You will hide this archive in a mp3 file with another tool you will package or you can use steghide's .au/.wav support, but .au seems too conspicuous or strange by current trends.

Here we try to clean up the facade so that it presents itself as free without cryptography. You need the following changes to your initramfs to avoid a sensitive rubberhoser:
* You will delete everything in the custom initramfs-init referring to encryption. This includes cryptroot, cryptdm, crypt-anything, etc init options.
* You need to delete references in nlplug-findfs to cryptsetup and recompile the mkinitfs package.
* You could program the init script to boot into a facade partition but drop into sh if a hidden special keypress sequence is met.

You need to create a custom init continuation script:
* Your initscript should drop into single mode which you will mount the encrypted path manually.
* You will manually steg-unhide the encrypted archive hidden in the mp3 file and extract it to the ramdisk.
* You will run the custom init continuation script manually.
* This custom init continuation will automate the process of extracting the gpg keys from another device and image files into the ramdisk. This will then automate the mounting of the encrypted drive. This resume continuation script should handle both cold boot and hibernate.
* You will finish resuming running the other half of mkinitfs-init or specifically where the points after where it typically will mount cryptsetup and hibernate devices.

If you use a USB keyboard, you will unlock the encrypted devices in early userspace. You will need to either compile the USB keyboard drivers in the kernel or you need to add additional modules when generating the mkinitfs. You will need the hid, hid-generic, ehci-hcd, uhci-hcd, usbcore driver and add those paths in a customized <code>/etc/mkinitfs/features.d/usb-keyboard.modules</code>. It should be separate from usb.modules because apk updates may overwrite it. Use the <code>lsmod</code> utility from the kmod package to find what drivers your USB keyboard uses.

You need to generate the final mkinitfs.
First you need the kernelversion to pass into mkinitfs. To obtain that information do <code>ls /lib/modules</code> which will show some folders. Once you found it pass it to mkinitrafs by doing and replacing kernelversion below:

sudo mkinitramfs -i $HOMEDIR/initramfs-init -c "$HOMEDIR"/mkinitfs.conf kernelversion

The $HOMEDIR should be replaced with the full path if you are not root.

== Install the bootloader in the USB thumb drive ==

To install grub, you need to install grub on the ramdisk first on the host.

apk add grub

To get a list of partitions

fdisk -l

Mount the boot partition in /boot

mount /dev/sdb /boot

Make changes to grub's configuration

nano /boot/grub/grub.cfg

'''You need to customize the initramfs in order to use GPG keys since there is no support from it.'''

The steps here below assumes that these custom initramfs features have been implemented.

The following boot loader settings is '''not sufficient''' for deniable encryption because it exposes the fact that an encrypted drive exists because an attacker can discover that encryption was used through the edit option of the grub menu. To protect yourself from a rubberhose attack, you really need to customize the initramfs so that references to anything mentioning encryption, ciphers, hashing are not explicitly mentioned. These configurations should be considered an intermediate form for used in debugging purposes. In addition, the attacker just can inspect grub.cfg files directly.

The following are just examples to just get it working but should be modified so that it doesn't hint to the rubberhoser of a hidden partition or encrypted partitions.

The entry should look like:

For 'luks'

{{cat|/boot/grub/grub.cfg|<nowiki>
default=0
timeout=0

menuentry 'Windows 10' {
set root=(hd0,2)
chainloader +1
}

menuentry 'Alpine Linux' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/root rw modules=sd-mod,usb-storage,ext4,dm-crypt,aes-x86_64,sha256-mb cryptroot=/dev/sda1 cryptdm=root
initrd /initramfs-hardened
}

menuentry 'Alpine Linux (Rescue)' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/root rw modules=sd-mod,usb-storage,ext4,dm-crypt,aes-x86_64,sha256-mb cryptroot=/dev/sda4 cryptdm=root
initrd /initramfs-hardened
}

if keystatus; then
if keystatus --ctrl; then
set timeout=-1
else
set timeout=0
fi
fi
</nowiki>}}

For 'plain dm-crypt':

The stock mkinitfs may not support plain dm-crypt. It looks like it only supports luks. Customization of the initramfs is required.

{{cat|/boot/grub/grub.cfg|<nowiki>
default=0
timeout=0

menuentry 'Windows 10' {
set root=(hd0,2)
chainloader +1
}

menuentry 'Alpine Linux' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/vgroot-root rw modules=sd-mod,usb-storage,ext4,dm-crypt,dm-mod,dm-snapshot,aes-x86_64,sha256-mb cryptroot=/dev/sda cryptdm=root
initrd /initramfs-hardened
}

menuentry 'Alpine Linux (Rescue)' {
set root=(hd1,1)
linux /vmlinuz-hardened root=/dev/mapper/vgroot-rescue rw modules=sd-mod,usb-storage,ext4,dm-crypt,dm-mod,dm-snapshot,aes-x86_64,sha256-mb cryptroot=/dev/sda cryptdm=rescue
initrd /initramfs-hardened
}

if keystatus; then
if keystatus --ctrl; then
set timeout=-1
else
set timeout=0
fi
fi
</nowiki>}}

The source code of grub could possibly be modified and recompiled to use other non-standard keys. See [https://github.com/lemenkov/grub2/blob/master/grub-core/commands/keystatus.c]. Ideally, it should be not so obvious or accessible for the attacker.

The above grub.cfg is applied to the USB bootloader. For the facade bootloader, you just want the Windows 10 or Ubuntu entry, nothing more.

For the modules parameter, you need to add your crypto modules.
Use <code>find /lib/modules/ -name "*aes*"</code> where aes is the basename for your cipher or hash algorithm
Use <code>blkid</code> to obtain the UUID of your device

Install it to your USB thumb drive

grub-install /dev/sdb

== Home mounting with eCryptfs ==

We use eCryptfs to encrypt home. The rationale for having another encrypted file system is that if you leave your laptop unattended on break or accidentally leave your USB key in, your data will not be accessible. The other rationale is that if another person wants to use your computer, you can just log off and the data will be kept hidden and encrypted. When you log off due to inactivity, your home directory will be unmounted and encrypted. eCryptfs will encrypt/decrypt the filename and the contents and will sit on top of ext4 which sits on top of luks.

To install ecryptfs-utils:

sudo apk add ecryptfs-utils

This does one factor authentication mostly with just the password, but it should be modified to use the USB key too. You need to reconfigure pam with the pam_usb.so which is not in Alpine aports.

You need to use the pam_ecryptfs PAM module.

== Locking it down ==

Many times you will leave your laptop behind with people you trust. The following tools will help lock down the system.

=== physlock ===

This will auto lock the tty and when you return will prompt for password.

To install physlock:

sudo apk add physlock

It is currently bugged. See [https://bugs.alpinelinux.org/issues/3282]. physlock likely doesn't do two-factor authentication but it should.

You need to create custom script that will monitor idle time in TTY then call physlock. You load this script when you log on.

=== xscreensaver ===

This will lock you out of xserver

To install xscreensaver:

sudo apk add xscreensaver

=== USB key udev rule ===

You need to add a new [[udev]] rule that will suspend-to-ram or hibernate and log off once you pull the USB key. When you come back on, you should do 2 factor authentication to restore back everything. Hibernation and suspend-to-ram might mitigate cold-boot attack (but unlikely see notes at the bottom of the page) to extract plaintext private data and encryption keys in memory.

To find out the details of your USB do:

udevadm monitor --udev -p

The output should look like:

<pre>
UDEV [181762.722853] add /devices/pci0000:00/0000:00:13.2/usb2/2-5/2-5:1.0/host6/target6:0:0/6:0:0:0/block/sdc (block)
ACTION=add
DEVLINKS=/dev/disk/by-id/usb-Kingston_MSFT_NORB_MSFTLAKDA300EB3021790009-0:0 /dev/disk/by-path/pci-0000:00:13.2-usb-0:5:1.0-scsi-0:0:0:0 /dev/disk/by-uuid/5A96-03E4
DEVNAME=/dev/sdc
DEVPATH=/devices/pci0000:00/0000:00:13.2/usb2/2-5/2-5:1.0/host6/target6:0:0/6:0:0:0/block/sdc
DEVTYPE=disk
ID_BUS=usb
ID_FS_TYPE=vfat
ID_FS_USAGE=filesystem
ID_FS_UUID=5A96-03E4
ID_FS_UUID_ENC=5A96-03E4
ID_FS_VERSION=FAT32
ID_INSTANCE=0:0
ID_MODEL=MSFT_NORB
ID_MODEL_ENC=MSFT\x20NORB\x20\x20\x20\x20\x20\x20\x20
ID_MODEL_ID=1645
ID_PATH=pci-0000:00:13.2-usb-0:5:1.0-scsi-0:0:0:0
ID_PATH_TAG=pci-0000_00_13_2-usb-0_5_1_0-scsi-0_0_0_0
ID_REVISION=PMAP
ID_SERIAL=Kingston_MSFT_NORB_MSFTLAKDA300EB3021790009-0:0
ID_SERIAL_SHORT=MSFTLAKDA300EB3021790009
ID_TYPE=disk
ID_USB_DRIVER=usb-storage
ID_USB_INTERFACES=:080650:
ID_USB_INTERFACE_NUM=00
ID_VENDOR=Kingston
ID_VENDOR_ENC=Kingston
ID_VENDOR_ID=0951
MAJOR=8
MINOR=32
SEQNUM=2027
SUBSYSTEM=block
USEC_INITIALIZED=1762722168
</pre>

You want to extract the <code>ID_SERIAL_SHORT=MSFTLAKDA300EB3021790009</code> or whatever is associated with your USB thumb drive.

You need pm-utils for ps-suspend. So to install it do:

sudo apk add pm-utils

You will create a udev rules so that when you pull out the USB, it will suspend-to-ram or you can use your own script. To do that create a file with the following contents:

{{Cat|/etc/udev/rules.d/50-usb-thumb-drive.rules|<nowiki>

ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SERIAL_SHORT}=="MSFTLAKDA300EB3021790009", RUN+="/usr/sbin/pm-suspend"

</nowiki>}}

== Extending battery life ==

'''WARNING: If you do not use the proper mitigation for cold boot attack, you are better off auto-shutdowning the laptop instead of using suspend or hibernate.'''

=== ACPI ===

ACPI is a good daemon to use to execute certain scripts when laptop events are triggered.

To install ACPI do:

apk add acpi

The events to pay attention to are:

{| cellpadding="5" border="1" class="wikitable"
! Event
! ACPI Event
! What your script should do
|-
| lid close
|
| log off ttys and suspend-to-ram. ALSA should either set the volume to 0 for the sound card or the sound driver be unloaded. It might be a good idea to kill or mute any music or movie players if the sound loops loudly after lid open.
|-
| lid open
|
| lock all ttys and all xservers should be locked, possibly reinitialize ALSA and the sound system.
|-
| tapped power button
|
| lock all ttys and suspend-to-ram
|-
| held power button
|
| hibernate
|-
| unplugged power
|
| should switch to 'conservative' cpufreq governor at above 25% power ; 'powersave' governor at 25%. set hdparam spindown rate lower.
|-
| plugged power
|
| should switch to 'performance' governor. disable hdparam spindown.
|}

The purpose of the power governor is to regulate the running frequency (GHz) of the processor.

Certain event handlers are are managed through laptop-mode-tools. If you don't want the dependency, then you could write ACPI handler scripts.

<code>acpi_listen</code> can be used to retrieve the event name.

TODO: put scripts below

=== Adjusting the backlight dynamically ===

The backlight may be controlled using sysfs. The setting is a descendant of <code>/sys/class/backlight/</code>. The feature may allow you to echo a value to it. Use trial and error to discover the values.

The adjustment of the backlight should be function of battery life. So if it is like 33% battery life, you want to run it near lowest settings but readable. For 50 percent battery energy maybe 40% light. For 90% battery maybe 75% light.

=== hdparm ===

To install hdparam do:

sudo apk add hdparm

The settings that laptop-mode-tools messes with is the <code>-S</code> or the spindown timeout. It was also hinted that acoustic setting <code>-M</code> is associated with the speed meaning that louder is faster and quieter is slower which could contribute to the amount of energy used or reduced.

Again you want something like laptop-mode-tools or ACPI to dynamically adjust the settings based on ACPI events.

=== laptop-mode-tools ===

This is currently not in aports but worthy mentioning. It should really be packaged. This is a set of scripts to define a power policies. You can manage all the settings in one place here like the hard drive idle spindown time, CPU governor control, dynamic LCD backlight behavior based on running on battery or AC power supply.

=== cpufreqd ===

This is a useful daemon for regulating power.

To install cpufreqd do:

sudo apk add cpufreqd

Make sure you add the service:

sudo rc-update add cpufreqd

=== LCD screen refresh rate ===

The refresh rate sets the maximum framerate. The more frames pushed the more energy consumed on the battery. You want this adjusted dynamically per certain events. For gaming, you want it to be the highest as possible for the laptop and vsync off. For battery use and traveling, you want it capped at 60 FPS/60 Hz or lower but dynamically adjust when you plug in the AC power supply. You can adjust the framerate with xrandr. For movies and YouTube, you want 60FPS and vsync on.

== Hacking the kernel ==

You should refer to the [[Custom Kernel]] page for details.

== Hibernation ==

See [[Custom_Kernel#Hibernation_to_prevent_data_loss|Hibernation to prevent data loss]].

== WiFi management ==

Since you are using WiFi, you need a better WiFi management to quickly find open access WiFi access points. We don't have all day to debug complexities of WiFi settings while away from home.

To install NetworkManager do:

sudo apk add networkmanager

To find WiFi access points use the <code>nmtui</code> ncurses interface.

You also need other programs so install them as well:

apk add wpa-supplicant dhcpcd chrony macchanger wireless-tools iputils

What these programs do:

* wpa-supplicant -- for WPA encryption
* dhcpcd -- for getting a dynamic IP address
* chrony -- for fixing the time with the atomic clock
* wireless-tools -- for additional information
* macchanger -- for protecting against WiFi access discrimination or increased anonymity. (optional)
* iputils -- for the ping command (optional)

You also need to add those services:

rc-update add chronyd
rc-update add wpa_supplicant
rc-update add dhcpcd
rc-update add networkmanager

To start the services manually (or just reboot):

rc-service chronyd start
rc-service wpa_supplicant start
rc-service dhcpcd start
rc-service networkmanager start

== Additional tools ==

=== actkbd ===

To control the sound with fn function keys, you need this daemon. It is currently not in aports. You could override the design and meaning of those keys with your own scripts and utilities. This daemon gives you that freedom.

If your laptop contains a brightness key, you want to set that up with this program. See also [[Setting_up_a_laptop#Adjusting_the_backlight_dynamically | Adjusting the backlight dynamically]].

=== secure-delete ===

Want to prevent cold-boot attack or decrypted keys in memory falling in the wrong hands? This maybe could work who knows? From research from cold boot attack, the data can actually stay in memory in minutes, just enough time for a hacker to copy the contents of the memory to a USB thumb drive.

To install secure-delete do:

sudo apk add secure-delete

smem only works for unused ram.[https://github.com/gordonrs/thc-secure-delete] If you use the vanilla kernel, this may work. If you use grsecurity, it will automatically sanitize memory if you enable it (but not enabled by default in the Alpine hardened kernel) when the memory page is freed.[https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecurity_and_PaX_Configuration_Options#Sanitize_all_freed_memory]

Close all important programs then call smem.

You call smem in your shutdown script or auto-logoff script.

You can call create a OpenRC shutdown script to run smem when most programs and services are closed. This will erase all your sensitive plaintext private data just in case.

You may want to create a wrapper script to call smem after your program closes.

You need to write a custom script that does the following:
* kill all running processes associated with your user account
* auto logoff terminals
* for the last terminal closed including all idle xservers, unmount your user home
* (optional) use smem to wipe all your plaintext private data in memory after all closed programs in case of cold boot attack

=== Sharing presentations over HDMI ===

If you want to use your laptop to share presentation over HDMI connection, you need libxinerama and xrandr.

To install libxinerama and xrandr do:

sudo apk add libxinerama xrandr

== Important notes ==

If you lose or break your USB key, that is it and you cannot decrypt your drive. It would be wise to make a backup of it.

By default, suspend-to-ram or hibernate will not sufficiently clear the AES encryption keys off ram in those phases which would invite a cold boot attack. This has been covered by the TRESOR kernel patch.[https://en.wikipedia.org/wiki/TRESOR][https://www1.cs.fau.de/tresor] This patch hasn't been updated since the 4.x kernel series.[https://www1.cs.fau.de/tresor]. This patch currently only works on 32-bit x86 Linux with SSE and MMX, and on processors with the AES-NI instruction set for x86_64 Linux. TRESOR doesn't work with DMA attack, but it can be mitigated by disabling DMA.[https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.303.3053&rep=rep1&type=pdf] The 32-bit version of TRESOR has only a key size of 128. The AES-NI version of TRESOR has a largest key size of 256 bit. See [[Setting_up_a_laptop#Choosing_ciphers | Choosing ciphers]] for the number of rounds cracked.

Loop-Amnesia works with LoopAES and is only for 64 bit Linux and only supports 128 bit keys but can result in data loss if their recommendations are not followed. [https://moongate.ydns.eu/amnesia.html]

Please read the Wikipedia article on Cold Boot Attack especially the mitigation section.[https://en.wikipedia.org/wiki/Cold_boot_attack] Full disk encryption will not protect your data especially for older hardware if you do not have the proper mitigation (implying not full proof) prerequisites such as a patched kernel, memory scrambling, permanent memory module mounting for example.

If you have a different but fully encrypted device like iPad, you still can be rubberhosed or interrogated with a perfect deniable encrypted laptop. This guide doesn't protect you from that possibility. If you do not want to be rubberhosed, don't possess those devices.

Additional tips to mitigate against a DMA Attack to exfiltrate encryption keys:

Disable DMA in the BIOS and set the password for the BIOS according to Wikipedia.[https://en.wikipedia.org/wiki/DMA_attack]

Blacklist kernel modules that use DMA and any unused expansion modules (FireWire, CardBus, ExpressCard, Thunderbolt, USB 3.0, PCI Express and hotplug modules) that use DMA.

You may need a custom (or customize a) BIOS or use Intel TXT or TPM which will authenticate the boot devices or boot from specific serial numbers not just any. For cold boot attack, it is not required to remove the RAM but to to slow down the rate of decay of the RAM module with liquid air in addition an USB thumb drive containing an encryption key retriever bypassing the operating system.[https://youtu.be/XfUlRsE3ymQ]

[[Category:Installation]]
[[Category:Security]]
[[category: Desktop]]

User:154pinkchairs

2023-10-25T06:22:22Z

154pinkchairs: /* Marcelina H. */ update editor

== Marcelina H. ==
=== [https://github.com/154pinkchairs/ Github] ===
=== [https://mjholub.me/ Website]===
'''Current city:''' Kraków, PL

Tech stack (mostly): Go, Rust, TS

Setup: Sway, Waybar, Rofi, Fish, Lazyvim, foot, Librewolf

Libre software and privacy/digital rights enthusiast and advocate (aren't we all?).

User:154pinkchairs

2023-10-25T06:22:01Z

154pinkchairs: /* Marcelina Hołub */ refactor

== Marcelina H. ==
=== [https://github.com/154pinkchairs/ Github] ===
=== [https://mjholub.me/ Website]===
'''Current city:''' Kraków, PL

Tech stack (mostly): Go, Rust, TS

Setup: Sway, Waybar, Rofi, Fish, Lapce, foot, Librewolf

Libre software and privacy/digital rights enthusiast and advocate (aren't we all?).

AppArmor

2023-10-25T06:20:03Z

154pinkchairs: /* Creating additional profiles */ mention that kernel log level should be set back to less verbose afterwards

{{TOC right}}

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 <code>apparmor-utils</code> if you want to use the <code>aa</code> 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.

 

=== With SYSLINUX ===

Use a text editor of your choice (preferably a TUI based one since some GUI setups don't work with privilege escalation, unless you use sudo -e) to edit <pre>/boot/extlinux.conf</pre> such that the <code>'''APPEND'''</code> 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.

=== With GRUB ===

Add the following at the end of the value for key <code>'''GRUB_CMDLINE_LINUX_DEFAULT'''</code> to <code>/etc/default/grub</code>:

<pre>
apparmor=1 security=apparmor
</pre>

Then apply with:

{{Cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

 

== Running ==

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 <code>aa-enabled</code>

{{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 following installation

=== Enabling Extra Profiles ===

Extra profiles reside in {{Path|/usr/share/apparmor/extra-profiles/}}. In order to enable to profile, it needs to be copied to {{Path|/etc/apparmor.d/}}:

If you want to enable the profile for <code>usr.bin.chromium-browser</code>, for example:

{{Cmd|# cp /usr/share/apparmor/extra-profiles/usr.bin.chromium-browser /etc/apparmor.d/}}

This will ''install'' the profile, it then needs to be set to '''complain''' or '''enforce''' mode:

{{Cmd|# aa-complain /etc/apparmor.d/usr.bin.chromium-browser}}

{{Note|Use <code>aa-enforce</code> to set it to enforce mode, '''but beware that this could break functionality'''.}}

=== Creating additional profiles ===

The profiles provided by the apparmor-profiles package are just a starter. You can create your own profiles by running

{{Cmd|# aa-easyprof <binary name>}}

or

{{Cmd|# aa-genprof <binary name>}}
 

Note that for this to work you'll probably need to set a more verbose [https://linuxconfig.org/introduction-to-the-linux-kernel-log-levels kernel log level]. For improved security, set it back to a higher level afterwards.

== Use ==

View AppArmor's report:

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

== Troubleshooting ==

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

== See Also ==

* [https://wiki.apparmor.net/ AppArmor Wiki]
* [https://wiki.debian.org/AppArmor/HowToUse Debian Wiki: How to use AppArmor]
* [https://wiki.archlinux.org/title/AppArmor AppArmor entry on ArchWiki]

[[Category:Security]]
[[Category:Kernel]]

Sway

2023-10-25T06:17:11Z

154pinkchairs: /* Steam games launched via Proton crash before creating a window */ mention proton-ge with a disclaimer that it'll only work with nix, with a warning on potential privacy risks, with a link to steam's TOSDR

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

== Installation ==

{{:Include:Setup_Device_Manager}}

Graphics drivers:

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

{{Cmd|# adduser $USER input
<nowiki>#</nowiki> adduser $USER video
}}

Install some TTF fonts:

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

seatd daemon:

{{Cmd|# apk add seatd
<nowiki>#</nowiki> rc-update add seatd
<nowiki>#</nowiki> rc-service seatd start
<nowiki>#</nowiki> adduser $USER seat
}}

Install sway:

{{Cmd|# apk add sway
<nowiki>#</nowiki> 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
}}

For complimentary software alternatives, see for example [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]

Configure [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].

== Usage ==

For inter-program communication and functionality such as screensharing, install and enable [[D-Bus]] 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:

{{Cmd|dbus-run-session -- sway #prepend with exec in your login shell init script}}

== 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 pipewire on sway startup:
<pre>
exec /usr/libexec/pipewire-launcher
</pre>
* xdg-desktop-portal will start xdg-desktop-portal-wlr when needed, but needs a few environment variables. Unless <code>dbus-daemon</code> is a descendant of the <code>sway</code> process, add to the sway config:
<pre>
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
</pre>
* Export the following variables:

{{Cmd|export MOZ_ENABLE_WAYLAND {{=}}"1"
export XDG_CURRENT_DESKTOP{{=}}sway
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}

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

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

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

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

<strike>Install clipman from testing repo and add the following to sway config:</strike>

Unfortunately, the clipman project has been abandoned and deleted from GitHub. Use [https://github.com/sentriz/cliphist cliphist] instead, which is also available in the testing repository.
See [https://github.com/sentriz/cliphist#picker-examples picker examples] section on the project's page to add an appropriate keybinding line to your 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:

{{Cat|/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
}
}}

Then run

{{Cmd|# chmod +x /etc/init.d/sway}}

and

{{Cmd|# rc-update add sway default}}

Make sure you have {{Pkg|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]]

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

== See Also ==

* [https://wiki.archlinux.org/title/Sway Archwiki]

[[Category:Desktop]]
[[Category:Window Managers]]

Sway

2023-10-25T06:04:39Z

154pinkchairs: /* Make clipboard content persistent */ mention cliphist since clipman has been abandoned

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

== Installation ==

{{:Include:Setup_Device_Manager}}

Graphics drivers:

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

{{Cmd|# adduser $USER input
<nowiki>#</nowiki> adduser $USER video
}}

Install some TTF fonts:

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

seatd daemon:

{{Cmd|# apk add seatd
<nowiki>#</nowiki> rc-update add seatd
<nowiki>#</nowiki> rc-service seatd start
<nowiki>#</nowiki> adduser $USER seat
}}

Install sway:

{{Cmd|# apk add sway
<nowiki>#</nowiki> 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
}}

For complimentary software alternatives, see for example [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]

Configure [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].

== Usage ==

For inter-program communication and functionality such as screensharing, install and enable [[D-Bus]] 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:

{{Cmd|dbus-run-session -- sway #prepend with exec in your login shell init script}}

== 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 pipewire on sway startup:
<pre>
exec /usr/libexec/pipewire-launcher
</pre>
* xdg-desktop-portal will start xdg-desktop-portal-wlr when needed, but needs a few environment variables. Unless <code>dbus-daemon</code> is a descendant of the <code>sway</code> process, add to the sway config:
<pre>
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
</pre>
* Export the following variables:

{{Cmd|export MOZ_ENABLE_WAYLAND {{=}}"1"
export XDG_CURRENT_DESKTOP{{=}}sway
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}

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

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

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

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

<strike>Install clipman from testing repo and add the following to sway config:</strike>

Unfortunately, the clipman project has been abandoned and deleted from GitHub. Use [https://github.com/sentriz/cliphist cliphist] instead, which is also available in the testing repository.
See [https://github.com/sentriz/cliphist#picker-examples picker examples] section on the project's page to add an appropriate keybinding line to your 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:

{{Cat|/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
}
}}

Then run

{{Cmd|# chmod +x /etc/init.d/sway}}

and

{{Cmd|# rc-update add sway default}}

Make sure you have {{Pkg|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]]

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

== See Also ==

* [https://wiki.archlinux.org/title/Sway Archwiki]

[[Category:Desktop]]
[[Category:Window Managers]]

Sway

2023-10-25T05:52:25Z

154pinkchairs: /* Installation */ link with alt. complimentary software list from gentoo wiki

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

== Installation ==

{{:Include:Setup_Device_Manager}}

Graphics drivers:

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

{{Cmd|# adduser $USER input
<nowiki>#</nowiki> adduser $USER video
}}

Install some TTF fonts:

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

seatd daemon:

{{Cmd|# apk add seatd
<nowiki>#</nowiki> rc-update add seatd
<nowiki>#</nowiki> rc-service seatd start
<nowiki>#</nowiki> adduser $USER seat
}}

Install sway:

{{Cmd|# apk add sway
<nowiki>#</nowiki> 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
}}

For complimentary software alternatives, see for example [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]

Configure [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].

== Usage ==

For inter-program communication and functionality such as screensharing, install and enable [[D-Bus]] 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:

{{Cmd|dbus-run-session -- sway #prepend with exec in your login shell init script}}

== 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 pipewire on sway startup:
<pre>
exec /usr/libexec/pipewire-launcher
</pre>
* xdg-desktop-portal will start xdg-desktop-portal-wlr when needed, but needs a few environment variables. Unless <code>dbus-daemon</code> is a descendant of the <code>sway</code> process, add to the sway config:
<pre>
exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway
</pre>
* Export the following variables:

{{Cmd|export MOZ_ENABLE_WAYLAND {{=}}"1"
export XDG_CURRENT_DESKTOP{{=}}sway
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}

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

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

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

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

{{Cat|/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
}
}}

Then run

{{Cmd|# chmod +x /etc/init.d/sway}}

and

{{Cmd|# rc-update add sway default}}

Make sure you have {{Pkg|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]]

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

== See Also ==

* [https://wiki.archlinux.org/title/Sway Archwiki]

[[Category:Desktop]]
[[Category:Window Managers]]

AppArmor

2023-04-11T01:24:11Z

154pinkchairs: /* Additional profiles */ fix spelling

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.

 

=== With SYSLINUX ===

Use a text editor of your choice (preferably a TUI based one since some GUI setups don't work with privilege escalation, unless you use sudo -e) 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.

 

=== With GRUB ===

Add the following at the end of the value for key '''GRUB_CMDLINE_LINUX_DEFAULT''' to /etc/default/grub:

<pre>
apparmor=1 security=apparmor
</pre>

Then apply with:
{{Cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

 

== Running ==

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.

== Additional profiles ==

The profiles provided by the apparmor-profiles package are just a starter. You can create your own profiles by running

{{Cmd|# aa-easyprof <binary name>}}
or
{{Cmd|# aa-genprof <binary name>}}
 

Note that for this to work you'll probably need to set a more verbose [https://linuxconfig.org/introduction-to-the-linux-kernel-log-levels kernel log level.]

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

[[Category:Security]]

AppArmor

2023-04-11T01:23:33Z

154pinkchairs: /* Additional profiles */ add info that profiling requires a more verbose kernel log level.

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.

 

=== With SYSLINUX ===

Use a text editor of your choice (preferably a TUI based one since some GUI setups don't work with privilege escalation, unless you use sudo -e) 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.

 

=== With GRUB ===

Add the following at the end of the value for key '''GRUB_CMDLINE_LINUX_DEFAULT''' to /etc/default/grub:

<pre>
apparmor=1 security=apparmor
</pre>

Then apply with:
{{Cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

 

== Running ==

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.

== Additional profiles ==

The profiles provided by the apparmor-profiles package are just a starter. You can create your own profiles by running

{{Cmd|# aa-easyprof <binary name>}}
or
{{Cmd|# aa-genprof <binary name>}}
 

Note that for this to work you'll probably need to set a more vebose [https://linuxconfig.org/introduction-to-the-linux-kernel-log-levels kernel log level.]

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

[[Category:Security]]

AppArmor

2023-04-11T01:18:37Z

154pinkchairs: /* With GRUB */ clarify which file to edit

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.

 

=== With SYSLINUX ===

Use a text editor of your choice (preferably a TUI based one since some GUI setups don't work with privilege escalation, unless you use sudo -e) 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.

 

=== With GRUB ===

Add the following at the end of the value for key '''GRUB_CMDLINE_LINUX_DEFAULT''' to /etc/default/grub:

<pre>
apparmor=1 security=apparmor
</pre>

Then apply with:
{{Cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

 

== Running ==

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.

== Additional profiles ==

The profiles provided by the apparmor-profiles package are just a starter. You can create your own profiles by running

{{Cmd|# aa-easyprof <binary name>}}
or
{{Cmd|# aa-genprof <binary name>}}
 

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

[[Category:Security]]

User:154pinkchairs

2023-04-09T03:05:40Z

154pinkchairs: fix: missing line break

== Marcelina Hołub ==
=== [https://github.com/154pinkchairs/ Github] ===
=== [https://mjholub.me/ Website]===
'''Current city:''' Kraków, PL

Tech stack (mostly): Go, Rust, TS

Setup: Sway, Waybar, Rofi, Fish, Lapce, foot, Librewolf

Libre software enthusiast since the age of 12. A staunch privacy/digital rights enthusiast and advocate.

User:154pinkchairs

2023-04-09T03:05:16Z

154pinkchairs: fix city formatting

== Marcelina Hołub ==
=== [https://github.com/154pinkchairs/ Github] ===
=== [https://mjholub.me/ Website]===
'''Current city:''' Kraków, PL

Tech stack (mostly): Go, Rust, TS
Setup: Sway, Waybar, Rofi, Fish, Lapce, foot, Librewolf

Libre software enthusiast since the age of 12. A staunch privacy/digital rights enthusiast and advocate.

User:154pinkchairs

2023-04-09T03:04:53Z

154pinkchairs: add country

== Marcelina Hołub ==
=== [https://github.com/154pinkchairs/ Github] ===
=== [https://mjholub.me/ Website]===
=== '''Current city:''' === Kraków, PL

Tech stack (mostly): Go, Rust, TS
Setup: Sway, Waybar, Rofi, Fish, Lapce, foot, Librewolf

Libre software enthusiast since the age of 12. A staunch privacy/digital rights enthusiast and advocate.

User:154pinkchairs

2023-04-09T03:04:34Z

154pinkchairs: /* Marcelina Hołub */ add setup, simplify tech stack, add website

== Marcelina Hołub ==
=== [https://github.com/154pinkchairs/ Github] ===
=== [https://mjholub.me/ Website]===
===== '''Current city:''' ===== Kraków

Tech stack (mostly): Go, Rust, TS
Setup: Sway, Waybar, Rofi, Fish, Lapce, foot, Librewolf

Libre software enthusiast since the age of 12. A staunch privacy/digital rights enthusiast and advocate.

AppArmor

2023-04-09T03:01:24Z

154pinkchairs: /* Additional profiles */ feat: add aa-genprof as an alternative

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.

 

=== With SYSLINUX ===

Use a text editor of your choice (preferably a TUI based one since some GUI setups don't work with privilege escalation, unless you use sudo -e) 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.

 

=== With GRUB ===

Add the following at the end of the value for key '''GRUB_CMDLINE_LINUX_DEFAULT''':

<pre>
apparmor=1 security=apparmor
</pre>

Then apply with:
{{Cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

 

== Running ==

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.

== Additional profiles ==

The profiles provided by the apparmor-profiles package are just a starter. You can create your own profiles by running

{{Cmd|# aa-easyprof <binary name>}}
or
{{Cmd|# aa-genprof <binary name>}}
 

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

[[Category:Security]]

AppArmor

2023-04-09T03:00:33Z

154pinkchairs: /* With SYSLINUX */ fix: rm nonexistent inline code template ref. for sudo -e

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.

 

=== With SYSLINUX ===

Use a text editor of your choice (preferably a TUI based one since some GUI setups don't work with privilege escalation, unless you use sudo -e) 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.

 

=== With GRUB ===

Add the following at the end of the value for key '''GRUB_CMDLINE_LINUX_DEFAULT''':

<pre>
apparmor=1 security=apparmor
</pre>

Then apply with:
{{Cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

 

== Running ==

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.

== Additional profiles ==

The profiles provided by the apparmor-profiles package are just a starter. You can create your own profiles by running

{{Cmd|# aa-easyprof <binary name>}}

 

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

[[Category:Security]]

AppArmor

2023-04-09T02:59:51Z

154pinkchairs: /* With GRUB */ fix: remove nonexistent ref to inline code tpl

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.

 

=== With SYSLINUX ===

Use a text editor of your choice (preferably a TUI based one since some GUI setups don't work with privilege escalation, unless you use {{Inline-code |sudo -e}}) 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.

 

=== With GRUB ===

Add the following at the end of the value for key '''GRUB_CMDLINE_LINUX_DEFAULT''':

<pre>
apparmor=1 security=apparmor
</pre>

Then apply with:
{{Cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

 

== Running ==

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.

== Additional profiles ==

The profiles provided by the apparmor-profiles package are just a starter. You can create your own profiles by running

{{Cmd|# aa-easyprof <binary name>}}

 

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

[[Category:Security]]

AppArmor

2023-04-09T02:58:56Z

154pinkchairs: deduplicate profile obtaining instructions

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.

 

=== With SYSLINUX ===

Use a text editor of your choice (preferably a TUI based one since some GUI setups don't work with privilege escalation, unless you use {{Inline-code |sudo -e}}) 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.

 

=== With GRUB ===

Add the following at the end of the value for key {{Inline-code |GRUB_CMDLINE_LINUX_DEFAULT}}:

<pre>
apparmor=1 security=apparmor
</pre>

Then apply with:
{{Cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

 

== Running ==

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.

== Additional profiles ==

The profiles provided by the apparmor-profiles package are just a starter. You can create your own profiles by running

{{Cmd|# aa-easyprof <binary name>}}

 

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

[[Category:Security]]

AppArmor

2023-04-09T02:56:25Z

154pinkchairs: /* Setup */ add instructions for GRUB, describe creating your own profiles and getting the default ones

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.

 

=== With SYSLINUX ===

Use a text editor of your choice (preferably a TUI based one since some GUI setups don't work with privilege escalation, unless you use {{Inline-code |sudo -e}}) 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.

 

=== With GRUB ===

Add the following at the end of the value for key {{Inline-code |GRUB_CMDLINE_LINUX_DEFAULT}}:

<pre>
apparmor=1 security=apparmor
</pre>

Then apply with:
{{Cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

 

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

 

If you notice that

{{Cmd|# aa-status}}

doesn't report any profiles to be loaded, then you should run

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

then reload apparmor by restarting the system.

== Additional profiles ==

The profiles provided by the apparmor-profiles package are just a starter. You can create your own profiles by running

{{Cmd|# aa-easyprof <binary name>}}

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

[[Category:Security]]

Rsnapshot

2023-03-26T05:49:44Z

154pinkchairs: /* Automation */ add a script to write the contents of each file

[http://rsnapshot.org/ <samp>rsnapshot</samp>] is a filesystem backup utility based on [[rsync|<samp>rsync</samp>]]. Using <samp>rsnapshot</samp>, it is possible to take snapshots of your filesystems at different points in time. Using hard links, rsnapshot creates the illusion of multiple full backups, while only taking up the space of one full backup plus differences. When coupled with <samp>ssh</samp>, it is possible to take snapshots of remote filesystems as well. This document is a tutorial on the installation and configuration of rsnapshot.

== Installation ==
To install rsnapshot:
<pre>
apk add rsnapshot
</pre>

== Configuration ==
To configure <samp>rsnapshot</samp>, copy the example configuration <samp>/etc/rsnapshot.conf.default</samp> to <samp>/etc/rsnapshot.conf</samp>, and edit it to your needs based on the comments and the [http://rsnapshot.org/rsnapshot/docs/docbook/rest.html official documentation]. Note that <samp>rsnapshot</samp> requires tabs between options and values in <samp>rsnapshot.conf</samp>. This is done so spaces can be included in filenames without requiring any extra escaping or quoting.

The most important parts to modify are where to store the backups:
<pre>
snapshot_root /mnt/backup
</pre>
How many backups to retain:
<pre>
retain daily 7
retain weekly 4
retain monthly 12
</pre>
And what to backup:
<pre>
# Local
backup /home/ local/
backup /etc/ local/

# Remote
backup user@remote:/home/user/ remote/ exclude=/home/user/Downloads
</pre>
In this case, every 7th <samp>daily</samp> backup is saved as a <samp>weekly</samp> backup, every 4th <samp>weekly</samp> backup is retained as a <samp>monthly</samp> backup, and every 12th <samp>monthly</samp> backup is deleted. The folders <samp>/home</samp> and <samp>/etc</samp> from the local machine are backed up to <samp>/mnt/backup/local/</samp>, while it uses <samp>ssh</samp> to back up the folder <samp>/home/user</samp> on the machine <samp>remote</samp> to <samp>/mnt/backup/remote/</samp>. Make sure <samp>root</samp> has passwordless <samp>ssh</samp> access to the machines you want to backup over the internet (i.e. run <samp>ssh-keygen</samp> and <samp>ssh-copy-id</samp> as <samp>root</samp>). 
The last line also shows an example of how you can exclude parts of the location from backups.

== Testing ==
To test that your config file has the correct syntax:
<pre>
rsnapshot configtest
</pre>
To check what the system would do when running a backup without executing the commands, i.e. a dry run:
<pre>
rsnapshot -t daily
rsnapshot -t weekly
rsnapshot -t monthly
</pre>
Finally, perform the first backup:
<pre>
rsnapshot daily
</pre>
The last part might take a while. Subsequent backups should be much faster, as it will then only have to copy files that have changed since the last backup.

== Automation ==
After setting up and testing <samp>rsnapshot</samp> as described above, the next step is to make [[cron|<samp>cron</samp>]] automatically run <samp>rsnapshot</samp> at fixed intervals. The easiest way to achieve this is to create a few scripts in the folders <samp>/etc/periodic/*</samp> that <samp>crond</samp> monitors. The script below will write the appropriate contents to those files and make them executable:
<pre>
#!/bin/sh
cd /etc/periodic
dirs=("daily" "weekly" "monthly")

for dir in "${dirs[@]}"; do
echo -e "#!/bin/sh\nexec /usr/bin/rsnapshot $dir" > "$dir/rsnapshot"
chmod +x "$dir/rsnapshot"
done

</pre>

{{Cat|/etc/periodic/daily/rsnapshot|#!/bin/sh

exec /usr/bin/rsnapshot daily
}}

{{Cat|/etc/periodic/weekly/rsnapshot|#!/bin/sh

exec /usr/bin/rsnapshot weekly
}}

{{Cat|/etc/periodic/monthly/rsnapshot|#!/bin/sh

exec /usr/bin/rsnapshot monthly
}}

Remember to make the scripts executable:
<pre>
chmod +x /etc/periodic/*/rsnapshot
</pre>
After that, test that the scripts work as expected:
<pre>
run-parts /etc/periodic/daily
run-parts /etc/periodic/weekly
run-parts /etc/periodic/monthly
</pre>
Assuming <samp>crond</samp> is set to start at boot (the default), your system should now make backups automatically.

[[Category:System Administration]]

Sway

2023-01-03T22:14:18Z

154pinkchairs: Merge tips&tricks with configuration

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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>

=== 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-03T22:10:55Z

154pinkchairs: /* Troubleshooting */ increase heading levels, reorganize sections

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

=== Tips and tricks ===

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.

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

Sway

2023-01-03T22:07:23Z

154pinkchairs: /* Missing file picker in Firefox (Flatpak)/cannot download */ fix formatting

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

==== Disappearing cursor in GTK apps or in Firefox (Flatpak) ====
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 in Firefox (Flatpak)/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]]

=== Tips and tricks ===

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.

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

Sway

2023-01-03T22:06:40Z

154pinkchairs: /* Missing file picker in Firefox (Flatpak)/cannot download */ fix URL

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

==== Disappearing cursor in GTK apps or in Firefox (Flatpak) ====
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 in Firefox (Flatpak)/cannot download ====

Go to about:config and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

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

Sway

2023-01-03T22:06:18Z

154pinkchairs: /* Missing file picker in Firefox (Flatpak)/cannot download */ fix URL

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

==== Disappearing cursor in GTK apps or in Firefox (Flatpak) ====
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 in Firefox (Flatpak)/cannot download ====

Go to [about:config about:config] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

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

Sway

2023-01-03T22:04:40Z

154pinkchairs: /* Screenshots */ add missing <pre> tags

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

==== Disappearing cursor in GTK apps or in Firefox (Flatpak) ====
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 in Firefox (Flatpak)/cannot download ====

Go to [[about:config]] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

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

Sway

2023-01-03T22:04:00Z

154pinkchairs: /* Firefox picture-in-picture mode/floating windows */ change librewolf to firefox

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

==== Disappearing cursor in GTK apps or in Firefox (Flatpak) ====
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 in Firefox (Flatpak)/cannot download ====

Go to [[about:config]] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

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

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

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

Sway

2023-01-03T22:03:18Z

154pinkchairs: /* Custom keyboard layout */ fix unclosed <pre> tags

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

==== Disappearing cursor in GTK apps or in Firefox (Flatpak) ====
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 in Firefox (Flatpak)/cannot download ====

Go to [[about:config]] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

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

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

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

Sway

2023-01-03T22:00:38Z

154pinkchairs: /* Tips and tricks */ convert numbered lists into headers

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

==== Disappearing cursor in GTK apps or in Firefox (Flatpak) ====
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 in Firefox (Flatpak)/cannot download ====

Go to [[about:config]] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

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

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

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

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

Sway

2023-01-03T21:59:25Z

154pinkchairs: /* Troubleshooting */ change numbered lists into headers

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

==== Disappearing cursor in GTK apps or in Firefox (Flatpak) ====
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 in Firefox (Flatpak)/cannot download ====

Go to [[about:config]] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

# 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="librewolf" 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:

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

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

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

Sway

2023-01-03T21:55:42Z

154pinkchairs: /* Installation */ fix a typo

[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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

# Disappearing cursor in GTK apps or in Firefox (Flatpak)
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 in Firefox (Flatpak)/cannot download

Go to [[about:config]] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

# 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="librewolf" 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:

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

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

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

Sway

2022-12-31T01:52:23Z

154pinkchairs: /* Installation */ fix incorrectly closed <code>

[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> on 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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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.

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>

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

[[Category:Desktop]]

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

# Disappearing cursor in GTK apps or in Firefox (Flatpak)
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 in Firefox (Flatpak)/cannot download

Go to [[about:config]] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

# 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="librewolf" 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:

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

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

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

Sway

2022-12-31T01:01:02Z

154pinkchairs: fix missing command for suspending without elogind

[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> on 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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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</sock> 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.

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>

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

[[Category:Desktop]]

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

# Disappearing cursor in GTK apps or in Firefox (Flatpak)
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 in Firefox (Flatpak)/cannot download

Go to [[about:config]] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

# 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="librewolf" 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:

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

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

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

Sway

2022-12-31T00:59:35Z

154pinkchairs: Add tips and tricks and troubleshooting sections.

[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 on 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 XDG_RUNTIME_DIR. Add the following to shell init scripts, for the default ash shell it is ~/.profile:

<pre>
if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/$(id -u)-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</pre>

If you have also installed elogind, which depends on the package linux-pam, you will also need to prepend the above 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</sock> 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.

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>

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

[[Category:Desktop]]

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

# Disappearing cursor in GTK apps or in Firefox (Flatpak)
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 in Firefox (Flatpak)/cannot download

Go to [[about:config]] and set widget.use-xdg-desktop-portal.file-picker 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]]

=== Tips and tricks ===

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.

# 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="librewolf" 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:

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

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

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

Sway

2022-12-30T23:06:31Z

154pinkchairs: /* Installation */ add env variables required by pam

PipeWire

2022-12-30T22:51:35Z

154pinkchairs: /* XDG_RUNTIME_DIR */ add additional instructions for Sway

{{Draft|The instructions below have not been thoroughly tested and may break things.}}

[https://pipewire.org/ PipeWire] is a multimedia processing engine that aims to improve audio and video handling on Linux.

== Prerequisites ==

=== Device access ===

PipeWire needs proper permissions to access devices. If you do not use [[Elogind|elogind]], your user should be in <code>audio</code> and <code>video</code> groups:

<pre>
# addgroup <user> audio
# addgroup <user> video
</pre>

Make sure to re-login for these changes to take effect.

=== D-Bus ===

PipeWire optionally requires a running [[D-Bus]] system and/or session bus for some of its functionality.

For certain configurations (e.g. only audio playback and recording) D-Bus setup is not necessary. Edit [[#Disable_D-Bus_support|configuration files]] to disable D-Bus support.

You can start a dbus session-wide like this: <code>export $(dbus-launch)</code>, or system-wide: <code>rc-service dbus start</code>

If you start dbus session-wide, make sure to start PipeWire in that same session.

=== XDG_RUNTIME_DIR ===

If you are not using a Desktop Manager, ensure that your <code>XDG_RUNTIME_DIR</code> is set to a user-writable location. By default for pulseaudio this is {{Path|/run/user/1000/}} or {{Path|/tmp}}. If this is not set, pipewire will create a directory in your home folder instead, called <code>~/pulse</code>, 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>

Under [[Sway]], in order for <code>xdg-desktop-portal-wlr</code> to work it may also be necessary to set <code>XDG_CURRENT_DESKTOP</code> and <code>XDG_SESSION_DESKTOP</code> to <code>sway</code>

== Installation ==

Install the {{Pkg|pipewire}} package.

=== Session Manager ===
PipeWire delegates plumbing work to session manager. There are two options available:
* '''[https://gitlab.freedesktop.org/pipewire/wireplumber WirePlumber]'''. It has modular design and supports Lua plugins. '''This is the recommended session manager. If you do not know which session manager you need, use WirePlumber.''' Package: {{Pkg|wireplumber}}
* '''[https://gitlab.freedesktop.org/pipewire/media-session pipewire-media-session]'''. It is much more simpler and covers only basic use cases. It was used for testing purposes. Now it does not make much sense since WirePlumber is available. Package: {{Pkg|pipewire-media-session}}

{{Note|This page assumes that you are using WirePlumber.}}

=== PulseAudio compatibility ===
Install {{Pkg|pipewire-pulse}} package, which provides a daemon so PulseAudio applications could use PipeWire as backend.

=== JACK compatibility ===
Install {{Pkg|pipewire-jack}} package, which provides ABI-compatible libraries for JACK applications.

=== ALSA support ===
Install {{Pkg|pipewire-alsa}} package.

== Configuration ==
PipeWire and WirePlumber store their default configuration in <code>/usr/share/pipewire</code> and <code>/usr/share/wireplumber</code> respectively. If you want to edit the configuration, you need to move it to <code>/etc</code>:

<pre>
# cp -a /usr/share/pipewire /etc
# cp -a /usr/share/wireplumber /etc
</pre>

=== Disable D-Bus support ===
Edit the following configuration parameters:

''/etc/pipewire/pipewire.conf''
<pre>
context.properties = {
...
support.dbus = false
}
</pre>

''/etc/wireplumber/wireplumber.conf''
<pre>
context.properties = {
...
support.dbus = false
}
</pre>

''/etc/wireplumber/bluetooth.lua.d/50-bluez-config.lua''
<pre>
bluez_monitor.properties = {
...
["with-logind"] = false,
}
</pre>

''/etc/wireplumber/main.lua.d/50-alsa-config.lua''
<pre>
alsa_monitor.properties = {
...
["alsa.reserve"] = false,
}
</pre>

''/etc/wireplumber/main.lua.d/50-default-access-config.lua''
<pre>
default_access.properties = {
...
["enable-flatpak-portal"] = false,
}
</pre>
=== Realtime scheduling ===

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

Alternatively, ensure your user has the right ulimit permissions. You generally need (limits.conf format):

<pre>
@audio - memlock 256
@audio - nice -11
@audio - rtprio 88
</pre>

This allows a member of the audio group to have the right permissions for PipeWire to use realtime scheduling without rtkit.

=== Video ===

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

=== Bluetooth audio ===

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

=== Screen sharing on Wayland ===

You will need the right [https://github.com/flatpak/xdg-desktop-portal xdg-desktop-portal] backend for your desktop environment. 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

== Running ==

{{Note|<code>pipewire-launcher</code> script is provided by Alpine Linux, not by upstream. Please report issues to Alpine Linux maintainers first.}}

Start the PipeWire media server. You'll probably get quite a few errors but just ignore them for now.

<pre>
$ /usr/libexec/pipewire-launcher
</pre>

If you do not have D-Bus session bus running (e.g. you are in tty or you are using minimalistic DE or window manager which does not launch D-Bus session) and you did not disable D-Bus in PipeWire configuration, use <code>dbus-launch</code>:

<pre>
$ dbus-launch /usr/libexec/pipewire-launcher
</pre>

{{Note| PipeWire doesn't auto-start a session manager anymore.
In 3.14 and earlier, the PipeWire default config was edited in packaging to auto-start pipewire-media-session as the default session manager. Since we now have wireplumber available as an alternative session manager, this has been changed in favor of a launch wrapper for pipewire at /usr/libexec/pipewire-launcher. When executed, this will launch pipewire, pipewire-media-session or wireplumber, and pipewire-pulse, depending on what modules are available. If you were launching /usr/bin/pipewire and the session manager manually before, please use the new launcher wrapper instead. WirePlumber can now also be used as a proper alternative for pipewire-media-session.}}

=== Auto launching ===
You can add <code>/usr/libexec/pipewire-launcher</code> to your <code>.xinitrc</code>.

If you do not use GUI by default and have D-Bus enabled in configuration, add the following stanza to your shell configuration file:
<pre>
export $(dbus-launch)
/usr/libexec/pipewire-launcher
</pre>

== Testing ==

In a different terminal window check the default output device. I don't yet know how this default can be changed for all applications, so you'd better hope it's right!

=== WirePlumber ===
<pre>
$ wpctl status
</pre>

=== pw-cat playback ===

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

<pre>
$ pw-cat -p test.flac
</pre>

=== pw-cat recording ===
If you have a microphone test audio recording is working.

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

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

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

<pre>
$ jack_simple_client
</pre>

You should hear a sustained beep.

== Troubleshooting ==

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

First, check whether ALSA knows about your sound card:

<pre>
aplay -l
</pre>

If sound devices are found, the issue is with your pipewire configuration. Consider double-checking the instructions above.

Otherwise, 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:

<pre>
uname -r
cat /proc/asound/card0/codec* | grep Codec
</pre>

=== Error acquiring bus address: Cannot autolaunch D-Bus without X11 $DISPLAY ===
This means D-Bus session bus is not started and GUI is not active (i.e. you are in a tty). Use <code>dbus-launch</code> as outlined [[#Running|above]]. Alternatively, [[#D-Bus|disable D-Bus support]].

== Quick Configuration ==

You might want to use {{Pkg|pavucontrol}} to have a simple GUI app for controlling sound, outputs, etc.

== See Also ==

* [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:Desktop]]
[[Category:Multimedia]]
[[Category:Sound]]

User:154pinkchairs

2022-09-06T20:50:02Z

154pinkchairs: /* Marcelina Hołub */

== Marcelina Hołub ==
=== [https://github.com/154pinkchairs/ Github] ===
==== [https://hosted.weblate.org/user/154pinkchairs/ Weblate] ====
===== '''Age:''' ===== 24 
===== '''Current city:''' ===== Kraków

Tech stack: Go, Python, Bash, node, Vue, Lua

Libre software enthusiast since the age of 12. A staunch privacy/digital rights enthusiast and advocate. Linux distros I've used: Ubuntu, Mint, Android (ungoogled), Debian, Fedora, Devuan, Manjaro, Puppy Linux, Tails, DD-WRT, openWRT and of course Alpine.

Nextcloud

2022-04-28T03:19:55Z

154pinkchairs: /* Increase upload size */ update from /etc/php to /etc/php8 as this is the current name of the folder created after installing the latest PHP version for 3.15

[https://nextcloud.com/ Nextcloud] is WedDAV-based solution for storing and sharing on-line your data, files, images, video, music, calendars and contacts. [http://karlitschek.de/2016/06/nextcloud/ Nextcloud is a fork of ownCloud with enterprise features included].

= Installation =
{{pkg|nextcloud}} is available from Alpine 3.5 and greater.

Before you start installing anything, make sure you have the latest packages available. Make sure you are using an 'http' repository in your {{path|/etc/apk/repositories}} file, then:
{{cmd|apk update}}
{{tip|Detailed information is found in [[Include:Upgrading_to_latest_release|this]] doc.}}

== Database ==
First you have to decide which database to use. Use one of the databases listed below.

=== Sqlite ===
All you need to do is to install the package:
{{cmd|apk add nextcloud-sqlite}}

=== PostgreSQL ===
Install the package:
{{cmd|apk add nextcloud-pgsql postgresql postgresql-client}}

Next thing is to configure and start the database:
{{cmd|/etc/init.d/postgresql setup
/etc/init.d/postgresql start}}

Next, you need to create a user and temporarily grant the CREATEDB privilege:
{{cmd|psql -U postgres
CREATE USER mycloud WITH PASSWORD 'test123';
ALTER ROLE mycloud CREATEDB;
\q}}
{{Note|Replace the above username 'mycloud' and password 'test123' with something secure. Remember these settings. You will need them later when setting up nextcloud.}}

Set postgresql to start on boot:
{{cmd|rc-update add postgresql}}

=== MariaDB ===
Install the package:
{{cmd|apk add nextcloud-mysql mariadb mariadb-client}}

Now configure and start {{pkg|mariadb}}:
{{cmd|<nowiki>mysql_install_db --user=mysql --datadir=/var/lib/mysql</nowiki>
service mariadb start
rc-update add mariadb
mysql_secure_installation}}
Follow the wizard to setup passwords, etc.
{{Note|Remember the usernames/passwords that you set using the wizard. You will need them later.}}

Next, you need to create a user and database and set permissions:
{{cmd|mysql -u root -p
CREATE DATABASE nextcloud;
GRANT ALL ON nextcloud.* TO 'mycloud'@'localhost' IDENTIFIED BY 'test123';
GRANT ALL ON nextcloud.* TO 'mycloud'@'localhost.localdomain' IDENTIFIED BY 'test123';
FLUSH PRIVILEGES;
EXIT}}
{{Note|Replace the above username 'mycloud' and password 'test123' with something secure. Remember these settings. You will need them later when setting up nextcloud.}}

{{pkg|mariadb-client}} is not needed anymore. Let's uninstall it:
{{cmd|apk del mariadb-client}}

== Webserver ==
Next thing is to choose, install, and configure a webserver. In this example we will install {{pkg|nginx}} or {{pkg|lighttpd}}. ''Nginx'' is preferred over ''Lighttpd'' since the latter will consume a lot of memory when working with large files (see [http://redmine.lighttpd.net/issues/1283 lighty bug #1283]). You are free to install any other webserver of your choice as long as it supports PHP and FastCGI. Generating an SSL certificate for your webserver is outside of the scope of this document.

{{pkg|nextcloud-initscript}} facilitates running the webserver with php-fpm.

{{cmd|apk add nextcloud-initscript}}

=== Nginx ===
Install the needed packages:
{{cmd|apk add nginx php8-fpm}}

Delete the default nginx website configuration:
{{cmd|rm /etc/nginx/http.d/default.conf}}

Create a configuration file for your site in {{path|/etc/nginx/http.d/mysite.mydomain.com.conf}}:
{{Cat|/etc/nginx/http.d/mysite.mydomain.com.conf|server {
#listen [::]:80; #uncomment for IPv6 support
listen 80;
return 301 https://$host$request_uri;
server_name mysite.mydomain.com;
}

server {
#listen [::]:443 ssl; #uncomment for IPv6 support
listen 443 ssl;
server_name mysite.mydomain.com;

root /usr/share/webapps/nextcloud;
index index.php index.html index.htm;
disable_symlinks off;

ssl_certificate /etc/ssl/cert.pem;
ssl_certificate_key /etc/ssl/key.pem;
ssl_session_timeout 5m;

#Enable Perfect Forward Secrecy and ciphers without known vulnerabilities
#Beware! It breaks compatibility with older OS and browsers (e.g. Windows XP, Android 2.x, etc.)
#ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA;
#ssl_prefer_server_ciphers on;

location / {
try_files $uri $uri/ /index.html;
}

# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
location ~ [^/]\.php(/|$) {
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
if (!-f $document_root$fastcgi_script_name) {
return 404;
}
#fastcgi_pass 127.0.0.1:9000;
#fastcgi_pass unix:/run/php-fpm/socket;
fastcgi_pass unix:/run/nextcloud/fastcgi.sock; # From the nextcloud-initscript package
fastcgi_index index.php;
include fastcgi.conf;
}

# Help pass nextcloud's configuration checks after install:
# Per https://docs.nextcloud.com/server/22/admin_manual/issues/general_troubleshooting.html#service-discovery
location ^~ /.well-known/carddav { return 301 /remote.php/dav/; }
location ^~ /.well-known/caldav { return 301 /remote.php/dav/; }
location ^~ /.well-known/webfinger { return 301 /index.php/.well-known/webfinger; }
location ^~ /.well-known/nodeinfo { return 301 /index.php/.well-known/nodeinfo; }
}
}}

If you plan to enable uploads - and you probably do) - then you need to modify the default:
<pre>
client_max_body_size 1m;'
</pre>
setting in {{path|/etc/nginx/nginx.conf}}. For testing purposes, I disabled the limit by changing it to:

<pre>
client_max_body_size 0;
</pre>

This enabled large file uploads and auto-uploads to work. Note, this is a file-size restriction in addition to the restriction set in {{path|/etc/php8/php-fpm.d/nextcloud.conf}}. That second restriction defaults to:

<pre>
; Maximal size of a file that can be uploaded via web interface.
php_admin_value[memory_limit] = 512M
php_admin_value[post_max_size] = 513M
php_admin_value[upload_max_filesize] = 513M
</pre>

Another setting that may limit file-size is in configuration file {{path|/etc/php8/php.ini}}, where I set the restriction to to:
<pre>
upload_max_filesize = 513M
</pre>
to match the {{path|/etc/php8/php-fpm.d/nextcloud.conf}} file-size restriction.

If you are running from RAM and you're dealing with large files you might need to move the FastCGI temp file from {{path|/tmp}} to {{path|/var/tmp}} or to a directory that is mounted on hdd:
<pre>
fastcgi_temp_path /var/tmp/nginx/fastcgi 1 2;
</pre>

Large file uploads take some time to be processed by php-fpm, so you need to bump the Nginx default read timeout:

<pre>
fastcgi_read_timeout 300s;
</pre>

{{Note|If you are serving several users make sure to tune the *''pm.max_children'' setting in {{path|/etc/php8/php-fpm.d/nextcloud.conf}}}}

{{path|/etc/nginx/nginx.conf}} should already be configured to load your site config from this directory:
<pre>
...
# Includes virtual hosts configs.
include /etc/nginx/http.d/*;
...
</pre>

Start services:
{{cmd|service nginx start
service nextcloud start}}

Enable automatic startup of services:
{{cmd|rc-update add nginx
rc-update add nextcloud}}

=== Lighttpd ===
Install the package:
{{cmd|apk add lighttpd php5-cgi}}

Make sure you have FastCGI enabled in {{pkg|lighttpd}}:
{{cat|/etc/lighttpd/lighttpd.conf|...
include "mod_fastcgi.conf"
...}}

Start up the webserver:
{{cmd|/etc/init.d/lighttpd start}}

{{tip|You might want to follow the [http://wiki.alpinelinux.org/wiki/Lighttpd_Https_access Lighttpd_Https_access] doc in order to configure lighttpd to use https ''(securing your connections to your nextcloud server)''.}}

Link {{pkg|nextcloud}} installation to web server directory:
{{cmd|ln -s /usr/share/webapps/nextcloud /var/www/localhost/htdocs}}

== Other settings ==
=== Hardening ===
Consider updating the variable <code>url.access-deny</code> in {{path|/etc/lighttpd/lighttpd.conf}} for additional security. Add <code>"config.php"</code> to the variable ''(that's where the database is stored)'' so it looks something like this:
{{cat|/etc/lighttpd/lighttpd.conf|...
url.access-deny {{=}} ("~", ".inc", "config.php")
...}}
Restart {{pkg|lighttpd}} to activate the changes:
{{cmd|/etc/init.d/lighttpd restart}}

=== Additional packages ===
Some large apps, such as pdfviewer, texteditor, notifications and videoplayer are in separate packages:
{{cmd|apk add nextcloud-files_pdfviewer nextcloud-text nextcloud-notifications nextcloud-files_videoplayer}}
You can also install a [https://pkgs.alpinelinux.org/package/v3.15/community/x86_64/nextcloud-default-apps meta-package] which installs all 30 core Nextcloud apps (listed as dependencies under aforementioned link):
{{cmd|apk add nextcloud-default-apps}}

=== How To Create a Self-Signed SSL Certificate ===
Install openssl:
{{cmd|apk add openssl}}
Generate your self signed certificate and its private key:
{{cmd|<nowiki>openssl req -x509 -nodes -days 365 -newkey rsa:4096 -keyout /etc/ssl1.1/private/nextcloud-selfsigned.key -out /etc/ssl1.1/certs/nextcloud-selfsigned.crt</nowiki>}}
Edit your nginx configuration:
{{cat|/etc/nginx/http.d/mysite.mydomain.com.conf|
ssl_certificate /etc/ssl1.1/certs/nextcloud-selfsigned.crt;
ssl_certificate_key /etc/ssl1.1/private/nextcloud-selfsigned.key;
}}

=== How To Install and Set Up Auto-Renewing LetsEncrypt SSL Certificate ===
After first setting up the Nextcloud server using the instructions in the 'Configure and use Nextcloud' section below, I then followed the SSL-setup instructions at: [[https://techjogging.com/create-letsencrypt-certificate-alpine-nginx.html Tech Jogging]].

I also had to add my Nextcloud servers Fully Qualified Domain Name (FQDN) to the list of trusted domains in /etc/nextcloud/config.php. In the section labelled: 'trusted_domains':

<pre>
'trusted_domains' =>
array (
0 => '<machine's local IP address>',
1 => 'nextcloud.mydomain.com',
),
}}
</pre>

= Configure and use Nextcloud =

== Configure ==
Point your browser at <code><nowiki>https://mysite.mydomain.com</nowiki></code> and follow the on-screen instructions to complete the installation, supplying the database user and password created before.

== Hardening PostgreSQL ==
If you have chosen PGSQL backend, revoke CREATEDB privilege from 'mycloud' user:
{{cmd|psql -U postgres
ALTER ROLE mycloud NOCREATEDB;
\q}}

== Increase upload size ==
{{path|/etc/php8/php-fpm.d/nextcloud.conf}} has overridden default file sizes, but they can be modified further to suit your needs:
<pre>
; Maximal size of a file that can be uploaded via web interface.
php_admin_value[memory_limit] = 512M
php_admin_value[post_max_size] = 513M
php_admin_value[upload_max_filesize] = 513M
</pre>

== enable opcache for nginx/php8 ==
To increase performace install
{{cmd|apk add php8-opcache}}

Now uncomment/edit lines in /etc/php8/php.ini:
<pre>
...
opcache.enable=1
opcache.enable_cli=1
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.memory_consumption=128 //you can reduce this slightly when short on RAM
opcache.save_comments=1
opcache.revalidate_freq=1
...
</pre>

Restart php-fpm8
{{cmd|rc-service php-fpm8 restart}}

== Clients ==
There are clients available for many platforms, Android included:
* http://nextcloud.org/sync-clients/ ''(nextcloud Sync clients)''
* http://nextcloud.org/support/android/ ''(Android client)''

[http://pkgs.alpinelinux.org/packages?name=nextcloud-client&branch=&repo=&arch=&maintainer= nextcloud-client] is currently available in the testing repo.

= Video Communication =
One of the major features of Nextcloud 11, available on Alpine 3.6 (currently edge) is a [https://nextcloud.com/webrtc/ WebRTC app], which relies on Spreed WebRTC server, which is available in the Alpine testing repository. Everything is still beta, so be aware of it :-). If you want a private video conferencing server install Nextcloud using Nginx and do the following (you can use Apache as well and follow the ''Apache config'' instructions [https://nextcloud.com/webrtc/ nextcloud.com]):

Put the following config in the ''server'' section of Nginx:
<pre>
# Spreed WebRTC
location ^~ /webrtc {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_buffering on;
proxy_ignore_client_abort off;
proxy_redirect off;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_buffer_size 4k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
proxy_temp_file_write_size 64k;
proxy_next_upstream error timeout invalid_header http_502 http_503 http_504;
}
</pre>

Put the following section in the ''http'' section of Nginx:
<pre>
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
</pre>

Reload Nginx:
{{cmd|rc-service nginx reload}}

Install Spreed WedRTC server (make sure you have the testing [https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management#Packages_and_Repositories repository] enabled):
{{cmd|apk add spreed-web-server}}

Using the configuration file in ''/etc/spreed-webrtc/spreed-webrtc-server.conf'' follow the instructions at [https://nextcloud.com/webrtc/ nextcloud.com] to configure Spreed WebRTC server. Then start the server:
{{cmd|rc-service spreed-web-server start}}
{{cmd|rc-update add spreed-web-server}}

Install the ''Spreed video calls'' app in Nextcloud and enjoy your private video calls.

[[Category:Server]]

User:154pinkchairs

2022-04-24T16:08:12Z

154pinkchairs: /* Marcelina Hołub */

== Marcelina Hołub ==
=== [https://github.com/154pinkchairs/ Github] ===
==== [https://hosted.weblate.org/user/154pinkchairs/ Weblate] ====
===== '''Age:''' ===== 24 
===== '''Current city:''' ===== Kraków

Libre software enthusiast since the age of 12. Self learning programmer, currently quite well skilled in Python, Shell scripts, web design and to some extent in JS/TS; looking forward to learn C++ or Go. A staunch privacy/digital rights enthusiast and advocate. Neuroatypical and queer 🌈️♾️🏳️‍🌈️, cat lover 😺️ and brutalism appreciator 🪨️. Using Manjaro XFCE as my daily driver and Alpine on my VPS. I love the very low memory footprint whereas OpenRC also doesn't seem to be as affected by adding new services as systemd. Tried migrating to Artix on my desktop, but it resulted in too many problems.

{
└─(17:30:51)──> neofetch ──(Sun,Apr24)─┘ 
 
██████████████████ ████████ x@Aurora 
██████████████████ ████████ ------- 
██████████████████ ████████ OS: Manjaro Linux x86_64 
██████████████████ ████████ Host: Lenovo IdeaPad Y580 Lenovo IdeaPad Y580 
████████ ████████ Kernel: 5.17.1-3-MANJARO 
████████ ████████ ████████ Uptime: 2 days, 19 hours, 31 mins 
████████ ████████ ████████ Packages: 2331 (pacman) 
████████ ████████ ████████ Shell: zsh 5.8.1 
████████ ████████ ████████ Resolution: 1366x768, 1920x1080 
████████ ████████ ████████ DE: Xfce 4.16 
████████ ████████ ████████ WM: Xfwm4 
████████ ████████ ████████ WM Theme: Fluent-dark 
████████ ████████ ████████ Theme: Fluent-dark [GTK2], adwaita-creamy [GTK3] 
████████ ████████ ████████ Icons: Zafiro-icons-Dark [GTK2], Adwaita [GTK3] 
Terminal: xfce4-terminal 
Terminal Font: Inconsolata 12 
CPU: Intel i7-3630QM (8) @ 2.040GHz 
GPU: Intel 3rd Gen Core processor Graphics Controller 
GPU: NVIDIA GeForce GTX 660M 
Memory: 4666MiB / 7846MiB 
} 
Second PC: also runs Manjaro (Budgie), plus Windows solely for gaming with multiple spyware blocking solutions; i5-6660K, 24 GB DDR4 2400MHz, need to buy a SSD and GPU for it. Haven't decided yet what to install on the SSD, might give a try to Gentoo. Linux distros I've used: Ubuntu, Mint, Android (ungoogled), Debian, Fedora, Devuan, Manjaro, Puppy Linux, Tails, DD-WRT and of course Alpine.

User:154pinkchairs

2022-04-24T16:07:53Z

154pinkchairs: /* Marcelina Hołub */

== Marcelina Hołub ==
=== [https://github.com/154pinkchairs/ Github] ===
==== [https://hosted.weblate.org/user/154pinkchairs/ Weblate] ====
===== '''Age:''' ===== 24 
===== '''Current city:''' ===== Kraków

Libre software enthusiast since the age of 12. Self learning programmer, currently quite well skilled in Python, Shell scripts, web design and to some extent in JS/TS; looking forward to learn C++ or Go. A staunch privacy/digital rights enthusiast and advocate. Neuroatypical and queer 🌈️♾️🏳️‍🌈️, cat lover 😺️ and brutalism appreciator 🪨️. Using Manjaro XFCE as my daily driver and Alpine on my VPS. I love the very low memory footprint whereas OpenRC also doesn't seem to be as affected by adding new services as systemd. Tried migrating to Artix on my desktop, but it resulted in too many problems.

{
└─(17:30:51)──> neofetch ──(Sun,Apr24)─┘ 
 
██████████████████ ████████ x@Aurora 
██████████████████ ████████ ------- 
██████████████████ ████████ OS: Manjaro Linux x86_64 
██████████████████ ████████ Host: Lenovo IdeaPad Y580 Lenovo IdeaPad Y580 
████████ ████████ Kernel: 5.17.1-3-MANJARO
████████ ████████ ████████ Uptime: 2 days, 19 hours, 31 mins 
████████ ████████ ████████ Packages: 2331 (pacman) 
████████ ████████ ████████ Shell: zsh 5.8.1 
████████ ████████ ████████ Resolution: 1366x768, 1920x1080 
████████ ████████ ████████ DE: Xfce 4.16 
████████ ████████ ████████ WM: Xfwm4 
████████ ████████ ████████ WM Theme: Fluent-dark 
████████ ████████ ████████ Theme: Fluent-dark [GTK2], adwaita-creamy [GTK3] 
████████ ████████ ████████ Icons: Zafiro-icons-Dark [GTK2], Adwaita [GTK3] 
Terminal: xfce4-terminal 
Terminal Font: Inconsolata 12 
CPU: Intel i7-3630QM (8) @ 2.040GHz 
GPU: Intel 3rd Gen Core processor Graphics Controller 
GPU: NVIDIA GeForce GTX 660M 
Memory: 4666MiB / 7846MiB 
} 
Second PC: also runs Manjaro (Budgie), plus Windows solely for gaming with multiple spyware blocking solutions; i5-6660K, 24 GB DDR4 2400MHz, need to buy a SSD and GPU for it. Haven't decided yet what to install on the SSD, might give a try to Gentoo. Linux distros I've used: Ubuntu, Mint, Android (ungoogled), Debian, Fedora, Devuan, Manjaro, Puppy Linux, Tails, DD-WRT and of course Alpine.

User:154pinkchairs

2022-04-24T16:06:34Z

154pinkchairs: fix newlines

== Marcelina Hołub ==
=== [https://github.com/154pinkchairs/ Github] ===
==== [https://hosted.weblate.org/user/154pinkchairs/ Weblate] ====
===== '''Age:''' ===== 24 
===== '''Current city:''' ===== Kraków

Libre software enthusiast since the age of 12. Self learning programmer, currently quite well skilled in Python, Shell scripts, web design and to some extent in JS/TS; looking forward to learn C++ or Go. A staunch privacy/digital rights enthusiast and advocate. Neuroatypical and queer 🌈️♾️🏳️‍🌈️, cat lover 😺️ and brutalism appreciator 🪨️. Using Manjaro XFCE as my daily driver and Alpine on my VPS. I love the very low memory footprint whereas OpenRC also doesn't seem to be as affected by adding new services as systemd. Tried migrating to Artix on my desktop, but it resulted in too many problems.

{
└─(17:30:51)──> neofetch ──(Sun,Apr24)─┘ 
 
██████████████████ ████████ x@Aurora 
██████████████████ ████████ ------- 
██████████████████ ████████ OS: Manjaro Linux x86_64 
██████████████████ ████████ Host: Lenovo IdeaPad Y580 Lenovo IdeaPad Y580 
████████ ████████ Kernel: 5.17.1-3-MANJARO 
████████ ████████ ████████ Uptime: 2 days, 19 hours, 31 mins 
████████ ████████ ████████ Packages: 2331 (pacman) 
████████ ████████ ████████ Shell: zsh 5.8.1 
████████ ████████ ████████ Resolution: 1366x768, 1920x1080 
████████ ████████ ████████ DE: Xfce 4.16 
████████ ████████ ████████ WM: Xfwm4 
████████ ████████ ████████ WM Theme: Fluent-dark 
████████ ████████ ████████ Theme: Fluent-dark [GTK2], adwaita-creamy [GTK3] 
████████ ████████ ████████ Icons: Zafiro-icons-Dark [GTK2], Adwaita [GTK3] 
Terminal: xfce4-terminal 
Terminal Font: Inconsolata 12 
CPU: Intel i7-3630QM (8) @ 2.040GHz 
GPU: Intel 3rd Gen Core processor Graphics Controller 
GPU: NVIDIA GeForce GTX 660M 
Memory: 4666MiB / 7846MiB 
} 
Second PC: also runs Manjaro (Budgie), plus Windows solely for gaming with multiple spyware blocking solutions; i5-6660K, 24 GB DDR4 2400MHz, need to buy a SSD and GPU for it. Haven't decided yet what to install on the SSD, might give a try to Gentoo. Linux distros I've used: Ubuntu, Mint, Android (ungoogled), Debian, Fedora, Devuan, Manjaro, Puppy Linux, Tails, DD-WRT and of course Alpine.

User:154pinkchairs

2022-04-24T16:04:44Z

154pinkchairs: self-intro

== Marcelina Hołub ==
=== [https://github.com/154pinkchairs/ Github] ===
==== [https://hosted.weblate.org/user/154pinkchairs/ Weblate] ====
===== '''Age:''' ===== 24
===== '''Current city:''' ===== Kraków

Libre software enthusiast since the age of 12. Self learning programmer, currently quite well skilled in Python, Shell scripts, web design and to some extent in JS/TS; looking forward to learn C++ or Go. A staunch privacy/digital rights enthusiast and advocate. Neuroatypical and queer 🌈️♾️🏳️‍🌈️, cat lover 😺️ and brutalism appreciator 🪨️. Using Manjaro XFCE as my daily driver and Alpine on my VPS. I love the very low memory footprint whereas OpenRC also doesn't seem to be as affected by adding new services as systemd. Tried migrating to Artix on my desktop, but it resulted in too many problems.

{
└─(17:30:51)──> neofetch ──(Sun,Apr24)─┘
██████████████████ ████████ x@Aurora
██████████████████ ████████ -------
██████████████████ ████████ OS: Manjaro Linux x86_64
██████████████████ ████████ Host: Lenovo IdeaPad Y580 Lenovo IdeaPad Y580
████████ ████████ Kernel: 5.17.1-3-MANJARO
████████ ████████ ████████ Uptime: 2 days, 19 hours, 31 mins
████████ ████████ ████████ Packages: 2331 (pacman)
████████ ████████ ████████ Shell: zsh 5.8.1
████████ ████████ ████████ Resolution: 1366x768, 1920x1080
████████ ████████ ████████ DE: Xfce 4.16
████████ ████████ ████████ WM: Xfwm4
████████ ████████ ████████ WM Theme: Fluent-dark
████████ ████████ ████████ Theme: Fluent-dark [GTK2], adwaita-creamy [GTK3]
████████ ████████ ████████ Icons: Zafiro-icons-Dark [GTK2], Adwaita [GTK3]
Terminal: xfce4-terminal
Terminal Font: Inconsolata 12
CPU: Intel i7-3630QM (8) @ 2.040GHz
GPU: Intel 3rd Gen Core processor Graphics Controller
GPU: NVIDIA GeForce GTX 660M
Memory: 4666MiB / 7846MiB
}
Second PC: also runs Manjaro (Budgie), plus Windows solely for gaming with multiple spyware blocking solutions; i5-6660K, 24 GB DDR4 2400MHz, need to buy a SSD and GPU for it. Haven't decided yet what to install on the SSD, might give a try to Gentoo. Linux distros I've used: Ubuntu, Mint, Android (ungoogled), Debian, Fedora, Devuan, Manjaro, Puppy Linux, Tails, DD-WRT and of course Alpine.

Nextcloud

2022-04-24T14:59:17Z

154pinkchairs: /* enable opcache for nginx/php7 */ » /* (...)/php8 */ update to current php version. Add a comment that opcache.memory_consumption might be reduced when the user has limited RAM available.

[https://nextcloud.com/ Nextcloud] is WedDAV-based solution for storing and sharing on-line your data, files, images, video, music, calendars and contacts. [http://karlitschek.de/2016/06/nextcloud/ Nextcloud is a fork of ownCloud with enterprise features included].

= Installation =
{{pkg|nextcloud}} is available from Alpine 3.5 and greater.

Before you start installing anything, make sure you have the latest packages available. Make sure you are using an 'http' repository in your {{path|/etc/apk/repositories}} file, then:
{{cmd|apk update}}
{{tip|Detailed information is found in [[Include:Upgrading_to_latest_release|this]] doc.}}

== Database ==
First you have to decide which database to use. Use one of the databases listed below.

=== Sqlite ===
All you need to do is to install the package:
{{cmd|apk add nextcloud-sqlite}}

=== PostgreSQL ===
Install the package:
{{cmd|apk add nextcloud-pgsql postgresql postgresql-client}}

Next thing is to configure and start the database:
{{cmd|/etc/init.d/postgresql setup
/etc/init.d/postgresql start}}

Next, you need to create a user and temporarily grant the CREATEDB privilege:
{{cmd|psql -U postgres
CREATE USER mycloud WITH PASSWORD 'test123';
ALTER ROLE mycloud CREATEDB;
\q}}
{{Note|Replace the above username 'mycloud' and password 'test123' with something secure. Remember these settings. You will need them later when setting up nextcloud.}}

Set postgresql to start on boot:
{{cmd|rc-update add postgresql}}

=== MariaDB ===
Install the package:
{{cmd|apk add nextcloud-mysql mariadb mariadb-client}}

Now configure and start {{pkg|mariadb}}:
{{cmd|<nowiki>mysql_install_db --user=mysql --datadir=/var/lib/mysql</nowiki>
service mariadb start
rc-update add mariadb
mysql_secure_installation}}
Follow the wizard to setup passwords, etc.
{{Note|Remember the usernames/passwords that you set using the wizard. You will need them later.}}

Next, you need to create a user and database and set permissions:
{{cmd|mysql -u root -p
CREATE DATABASE nextcloud;
GRANT ALL ON nextcloud.* TO 'mycloud'@'localhost' IDENTIFIED BY 'test123';
GRANT ALL ON nextcloud.* TO 'mycloud'@'localhost.localdomain' IDENTIFIED BY 'test123';
FLUSH PRIVILEGES;
EXIT}}
{{Note|Replace the above username 'mycloud' and password 'test123' with something secure. Remember these settings. You will need them later when setting up nextcloud.}}

{{pkg|mariadb-client}} is not needed anymore. Let's uninstall it:
{{cmd|apk del mariadb-client}}

== Webserver ==
Next thing is to choose, install, and configure a webserver. In this example we will install {{pkg|nginx}} or {{pkg|lighttpd}}. ''Nginx'' is preferred over ''Lighttpd'' since the latter will consume a lot of memory when working with large files (see [http://redmine.lighttpd.net/issues/1283 lighty bug #1283]). You are free to install any other webserver of your choice as long as it supports PHP and FastCGI. Generating an SSL certificate for your webserver is outside of the scope of this document.

{{pkg|nextcloud-initscript}} facilitates running the webserver with php-fpm.

{{cmd|apk add nextcloud-initscript}}

=== Nginx ===
Install the needed packages:
{{cmd|apk add nginx php8-fpm}}

Delete the default nginx website configuration:
{{cmd|rm /etc/nginx/http.d/default.conf}}

Create a configuration file for your site in {{path|/etc/nginx/http.d/mysite.mydomain.com.conf}}:
{{Cat|/etc/nginx/http.d/mysite.mydomain.com.conf|server {
#listen [::]:80; #uncomment for IPv6 support
listen 80;
return 301 https://$host$request_uri;
server_name mysite.mydomain.com;
}

server {
#listen [::]:443 ssl; #uncomment for IPv6 support
listen 443 ssl;
server_name mysite.mydomain.com;

root /usr/share/webapps/nextcloud;
index index.php index.html index.htm;
disable_symlinks off;

ssl_certificate /etc/ssl/cert.pem;
ssl_certificate_key /etc/ssl/key.pem;
ssl_session_timeout 5m;

#Enable Perfect Forward Secrecy and ciphers without known vulnerabilities
#Beware! It breaks compatibility with older OS and browsers (e.g. Windows XP, Android 2.x, etc.)
#ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA;
#ssl_prefer_server_ciphers on;

location / {
try_files $uri $uri/ /index.html;
}

# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
location ~ [^/]\.php(/|$) {
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
if (!-f $document_root$fastcgi_script_name) {
return 404;
}
#fastcgi_pass 127.0.0.1:9000;
#fastcgi_pass unix:/run/php-fpm/socket;
fastcgi_pass unix:/run/nextcloud/fastcgi.sock; # From the nextcloud-initscript package
fastcgi_index index.php;
include fastcgi.conf;
}

# Help pass nextcloud's configuration checks after install:
# Per https://docs.nextcloud.com/server/22/admin_manual/issues/general_troubleshooting.html#service-discovery
location ^~ /.well-known/carddav { return 301 /remote.php/dav/; }
location ^~ /.well-known/caldav { return 301 /remote.php/dav/; }
location ^~ /.well-known/webfinger { return 301 /index.php/.well-known/webfinger; }
location ^~ /.well-known/nodeinfo { return 301 /index.php/.well-known/nodeinfo; }
}
}}

If you plan to enable uploads - and you probably do) - then you need to modify the default:
<pre>
client_max_body_size 1m;'
</pre>
setting in {{path|/etc/nginx/nginx.conf}}. For testing purposes, I disabled the limit by changing it to:

<pre>
client_max_body_size 0;
</pre>

This enabled large file uploads and auto-uploads to work. Note, this is a file-size restriction in addition to the restriction set in {{path|/etc/php8/php-fpm.d/nextcloud.conf}}. That second restriction defaults to:

<pre>
; Maximal size of a file that can be uploaded via web interface.
php_admin_value[memory_limit] = 512M
php_admin_value[post_max_size] = 513M
php_admin_value[upload_max_filesize] = 513M
</pre>

Another setting that may limit file-size is in configuration file {{path|/etc/php8/php.ini}}, where I set the restriction to to:
<pre>
upload_max_filesize = 513M
</pre>
to match the {{path|/etc/php8/php-fpm.d/nextcloud.conf}} file-size restriction.

If you are running from RAM and you're dealing with large files you might need to move the FastCGI temp file from {{path|/tmp}} to {{path|/var/tmp}} or to a directory that is mounted on hdd:
<pre>
fastcgi_temp_path /var/tmp/nginx/fastcgi 1 2;
</pre>

Large file uploads take some time to be processed by php-fpm, so you need to bump the Nginx default read timeout:

<pre>
fastcgi_read_timeout 300s;
</pre>

{{Note|If you are serving several users make sure to tune the *''pm.max_children'' setting in {{path|/etc/php8/php-fpm.d/nextcloud.conf}}}}

{{path|/etc/nginx/nginx.conf}} should already be configured to load your site config from this directory:
<pre>
...
# Includes virtual hosts configs.
include /etc/nginx/http.d/*;
...
</pre>

Start services:
{{cmd|service nginx start
service nextcloud start}}

Enable automatic startup of services:
{{cmd|rc-update add nginx
rc-update add nextcloud}}

=== Lighttpd ===
Install the package:
{{cmd|apk add lighttpd php5-cgi}}

Make sure you have FastCGI enabled in {{pkg|lighttpd}}:
{{cat|/etc/lighttpd/lighttpd.conf|...
include "mod_fastcgi.conf"
...}}

Start up the webserver:
{{cmd|/etc/init.d/lighttpd start}}

{{tip|You might want to follow the [http://wiki.alpinelinux.org/wiki/Lighttpd_Https_access Lighttpd_Https_access] doc in order to configure lighttpd to use https ''(securing your connections to your nextcloud server)''.}}

Link {{pkg|nextcloud}} installation to web server directory:
{{cmd|ln -s /usr/share/webapps/nextcloud /var/www/localhost/htdocs}}

== Other settings ==
=== Hardening ===
Consider updating the variable <code>url.access-deny</code> in {{path|/etc/lighttpd/lighttpd.conf}} for additional security. Add <code>"config.php"</code> to the variable ''(that's where the database is stored)'' so it looks something like this:
{{cat|/etc/lighttpd/lighttpd.conf|...
url.access-deny {{=}} ("~", ".inc", "config.php")
...}}
Restart {{pkg|lighttpd}} to activate the changes:
{{cmd|/etc/init.d/lighttpd restart}}

=== Additional packages ===
Some large apps, such as pdfviewer, texteditor, notifications and videoplayer are in separate packages:
{{cmd|apk add nextcloud-files_pdfviewer nextcloud-text nextcloud-notifications nextcloud-files_videoplayer}}
You can also install a [https://pkgs.alpinelinux.org/package/v3.15/community/x86_64/nextcloud-default-apps meta-package] which installs all 30 core Nextcloud apps (listed as dependencies under aforementioned link):
{{cmd|apk add nextcloud-default-apps}}

=== How To Create a Self-Signed SSL Certificate ===
Install openssl:
{{cmd|apk add openssl}}
Generate your self signed certificate and its private key:
{{cmd|<nowiki>openssl req -x509 -nodes -days 365 -newkey rsa:4096 -keyout /etc/ssl1.1/private/nextcloud-selfsigned.key -out /etc/ssl1.1/certs/nextcloud-selfsigned.crt</nowiki>}}
Edit your nginx configuration:
{{cat|/etc/nginx/http.d/mysite.mydomain.com.conf|
ssl_certificate /etc/ssl1.1/certs/nextcloud-selfsigned.crt;
ssl_certificate_key /etc/ssl1.1/private/nextcloud-selfsigned.key;
}}

=== How To Install and Set Up Auto-Renewing LetsEncrypt SSL Certificate ===
After first setting up the Nextcloud server using the instructions in the 'Configure and use Nextcloud' section below, I then followed the SSL-setup instructions at: [[https://techjogging.com/create-letsencrypt-certificate-alpine-nginx.html Tech Jogging]].

I also had to add my Nextcloud servers Fully Qualified Domain Name (FQDN) to the list of trusted domains in /etc/nextcloud/config.php. In the section labelled: 'trusted_domains':

<pre>
'trusted_domains' =>
array (
0 => '<machine's local IP address>',
1 => 'nextcloud.mydomain.com',
),
}}
</pre>

= Configure and use Nextcloud =

== Configure ==
Point your browser at <code><nowiki>https://mysite.mydomain.com</nowiki></code> and follow the on-screen instructions to complete the installation, supplying the database user and password created before.

== Hardening PostgreSQL ==
If you have chosen PGSQL backend, revoke CREATEDB privilege from 'mycloud' user:
{{cmd|psql -U postgres
ALTER ROLE mycloud NOCREATEDB;
\q}}

== Increase upload size ==
{{path|/etc/php/php-fpm.d/nextcloud.conf}} has overridden default file sizes, but they can be modified further to suit your needs:
<pre>
; Maximal size of a file that can be uploaded via web interface.
php_admin_value[memory_limit] = 512M
php_admin_value[post_max_size] = 513M
php_admin_value[upload_max_filesize] = 513M
</pre>

== enable opcache for nginx/php8 ==
To increase performace install
{{cmd|apk add php8-opcache}}

Now uncomment/edit lines in /etc/php8/php.ini:
<pre>
...
opcache.enable=1
opcache.enable_cli=1
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.memory_consumption=128 //you can reduce this slightly when short on RAM
opcache.save_comments=1
opcache.revalidate_freq=1
...
</pre>

Restart php-fpm8
{{cmd|rc-service php-fpm8 restart}}

== Clients ==
There are clients available for many platforms, Android included:
* http://nextcloud.org/sync-clients/ ''(nextcloud Sync clients)''
* http://nextcloud.org/support/android/ ''(Android client)''

[http://pkgs.alpinelinux.org/packages?name=nextcloud-client&branch=&repo=&arch=&maintainer= nextcloud-client] is currently available in the testing repo.

= Video Communication =
One of the major features of Nextcloud 11, available on Alpine 3.6 (currently edge) is a [https://nextcloud.com/webrtc/ WebRTC app], which relies on Spreed WebRTC server, which is available in the Alpine testing repository. Everything is still beta, so be aware of it :-). If you want a private video conferencing server install Nextcloud using Nginx and do the following (you can use Apache as well and follow the ''Apache config'' instructions [https://nextcloud.com/webrtc/ nextcloud.com]):

Put the following config in the ''server'' section of Nginx:
<pre>
# Spreed WebRTC
location ^~ /webrtc {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_buffering on;
proxy_ignore_client_abort off;
proxy_redirect off;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_buffer_size 4k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
proxy_temp_file_write_size 64k;
proxy_next_upstream error timeout invalid_header http_502 http_503 http_504;
}
</pre>

Put the following section in the ''http'' section of Nginx:
<pre>
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
</pre>

Reload Nginx:
{{cmd|rc-service nginx reload}}

Install Spreed WedRTC server (make sure you have the testing [https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management#Packages_and_Repositories repository] enabled):
{{cmd|apk add spreed-web-server}}

Using the configuration file in ''/etc/spreed-webrtc/spreed-webrtc-server.conf'' follow the instructions at [https://nextcloud.com/webrtc/ nextcloud.com] to configure Spreed WebRTC server. Then start the server:
{{cmd|rc-service spreed-web-server start}}
{{cmd|rc-update add spreed-web-server}}

Install the ''Spreed video calls'' app in Nextcloud and enjoy your private video calls.

[[Category:Server]]

Nextcloud

2022-04-24T13:50:51Z

154pinkchairs: /* Additional packages */ update package names, mention nextcloud-default-apps meta-package. Src: https://pkgs.alpinelinux.org/packages?name=nextcloud-*&branch=v3.15&arch=x86_64

[https://nextcloud.com/ Nextcloud] is WedDAV-based solution for storing and sharing on-line your data, files, images, video, music, calendars and contacts. [http://karlitschek.de/2016/06/nextcloud/ Nextcloud is a fork of ownCloud with enterprise features included].

= Installation =
{{pkg|nextcloud}} is available from Alpine 3.5 and greater.

Before you start installing anything, make sure you have the latest packages available. Make sure you are using an 'http' repository in your {{path|/etc/apk/repositories}} file, then:
{{cmd|apk update}}
{{tip|Detailed information is found in [[Include:Upgrading_to_latest_release|this]] doc.}}

== Database ==
First you have to decide which database to use. Use one of the databases listed below.

=== Sqlite ===
All you need to do is to install the package:
{{cmd|apk add nextcloud-sqlite}}

=== PostgreSQL ===
Install the package:
{{cmd|apk add nextcloud-pgsql postgresql postgresql-client}}

Next thing is to configure and start the database:
{{cmd|/etc/init.d/postgresql setup
/etc/init.d/postgresql start}}

Next, you need to create a user and temporarily grant the CREATEDB privilege:
{{cmd|psql -U postgres
CREATE USER mycloud WITH PASSWORD 'test123';
ALTER ROLE mycloud CREATEDB;
\q}}
{{Note|Replace the above username 'mycloud' and password 'test123' with something secure. Remember these settings. You will need them later when setting up nextcloud.}}

Set postgresql to start on boot:
{{cmd|rc-update add postgresql}}

=== MariaDB ===
Install the package:
{{cmd|apk add nextcloud-mysql mariadb mariadb-client}}

Now configure and start {{pkg|mariadb}}:
{{cmd|<nowiki>mysql_install_db --user=mysql --datadir=/var/lib/mysql</nowiki>
service mariadb start
rc-update add mariadb
mysql_secure_installation}}
Follow the wizard to setup passwords, etc.
{{Note|Remember the usernames/passwords that you set using the wizard. You will need them later.}}

Next, you need to create a user and database and set permissions:
{{cmd|mysql -u root -p
CREATE DATABASE nextcloud;
GRANT ALL ON nextcloud.* TO 'mycloud'@'localhost' IDENTIFIED BY 'test123';
GRANT ALL ON nextcloud.* TO 'mycloud'@'localhost.localdomain' IDENTIFIED BY 'test123';
FLUSH PRIVILEGES;
EXIT}}
{{Note|Replace the above username 'mycloud' and password 'test123' with something secure. Remember these settings. You will need them later when setting up nextcloud.}}

{{pkg|mariadb-client}} is not needed anymore. Let's uninstall it:
{{cmd|apk del mariadb-client}}

== Webserver ==
Next thing is to choose, install, and configure a webserver. In this example we will install {{pkg|nginx}} or {{pkg|lighttpd}}. ''Nginx'' is preferred over ''Lighttpd'' since the latter will consume a lot of memory when working with large files (see [http://redmine.lighttpd.net/issues/1283 lighty bug #1283]). You are free to install any other webserver of your choice as long as it supports PHP and FastCGI. Generating an SSL certificate for your webserver is outside of the scope of this document.

{{pkg|nextcloud-initscript}} facilitates running the webserver with php-fpm.

{{cmd|apk add nextcloud-initscript}}

=== Nginx ===
Install the needed packages:
{{cmd|apk add nginx php8-fpm}}

Delete the default nginx website configuration:
{{cmd|rm /etc/nginx/http.d/default.conf}}

Create a configuration file for your site in {{path|/etc/nginx/http.d/mysite.mydomain.com.conf}}:
{{Cat|/etc/nginx/http.d/mysite.mydomain.com.conf|server {
#listen [::]:80; #uncomment for IPv6 support
listen 80;
return 301 https://$host$request_uri;
server_name mysite.mydomain.com;
}

server {
#listen [::]:443 ssl; #uncomment for IPv6 support
listen 443 ssl;
server_name mysite.mydomain.com;

root /usr/share/webapps/nextcloud;
index index.php index.html index.htm;
disable_symlinks off;

ssl_certificate /etc/ssl/cert.pem;
ssl_certificate_key /etc/ssl/key.pem;
ssl_session_timeout 5m;

#Enable Perfect Forward Secrecy and ciphers without known vulnerabilities
#Beware! It breaks compatibility with older OS and browsers (e.g. Windows XP, Android 2.x, etc.)
#ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA;
#ssl_prefer_server_ciphers on;

location / {
try_files $uri $uri/ /index.html;
}

# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
location ~ [^/]\.php(/|$) {
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
if (!-f $document_root$fastcgi_script_name) {
return 404;
}
#fastcgi_pass 127.0.0.1:9000;
#fastcgi_pass unix:/run/php-fpm/socket;
fastcgi_pass unix:/run/nextcloud/fastcgi.sock; # From the nextcloud-initscript package
fastcgi_index index.php;
include fastcgi.conf;
}

# Help pass nextcloud's configuration checks after install:
# Per https://docs.nextcloud.com/server/22/admin_manual/issues/general_troubleshooting.html#service-discovery
location ^~ /.well-known/carddav { return 301 /remote.php/dav/; }
location ^~ /.well-known/caldav { return 301 /remote.php/dav/; }
location ^~ /.well-known/webfinger { return 301 /index.php/.well-known/webfinger; }
location ^~ /.well-known/nodeinfo { return 301 /index.php/.well-known/nodeinfo; }
}
}}

If you plan to enable uploads - and you probably do) - then you need to modify the default:
<pre>
client_max_body_size 1m;'
</pre>
setting in {{path|/etc/nginx/nginx.conf}}. For testing purposes, I disabled the limit by changing it to:

<pre>
client_max_body_size 0;
</pre>

This enabled large file uploads and auto-uploads to work. Note, this is a file-size restriction in addition to the restriction set in {{path|/etc/php8/php-fpm.d/nextcloud.conf}}. That second restriction defaults to:

<pre>
; Maximal size of a file that can be uploaded via web interface.
php_admin_value[memory_limit] = 512M
php_admin_value[post_max_size] = 513M
php_admin_value[upload_max_filesize] = 513M
</pre>

Another setting that may limit file-size is in configuration file {{path|/etc/php8/php.ini}}, where I set the restriction to to:
<pre>
upload_max_filesize = 513M
</pre>
to match the {{path|/etc/php8/php-fpm.d/nextcloud.conf}} file-size restriction.

If you are running from RAM and you're dealing with large files you might need to move the FastCGI temp file from {{path|/tmp}} to {{path|/var/tmp}} or to a directory that is mounted on hdd:
<pre>
fastcgi_temp_path /var/tmp/nginx/fastcgi 1 2;
</pre>

Large file uploads take some time to be processed by php-fpm, so you need to bump the Nginx default read timeout:

<pre>
fastcgi_read_timeout 300s;
</pre>

{{Note|If you are serving several users make sure to tune the *''pm.max_children'' setting in {{path|/etc/php8/php-fpm.d/nextcloud.conf}}}}

{{path|/etc/nginx/nginx.conf}} should already be configured to load your site config from this directory:
<pre>
...
# Includes virtual hosts configs.
include /etc/nginx/http.d/*;
...
</pre>

Start services:
{{cmd|service nginx start
service nextcloud start}}

Enable automatic startup of services:
{{cmd|rc-update add nginx
rc-update add nextcloud}}

=== Lighttpd ===
Install the package:
{{cmd|apk add lighttpd php5-cgi}}

Make sure you have FastCGI enabled in {{pkg|lighttpd}}:
{{cat|/etc/lighttpd/lighttpd.conf|...
include "mod_fastcgi.conf"
...}}

Start up the webserver:
{{cmd|/etc/init.d/lighttpd start}}

{{tip|You might want to follow the [http://wiki.alpinelinux.org/wiki/Lighttpd_Https_access Lighttpd_Https_access] doc in order to configure lighttpd to use https ''(securing your connections to your nextcloud server)''.}}

Link {{pkg|nextcloud}} installation to web server directory:
{{cmd|ln -s /usr/share/webapps/nextcloud /var/www/localhost/htdocs}}

== Other settings ==
=== Hardening ===
Consider updating the variable <code>url.access-deny</code> in {{path|/etc/lighttpd/lighttpd.conf}} for additional security. Add <code>"config.php"</code> to the variable ''(that's where the database is stored)'' so it looks something like this:
{{cat|/etc/lighttpd/lighttpd.conf|...
url.access-deny {{=}} ("~", ".inc", "config.php")
...}}
Restart {{pkg|lighttpd}} to activate the changes:
{{cmd|/etc/init.d/lighttpd restart}}

=== Additional packages ===
Some large apps, such as pdfviewer, texteditor, notifications and videoplayer are in separate packages:
{{cmd|apk add nextcloud-files_pdfviewer nextcloud-text nextcloud-notifications nextcloud-files_videoplayer}}
You can also install a [https://pkgs.alpinelinux.org/package/v3.15/community/x86_64/nextcloud-default-apps meta-package] which installs all 30 core Nextcloud apps (listed as dependencies under aforementioned link):
{{cmd|apk add nextcloud-default-apps}}

=== How To Create a Self-Signed SSL Certificate ===
Install openssl:
{{cmd|apk add openssl}}
Generate your self signed certificate and its private key:
{{cmd|<nowiki>openssl req -x509 -nodes -days 365 -newkey rsa:4096 -keyout /etc/ssl1.1/private/nextcloud-selfsigned.key -out /etc/ssl1.1/certs/nextcloud-selfsigned.crt</nowiki>}}
Edit your nginx configuration:
{{cat|/etc/nginx/http.d/mysite.mydomain.com.conf|
ssl_certificate /etc/ssl1.1/certs/nextcloud-selfsigned.crt;
ssl_certificate_key /etc/ssl1.1/private/nextcloud-selfsigned.key;
}}

=== How To Install and Set Up Auto-Renewing LetsEncrypt SSL Certificate ===
After first setting up the Nextcloud server using the instructions in the 'Configure and use Nextcloud' section below, I then followed the SSL-setup instructions at: [[https://techjogging.com/create-letsencrypt-certificate-alpine-nginx.html Tech Jogging]].

I also had to add my Nextcloud servers Fully Qualified Domain Name (FQDN) to the list of trusted domains in /etc/nextcloud/config.php. In the section labelled: 'trusted_domains':

<pre>
'trusted_domains' =>
array (
0 => '<machine's local IP address>',
1 => 'nextcloud.mydomain.com',
),
}}
</pre>

= Configure and use Nextcloud =

== Configure ==
Point your browser at <code><nowiki>https://mysite.mydomain.com</nowiki></code> and follow the on-screen instructions to complete the installation, supplying the database user and password created before.

== Hardening PostgreSQL ==
If you have chosen PGSQL backend, revoke CREATEDB privilege from 'mycloud' user:
{{cmd|psql -U postgres
ALTER ROLE mycloud NOCREATEDB;
\q}}

== Increase upload size ==
{{path|/etc/php/php-fpm.d/nextcloud.conf}} has overridden default file sizes, but they can be modified further to suit your needs:
<pre>
; Maximal size of a file that can be uploaded via web interface.
php_admin_value[memory_limit] = 512M
php_admin_value[post_max_size] = 513M
php_admin_value[upload_max_filesize] = 513M
</pre>

== enable opcache for nginx/php7 ==
To increase performace install
{{cmd|apk add php7-opcache}}

Now uncomment/edit lines in /etc/php7/php.ini:
<pre>
...
opcache.enable=1
opcache.enable_cli=1
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.memory_consumption=128
opcache.save_comments=1
opcache.revalidate_freq=1
...
</pre>

Restart php-fpm7
{{cmd|rc-service php-fpm7 restart}}

== Clients ==
There are clients available for many platforms, Android included:
* http://nextcloud.org/sync-clients/ ''(nextcloud Sync clients)''
* http://nextcloud.org/support/android/ ''(Android client)''

[http://pkgs.alpinelinux.org/packages?name=nextcloud-client&branch=&repo=&arch=&maintainer= nextcloud-client] is currently available in the testing repo.

= Video Communication =
One of the major features of Nextcloud 11, available on Alpine 3.6 (currently edge) is a [https://nextcloud.com/webrtc/ WebRTC app], which relies on Spreed WebRTC server, which is available in the Alpine testing repository. Everything is still beta, so be aware of it :-). If you want a private video conferencing server install Nextcloud using Nginx and do the following (you can use Apache as well and follow the ''Apache config'' instructions [https://nextcloud.com/webrtc/ nextcloud.com]):

Put the following config in the ''server'' section of Nginx:
<pre>
# Spreed WebRTC
location ^~ /webrtc {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_buffering on;
proxy_ignore_client_abort off;
proxy_redirect off;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_buffer_size 4k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
proxy_temp_file_write_size 64k;
proxy_next_upstream error timeout invalid_header http_502 http_503 http_504;
}
</pre>

Put the following section in the ''http'' section of Nginx:
<pre>
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
</pre>

Reload Nginx:
{{cmd|rc-service nginx reload}}

Install Spreed WedRTC server (make sure you have the testing [https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management#Packages_and_Repositories repository] enabled):
{{cmd|apk add spreed-web-server}}

Using the configuration file in ''/etc/spreed-webrtc/spreed-webrtc-server.conf'' follow the instructions at [https://nextcloud.com/webrtc/ nextcloud.com] to configure Spreed WebRTC server. Then start the server:
{{cmd|rc-service spreed-web-server start}}
{{cmd|rc-update add spreed-web-server}}

Install the ''Spreed video calls'' app in Nextcloud and enjoy your private video calls.

[[Category:Server]]