lnorg/documentation
1
2
Fork 0
Code Issues 30 Pull requests Projects 6 Activity

Fixed #77, fixed #76, fixed#75

Browse source
This commit is contained in:
nils 2025-01-25 20:41:52 +01:00
parent a07c9b7d63
commit 75a9b07f1a
6 changed files with 74 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/gentoo-desktop-setup/graphical-session/login-manager.md
View file

@ -23,7 +23,7 @@ gui-apps/gtkgreet ~amd64
Then emerge River and the `greetd` components: Then emerge River and the `greetd` components:
``` ```
root@host:~# emerge -av river gtkgreet greetd display-manager-init swaybg sh# emerge -av river gtkgreet greetd display-manager-init swaybg
``` ```
Now `greetd` has to be configured to launch River with `gtkgreet`. Besides that styling `gtkgreet` can be done using css files and GTK themes and using this configuration a wallpaper which resides at `/etc/greetd/current_wallpaper.png`. Now `greetd` has to be configured to launch River with `gtkgreet`. Besides that styling `gtkgreet` can be done using css files and GTK themes and using this configuration a wallpaper which resides at `/etc/greetd/current_wallpaper.png`.
@ -102,7 +102,7 @@ DISPLAYMANAGER="greetd"
Then enable the `display-manager` service to start on boot: Then enable the `display-manager` service to start on boot:
``` ```
root@host:~# rc-update add display-manager default sh# rc-update add display-manager default
``` ```
> Before enabling the `display-manager` service it is recommend to simply first start it ones to see if it works. > Before enabling the `display-manager` service it is recommend to simply first start it ones to see if it works.

11
docs/gentoo-desktop-setup/graphical-session/session-manager.md
View file

@ -1,21 +1,20 @@
Session management is necessary for tracking and giving rights to certain users. For a functional setup install both `elogind` and `turnstile` and enable their corresponding services. Session management is necessary for tracking and giving rights to certain users. For a functional setup install both `elogind` and `turnstile` and enable their corresponding services.
``` shell-session ``` shell-session
root@host:~# emerge -av elogind turnstile sh# emerge -av elogind turnstile
root@host:~# rc-update add elogind boot sh# rc-update add elogind boot
root@host:~# rc-update add turnstiled sh# rc-update add turnstiled
``` ```
Then configure `pam` to allow them to track the user: Then configure `pam` to turnstile to track the user:
``` shell title="/etc/pam.d/system-login" ``` shell title="/etc/pam.d/system-login"
... ...
session optional pam_elogind.so
session optional pam_turnstile.so session optional pam_turnstile.so
``` ```
When a user logs in it should now be able to start a graphical session. This should be done with: When a user logs in it should now be able to start a graphical session. This should be done with:
``` shell-session ``` shell-session
user@host:~$ dbus-run-session -- <window_manager> sh$ dbus-run-session -- <window_manager>
``` ```

88
docs/gentoo-desktop-setup/installation.md
View file

@ -3,25 +3,25 @@ Now is the time to actually install Gentoo.
First import the pool again: First import the pool again:
``` shell-session ``` shell-session
root@host:~# zpool import -N -R /mnt rpool sh# zpool import -N -R /mnt rpool
root@host:~# zfs load-key -L file:///tmp/rpool.key rpool sh# zfs load-key -L file:///tmp/rpool.key rpool
``` ```
Then mount the datasets and the ESP on `/mnt`: Then mount the datasets and the ESP on `/mnt`:
``` shell-session ``` shell-session
root@host:~# mount -t zfs rpool/root/gentoo /mnt sh# mount -t zfs rpool/root/gentoo /mnt
root@host:~# mkdir /mnt/var sh# mkdir /mnt/var
root@host:~# mount -t zfs rpool/root/gentoo/var /mnt/var sh# mount -t zfs rpool/root/gentoo/var /mnt/var
root@host:~# mkdir /mnt/efi sh# mkdir /mnt/efi
root@host:~# mount -t vfat /dev/disk/by-label/esp /mnt/efi sh# mount -t vfat /dev/disk/by-label/esp /mnt/efi
``` ```
Now we're going to fetch a stage3 tarball for on the root of the system. Replace the `<release_date>` with the latest tarball release. Now we're going to fetch a stage3 tarball for on the root of the system. Replace the `<release_date>` with the latest tarball release.
``` shell-session ``` shell-session
root@host:~# cd /mnt sh# cd /mnt
root@host:/mnt# wget https://distfiles.gentoo.org/releases/amd64/autobuilds/current-stage3-amd64-musl-hardened/stage3-amd64-musl-hardened-<release_date>.tar.xz sh# wget https://distfiles.gentoo.org/releases/amd64/autobuilds/current-stage3-amd64-musl-hardened/stage3-amd64-musl-hardened-<release_date>.tar.xz
``` ```
This should have placed a tarball at `/mnt/stage3-amd64-musl-hardened-*-.tar.xz`. There are also other mirrors like `https://ftp.snt.utwente.nl/pub/os/linux/gentoo/releases/amd64/autobuilds/current-stage3-amd64-musl-hardened/` which might provide a faster download depending on your location. Check out <https://www.gentoo.org/downloads/mirrors/> for other mirrors. This should have placed a tarball at `/mnt/stage3-amd64-musl-hardened-*-.tar.xz`. There are also other mirrors like `https://ftp.snt.utwente.nl/pub/os/linux/gentoo/releases/amd64/autobuilds/current-stage3-amd64-musl-hardened/` which might provide a faster download depending on your location. Check out <https://www.gentoo.org/downloads/mirrors/> for other mirrors.
@ -31,16 +31,18 @@ This should have placed a tarball at `/mnt/stage3-amd64-musl-hardened-*-.tar.xz`
Unpack it in the new root: Unpack it in the new root:
``` shell-session ``` shell-session
root@host:/mnt# tar xpvf stage3-*.tar.xz --numeric-owner -C /mnt sh# tar xpvf stage3-*.tar.xz --numeric-owner -C /mnt
``` ```
Then before finally chrooting into the system simply copy over the `resolv.conf` for internet connection inside the chroot. Then before finally chrooting into the system simply copy over the `resolv.conf` for internet connection inside the chroot.
``` shell-session ``` shell-session
root@host:/# cp /etc/resolv.conf /mnt/etc/. sh# cp /etc/resolv.conf /mnt/etc/.
root@host:/# cp /tmp/rpool.key /mnt/tmp sh# cp /tmp/rpool.key /mnt/tmp
root@host:/# for i in dev proc sys run; do mount --rbind --make-rslave /$i /mnt/$i; done sh# for i in dev proc sys run; do
root@host:/# chroot /mnt > mount --rbind --make-rslave /$i /mnt/$i
> done
sh# chroot /mnt
``` ```
## Configuring the system ## Configuring the system
@ -100,11 +102,11 @@ MODULES_SIGN_HASH="sha512"
Now finally sync the repositories and try installing a package like `vim`. Now finally sync the repositories and try installing a package like `vim`.
``` shell-session ``` shell-session
root@chroot:~# emaint sync sh# emaint sync
... ...
Action: sync for repo: gentoo, returned code = 0 Action: sync for repo: gentoo, returned code = 0
root@chroot:~# emerge --ask --verbose app-editors/vim sh# emerge --ask --verbose app-editors/vim
>>> Completed (3 of 4) app-editors/vim-*::gentoo >>> Completed (3 of 4) app-editors/vim-*::gentoo
``` ```
@ -128,7 +130,7 @@ proc /proc proc nodev,nosuid,noexec,hidepid=2
Musl does not come with timezone's installed by default. Install `timezone-data` with: Musl does not come with timezone's installed by default. Install `timezone-data` with:
``` shell-session ``` shell-session
root@chroot:~# emerge -av sys-libs/timezone-data sh# emerge -av sys-libs/timezone-data
``` ```
Select the correct timezone with: Select the correct timezone with:
@ -140,15 +142,15 @@ TZ="/usr/share/zoneinfo/<region>/<city>"
Update the environment of your shell-session: Update the environment of your shell-session:
``` shell-session ``` shell-session
root@chroot:~# env-update && source /etc/profile sh# env-update && source /etc/profile
``` ```
To sync your system's time with a server set up a *Network Time Protocol daemon*. It's recommended to use OpenBSD's `openntpd` which aims to be as secure and minimal as possible: To sync your system's time with a server set up a *Network Time Protocol daemon*. It's recommended to use OpenBSD's `openntpd` which aims to be as secure and minimal as possible:
``` shell-session ``` shell-session
root@chroot:~# emerge -av net-misc/openntpd sh# emerge -av net-misc/openntpd
root@chroot:~# rc-update add ntpd default sh# rc-update add ntpd default
root@chroot:~# rc-service ntpd start sh# rc-service ntpd start
``` ```
### Set up locales ### Set up locales
@ -156,7 +158,7 @@ root@chroot:~# rc-service ntpd start
Musl also does not support locales out of the box. They aren't necessary but some programs rely on them to set the language of their application. To be able to use locales install the `musl-locales` package: Musl also does not support locales out of the box. They aren't necessary but some programs rely on them to set the language of their application. To be able to use locales install the `musl-locales` package:
``` shell-session ``` shell-session
root@chroot:~# emerge -av sys-apps/musl-locales sh# emerge -av sys-apps/musl-locales
``` ```
And to allow the system to know where the locales are located: And to allow the system to know where the locales are located:
@ -168,9 +170,9 @@ MUSL_LOCPATH="/usr/share/i18n/locales/musl"
There are a multiple locales to choose from. In most situations choosing `en_US` is the standard but selecting a different one should not break the system. Choose the desired locale with $n \in \mathbb{N}$: There are a multiple locales to choose from. In most situations choosing `en_US` is the standard but selecting a different one should not break the system. Choose the desired locale with $n \in \mathbb{N}$:
``` shell-session ``` shell-session
root@chroot:~# eselect locale list sh# env-update && source /etc/profile
root@chroot:~# eselect locale set <n> sh# eselect locale list
root@chroot:~# env-update && source /etc/profile sh# eselect locale set <n>
``` ```
### Setting the hostname ### Setting the hostname
@ -178,7 +180,7 @@ root@chroot:~# env-update && source /etc/profile
The system's hostname is the name given to the machine. Other systems on a network will also be able to see this name. To set it replace <hostname> with the desired name: The system's hostname is the name given to the machine. Other systems on a network will also be able to see this name. To set it replace <hostname> with the desired name:
``` shell-session ``` shell-session
root@chroot:~# echo "<hostname>" > /etc/hostname sh# echo "<hostname>" > /etc/hostname
``` ```
### Internet ### Internet
@ -193,7 +195,7 @@ net-dns/dnsmasq dnssec
Also make sure the `networkmanager` USE flag is enabled in your `make.conf`. Then emerge `networkmananger` and `dnsmasq`: Also make sure the `networkmanager` USE flag is enabled in your `make.conf`. Then emerge `networkmananger` and `dnsmasq`:
``` shell-session ``` shell-session
root@chroot:~# emerge -av net-misc/networkmanager net-dns/dnsmasq sh# emerge -av net-misc/networkmanager net-dns/dnsmasq
``` ```
Now configure NetworkManager and Dnsmasq. This is a generally secure recommended setup: Now configure NetworkManager and Dnsmasq. This is a generally secure recommended setup:
@ -225,7 +227,7 @@ dnssec-check-unsigned
Then disable any other network services before enabling the `NetworkManager`service: Then disable any other network services before enabling the `NetworkManager`service:
``` shell-session ``` shell-session
root@chroot:~# rc-update add NetworkManager default sh# rc-update add NetworkManager default
* service NetworkManager added to runlevel default * service NetworkManager added to runlevel default
``` ```
@ -234,9 +236,9 @@ root@chroot:~# rc-update add NetworkManager default
GURU is an extra repository which contains packages not available in the main Gentoo repository. Although the packages it contains might not be as well tested as in the main repo they are still necessary for some setups. Add Guru with: GURU is an extra repository which contains packages not available in the main Gentoo repository. Although the packages it contains might not be as well tested as in the main repo they are still necessary for some setups. Add Guru with:
``` shell-session ``` shell-session
root@chroot:~# emerge -av app-eselect/eselect-repository sh# emerge -av app-eselect/eselect-repository
root@chroot:~# eselect repository enable guru sh# eselect repository enable guru
root@chroot:~# emaint sync --repo guru sh# emaint sync --repo guru
``` ```
To allow unstable packages from GURU set the `~amd64` keyword for it: To allow unstable packages from GURU set the `~amd64` keyword for it:
@ -252,7 +254,7 @@ To allow unstable packages from GURU set the `~amd64` keyword for it:
`sbctl` is a simple tool which allows for the management of Secureboot settings on a system. It can create, deploy and sign keys with ease. First off install `sbctl`: `sbctl` is a simple tool which allows for the management of Secureboot settings on a system. It can create, deploy and sign keys with ease. First off install `sbctl`:
``` shell-session ``` shell-session
root@chroot:~# emerge -av sbctl sh# emerge -av sbctl
``` ```
> Verify that Secureboot mode is on and in setup mode with `sbctl status` > Verify that Secureboot mode is on and in setup mode with `sbctl status`
@ -260,12 +262,12 @@ root@chroot:~# emerge -av sbctl
Then create and enroll keys into the system. Then create and enroll keys into the system.
``` shell-session ``` shell-session
root@chroot:~# sbctl create-keys sh# sbctl create-keys
Created Owner UUID abcde.... Created Owner UUID abcde....
Creating secure boot keys...✔ Creating secure boot keys...✔
Secure boot keys created! Secure boot keys created!
root@chroot:~# sbctl enroll-keys <--microsoft> sh# sbctl enroll-keys <--microsoft>
... ...
Enrolled keys to the EFI variables! Enrolled keys to the EFI variables!
``` ```
@ -277,8 +279,8 @@ Use the `--microsoft` flag if the system is unable to use custom keys or when du
`zlevis` is able to unlock an encrypted ZFS root pool with keys saved in a TPM, currently it's only available in the `portage-ample` repository and also has some dependencies in the `guru` repository. Add the `portage-ample` repository with: `zlevis` is able to unlock an encrypted ZFS root pool with keys saved in a TPM, currently it's only available in the `portage-ample` repository and also has some dependencies in the `guru` repository. Add the `portage-ample` repository with:
``` shell-session ``` shell-session
root@chroot:~# eselect repository add portage-ample git https://git.bijl.us/lnorg/portage-ample sh# eselect repository add portage-ample git https://git.bijl.us/lnorg/portage-ample
root@chroot:~# emaint sync -r portage-ample sh# emaint sync -r portage-ample
``` ```
Then before emerging add the `dracut` flag for zlevis: Then before emerging add the `dracut` flag for zlevis:
@ -290,13 +292,13 @@ app-crypt/zlevis dracut
Then simply install it: Then simply install it:
``` shell-session ``` shell-session
root@chroot:~# emerge -av app-crypt/zlevis sh# emerge -av app-crypt/zlevis
``` ```
Now add `zlevis` to the pool with Now add `zlevis` to the pool with
``` shell-session ``` shell-session
root@chroot:~# zfs set tpm:jwe=$(zlevis-encrypt '{}' < /tmp/rpool.key) rpool sh# zfs set tpm:jwe=$(zlevis-encrypt '{}' < /tmp/rpool.key) rpool
``` ```
### UKI's ### UKI's
@ -348,7 +350,7 @@ rw root=ZFS=rpool/root/gentoo quiet splash
Then finally install the packages mentioned which are required for a running system: Then finally install the packages mentioned which are required for a running system:
``` shell-session ``` shell-session
root@chroot:~# emerge -av sbsigntools systemd-utils linux-firmware gentoo-kernel-bin zfs-kmod sh# emerge -av sbsigntools systemd-utils linux-firmware gentoo-kernel-bin zfs-kmod
``` ```
> Note that `gentoo-kernel-bin` was installed which is the pre-compiled Gentoo kernel. Later on we will compile our own custom kernel. > Note that `gentoo-kernel-bin` was installed which is the pre-compiled Gentoo kernel. Later on we will compile our own custom kernel.
@ -358,7 +360,7 @@ It should have done this without throwing any errors.
Because Gentoo generates UKI's for all the kernels installed on a system it would be nice to be able to choose upon boot which one. For a nice boot interface install `systemd-boot` on the ESP: Because Gentoo generates UKI's for all the kernels installed on a system it would be nice to be able to choose upon boot which one. For a nice boot interface install `systemd-boot` on the ESP:
``` shell-session ``` shell-session
root@chroot:~# bootctl install sh# bootctl install
Copied "/usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed" to "/efi/EFI/systemd/systemd-bootx64.efi". Copied "/usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed" to "/efi/EFI/systemd/systemd-bootx64.efi".
Copied "/usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed" to "/efi/EFI/BOOT/BOOTX64.EFI". Copied "/usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed" to "/efi/EFI/BOOT/BOOTX64.EFI".
Random seed file /efi/loader/random-seed successfully refreshed (32 bytes). Random seed file /efi/loader/random-seed successfully refreshed (32 bytes).
@ -368,14 +370,14 @@ Created EFI boot entry "Linux Boot Manager".
The last thing to do is adding a few ZFS services on boot: The last thing to do is adding a few ZFS services on boot:
``` shell-session ``` shell-session
root@chroot:~# rc-update add zfs-import sysinit sh# rc-update add zfs-import sysinit
root@chroot:~# rc-update add zfs-mount sysinit sh# rc-update add zfs-mount sysinit
``` ```
Now exit the chroot and unmount the filesystem with: Now exit the chroot and unmount the filesystem with:
``` shell-session ``` shell-session
root@host:~# umount -lf /mnt sh# umount -lf /mnt
``` ```
The system should be functional after a reboot! The system should be functional after a reboot!

2
docs/gentoo-desktop-setup/post-install/ccache.md
View file

@ -1,7 +1,7 @@
`ccache` is a program which can save compiling cache, speeding up recompile's of big software. First install it: `ccache` is a program which can save compiling cache, speeding up recompile's of big software. First install it:
``` shell-session ``` shell-session
root@host:~# emerge -av dev-util/ccache sh# emerge -av dev-util/ccache
``` ```
And create a configuration file for `ccache`. And create a configuration file for `ccache`.

6
docs/gentoo-desktop-setup/post-install/users.md
View file

@ -1,8 +1,8 @@
Adding a user to the system is essential for actually using it as a desktop. It is pretty straight forward: Adding a user to the system is essential for actually using it as a desktop. It is pretty straight forward:
``` shell-session ``` shell-session
root@host:~# useradd -m -G <wheel,>plugdev,pipewire -s /bin/bash <username> sh# useradd -m -G <wheel,>plugdev,pipewire -s /bin/bash <username>
root@host:~# passwd <username> sh# passwd <username>
... ...
passwd: password updated successfully passwd: password updated successfully
``` ```
@ -22,7 +22,7 @@ app-admin/doas persist
> This USE flag is necessary when typing the user's password every few seconds gets to annoying. > This USE flag is necessary when typing the user's password every few seconds gets to annoying.
``` shell-session ``` shell-session
root@host:~# emerge -av doas sh# emerge -av doas
``` ```
``` title="/etc/doas.conf" ``` title="/etc/doas.conf"

33
docs/gentoo-desktop-setup/provisioning.md
View file

@ -14,40 +14,40 @@ sh# setup-apkrepos -c1
A few packages will have to be installed first, A few packages will have to be installed first,
``` shell-session ``` shell-session
root@host:~# apk add zfs lsblk sgdisk wipefs dosfstools sh# apk add zfs lsblk sgdisk wipefs dosfstools
``` ```
and load the ZFS kernel module and load the ZFS kernel module
``` shell-session ``` shell-session
root@host:~# modprobe zfs sh# modprobe zfs
``` ```
Wipe the existing disk partitions Wipe the existing disk partitions
``` shell-session ``` shell-session
root@host:~# zpool labelclear -f /dev/<disk> sh# zpool labelclear -f /dev/<disk>
root@host:~# wipefs -a /dev/<disk> sh# wipefs -a /dev/<disk>
root@host:~# sgdisk --zap-all /dev/<disk> sh# sgdisk --zap-all /dev/<disk>
``` ```
Create on the disk an `EFI system` partition (ESP) and a `Linux filesystem` partition Create on the disk an `EFI system` partition (ESP) and a `Linux filesystem` partition
``` shell-session ``` shell-session
root@host:~# sgdisk -n 1:1m:+512m -t 1:ef00 /dev/<disk> sh# sgdisk -n 1:1m:+512m -t 1:ef00 /dev/<disk>
root@host:~# sgdisk -n 2:0:-10m -t 2:8300 /dev/<disk> sh# sgdisk -n 2:0:-10m -t 2:8300 /dev/<disk>
``` ```
Reload the device nodes Reload the device nodes
``` shell-session ``` shell-session
root@host:~# mdev -s sh# mdev -s
``` ```
Then, format the ESP with a FAT32 filesystem Then, format the ESP with a FAT32 filesystem
``` shell-session ``` shell-session
root@host:~# mkfs.fat -F 32 -n esp /dev/<disk>1 sh# mkfs.fat -F 32 -n esp /dev/<disk>1
``` ```
## ZFS pool creation ## ZFS pool creation
@ -55,7 +55,7 @@ root@host:~# mkfs.fat -F 32 -n esp /dev/<disk>1
The ZFS system pool is going to be encrypted. First generate an encryption key and save it temporarily to the file `/tmp/rpool.key` with: The ZFS system pool is going to be encrypted. First generate an encryption key and save it temporarily to the file `/tmp/rpool.key` with:
``` shell-session ``` shell-session
root@host:~# cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 20 | head -n 1 > /tmp/rpool.key && cat /tmp/rpool.key sh# cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 20 | head -n 1 > /tmp/rpool.key && cat /tmp/rpool.key
``` ```
> Later on in the guide `zlevis` will be used for automatic decryption, so this key only has to be entered a few times. However, if any changes are made to the bios or secureboot then this key will be needed again, so make sure to save it. > Later on in the guide `zlevis` will be used for automatic decryption, so this key only has to be entered a few times. However, if any changes are made to the bios or secureboot then this key will be needed again, so make sure to save it.
@ -63,7 +63,7 @@ root@host:~# cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 20 | head -n 1 > /t
Create the system pool: Create the system pool:
``` shell-session ``` shell-session
root@host:~# zpool create -f \ sh# zpool create -f \
-o ashift=12 \ -o ashift=12 \
-O compression=lz4 \ -O compression=lz4 \
-O acltype=posix \ -O acltype=posix \
@ -79,11 +79,14 @@ root@host:~# zpool create -f \
Then create the system datasets: Then create the system datasets:
``` shell-session ``` shell-session
root@host:~# zfs create -o mountpoint=none rpool/root sh# zfs create -o mountpoint=none rpool/root
root@host:~# zfs create -o mountpoint=legacy -o quota=48g rpool/root/gentoo sh# zfs create -o mountpoint=legacy -o quota=48g rpool/root/gentoo
root@host:~# zfs create -o mountpoint=legacy -o quota=32g rpool/root/gentoo/var sh# zfs create -o mountpoint=legacy -o quota=32g rpool/root/gentoo/var
root@host:~# zfs create -o mountpoint=/home -o atime=off -o setuid=off -o devices=off -o quota=<home-quota> rpool/home sh# zfs create -o mountpoint=/home -o atime=off -o setuid=off -o devices=off -o quota=<home-quota> rpool/home
``` ```
> Setting the `<home-quota>` depends on the total size of the pool, generally try to reserve some empty space in the pool. > Setting the `<home-quota>` depends on the total size of the pool, generally try to reserve some empty space in the pool.
``` shell-session
sh# zpool export rpool
```