Added an update-protocol section to alpine-server-setup.

docs/alpine-server-setup/installation.md

@@ -2,14 +2,14 @@
 
 To install the Alpine Linux distribution on the system, the datasets of the system pool and the EFI partitions have to be mounted to the main system. 
 
-First import and decrypt the system pool
+First import and decrypt the system pool.
 
 ```
 # zpool import -N -R /mnt tank
 # zfs load-key -L file:///tmp/tank.key tank
 ```
 
-Mount the datasets in the system pool and decrypt the home dataset
+Mount the datasets in the system pool and decrypt the home dataset.
 
 ```
 # zfs mount tank/root/alpine
@@ -17,26 +17,27 @@ Mount the datasets in the system pool and decrypt the home dataset
 # zfs mount tank/var
 ```
 
-Mount the ESP
+Mount the ESP.
 
 ```
 # mkdir /mnt/esp
 # mount /dev/md/esp /mnt/esp -t vfat
 ```
 
-Then install Alpine Linux
+Then install Alpine Linux.
 
 ```
+# export BOOTLOADER=none
 # setup-disk -m sys /mnt
 ```
 
 > This will also add `grub` as bootloader which will be replaced but for now it will reside on the ESP.
 
-To have a functional chroot into the system, bind the system process directories
+To have a functional chroot into the system, bind the system process directories.
 
 ```
-# for i in dev proc sys run; do
+# for dir in dev proc sys run; do
-> mount --rbind --make-rslave /$i /mnt/$i
+> mount --rbind --make-rslave /$dir /mnt/$dir
 > done
 # chroot /mnt
 ```
@@ -66,7 +67,7 @@ clock_hctosys="NO"
 clock_systohc="NO"
 ```
 
-Configure the ESP raid array to mount
+Configure the ESP raid array to mount.
 
 ```
 # modprobe raid1
@@ -76,7 +77,7 @@ Configure the ESP raid array to mount
 # rc-update add mdadm-raid boot
 ```
 
-Configure ZFS to mount
+Configure ZFS to mount.
 
 ```
 rc-update add zfs-import sysinit
@@ -139,7 +140,7 @@ Use `sbctl` to create secureboot keys and sign them.
 
 > Whilst enrolling the keys it might be necessary to add the `--microsoft` flag if you are unable to use custom keys.
 
-Set the cache-file of the ZFS pool
+Set the cache-file of the ZFS pool.
 
 ```
 # zpool set cachefile=/etc/zfs/zpool.cache tank
@@ -162,13 +163,15 @@ As discussed earlier `grub` will be replaced, install `gummiboot` as a bootloade
 # cp /usr/lib/gummiboot/gummibootx64.efi /esp/efi/boot/bootx64.efi
 ```
 
-Sign the bootloader with `sbctl`
+Sign the bootloader with `sbctl`.
 
 ```
 # sbctl sign -s /esp/efi/boot/bootx64.efi
 ```
 
-and also remove some remnants of `grub`.
+> One may verify the signed files by running `sbctl verify`, in this case `ESP_PATH=/esp` should be defined to work properly.
+
+Remove some remnants of `grub`.
 
 ```
 # rm -rf /boot/grub

docs/alpine-server-setup/post-install/containers.md

@@ -20,7 +20,7 @@ Set up the network namespace configuration for the user
 
 ```
 # modprobe tun
-# echo tun >> /etc/modules
+# echo tun >> /etc/modules-load.d/tun.conf
 # for i in subuid subgid; do
 > echo <username>:100000:65536 >> /etc/$i
 > done

docs/alpine-server-setup/post-install/security.md

@@ -50,12 +50,11 @@ After reconfiguring `kernel-hooks` try to reboot and it should boot. Although th
 
 ### Sysctl
 
-More kernel settings can be configured through sysctl. Edit `/etc/sysctl.d/main.conf`:
+More kernel settings can be configured through sysctl. 
+
+Create `/etc/sysctl.d/kernel.conf`:
 
 ```
-# Main security configuration.
-
-## Kernel
 kernel.kptr_restrict=2
 kernel.dmesg_restrict=1
 kernel.printk=3 3 3 3
@@ -65,10 +64,17 @@ dev.tty.ldisc_autoload=0
 kernel.kexec_load_disabled=1
 kernel.sysrq=0
 kernel.perf_event_paranoid=3
+```
 
-## Network
+Create `/etc/sysctl.d/network.conf`:
+
+```
+net.ipv4.icmp_echo_ignore_all=1
 net.ipv4.tcp_syncookies=1
 net.ipv4.tcp_rfc1337=1
+net.ipv4.tcp_sack=0
+net.ipv4.tcp_dsack=0
+net.ipv4.tcp_fack=0
 net.ipv4.conf.all.rp_filter=1
 net.ipv4.conf.default.rp_filter=1
 net.ipv4.conf.all.accept_redirects=0
@@ -77,14 +83,13 @@ net.ipv4.conf.all.secure_redirects=0
 net.ipv4.conf.default.secure_redirects=0
 net.ipv4.conf.all.send_redirects=0
 net.ipv4.conf.default.send_redirects=0
-net.ipv4.icmp_echo_ignore_all=1
 net.ipv4.conf.all.accept_source_route=0
 net.ipv4.conf.default.accept_source_route=0
-net.ipv4.tcp_sack=0
+```
-net.ipv4.tcp_dsack=0
-net.ipv4.tcp_fack=0
 
-## User space
+Create `/etc/sysctl.d/user.conf`:
+
+```
 kernel.yama.ptrace_scope=2
 vm.mmap_rnd_bits=32
 vm.mmap_rnd_compat_bits=16
@@ -92,8 +97,11 @@ fs.protected_symlinks=1
 fs.protected_hardlinks=1
 fs.protected_fifos=2
 fs.protected_regular=2
+```
 
-## For hardened_malloc
+Create `/etc/sysctl.d/malloc.conf`:
+
+```
 vm.max_map_count=1048576
 ```
 

docs/alpine-server-setup/post-install/update-protocol.md

@@ -0,0 +1,52 @@
+# Update protocol
+
+ZFS opens up new methods to safely update the system. These methods are described in this section in combination with general practises to maintain ZFS filesystems.
+
+## Pre-update
+
+To be able to rollback the system after a system update one may create a snapshot of the root filesystem. 
+
+```
+# zfs snapshot tank/root/alpine@previous
+```
+
+> Tip: `zfs destroy` can be used to remove snapshots and `zfs list -t snapshot` can be used to list them.
+
+## Update
+
+Perform a system update.
+
+```
+# apk upgrade
+# reboot
+```
+
+If the system does not behave accordingly after reboot, one may rollback to the previous snapshot and further investigate from there.
+
+```
+# zfs rollback -r tank/root/alpine@previous
+```
+
+## Post-update
+
+To maintain the performance of the SSDs in the system, perform a trim on the zfs-pool.
+
+```
+# zpool trim --secure --wait tank
+```
+
+> Some devices may not support the option `--secure`, remove it then, if necessary.
+
+Thereafter, perform a scrub on the zfs-pool which checks and repairs the data in the pool.
+
+```
+# zpool scrub tank
+```
+
+This may take a while, the progress can be checked with:
+
+```
+# zpool status tank
+```
+
+> A ZFS scrub only repairs if mirror or a zraid mode is used in the pool.

docs/alpine-server-setup/post-install/users.md

@@ -10,7 +10,7 @@ Before creating the user, install `doas`. To be able to "do as" root when it is
 # apk add doas
 ```
 
-Configure `doas` through `/etc/doas.d/main.conf`:
+Configure `doas` through `/etc/doas.d/wheel.conf`:
 
 ```
 permit persist :wheel as root

mkdocs.yml

@@ -79,6 +79,7 @@ nav:
       - 'Logging': alpine-server-setup/post-install/logging.md
       - 'Swap': alpine-server-setup/post-install/swap.md
       - 'Users': alpine-server-setup/post-install/users.md
+      - 'Update protocol': alpine-server-setup/post-install/update-protocol.md
       - 'Containers': alpine-server-setup/post-install/containers.md
 
   - 'Void-desktop setup':