From 1c4f2e4e6f33fba453f4c8725fcf1fb81120ed8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Sun, 22 Oct 2023 17:50:03 +0200 Subject: [PATCH] Fix spelling mistakes to pass spellcheck. Reflect review feedback (to be squashed once PR acked). --- doc/.custom_wordlist.txt | 80 +++++++++++++ doc/.wordlist.txt | 35 +++--- doc/explanation/configure-storage.rst | 12 +- doc/explanation/operate-server-installer.rst | 24 ++-- doc/howto/autoinstall-quickstart-s390x.rst | 10 +- doc/howto/autoinstall-quickstart.rst | 36 +++--- doc/howto/report-bugs.rst | 4 +- doc/index.rst | 20 +--- doc/intro-to-autoinstall.rst | 45 ++++---- doc/reference/autoinstall-reference.rst | 113 +++++++++---------- doc/reference/autoinstall-schema.rst | 12 +- doc/tutorial/basic-server-installation.rst | 46 ++++---- doc/tutorial/screen-by-screen.rst | 16 +-- 13 files changed, 256 insertions(+), 197 deletions(-) create mode 100644 doc/.custom_wordlist.txt diff --git a/doc/.custom_wordlist.txt b/doc/.custom_wordlist.txt new file mode 100644 index 00000000..edeefb12 --- /dev/null +++ b/doc/.custom_wordlist.txt @@ -0,0 +1,80 @@ +Autoinstall +Autoinstalls +Btrfs +DHCP +EFI +Esc +ESP +ESPs +GPT +GUID +GiB +GiB +Libera +LPAR +LTS +LUKS +LV +LVM +LinuxONE +MiB +NIC +Netplan +NoCloud +OEM +OpenSSH +Petitboot +PgDown +PgUp +POST +PPA +PReP +SSD +Seagate +Subiquity +UEFI +URI +Zdev +amd +authorized-keys +autoinstall +autoinstaller +autoinstalls +bootable +bootloader +bootloaders +codecs +config +curtin +debconf +debian-installer +el +flavor +geoip +globbing +hostname +iSCSI +init +md +oem +passwd +ppc +pre +preseed +preseeded +preseeding +preseeds +pw +realname +rootfs +rsyslog +subvolume +subvolumes +superset +traceback +tty +ubuntu +udev +unformatted +VLAN +webhook diff --git a/doc/.wordlist.txt b/doc/.wordlist.txt index c0feb8f2..4edd132f 100644 --- a/doc/.wordlist.txt +++ b/doc/.wordlist.txt @@ -1,37 +1,38 @@ -addons + API APIs -balancer -Charmhub CLI -dropdown +Charmhub Diátaxis EBS EKS -favicon Grafana IAM -installable JSON +Jira Juju -Kubernetes Kubeflow +Kubernetes Makefile MyST -namespace -namespaces NodePort -observability OLM Permalink -ReadMe -reST -reStructuredText RTD -subdirectories -subtree -subfolders +ReadMe UI -Jira VM YAML +addons +balancer +dropdown +favicon +installable +namespace +namespaces +observability +reST +reStructuredText +subdirectories +subfolders +subtree diff --git a/doc/explanation/configure-storage.rst b/doc/explanation/configure-storage.rst index 51d367a0..98e9a06f 100644 --- a/doc/explanation/configure-storage.rst +++ b/doc/explanation/configure-storage.rst @@ -81,9 +81,9 @@ Logical Volume Manager (LVM) .. image:: figures/configure-storage-lvm.png :alt: -The LVM is a system of managing logical volumes, or filesystems, that is much +The LVM is a system of managing logical volumes, or file systems, that is much more advanced and flexible than the traditional method of partitioning a disk -into one or more segments and formatting that partition with a filesystem. It +into one or more segments and formatting that partition with a file system. It can be used to combine several disks into one larger pool of storage but it offers advantages even in a single disk system, such as snapshots and easy resizing of logical volumes. @@ -113,7 +113,7 @@ but this can be changed later. On amd64 and arm64 systems, multiple disks can be selected as boot devices, which means a system can be configured so that it will continue to boot after -a failure of any one drive (assuming the root filesystem is placed on a RAID). +a failure of any one drive (assuming the root file system is placed on a RAID). The bootloader will be installed to each of these drives, and the operating system configured to install new versions of GRUB to each drive as it is updated. @@ -151,8 +151,8 @@ operating system. One of the ESPs must be mounted at ``/boot/efi``. Supported arm64 servers boot using UEFI, and are configured the same way as an UEFI-booting amd64 system. -ppc64el systems also load their bootloader (Petitboot, a small linux kernel) -from a "PReP" partition with a special flag, so in most ways they are similar +ppc64el systems also load their bootloader (Petitboot, a small Linux kernel) +from a PReP (PowerPC Reference Platform) partition with a special flag, so in most ways they are similar to a UEFI system. The installer only supports one PReP partition at this time. Limitations and workarounds @@ -173,4 +173,4 @@ with desired parameters, and then select these partitions or devices as mount points in the installer. Any changes you make while the installer is running but before altering the storage configuration will reflected in the installer. -The installer cannot yet configure iSCSI mounts or btrfs subvolumes. +The installer cannot yet configure iSCSI mounts or BTRFS subvolumes. diff --git a/doc/explanation/operate-server-installer.rst b/doc/explanation/operate-server-installer.rst index b7c6b57c..2f9e9638 100644 --- a/doc/explanation/operate-server-installer.rst +++ b/doc/explanation/operate-server-installer.rst @@ -10,15 +10,15 @@ step-by-step guide through the screens of the installer, you can use our Get the installer ================= -Installer images are made (approximately) daily and are available from -https://cdimage.ubuntu.com/ubuntu-server/daily-live/current/. These are not +Installer images are created (approximately) daily and are available from the +`Ubuntu release `_ page. These are not tested as extensively as the images from release day, but they contain the -latest packages and installer, so fewer updates will be required during or +latest packages and installer, so fewer updates are required during or after installation. -You can download the server installer for amd64 from -https://ubuntu.com/download/server and other architectures from -http://cdimage.ubuntu.com/releases/20.04/release/. +You can download the server installer for amd64 from the +`Ubuntu Server `_ page and other architectures from the +`release directory `_. Installer UI navigation ======================= @@ -30,8 +30,8 @@ and :kbd:`space` or :kbd:`Enter` keys and a little typing. :kbd:`Home` / :kbd:`End` / :kbd:`Page Up` / :kbd:`Page Down` can be used to navigate through long lists more quickly in the usual way. -Running the installer over serial -================================= +Running the installer over a serial port +======================================== By default, the installer runs on the first virtual terminal, ``tty1``. This is what is displayed on any connected monitor by default. However, servers do @@ -42,10 +42,10 @@ the serial port. To do this, the kernel command line needs to specified on it -- a common value is ``console=ttyS0`` but this is not something that can be generically documented. -When running on serial, the installer starts in a basic mode that uses only +When running on a serial port, the installer starts in a basic mode that uses only the ASCII character set and black and white colours. If you are connecting from -a terminal emulator such as gnome-terminal that supports Unicode and rich -colours you can switch to "rich mode" which uses Unicode, colours and supports +a terminal emulator, such as gnome-terminal, that supports Unicode and rich +colours, you can switch to "rich mode" which uses Unicode and colours, and supports many languages. .. _connect-via-ssh: @@ -88,7 +88,7 @@ There are some global keys you can press at any time: ==================================== ============================================= Key Action ==================================== ============================================= -:kbd:`ESC` Go back +:kbd:`Esc` Go back :kbd:`F1` Open help menu :kbd:`Control` + :kbd:`Z`, :kbd:`F2` Switch to shell :kbd:`Control` + :kbd:`L`, :kbd:`F3` Redraw screen diff --git a/doc/howto/autoinstall-quickstart-s390x.rst b/doc/howto/autoinstall-quickstart-s390x.rst index 54f2abd1..2aaef516 100644 --- a/doc/howto/autoinstall-quickstart-s390x.rst +++ b/doc/howto/autoinstall-quickstart-s390x.rst @@ -26,8 +26,8 @@ Mount the ISO mkdir -p ~/iso sudo mount -r ~/Downloads/ubuntu-|ubuntu-latest-version|-live-server-s390x.iso ~/iso -Write your autoinstall config -============================= +Write your autoinstall configuration +==================================== Create a cloud-init configuration: @@ -46,10 +46,10 @@ Create a cloud-init configuration: EOF touch meta-data -The crypted password is ``ubuntu``. +The encrypted password is ``ubuntu``. -Serve the cloud-init config over HTTP -===================================== +Serve the cloud-init configuration over HTTP +============================================ Leave this running in one terminal window: diff --git a/doc/howto/autoinstall-quickstart.rst b/doc/howto/autoinstall-quickstart.rst index d421161a..b1a48aa5 100644 --- a/doc/howto/autoinstall-quickstart.rst +++ b/doc/howto/autoinstall-quickstart.rst @@ -17,7 +17,7 @@ Providing the autoinstall data over the network =============================================== This method is the one that generalises most easily to doing an entirely -network-based install, where a machine netboots and then is automatically +network-based installation where a machine boots over a network and then is automatically installed. Download the ISO @@ -37,10 +37,10 @@ Where you should change `` to match the number of the LTS or release you have downloaded (e.g., `22.04.3` for Jammy or `23.04` for the Lunar interim release). -Write your autoinstall config ------------------------------ +Write your autoinstall configuration +------------------------------------ -This means creating cloud-init config as follows: +This means creating cloud-init configuration as follows: .. code-block:: bash @@ -57,10 +57,10 @@ This means creating cloud-init config as follows: EOF touch meta-data -The crypted password is just "ubuntu". +The encrypted password is ``ubuntu``. -Serve the cloud-init config over HTTP -------------------------------------- +Serve the cloud-init configuration over HTTP +-------------------------------------------- Leave this running in one terminal window: @@ -76,8 +76,8 @@ Create a target disk truncate -s 10G image.img -Run the install! ----------------- +Run the installation +-------------------- As before, you will need to change `` in the following command to match the release ISO you downloaded. @@ -91,8 +91,8 @@ to match the release ISO you downloaded. -initrd /mnt/casper/initrd \ -append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/' -This will boot, download the config from the server (set up in the previous -step) and run the install. The installer reboots at the end but the +This will boot, download the configuration from the server (set up in the previous +step) and run the installation. The installer reboots at the end but the ``-no-reboot`` flag to ``kvm`` means that ``kvm`` will exit when this happens. It should take about 5 minutes. @@ -107,8 +107,8 @@ Boot the installed system This will boot into the freshly installed system and you should be able to log in as ``ubuntu/ubuntu``. -Using another volume to provide the autoinstall config -====================================================== +Using another volume to provide the autoinstall configuration +============================================================= This is the method to use when you want to create media that you can just plug into a system to have it be installed. @@ -137,7 +137,7 @@ Create your user-data and meta-data files EOF touch meta-data -The crypted password is just ``ubuntu``. +The encrypted password is ``ubuntu``. Create an ISO to use as a cloud-init data source ------------------------------------------------ @@ -154,8 +154,8 @@ Create a target disk truncate -s 10G image.img -Run the install! ----------------- +Run the installation +-------------------- As before, you will need to change `` in the following command to match the release ISO you downloaded. @@ -167,8 +167,8 @@ to match the release ISO you downloaded. -drive file=~/seed.iso,format=raw,cache=none,if=virtio \ -cdrom ~/Downloads/ubuntu--live-server-amd64.iso -This will boot and run the install. Unless you interrupt boot to add -'autoinstall' to the kernel command line, the installer will prompt for +This boots the system and runs the installation. Unless you interrupt boot to add +``autoinstall`` to the kernel command line, the installer prompts for confirmation before touching the disk. The installer reboots at the end but the ``-no-reboot`` flag to ``kvm`` means diff --git a/doc/howto/report-bugs.rst b/doc/howto/report-bugs.rst index bcab26c9..f49d5380 100644 --- a/doc/howto/report-bugs.rst +++ b/doc/howto/report-bugs.rst @@ -3,7 +3,7 @@ How to report a problem *********************** -We always hope, of course, that every install with the server installer +We always hope, of course, that every installation with the server installer succeeds. But reality doesn't always work that way and there will sometimes be failures of various kinds. This section explains the most useful way to report any failures so that we can fix the bugs causing them, and we'll keep the topic @@ -22,7 +22,7 @@ Crash reports A failure will result in a crash report being generated which bundles up all the information we need to fully diagnose a failure. These live in ``/var/crash`` in the installer environment, and for Ubuntu 19.10 and newer -this is persisted to the install media by default (if there is space). +this is persisted to the installation media by default (if there is space). When an error occurs you are presented with a dialog that allows you to upload the report to the error tracker and offers options for continuing. Uploads to diff --git a/doc/index.rst b/doc/index.rst index 7b51b7bb..c315ed1c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,24 +3,6 @@ Ubuntu Installation documentation ################################# -A single sentence that says what the product is, succinctly and memorably -consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et -dolore magna aliqua. - -A paragraph of one to three short sentences, that describe what the product -does. Urna cursus eget nunc scelerisque viverra mauris in. Nibh mauris cursus -mattis molestie a iaculis at vestibulum rhoncus est pellentesque elit. Diam -phasellus vestibulum lorem sed. - -A third paragraph of similar length, this time explaining what need the product -meets. Dui ut ornare lectus sit amet est. Nunc sed augue lacus viverra vitae -congue eu consequat ac libero id faucibus nisl tincidunt eget nullam. - -Finally, a paragraph that describes whom the product is useful for. Nunc non -blandit massa enim nec dui nunc mattis enim. Ornare arcu odio ut sem nulla -pharetra diam porttitor leo a diam sollicitudin tempor id eu. Ipsum dolor sit -amet consectetur adipiscing elit pellentesque habitant. - ----- .. grid:: 1 1 2 2 @@ -67,7 +49,7 @@ warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback. * Read our `Code of Conduct`_. -* IRC: `Libera.Chat`_, the *#ubuntu-server* channel. +* IRC: `Libera.Chat`_, the :spellexception:`#ubuntu-server` channel. * Discourse: `Ubuntu Foundations`_. * Contribute: See `CONTRIBUTING.md`_ on GitHub. diff --git a/doc/intro-to-autoinstall.rst b/doc/intro-to-autoinstall.rst index 312b2271..81423a18 100644 --- a/doc/intro-to-autoinstall.rst +++ b/doc/intro-to-autoinstall.rst @@ -11,15 +11,15 @@ This format is supported in the following installers: * Ubuntu Server, version 20.04 and later * Ubuntu Desktop, version 23.04 and later -Autoinstallation lets you answer all those configuration questions ahead of -time with an *autoinstall config* and lets the installation process run without +Automatic installation lets you answer all those configuration questions ahead of +time with an *autoinstall configuration* and lets the installation process run without any interaction. -Differences from debian-installer preseeding +Differences from :spellexception:`debian-installer` preseeding ============================================ -*preseeds* are the way to automate an installer based on debian-installer +*preseeds* are the way to automate an installer based on :spellexception:`debian-installer` (also known as d-i). Autoinstalls differ from preseeds in the following ways: @@ -38,23 +38,22 @@ Providing the autoinstall configuration ======================================= There are 2 ways to provide the autoinstall configuration: - * Provide :external+cloud-init:ref:`#cloud-config - user-data` containing ``autoinstall:`` + * Provide :external+cloud-init:ref:`#cloud-config user data ` containing ``autoinstall:`` configuration directives to cloud-init at boot time - * Directly on the install media + * Directly on the installation media -Autoinstall by way of cloud-config +Autoinstall by way of cloud-:spellexception:`config` ---------------------------------- -The suggested way of providing autoinstall config to the Ubuntu installer is +The suggested way of providing autoinstall configuration to the Ubuntu installer is via cloud-init. This allows the configuration to be applied to the installer -without having to modify the install media. +without having to modify the installation media. -The autoinstall config is provided via cloud-init configuration, which is +The autoinstall configuration is provided via cloud-init configuration, which is almost endlessly flexible. In most scenarios the easiest way will be to provide user data via the :external+cloud-init:ref:`datasource_nocloud` data source. -When providing autoinstall via cloud-init, the autoinstall config is provided +When providing autoinstall via cloud-init, the autoinstall configuration is provided as :external+cloud-init:ref:`user_data_formats-cloud_config`. This means we need a :code:`#cloud-config` header. The autoinstall directives are placed under a top level :code:`autoinstall:` key, like so: @@ -69,16 +68,16 @@ placed under a top level :code:`autoinstall:` key, like so: .. note:: :external+cloud-init:ref:`user_data_formats-cloud_config` files must contain - the ``#cloud-config`` header to be recognized as a valid cloud config data + the ``#cloud-config`` header to be recognised as a valid cloud configuration data file. -Autoinstall on the install media --------------------------------- +Autoinstall on the installation media +------------------------------------- Another option for supplying autoinstall to the Ubuntu installer is to place a -file named :code:`autoinstall.yaml` on the install media itself. +file named :code:`autoinstall.yaml` on the installation media itself. -There are two potential locations that subiquity will check for the +There are two potential locations that Subiquity will check for the :code:`autoinstall.yaml` file: * At the root of the "CD-ROM". When you write the installation ISO to a USB @@ -117,14 +116,14 @@ autoinstall file in the following order and pick the first existing one: 1. Kernel command line 2. Root of the installation system -3. Cloud Config +3. Cloud-:spellexception:`config` 4. Root of the CD-ROM (ISO) Cloud-init and autoinstall interaction ====================================== -Cloud-init runs in both the ephemeral system (during install) and in the target +Cloud-init runs in both the ephemeral system (during installation) and in the target system during first boot. Cloud-init then becomes inert for every subsequent reboot. @@ -141,7 +140,7 @@ being installed, they must appear under a :ref:`ai-user-data` section under #cloud-config # cloud-init directives may optionally be specified here. - # These directives affect the ephemeral system performing the install. + # These directives affect the ephemeral system performing the installation. autoinstall: # autoinstall directives must be specified here, not directly at the @@ -174,11 +173,11 @@ To bypass this prompt, arrange for the argument :code:`autoinstall` to be present on the kernel command line. -Creating an autoinstall config -============================== +Creating an autoinstall configuration +===================================== When any system is installed using the Ubuntu installer, an autoinstall file -for repeating the install is created at +for repeating the installation is created at :code:`/var/log/installer/autoinstall-user-data`. diff --git a/doc/reference/autoinstall-reference.rst b/doc/reference/autoinstall-reference.rst index 9ee65801..65c99245 100644 --- a/doc/reference/autoinstall-reference.rst +++ b/doc/reference/autoinstall-reference.rst @@ -4,14 +4,14 @@ Autoinstall configuration reference manual ****************************************** The autoinstall file is YAML. At top level it must be a mapping containing the -keys described in this document. Unrecognized keys are ignored. +keys described in this document. Unrecognised keys are ignored. .. _ai-schema: Schema ====== -Autoinstall configs are +Autoinstall configurations are :doc:`validated against a JSON schema` before they are used. @@ -20,10 +20,10 @@ used. Command lists ============= -Several config keys are lists of commands to be executed. Each command can be +Several configuration keys are lists of commands to be executed. Each command can be a string (in which case it is executed via ``sh -c``) or a list, in which case it is executed directly. Any command exiting with a non-zero return code is -considered an error and aborts the install (except for error-commands, where +considered an error and aborts the installation (except for error-commands, where it is ignored). .. _ai-top-level-keys: @@ -39,7 +39,7 @@ version * **type:** integer * **default:** no default -A future-proofing config file version field. Currently this must be "1". +A future-proofing configuration file version field. Currently this must be "1". .. _ai-interactive-sections: @@ -49,7 +49,7 @@ interactive-sections * **type:** list of strings * **default:** [] -A list of config keys to still show in the UI. So for example: +A list of configuration keys to still show in the UI. For example: .. code-block:: yaml @@ -60,15 +60,15 @@ A list of config keys to still show in the UI. So for example: username: ubuntu password: $crypted_pass -Would stop on the network screen and allow the user to change the defaults. If -a value is provided for an interactive section it is used as the default. +This example stops on the network screen and allows the user to change the defaults. If +a value is provided for an interactive section, it is used as the default. -You can use the special section name of "\*" to indicate that the installer +You can use the special section name of ``*`` to indicate that the installer should ask all the usual questions -- in this case, the :file:`autoinstall.yaml` file is not really an "autoinstall" file at all, instead just a way to change the defaults in the UI. -Not all config keys correspond to screens in the UI. This documentation +Not all configuration keys correspond to screens in the UI. This documentation indicates if a given section can be interactive or not. If there are any interactive sections at all, the :ref:`ai-reporting` key is @@ -85,9 +85,9 @@ early-commands A list of shell commands to invoke as soon as the installer starts, in particular before probing for block and network devices. The autoinstall -config is available at :file:`/autoinstall.yaml` (irrespective of how it was +configuration is available at :file:`/autoinstall.yaml` (irrespective of how it was provided) and the file will be re-read after the ``early-commands`` have run to -allow them to alter the config if necessary. +allow them to alter the configuration if necessary. .. _ai-locale: @@ -143,7 +143,7 @@ The layout of any attached keyboard. Often systems being automatically installed will not have a keyboard at all in which case the value used here does not matter. -The mapping's keys correspond to settings in the :file:`/etc/default/keyboard` +The mapping keys correspond to settings in the :file:`/etc/default/keyboard` configuration file. See the :manualpage:`keyboard(5) manual page ` for more details. @@ -206,24 +206,24 @@ id * **type:** string * **default:** identifier of the first available source. -Identifier of the source to install (e.g., ``"ubuntu-server-minimal"``). +Identifier of the source to install (e.g., ``ubuntu-server-minimal``). .. _ai-network: network ------- -* **type:** netplan-format mapping, see below +* **type:** Netplan-format mapping, see below * **default:** DHCP on interfaces named ``eth*`` or ``en*`` * **can be interactive:** yes `Netplan-formatted `_ network configuration. This will be applied during installation as well as in the installed system. -The default is to interpret the config for the install media, which runs -DHCPv4 on any interface with a name matching "``eth*``" or "``en*``" but then +The default is to interpret the configuration for the installation media, which runs +DHCP version 4 on any interface with a name matching ``eth*`` or ``en*`` but then disables any interface that does not receive an address. -For example, to run DHCPv6 on a particular NIC: +For example, to run DHCP version 6 on a specific network interface: .. code-block:: yaml @@ -234,8 +234,7 @@ For example, to run DHCPv6 on a particular NIC: dhcp6: true Note that in the 20.04 GA release of Subiquity, the behaviour is slightly -different and requires you to write this with an extra ``network:`` key, like -so: +different and requires you to write this with an extra ``network:`` key: .. code-block:: yaml @@ -270,7 +269,7 @@ apt * **default:** see below * **can be interactive:** yes -APT configuration, used both during the install and once booted into the target +APT configuration, used both during the installation and once booted into the target system. This section historically used the same format as curtin, @@ -280,7 +279,7 @@ Nonetheless, some key differences with the format supported by curtin have been - Subiquity supports an alternative format for the ``primary`` section, allowing configuration of a list of candidate primary mirrors. During installation, Subiquity will automatically test the specified mirrors and - select the first one that seems usable. This new behavior is only activated + select the first one that seems usable. This new behaviour is only activated when the ``primary`` section is wrapped in the ``mirror-selection`` section. - The ``fallback`` key controls what Subiquity should do if no primary mirror @@ -323,7 +322,7 @@ can be expressed in two different ways: * The special value ``country-mirror`` * A mapping with the following keys: - * ``uri``: The URI of the mirror to use, e.g., "http://fr.archive.ubuntu.com/ubuntu" + * ``uri``: The URI of the mirror to use, e.g., ``http://fr.archive.ubuntu.com/ubuntu`` * ``arches``: An optional list of architectures supported by the mirror. By default, this list contains the current CPU architecture. @@ -353,7 +352,7 @@ Subiquity then sets the mirror URI to ``http://CC.archive.ubuntu.com/ubuntu`` (or similar for ports) where ``CC`` is the country code returned by the lookup. If this section is not interactive, the request is timed out after 10 seconds. -If the legacy behavior (i.e., without mirror-selection) is in use, the geoip +If the legacy behaviour (i.e., without mirror-selection) is in use, the geoip request is made if the mirror to be used is the default, and its URI ends up getting replaced by the proper country mirror URI. @@ -368,7 +367,7 @@ If you just want to specify a mirror, you can use a configuration like this: - country-mirror - uri: http://archive.ubuntu.com/ubuntu -To add a ppa: +To add a PPA: .. code-block:: yaml @@ -383,8 +382,8 @@ storage ------- * **type:** mapping, see below -* **default:** use "lvm" layout in a single disk system, no default in a - multiple disk system +* **default:** use the ``lvm`` layout on single-disk systems; there is no default for + multiple-disk systems * **can be interactive:** yes Storage configuration is a complex topic and the description of the desired @@ -394,7 +393,7 @@ supports "layouts"; simple ways of expressing common configurations. Supported layouts ~~~~~~~~~~~~~~~~~ -The three supported layouts at the time of writing are "lvm", "direct", and "zfs". +The three supported layouts at the time of writing are ``lvm``, ``direct`` and ``zfs``. .. code-block:: yaml @@ -428,7 +427,7 @@ supply a match spec (see below) to indicate which disk to use: .. note:: Match spec -- using "``match: {}``" will match an arbitrary disk -When using the "lvm" layout, LUKS encryption can be enabled by supplying a +When using the ``lvm`` layout, LUKS encryption can be enabled by supplying a password. .. code-block:: yaml @@ -444,9 +443,9 @@ The default is to use the ``lvm`` layout. Sizing-policy ~~~~~~~~~~~~~ -The lvm layout will, by default, attempt to leave room for snapshots and +The ``lvm`` layout, by default, attempts to leave room for snapshots and further expansion. A sizing-policy key may be supplied to control this -behavior. +behaviour. * **type:** string (enumeration) * **default:** scaled @@ -459,10 +458,10 @@ Supported values are: The scaling system is currently as follows: -* Less than 10 GiB: use all remaining space for root filesystem -* Between 10--20 GiB: 10 GiB root filesystem -* Between 20--200 GiB: use half of remaining space for root filesystem -* Greater than 200 GiB: 100 GiB root filesystem +* Less than 10 GiB: use all remaining space for root file system +* Between 10--20 GiB: 10 GiB root file system +* Between 20--200 GiB: use half of remaining space for root file system +* Greater than 200 GiB: 100 GiB root file system Example with no size scaling and a passphrase: @@ -474,20 +473,20 @@ Example with no size scaling and a passphrase: sizing-policy: all password: LUKS_PASSPHRASE -Action-based config -~~~~~~~~~~~~~~~~~~~ +Action-based configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~ For full flexibility, the installer allows storage configuration to be done using a syntax which is a superset of that supported by curtin, as described in `the curtin documentation `_. -If the "layout" feature is used to configure the disks, the "config" section -will not be used. +If the ``layout`` feature is used to configure the disks, the ``config`` section +is not used. -As well as putting the list of actions under the 'config' key, the +As well as putting the list of actions under the ``config`` key, the `grub `_ and `swap `_ -curtin config items can be put here. So a storage section might look like: +curtin configuration items can be put here. So a storage section might look like: .. code-block:: yaml @@ -513,7 +512,7 @@ Curtin supported identifying disks by serial (e.g. server installer supports this as well. The installer additionally supports a ''match spec'' on a disk action that supports more flexible matching. -The actions in the storage config are processed in the order they are in the +The actions in the storage configuration are processed in the order they are in the autoinstall file. Any disk action is assigned a matching disk -- chosen arbitrarily from the set of unassigned disks if there is more than one, and causing the installation to fail if there is no unassigned matching disk. @@ -540,7 +539,7 @@ A match spec supports the following keys: A special sort of key is ``install-media: true``, which will take the disk the installer was loaded from (the ``ssd`` and ``size`` selectors will never return -this disk). If installing to the install media, care obviously needs to be taken +this disk). If installing to the installation media, care obviously needs to be taken to not overwrite the installer itself! So for example, to match an arbitrary disk it is simply: @@ -574,7 +573,7 @@ Partition/logical volume extensions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The size of a partition or logical volume in curtin is specified as a number of -bytes. The autoinstall config is more flexible: +bytes. The autoinstall configuration is more flexible: * You can specify the size using the "1G", "512M" syntax supported in the installer UI. @@ -607,7 +606,7 @@ identity * **default:** no default * **can be interactive:** yes -Configure the initial user for the system. This is the only config key that +Configure the initial user for the system. This is the only configuration key that must be present (unless the :ref:`user-data section ` is present, in which case it is optional). @@ -634,11 +633,11 @@ password The password for the new user, encrypted. This is required for use with ``sudo``, even if SSH access is configured. -The crypted password string must conform to what the +The encrypted password string must conform to what the ``passwd`` command requires. See the :manualpage:`passwd(1) manual page ` for details. Quote the password hash to ensure correct treatment of any special characters. -Several tools can generate the crypted password, such as ``mkpasswd`` from the +Several tools can generate the encrypted password, such as ``mkpasswd`` from the ``whois`` package, or ``openssl passwd``. Example: @@ -711,7 +710,7 @@ install-server Whether to install OpenSSH server in the target system. -authorized-keys +:spellexception:`authorized-keys` ~~~~~~~~~~~~~~~ * **type:** list of strings @@ -807,7 +806,7 @@ debconf-selections ------------------ * **type:** string -* **default:** no config +* **default:** no configuration * **can be interactive:** no The installer will update the target with debconf set-selection values. Users @@ -837,7 +836,7 @@ kernel * **can be interactive:** no Which kernel gets installed. Either the name of the package or the name of the -flavor must be specified. +flavour must be specified. package ~~~~~~~ @@ -851,7 +850,7 @@ flavor * **type:** string -The flavor of the kernel, e.g., ``generic`` or ``hwe``. +The ``flavor`` of the kernel, e.g., ``generic`` or ``hwe``. .. _ai-timezone: @@ -875,7 +874,7 @@ updates * **can be interactive:** no The type of updates that will be downloaded and installed after the system -install. Supported values are: +installation. Supported values are: * ``security`` -> download and install updates from the -security pocket * ``all`` -> also download and install updates from the -updates pocket @@ -904,7 +903,7 @@ late-commands * **default:** no commands * **can be interactive:** no -Shell commands to run after the install has completed successfully and any +Shell commands to run after the installation has completed successfully and any updates and packages installed, just before the system reboots. They are run in the installer environment with the installed system mounted at ``/target``. You can run ``curtin in-target -- $shell_command`` (with the version of Subiquity @@ -922,7 +921,7 @@ error-commands * **default:** no commands * **can be interactive:** no -Shell commands to run after the install has failed. They are run in the +Shell commands to run after the installation has failed. They are run in the installer environment, and the target system (or as much of it as the installer managed to configure) will be mounted at ``/target``. Logs will be available at :file:`/var/log/installer` in the live session. @@ -940,10 +939,10 @@ reporting The installer supports reporting progress to a variety of destinations. Note that this section is ignored if there are any :ref:`interactive sections `; it only applies to fully automated installs. -The config, and indeed the implementation, is 90% the same as +The configuration, and indeed the implementation, is 90% the same as `that used by curtin `_. -Each key in the ``reporting`` mapping in the config defines a destination, +Each key in the ``reporting`` mapping in the configuration defines a destination, where the ``type`` sub-key is one of: **The rsyslog reporter does not yet exist** @@ -952,7 +951,7 @@ where the ``type`` sub-key is one of: console. There is no other configuration. * **rsyslog**: report progress via rsyslog. The **destination** key specifies where to send output. -* **webhook**: report progress via POSTing JSON reports to a URL. Accepts the +* **webhook**: report progress by sending JSON reports to a URL using POST requests. Accepts the same `configuration as curtin `_. * **none**: do not report progress. Only useful to inhibit the default output. diff --git a/doc/reference/autoinstall-schema.rst b/doc/reference/autoinstall-schema.rst index 1b8bf0a9..63a6f6ae 100644 --- a/doc/reference/autoinstall-schema.rst +++ b/doc/reference/autoinstall-schema.rst @@ -3,15 +3,15 @@ Autoinstall schema ****************** -The server installer validates the provided autoinstall config against a +The server installer validates the provided autoinstall configuration against a :ref:`JSON schema`. -How the config is validated -=========================== +How the configuration is validated +================================== Although the schema is presented below as a single document, and if you want -to pre-validate your config you should validate it against this document, the -config is not actually validated against this document at run time. What +to pre-validate your configuration you should validate it against this document, the +configuration is not actually validated against this document at run time. What happens instead is that some sections are loaded, validated, and applied first, before all other sections are validated. In detail: @@ -19,7 +19,7 @@ first, before all other sections are validated. In detail: 2. The error commands are loaded and validated. 3. The early commands are loaded and validated. 4. The early commands, if any, are run. -5. The config is reloaded, and now all sections are loaded and validated. +5. The configuration is reloaded, and now all sections are loaded and validated. This is so that validation errors in most sections can be reported via the reporting and error-commands configuration, as all other errors are. diff --git a/doc/tutorial/basic-server-installation.rst b/doc/tutorial/basic-server-installation.rst index a3c39f91..0065308e 100644 --- a/doc/tutorial/basic-server-installation.rst +++ b/doc/tutorial/basic-server-installation.rst @@ -18,7 +18,7 @@ System requirements ------------------- Ubuntu Server Edition provides a common, minimalist base for a variety of -server applications, such as file/print services, web hosting, email hosting, +server applications, such as file or print services, web hosting, email hosting, etc. This version supports four 64-bit architectures: * amd64 (Intel/AMD 64-bit) @@ -32,8 +32,8 @@ The recommended system requirements are: * RAM: 1 gigabyte or more * Disk: a minimum of 2.5 gigabytes -Perform a system back up ------------------------- +Perform a system backup +----------------------- Before installing Ubuntu Server Edition you should make sure all data on the system is backed up. @@ -50,8 +50,8 @@ use, but they also perform destructive actions. Download the server ISO ----------------------- -You can obtain the amd64 server download from https://releases.ubuntu.com/. -Select the version you wish to install and select the "server install image" +You can obtain the amd64 server download from `releases.ubuntu.com `_. +Select the version you wish to install and select the "Server install image" download. Note that the server download includes the installer. There are platform-specific how-to guides for installations on: @@ -73,7 +73,7 @@ are also available). Perform the installation ======================== -Now that you have prepared your install medium, you are ready to install. +Now that you have prepared your installation medium, you are ready to install. Boot the installer ------------------ @@ -83,17 +83,16 @@ Plug the USB stick into the system to be installed and start it. Most computers will automatically boot from USB or DVD, though in some cases this is disabled to improve boot times. If you don't see the boot message and the "Welcome" screen which should appear after it, you will need to set your -computer to boot from the install media. +computer to boot from the installation media. There should be an on-screen message when the computer starts, telling you what key to press for settings or a boot menu. Depending on the manufacturer, this could be :kbd:`Escape`, :kbd:`F2`, :kbd:`F10` or :kbd:`F12`. Restart your computer and hold down this key until the boot menu appears, then select the -drive with the Ubuntu install media. +drive with the Ubuntu installation media. -If you are still having problems, check out the -`Ubuntu Community documentation on booting from -CD/DVD `_. +If you are still having problems, see the +`Ubuntu Community documentation on booting from CD/DVD `_. After a few moments, the installer will start in its language selection screen. @@ -103,21 +102,20 @@ After a few moments, the installer will start in its language selection screen. Using the installer ------------------- -The installer is designed to be easy to use and have sensible defaults so for -a first install you can mostly just accept the defaults for the most -straightforward install: +The installer is designed to be easy to use and have sensible defaults, so for +a first installation you can accept the defaults: -* Choose your language -* Update the installer (if offered) -* Select your keyboard layout +* Choose your language. +* Update the installer (if offered). +* Select your keyboard layout. * Do not configure networking (the installer attempts to configure wired network interfaces via DHCP, but you can continue without networking if this - fails) -* Do not configure a proxy or custom mirror unless you have to in your network + fails). +* Do not configure a proxy or custom mirror unless you have to in your network. * For storage, leave "use an entire disk" checked, and choose a disk to install - to, then select "Done" on the configuration screen and confirm the install -* Enter a username, hostname and password -* On the SSH and snap screens, select "Done" -* You will now see log messages as the install is completed + to, then select "Done" on the configuration screen and confirm the installation. +* Enter a username, hostname and password. +* On the SSH and snap screens, select "Done". +* You now see log messages as the installation is completed. * Select restart when this is complete, and log in using the username and - password provided + password provided. diff --git a/doc/tutorial/screen-by-screen.rst b/doc/tutorial/screen-by-screen.rst index aa6243ff..5731ecab 100644 --- a/doc/tutorial/screen-by-screen.rst +++ b/doc/tutorial/screen-by-screen.rst @@ -72,8 +72,8 @@ Zdev (s390x only) This screen is only shown on s390x and allows z-specific configuration of devices. -The list of devices can be long. :kbd:`Home` / :kbd:`End` / :kbd:`PageUp` -/ :kbd:`PageDown` can be used to navigate through the list more quickly. +The list of devices can be long. :kbd:`Home` / :kbd:`End` / :kbd:`PgUp` +/ :kbd:`PgDown` can be used to navigate through the list more quickly. Network ======= @@ -81,10 +81,10 @@ Network .. image:: figures/sbs-network.png :alt: -This screen allows the configuration of the network. Ubuntu Server uses NetPlan +This screen allows the configuration of the network. Ubuntu Server uses Netplan to configure networking and the UI of the installer can configure a subset of -NetPlan's capabilities. In particular it can configure DHCP or static -addressing, VLANs and bonds. +Netplan capabilities. In particular, it can configure DHCP or static +addressing, VLAN and bonds. If networking is present (defined as "at least one interface has a default route") then the installer will install updates from the archive at the end of @@ -121,7 +121,7 @@ Storage configuration is a complicated topic and :ref:`has its own page for docu .. image:: figures/sbs-confirm-storage.png :alt: -Once the storage configuration is confirmed, the install begins in the +Once the storage configuration is confirmed, the installation begins in the background. Identity @@ -140,7 +140,7 @@ SSH .. image:: figures/sbs-ssh.png :alt: -A default Ubuntu install has no open ports. It is very common to administer +A default Ubuntu installation has no open ports. It is very common to administer servers via SSH so the installer allows it to be installed with the click of a button. @@ -165,7 +165,7 @@ Installation logs :alt: The final screen of the installer shows the progress of the installer and -allows viewing of the full log file. Once the install has completed and +allows viewing of the full log file. Once the installation has completed and security updates installed, the installer waits for confirmation before restarting.