Merge pull request #2 from rkratky/pr-2095

Lang. + formatting fixes in Security overview

doc/explanation/security-overview.rst

@@ -1,38 +1,43 @@
-.. _security-overview
+.. _subiquity-security-overview:
 
-Security overview
-=================
+Subiquity security overview
+===========================
 
-This explanation covers several security related topics for the Subiquity and
-Ubuntu-desktop-bootstrap installation ISOs.
+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 install system must be able to make arbitrary changes to the
-target system so that the install can complete successfully.  Additionally,
-there is an ``/etc/sudoers.d`` ``NOPASSWD`` entry for the default user, which
+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
-``sudo`` invocation.
+:command:`sudo` invocation.
 
 
-Ubuntu-server ISO has listening by default with a random password
------------------------------------------------------------------
+Ubuntu-server ISO is listening by default with a random password
+----------------------------------------------------------------
 
-The Ubuntu Server ISO offers SSH access to the installation system, to
-facilitate installs which need to start over a minimal serial line that may not
-be rich enough to run the installer user interface.  In that case, the SSH
+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.
 
-Additionally, from the Subiquity UI, one can see the SSH access info by
-navigating to the Help Menu -> Help on SSH Access.
+* 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, that instead a 20 character random
+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
@@ -44,38 +49,38 @@ 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
+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
+Details on encrypted installations
 ----------------------------------
 
 LVM
 ^^^
 
-To implement full disk encryption in the style referred to as "LVM", 3
+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 ``/boot``
+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
-   Volume Group physical device, and the rootfs is created in a logical volume.
+   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.
+The configured passphrase is then used to unlock the LUKS-encrypted device.
 
-Note that while the term "full disk encryption" is used, ``/boot`` and any data
+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.
+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.

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.
 

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
 ^^^^^^^^^^^^