Merge pull request #1854 from rkratky/FR-5772_review-explanations

Review explanation docs
This commit is contained in:
Dan Bungert 2023-10-25 13:08:05 -06:00 committed by GitHub
commit a6708aabf3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 66 additions and 168 deletions

View File

@ -24,7 +24,7 @@ NoCloud
OEM
OpenSSH
Petitboot
PgDown
PgDn
PgUp
POST
PPA

View File

@ -1,176 +1,108 @@
.. _configure-storage:
Configuring storage
*******************
===================
There are a lot of options for storage configuration with the Subiquity
installer. This guide will walk you through some of the common options for an
Ubuntu Server installation.
This article describes how to use the most common options for storage configuration of the Subiquity installer.
Guided options
==============
--------------
.. image:: figures/configure-storage-guided-options.png
:alt:
Selecting "Use an entire disk" on the Guided storage configuration screen will
install Ubuntu onto the selected disk, replacing any partitions or data already
there.
Select :guilabel:`Use an entire disk` on the :guilabel:`Guided storage configuration` screen to install Ubuntu to the selected disk, replacing any partitions or data already there.
You can choose whether or not to set up LVM, and if you do, whether or not to
encrypt the volume with LUKS. If you encrypt the volume, you need to choose a
passphrase that will need to be entered each time the system boots.
You can choose whether or not to set up LVM, and if you do, whether or not to encrypt the volume with LUKS. If you encrypt the volume, choose a passphrase to be entered every time the system boots.
If you select "Custom storage layout", no configuration will be applied to the
disks.
Select :guilabel:`Custom storage layout` to apply no configuration to the disks.
In either case, the installer moves onto the main storage customisation screen.
The installer then moves to the main storage customisation screen.
The main storage screen
=======================
-----------------------
.. image:: figures/configure-storage-main-screen.png
:alt:
This screen presents a summary of the current storage configuration. Each
device or partition of a device corresponds to a different row (which can be
selected), and pressing :kbd:`Enter` or :kbd:`space` while a device is selected
opens a menu of actions that apply to that device.
This screen presents a summary of the current storage configuration. Each device or partition of a device corresponds to a different row (which can be selected). Press :kbd:`Enter` or :kbd:`space` while a device is selected to open a menu of actions that apply to that device.
Partitions
==========
----------
.. image:: figures/configure-storage-partitions.png
:alt:
To add a partition to a device, select "Add GPT Partition" for that device.
To add a partition to a device, select :guilabel:`Add GPT Partition` for that device.
.. image:: figures/configure-storage-GPT-partition.png
:alt:
You can leave "Size" blank to use all the remaining space on the device.
To use all the remaining space on the device, leave :guilabel:`Size` blank.
RAID
====
----
.. image:: figures/configure-storage-raid.png
:alt:
`Linux software RAID <https://raid.wiki.kernel.org/index.php/Linux_Raid>`_
(where RAID stands for "Redundant Array of Inexpensive 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://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.
A software RAID device can be created out of entire disks or unformatted
partitions. Select the "Create software RAID ("MD")" button to open the
creation dialog.
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 devices with RAID level 0, 1, 5, 6 or 10 being
created. It does not allow customising other options such as metadata format or
RAID10 layout at this time. 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://raid.wiki.kernel.org/index.php/Linux_Raid>`_ for more details.
A software RAID device can be formatted and mounted directly, can be
partitioned into several partitions, and can even be used as part of another
RAID device or LVM volume group.
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.
Logical Volume Manager (LVM)
============================
----------------------------
.. image:: figures/configure-storage-lvm.png
:alt:
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 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.
LVM is a system of managing logical volumes, or file systems, that is more advanced and flexible than the traditional method of partitioning a disk into one or more segments and formatting that partition with a file system. LVM can be used to combine several disks into one larger pool of storage. It also offers advantages for single-disk systems, such as snapshots and easy resizing of logical volumes.
As with RAID, a LVM volume group can be created out of entire disks or
unformatted partitions. Select the "Create LVM volume group" button to open
the creation dialog.
As with RAID, a LVM volume group can be created from entire disks or unformatted partitions. Select the :guilabel:`Create LVM volume group` button to open the creation dialog.
Once a volume group has been created, it can be divided into named logical
volumes which can then be formatted and mounted. It generally makes sense to
leave some space in the volume group for storage of snapshots and creation of
more logical volumes as needed.
Once a volume group has been created, it can be divided into named logical volumes, which can then be formatted and mounted. It is recommended to leave some space in the volume group for storage of snapshots and creation of more logical volumes as needed.
The server installer does not supported configuring any of the many, many
options that LVM supports when creating volume groups and logical volumes.
The server installer does not support configuring any LVM options for creating volume groups and logical volumes.
Selecting boot devices
======================
----------------------
.. image:: figures/configure-storage-boot-devices.png
:alt:
On all architectures other than s390x, the bootloader needs to be installed to
a disk in such a way that the system firmware can find it on boot. By default,
the first device to have a partition created on it is selected as a boot device
but this can be changed later.
On all architectures other than s390x, the bootloader needs to be installed to a disk in such a way that the system firmware can find it on boot. By default, the first device to have a partition created on it is selected as a boot device. 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 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.
On amd64 and arm64 systems, multiple disks can be selected as boot devices, which means a system can be configured to continue booting after a failure of any one drive (provided the root file system is placed on a RAID). The bootloader is installed to each of these drives, and the operating system configured to install new versions of GRUB to each drive as it is updated.
amd64 systems use GRUB as the bootloader. amd64 systems can boot in either UEFI
or legacy (sometimes called "BIOS") mode (many systems can be configured to
boot in either mode) and the bootloader is located completely differently in
the two modes.
amd64 systems use GRUB as the bootloader. amd64 systems can boot in either UEFI (Unified Extensible Firmware Interface) or legacy (sometimes called "BIOS") mode (many systems can be configured to boot in either mode). The bootloader is located in different places in the two modes.
Legacy mode
-----------
~~~~~~~~~~~
In legacy mode, the bootloader is read from the first "sector" of a hard drive
(exactly which hard drive is up to the system firmware, which can usually be
configured in a vendor-specific way). The installer will write GRUB to the
start of all disks selected as a boot devices. As GRUB does not entirely fit
in one sector, a small unformatted partition is needed at the start of the
disk, which will automatically be created when a disk is selected as a boot
device (a disk with an existing GPT partition table can only be used as a boot
device if it has this partition).
In legacy mode, the bootloader is read from the first "sector" of a hard drive (which hard drive depends on the system firmware, which can usually be configured in a vendor-specific way). The installer writes GRUB to the start of all disks selected as boot devices. As GRUB does not entirely fit in one sector, a small unformatted partition is needed at the start of the disk, which is automatically created when a disk is selected as a boot device (a disk with an existing GPT partition table can only be used as a boot device if it has this partition).
UEFI mode
---------
~~~~~~~~~
In UEFI mode, the bootloader loaded from a "EFI System Partition" (ESP), which
is a partition with a particular type GUID. The installer automatically creates
an ESP (with minimum size 538 MiB) on a disk when it is selected as a boot
device and will install GRUB there (a disk with an existing partition table can
only be used as a boot device if it has an ESP -- bootloaders for multiple
operating systems can be installed into a single ESP). UEFI defines a standard
way to configure the way in which the operating system is chosen on boot, and
the installer uses this to configure the system to boot the just-installed
operating system. One of the ESPs must be mounted at ``/boot/efi``.
In UEFI mode, the bootloader is loaded from an "EFI System Partition" (ESP), which is a partition with a particular GUID type. The installer automatically creates an ESP (with a minimum size of 538 MiB) on a disk when it is selected as a boot device and install GRUB there (a disk with an existing partition table can only be used as a boot device if it has an ESP -- bootloaders for multiple operating systems can be installed into a single ESP).
Supported arm64 servers boot using UEFI, and are configured the same way as an
UEFI-booting amd64 system.
UEFI defines a standard way to configure the way in which the operating system is chosen on boot, and the installer uses this to configure the system to boot the just-installed operating system. One of the ESPs must be mounted at ``/boot/efi``.
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.
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 (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.
Limitations and workarounds
===========================
---------------------------
Currently, the installer cannot **edit** partition tables. You can use existing
partitions or reformat a drive entirely, but you cannot (for example) remove a
large partition and replace it with two smaller ones.
The installer cannot **edit** partition tables. You can use existing partitions or reformat a drive entirely, but you cannot, for example, remove a large partition and replace it with two smaller ones.
The installer allows the creation of LVM volume groups and logical volumes and
MD raid devices, but does not allow tweaking of the parameters -- for example,
all logical volumes are linear and all MD raid devices use the default metadata
format (1.2).
The installer supports the creation of LVM volume groups, logical volumes, and MD RAID (software RAID) devices, but it does not provide a way to configure parameters. For example, all logical volumes are linear and all MD RAID devices use the default metadata format (1.2).
These limits can both be worked around in the same way: drop to a shell and use
the usual shell commands to edit the partition table or create the LV or RAID
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.
To work around these limitations, switch to a shell and use shell commands to edit the partition table or create the LV or RAID with desired parameters. 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 are reflected in the installer.
The installer cannot yet configure iSCSI mounts or BTRFS subvolumes.
The installer cannot configure iSCSI mounts or BTRFS subvolumes.

View File

@ -1,14 +1,12 @@
Explanation
***********
===========
Our explanatory and conceptual guides are written to provide a better
understanding of how Subiquity works. They enable you to expand your
knowledge and become better at using and configuring Subiquity.
The explanatory and conceptual guides are written to provide a better understanding of how Subiquity works. They enable you to expand your knowledge and become better at using and configuring Subiquity.
-----
About the Server installer
==========================
--------------------------
.. toctree::
:maxdepth: 1

View File

@ -1,89 +1,57 @@
.. _operate-server-installer:
Operating the Server installer
******************************
Operating the server installer
==============================
This document explains how to use the installer in general terms. For a
step-by-step guide through the screens of the installer, you can use our
`screen-by-screen reference guide <https://discourse.ubuntu.com/t/screen-by-screen-installer-guide/16690>`_.
This document explains how to use the installer in general terms. For a step-by-step guide through the screens of the installer, use the `screen-by-screen guide <https://discourse.ubuntu.com/t/screen-by-screen-installer-guide/16690>`_.
Get the installer
=================
-----------------
Installer images are created (approximately) daily and are available from the
`Ubuntu release <https://cdimage.ubuntu.com/ubuntu-server/daily-live/current/>`_ page. These are not
tested as extensively as the images from release day, but they contain the
latest packages and installer, so fewer updates are required during or
after installation.
Installer images are created (approximately) daily and are available from the `Ubuntu release <https://cdimage.ubuntu.com/ubuntu-server/daily-live/current/>`_ page. These images are not tested as extensively as the images from release days, but they contain the latest packages and installer. Therefore, fewer updates are required during or after installation.
You can download the server installer for amd64 from the
`Ubuntu Server <https://ubuntu.com/download/server>`_ page and other architectures from the
`release directory <http://cdimage.ubuntu.com/releases/20.04/release/>`_.
Download the server installer for amd64 from the `Ubuntu Server <https://ubuntu.com/download/server>`_ page and other architectures from the `release directory <http://cdimage.ubuntu.com/releases/20.04/release/>`_.
Installer UI navigation
=======================
-----------------------
In general, the installer can be used with the :kbd:`up` and :kbd:`down` arrows
and :kbd:`space` or :kbd:`Enter` keys and a little typing.
Use the :kbd:`↑` and :kbd:`↓` arrows, as well as the :kbd:`Space` or :kbd:`Enter` keys to navigate the installer.
:kbd:`Tab` and :kbd:`Shift` + :kbd:`Tab` move the focus down and up respectively.
:kbd:`Home` / :kbd:`End` / :kbd:`Page Up` / :kbd:`Page Down` can be used to
navigate through long lists more quickly in the usual way.
:kbd:`Tab` and :kbd:`Shift` + :kbd:`Tab` move the focus down and up respectively. Use :kbd:`Home`, :kbd:`End`, :kbd:`PgUp` and :kbd:`PgDn` to navigate through long lists quickly.
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
not always have a monitor. Some out-of-band management systems provide a
remote virtual terminal, but sometimes it is necessary to run the installer on
the serial port. To do this, the kernel command line needs to
`have an appropriate console <https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html>`_
specified on it -- a common value is ``console=ttyS0`` but this is not
something that can be generically documented.
By default, the installer runs on the first virtual terminal, ``tty1``. This is what is displayed on any connected monitor by default. On systems without a monitor or a remote virtual terminal, you can run the installer on the serial port. To do this, specify an `appropriate console <https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html>`_ on the kernel command line. A common value is ``console=ttyS0``.
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 and colours, and supports
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 and colours, and supports
many languages.
.. _connect-via-ssh:
Connecting to the installer over SSH
====================================
------------------------------------
If the only available terminal is very basic, an alternative is to connect via
SSH. If the network is up by the time the installer starts, instructions are
offered on the initial screen in basic mode. Otherwise, instructions are
available from the help menu once networking is configured.
An alternative to basic terminals is to connect via SSH. If the network is up by the time the installer starts, instructions are offered on the initial screen in basic mode. Otherwise, instructions are available from the help menu once networking is configured.
In addition, connecting via SSH is assumed to be capable of displaying all
Unicode characters, enabling more translations to be used than can be displayed
on a virtual terminal.
In addition, connecting via SSH is capable of displaying all Unicode characters, which enables the use of more translations than can be displayed on a virtual terminal.
Help menu
=========
---------
The help menu is always in the top right of the screen. It contains help --
both general and for the currently displayed screen -- and some general actions.
The help menu is in the top right of the screen. It contains help -- both general and for the currently displayed screen -- and some general actions.
Switching to a shell prompt
---------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can switch to a shell at any time by selecting "Enter shell" from the help
menu, or pressing :kbd:`Control` + :kbd:`Z` or :kbd:`F2`.
To switch to a shell at any time, select :guilabel:`Enter shell` from the help menu, or press :kbd:`Control` + :kbd:`Z` or :kbd:`F2`.
If you are accessing the installer via ``tty1``, you can also access a shell
by switching to a different virtual terminal (:kbd:`Control` + :kbd:`Alt` +
arrow, or :kbd:`Control` + :kbd:`Alt` + number keys, to move between virtual
terminals).
If you are accessing the installer via ``tty1``, you can also access a shell by switching to a different virtual terminal (:kbd:`Control` + :kbd:`Alt` + arrow, or :kbd:`Control` + :kbd:`Alt` + number keys, to move between virtual terminals).
Global keys
===========
There are some global keys you can press at any time:
-----------
The following global keys work at any time:
==================================== =============================================
Key Action

View File

@ -73,7 +73,7 @@ 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:`PgUp`
/ :kbd:`PgDown` can be used to navigate through the list more quickly.
/ :kbd:`PgDn` can be used to navigate through the list more quickly.
Network
=======