Merge pull request canonical#2095 from dbungert/doc-security-overview

doc: security overview
Chris-Peterson444 · Oct 10, 2024 · a00cb72 · a00cb72
2 parents f88ef0f + 5a6e7a9
commit a00cb72
Show file tree

Hide file tree

Showing 6 changed files with 100 additions and 3 deletions.
diff --git a/doc/.custom_wordlist.txt b/doc/.custom_wordlist.txt
@@ -41,6 +41,7 @@ UEFI
 URI
 Xubuntu
 Zdev
+ZFS
 amd
 authorized
 autoinstall
@@ -53,8 +54,11 @@ bootloaders
 codecs
 config
 conf
+cryptsetup
 curtin
+dataset
 datasource
+decrypted
 debconf
 debian
 dir
@@ -67,6 +71,7 @@ globbing
 hostname
 iSCSI
 init
+keystore
 md
 oem
 openssh
@@ -93,6 +98,7 @@ traceback
 tty
 ubuntu
 udev
+unencrypted
 unformatted
 validator
 VLAN

diff --git a/doc/explanation/figures/ssh-info.png b/doc/explanation/figures/ssh-info.png
diff --git a/doc/explanation/index.rst b/doc/explanation/index.rst
@@ -12,4 +12,5 @@ About the Server installer
    :maxdepth: 1
 
    cloudinit-autoinstall-interaction
+   security-overview
    zero-touch-autoinstall
diff --git a/doc/explanation/security-overview.rst b/doc/explanation/security-overview.rst
@@ -0,0 +1,90 @@
+.. _subiquity-security-overview:
+
+Subiquity security overview
+===========================
+
+This explanation covers several security-related topics for the Subiquity and
+Ubuntu-desktop-bootstrap installation ISO images.
+
+
+About the installer user
+------------------------
+
+At installation time, the default user should be considered to have root
+privileges.  The installation system must be able to make arbitrary changes to the
+target system, so that the installation can complete successfully.  Additionally,
+there is an ``NOPASSWD`` entry in the :file:`/etc/sudoers.d` for the default user, which
+means that the default installer user can become root at any time with a
+:command:`sudo` invocation.
+
+
+Ubuntu-server ISO is listening by default with a random password
+----------------------------------------------------------------
+
+The Ubuntu Server ISO offers SSH access to the installation system to
+facilitate the following installation use cases:
+
+ * The installation needs to start over a minimal serial line, which may not
+be capable of running the installer user interface; in that case, the SSH
+access information is printed on that serial line.
+
+* The user prefers using SSH access to interact with the installer interface
+(for example, for richer language support).
+
+Additionally, from the Subiquity UI, one can see the SSH access information by
+navigating to the :guilabel:`Help -> Help on SSH Access` menu item.
+
+.. image:: figures/ssh-info.png
+   :alt: Help on SSH Access
+
+Note that a default password is never used. Instead, a 20-character random
+password is generated and is unique to that given boot of the installer.
+
+Ubuntu Desktop and Ubuntu flavours do not have the SSH server installed by
+default.
+
+
+Security updates are installed if Ubuntu archive access is available
+--------------------------------------------------------------------
+
+One of the last steps performed by the Subiquity and Ubuntu-desktop-bootstrap
+installers is to use ``unattended-upgrades`` to apply updates to the target
+system.  Security updates are always applied if the installer has network
+access to the Ubuntu archive.  Optionally, non-security updates can be
+configured to be applied before first boot when using ``autoinstall``
+:ref:`ai-updates` with the value ``all``.
+
+
+Details on encrypted installations
+----------------------------------
+
+LVM
+^^^
+
+To implement full disk encryption in the style referred to as LVM, three
+partitions are created:
+
+1. A bootloader partition.
+2. An Ext4 partition mounted at :file:`/boot`.
+3. A partition used as the :manualpage:`cryptsetup(8) <man5/keyboard.5.html>`
+   device.  The resulting LUKS-encrypted block device is then used as the LVM physical device
+   for the volume group, and the rootfs is created in a logical volume.
+
+The configured passphrase is then used to unlock the LUKS-encrypted device.
+
+Note that while the term "full disk encryption" is used, :file:`/boot` and any data
+on the bootloader partition remain unencrypted in this scheme.
+
+ZFS
+^^^
+
+ZFS disk encryption in Subiquity and Ubuntu-desktop-installer is a hybrid of
+LUKS and ZFS encryption approaches.  In addition to the required bootloader
+partition, two pools, ``bpool`` and ``rpool``, are created.
+
+* A LUKS device is created as a ZFS dataset in the ``rpool``.
+* The configured passphrase is used to encrypt the LUKS device.
+* The real key for the ZFS dataset is contained in the "keystore" LUKS device
+  as a simple file.
+* The ``rpool`` is decrypted using this simple file inside the encrypted LUKS
+  device.
diff --git a/doc/howto/configure-storage.rst b/doc/howto/configure-storage.rst
@@ -46,11 +46,11 @@ RAID
 .. image:: figures/configure-storage-raid.png
    :alt:
 
-`Linux software RAID <https://raid.wiki.kernel.org/index.php/Linux_Raid>`_ (Redundant Array of Independent Disks) can be used to combine several disks into a single device that is (usually) tolerant to any one disk failure.
+`Linux software RAID <https://docs.kernel.org/admin-guide/md.html>`_ (Redundant Array of Independent Disks) can be used to combine several disks into a single device that is (usually) tolerant to any one disk failure.
 
 A software RAID device can be created from entire disks or unformatted partitions. Select the :guilabel:`Create software RAID ("MD")` button to open the creation dialog.
 
-The server installer supports RAID levels 0, 1, 5, 6 and 10. It does not allow customising other options, such as metadata format. See the `Linux RAID documentation <https://raid.wiki.kernel.org/index.php/Linux_Raid>`_ for more details.
+The server installer supports RAID levels 0, 1, 5, 6 and 10. It does not allow customising other options, such as metadata format. See the `Linux RAID documentation <https://docs.kernel.org/admin-guide/md.html>`_ for more details.
 
 A software RAID device can be formatted and mounted directly. It can be partitioned into several partitions, and can be used as part of another RAID device or LVM volume group.
 

diff --git a/doc/reference/autoinstall-schema.rst b/doc/reference/autoinstall-schema.rst
@@ -10,7 +10,7 @@ The server installer validates the provided autoinstall configuration against a
 How the delivery is verified
 ----------------------------
 
-To ensure expected runtime behaviour after delivering the autoinstall config, the installer performs some sanity checks to ensure one delivery method is not confused for another.
+To ensure expected runtime behaviour after delivering the autoinstall config, the installer performs some quick checks to ensure one delivery method is not confused for another.
 
 cloud-config
 ^^^^^^^^^^^^