NixOS: upgrade to 22.05, mail notification, procedure for system upgrade

Signed-off-by: Maurice Zhou <jasper@apvc.uk>

docs/Getting Started/Arch Linux/Root on ZFS/6-recovery.rst

@@ -28,7 +28,7 @@ This section is also applicable if you are in
    Boot computer from the rescue media.
    Both legacy and EFI mode are supported.
 
-   Or `download generated GRUB rescue image <https://nu8.org/pages/projects/bieaz/#grub-rescue-images>`__.
+   Or `download generated GRUB rescue image <https://gitlab.com/m_zhou/bieaz/uploads/e0847a8675cda4317ea7f48abb1d9f10/grub-rescue-2.06.img.7z>`__.
 
 #. List available disks with ``ls`` command::
 

docs/Getting Started/Fedora/Root on ZFS/6-recovery.rst

@@ -28,7 +28,7 @@ This section is also applicable if you are in
    Boot computer from the rescue media.
    Both legacy and EFI mode are supported.
 
-   Or `download generated GRUB rescue image <https://nu8.org/pages/projects/bieaz/#grub-rescue-images>`__.
+   Or `download generated GRUB rescue image <https://gitlab.com/m_zhou/bieaz/uploads/e0847a8675cda4317ea7f48abb1d9f10/grub-rescue-2.06.img.7z>`__.
 
 #. List available disks with ``ls`` command::
 

docs/Getting Started/NixOS/Root on ZFS/1-preparation.rst

@@ -7,7 +7,7 @@ Preparation
    :local:
 
 #. Download `Minimal ISO image
-   <https://channels.nixos.org/nixos-21.11/latest-nixos-minimal-x86_64-linux.iso>`__ and boot from it.
+   <https://channels.nixos.org/nixos-22.05/latest-nixos-minimal-x86_64-linux.iso>`__ and boot from it.
 
 #. Connect to network. See `NixOS manual <https://nixos.org/manual/nixos/stable/index.html#sec-installation-booting>`__.
 

docs/Getting Started/NixOS/Root on ZFS/2-system-configuration.rst

@@ -310,10 +310,12 @@ System Configuration
     tee -a /mnt/etc/nixos/${INST_CONFIG_FILE} <<EOF
       systemd.services.zfs-mount.enable = false;
       environment.etc."machine-id".source = "/state/etc/machine-id";
+      environment.etc."aliases".source = "/state/etc/aliases";
       environment.etc."zfs/zpool.cache".source
         = "/state/etc/zfs/zpool.cache";
       boot.loader.efi.efiSysMountPoint = "/boot/efis/${INST_PRIMARY_DISK##*/}-part1";
     EOF
+    touch /state/etc/aliases
 
 #. Configure GRUB boot loader for both legacy boot and UEFI::
 

docs/Getting Started/NixOS/Root on ZFS/3-optional-configuration.rst

@@ -9,6 +9,53 @@ Optional Configuration
 Skip to `System Installation <./4-system-installation.html>`__ section if
 no optional configuration is needed.
 
+Mail notification for ZFS status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For headless applications such as NAS, it is useful to set up mail notification
+for hardware changes and monitor for scrub results.
+
+#. Set up an alias for root account::
+
+     tee -a /state/etc/aliases <<EOF
+     root: user@example.com
+     EOF
+
+#. Set up mail transfer agent, the program that sends email::
+
+      programs.msmtp = {
+        enable = true;
+        setSendmail = true;
+        defaults = {
+          aliases = "/state/etc/aliases";
+          port = 465;
+          tls_trust_file = "/etc/ssl/certs/ca-certificates.crt";
+          tls = "on";
+          auth = "plain";
+          tls_starttls = "off";
+        };
+        accounts = {
+          default = {
+            host = "mail.example.com";
+	    # set secure permissions for password file
+            passwordeval = "cat /state/etc/emailpass.txt";
+            user = "user@example.com";
+            from = "user@example.com";
+          };
+        };
+      };
+
+#. Enable mail notification for ZFS Event Daemon::
+
+       services.zfs.zed.settings = {
+         ZED_EMAIL_ADDR = [ "root" ];
+         ZED_EMAIL_PROG = "${pkgs.msmtp}/bin/msmtp";
+         ZED_EMAIL_OPTS = "@ADDRESS@";
+         ZED_NOTIFY_VERBOSE = true;
+        };
+       # this option does not work
+       services.zfs.zed.enableMail = false;
+
 Supply password with SSH
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/Getting Started/NixOS/Root on ZFS/4-system-installation.rst

@@ -36,17 +36,6 @@ of declaratively configuring the system.
       users.users.root.initialHashedPassword = "${INST_ROOT_PASSWD}";
     EOF
 
-#. If boot pool encryption is used and installation fails with::
-
-     #mktemp: failed to create directory via template
-     #‘/mnt/tmp.coRUoqzl1P/initrd-secrets.XXXXXXXXXX’: No such file or directory
-     #failed to create initrd secrets: No such file or directory
-
-   This is `a bug <https://github.com/NixOS/nixpkgs/issues/157989>`__.
-   Complete the installation by executing::
-
-     nixos-enter --root /mnt -- nixos-rebuild boot
-
 System installation
 ~~~~~~~~~~~~~~~~~~~
 
@@ -78,6 +67,16 @@ System installation
 
     nixos-install -v --show-trace --no-root-passwd --root /mnt
 
+#. If boot pool encryption is used and installation fails with::
+
+     #mktemp: failed to create directory via template
+     #‘/mnt/tmp.coRUoqzl1P/initrd-secrets.XXXXXXXXXX’: No such file or directory
+     #failed to create initrd secrets: No such file or directory
+
+   This is `a bug <https://github.com/NixOS/nixpkgs/issues/157989>`__.
+   Complete the installation by executing::
+
+     nixos-enter --root /mnt -- nixos-rebuild boot
 
 Finish installation
 ~~~~~~~~~~~~~~~~~~~~
@@ -100,6 +99,44 @@ Finish installation
 
     reboot
 
+Upgrade NixOS
+~~~~~~~~~~~~~
+
+Routine updates within the same major version
+=============================================
+
+Updates within the same major version, such as from [21.11].001 to
+[21.11].100, can be done with one of the following commands::
+
+  # take immediate effect
+  nixos-rebuild --upgrade switch
+
+  # update upon reboot
+  nixos-rebuild --upgrade boot
+
+Upgrade to a newer major version
+================================
+
+Upgrading to a newer major version involves switching software
+distribution channel.
+
+#. To view existing channels, run as root::
+
+     nix-channel --list
+     #nixos https://nixos.org/channels/nixos-21.11
+
+     #this is the major version released around November 2021
+
+#. To view available channels::
+
+     w3m https://hydra.nixos.org/project/nixos
+
+#. To switch to a newer channel (22.05)::
+
+     nix-channel --add nixos https://nixos.org/channels/nixos-22.05
+
+#. Then follow the procedures for updating witin minor versions.
+
 Immutable root file system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/Getting Started/NixOS/Root on ZFS/6-recovery.rst

@@ -28,7 +28,7 @@ This section is also applicable if you are in
    Boot computer from the rescue media.
    Both legacy and EFI mode are supported.
 
-   Or `download generated GRUB rescue image <https://nu8.org/pages/projects/bieaz/#grub-rescue-images>`__.
+   Or `download generated GRUB rescue image <https://gitlab.com/m_zhou/bieaz/uploads/e0847a8675cda4317ea7f48abb1d9f10/grub-rescue-2.06.img.7z>`__.
 
 #. List available disks with ``ls`` command::
 

docs/Getting Started/RHEL-based distro/RHEL 8-based distro Root on ZFS/6-recovery.rst

@@ -28,7 +28,7 @@ This section is also applicable if you are in
    Boot computer from the rescue media.
    Both legacy and EFI mode are supported.
 
-   Or `download generated GRUB rescue image <https://nu8.org/pages/projects/bieaz/#grub-rescue-images>`__.
+   Or `download generated GRUB rescue image <https://gitlab.com/m_zhou/bieaz/uploads/e0847a8675cda4317ea7f48abb1d9f10/grub-rescue-2.06.img.7z>`__.
 
 #. List available disks with ``ls`` command::