diff --git a/doc/README.md b/doc/README.md index 5e3ad891..91513c4c 100644 --- a/doc/README.md +++ b/doc/README.md @@ -9,3 +9,13 @@ documentation. As the RTD version is not yet ready, documentation changes should be made to `../documentation` until this README is updated to say otherwise. As such, please make any desired documentation changes to `../documentation`. + +# Local preview + +To build this documentation, you can run `make install` from this folder to +create the virtual environment. + +Then run the `make run` command, which will build a html version of the docs, +and serve the docs in the virtual environment. This is very convenient if you +are working on them and want your saved changes to be reflected as a working +preview. diff --git a/doc/explanation/configure-storage.rst b/doc/explanation/configure-storage.rst new file mode 100644 index 00000000..5e460055 --- /dev/null +++ b/doc/explanation/configure-storage.rst @@ -0,0 +1,177 @@ +.. _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. + +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. + +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. + +If you select "Custom storage layout", no configuration will be applied to the +disks. + +In either case, the installer moves onto 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. + +Partitions +========== + +.. image:: figures/configure-storage-partitions.png + :alt: + +To add a partition to a device, select "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. + +RAID +==== + +.. image:: figures/configure-storage-raid.png + :alt: + +`Linux software 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. + +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. + +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 `_ +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. + +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 +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 +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. + +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. + +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. + +The server installer does not supported configuring any of the many, many +options that LVM supports when 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 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). +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. + +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. + +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). + +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 +a 512MiB ESP 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``. + +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 +to a UEFI system. The installer only supports one PReP partition at this time. + +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 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). + +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. + +The installer cannot yet configure iSCSI mounts, ZFS at all, or btrfs +subvolumes. diff --git a/doc/explanation/figures/basic-installation-start-screen.png b/doc/explanation/figures/basic-installation-start-screen.png new file mode 100644 index 00000000..845d68d2 Binary files /dev/null and b/doc/explanation/figures/basic-installation-start-screen.png differ diff --git a/doc/explanation/figures/configure-storage-GPT-partition.png b/doc/explanation/figures/configure-storage-GPT-partition.png new file mode 100644 index 00000000..afadcbdd Binary files /dev/null and b/doc/explanation/figures/configure-storage-GPT-partition.png differ diff --git a/doc/explanation/figures/configure-storage-boot-devices.png b/doc/explanation/figures/configure-storage-boot-devices.png new file mode 100644 index 00000000..cc291c76 Binary files /dev/null and b/doc/explanation/figures/configure-storage-boot-devices.png differ diff --git a/doc/explanation/figures/configure-storage-guided-options.png b/doc/explanation/figures/configure-storage-guided-options.png new file mode 100644 index 00000000..818eaf1e Binary files /dev/null and b/doc/explanation/figures/configure-storage-guided-options.png differ diff --git a/doc/explanation/figures/configure-storage-lvm.png b/doc/explanation/figures/configure-storage-lvm.png new file mode 100644 index 00000000..85279bc2 Binary files /dev/null and b/doc/explanation/figures/configure-storage-lvm.png differ diff --git a/doc/explanation/figures/configure-storage-main-screen.png b/doc/explanation/figures/configure-storage-main-screen.png new file mode 100644 index 00000000..a3c4b00a Binary files /dev/null and b/doc/explanation/figures/configure-storage-main-screen.png differ diff --git a/doc/explanation/figures/configure-storage-partitions.png b/doc/explanation/figures/configure-storage-partitions.png new file mode 100644 index 00000000..82d08cc1 Binary files /dev/null and b/doc/explanation/figures/configure-storage-partitions.png differ diff --git a/doc/explanation/figures/configure-storage-raid.png b/doc/explanation/figures/configure-storage-raid.png new file mode 100644 index 00000000..712f8bbd Binary files /dev/null and b/doc/explanation/figures/configure-storage-raid.png differ diff --git a/doc/explanation/index.rst b/doc/explanation/index.rst index fd7a2c2f..08e02bee 100644 --- a/doc/explanation/index.rst +++ b/doc/explanation/index.rst @@ -7,5 +7,11 @@ knowledge and become better at using and configuring Subiquity. ----- +About the Server installer +========================== + .. toctree:: :maxdepth: 1 + + operate-server-installer + configure-storage diff --git a/doc/explanation/operate-server-installer.rst b/doc/explanation/operate-server-installer.rst new file mode 100644 index 00000000..95e725f1 --- /dev/null +++ b/doc/explanation/operate-server-installer.rst @@ -0,0 +1,96 @@ +.. _operate-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 `_. + +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 +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 +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/. + +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. + +: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. + +Running the installer over serial +================================= + +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 `_ +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 +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 +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. + +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. + +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. + +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`. + +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: + + +==================================== ============================================= +Key Action +==================================== ============================================= +: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 +:kbd:`Control` + :kbd:`T`, :kbd:`F4` Toggle rich mode (colour, Unicode) on and off +==================================== ============================================= diff --git a/doc/howto/autoinstall-quickstart-s390x.rst b/doc/howto/autoinstall-quickstart-s390x.rst new file mode 100644 index 00000000..79829834 --- /dev/null +++ b/doc/howto/autoinstall-quickstart-s390x.rst @@ -0,0 +1,125 @@ +.. _autoinstall-quickstart-s390x: + +Autoinstall quick start for s390x +********************************* + +The intent of this page is to provide simple instructions to perform an +autoinstall in a VM on your machine on s390x. + +This page is just a slightly adapted page of the +`autoinstall quickstart page` mapped to s390x. + +Download an ISO +=============== + +At the time of writing (just after the Kinetic release), the best place to go +is here: +https://cdimage.ubuntu.com/ubuntu/releases/22.10/release/ + +..code-block:: bash + + wget https://cdimage.ubuntu.com/ubuntu/releases/22.10/release/ubuntu-22.10-live-server-s390x.iso -P ~/Downloads + +Mount the ISO +============= + +.. code-block:: bash + + mkdir -p ~/iso + sudo mount -r ~/Downloads/ubuntu-22.10-live-server-s390x.iso ~/iso + +Write your autoinstall config +============================= + +This means creating cloud-init config as follows: + +.. code-block:: bash + + mkdir -p ~/www + cd ~/www + cat > user-data << 'EOF' + #cloud-config + autoinstall: + version: 1 + identity: + hostname: ubuntu-server + password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0" + username: ubuntu + EOF + touch meta-data + +The crypted password is just ``ubuntu``. + +Serve the cloud-init config over HTTP +===================================== + +Leave this running in one terminal window: + +.. code-block:: bash + + cd ~/www + python3 -m http.server 3003 + +Create a target disk +==================== + +Proceed with a second terminal window: + +.. code-block:: bash + + sudo apt install qemu-utils + ... + + qemu-img create -f qcow2 disk-image.qcow2 10G + Formatting 'disk-image.qcow2', fmt=qcow2 size=10737418240 cluster_size=65536 lazy_refcounts=off refcount_bits=16 + + qemu-img info disk-image.qcow2 + image: disk-image.qcow2 + file format: qcow2 + virtual size: 10 GiB (10737418240 bytes) + disk size: 196 KiB + cluster_size: 65536 + Format specific information: + compat: 1.1 + lazy refcounts: false + refcount bits: 16 + corrupt: false + +Run the install! +================ + +.. code-block:: bash + + sudo apt install qemu-kvm + ... + +You may need to add the default user to the ``kvm`` group: <
> + +.. code-block:: bash + + sudo usermod -a -G kvm ubuntu # re-login to make the changes take effect + + kvm -no-reboot -name auto-inst-test -nographic -m 2048 \ + -drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio \ + -cdrom ~/Downloads/ubuntu-22.10-live-server-s390x.iso \ + -kernel ~/iso/boot/kernel.ubuntu \ + -initrd ~/iso/boot/initrd.ubuntu \ + -append 'autoinstall ds=nocloud-net;s=http://_gateway:3003/ console=ttysclp0' + +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 ``-no-reboot`` flag to ``kvm`` means +that ``kvm`` will exit when this happens. It should take about 5 minutes. + +Boot the installed system +========================= + +.. code-block:: bash + + kvm -no-reboot -name auto-inst-test -nographic -m 2048 \ + -drive file=disk-image.qcow2,format=qcow2,cache=none,if=virtio + +This will boot into the freshly installed system and you should be able to log +in as ``ubuntu/ubuntu``. + diff --git a/doc/howto/autoinstall-quickstart.rst b/doc/howto/autoinstall-quickstart.rst new file mode 100644 index 00000000..56abb7d1 --- /dev/null +++ b/doc/howto/autoinstall-quickstart.rst @@ -0,0 +1,183 @@ +.. _autoinstall_quickstart: + +Autoinstall quick start +*********************** + +The intent of this page is to provide simple instructions to perform an +autoinstall in a VM on your machine. + +This page assumes that you are willing to install the latest Ubuntu release +available i.e., 22.10 at the time of writing. For other releases, you would +need to substitute the name of the ISO image but the instructions should +otherwise remain the same. + +This page also assumes you are on the AMD64 architecture. There is a +:ref:`version for s390x` too. + +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 +installed. + +Download the ISO +---------------- + +Go to the `22.10 ISO download page`_ and download the latest Ubuntu 22.10 +live-server ISO. + +Mount the ISO +------------- + +.. code-block:: bash + + sudo mount -r ~/Downloads/ubuntu-22.10-live-server-amd64.iso /mnt + +Write your autoinstall config +----------------------------- + +This means creating cloud-init config as follows: + +.. code-block:: bash + + mkdir -p ~/www + cd ~/www + cat > user-data << 'EOF' + #cloud-config + autoinstall: + version: 1 + identity: + hostname: ubuntu-server + password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0" + username: ubuntu + EOF + touch meta-data + +The crypted password is just "ubuntu". + +Serve the cloud-init config over HTTP +------------------------------------- + +Leave this running in one terminal window: + +.. code-block:: bash + + cd ~/www + python3 -m http.server 3003 + +Create a target disk +-------------------- + +.. code-block:: + + truncate -s 10G image.img + +Run the install! +---------------- + +.. code-block:: bash + + kvm -no-reboot -m 2048 \ + -drive file=image.img,format=raw,cache=none,if=virtio \ + -cdrom ~/Downloads/ubuntu-22.10-live-server-amd64.iso \ + -kernel /mnt/casper/vmlinuz \ + -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 +``-no-reboot`` flag to ``kvm`` means that ``kvm`` will exit when this happens. +It should take about 5 minutes. + +Boot the installed system +------------------------- + +.. code-block:: bash + + kvm -no-reboot -m 2048 \ + -drive file=image.img,format=raw,cache=none,if=virtio + +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 +====================================================== + +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. + +Download the live-server ISO +---------------------------- + +Go to the `22.10 ISO download page`_ and download the latest Ubuntu 22.10 +live-server ISO. + +Create your user-data and meta-data files +----------------------------------------- + +.. code-block:: bash + + mkdir -p ~/cidata + cd ~/cidata + cat > user-data << 'EOF' + #cloud-config + autoinstall: + version: 1 + identity: + hostname: ubuntu-server + password: "$6$exDY1mhS4KUYCE/2$zmn9ToZwTKLhCw.b4/b.ZRTIZM30JZ4QrOQ2aOXJ8yk96xpcCof0kxKwuX1kqLG/ygbJ1f8wxED22bTL4F46P0" + username: ubuntu + EOF + touch meta-data + +The crypted password is just ``ubuntu``. + +Create an ISO to use as a cloud-init data source +------------------------------------------------ + +.. code-block:: bash + + sudo apt install cloud-image-utils + cloud-localds ~/seed.iso user-data meta-data + +Create a target disk +-------------------- + +.. code-block:: bash + + truncate -s 10G image.img + +Run the install! +---------------- + +.. code-block:: bash + + kvm -no-reboot -m 2048 \ + -drive file=image.img,format=raw,cache=none,if=virtio \ + -drive file=~/seed.iso,format=raw,cache=none,if=virtio \ + -cdrom ~/Downloads/ubuntu-22.10-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 +confirmation before touching the disk. + +The installer reboots at the end but the ``-no-reboot`` flag to ``kvm`` means +that ``kvm`` will exit when this happens. + +The whole process should take about 5 minutes. + +Boot the installed system +------------------------- + +.. code-block:: bash + + kvm -no-reboot -m 2048 \ + -drive file=image.img,format=raw,cache=none,if=virtio + +This will boot into the freshly installed system and you should be able to log +in as ``ubuntu/ubuntu``. + +.. LINKS + +.. _22.10 ISO download page: https://releases.ubuntu.com/22.10/ \ No newline at end of file diff --git a/doc/howto/index.rst b/doc/howto/index.rst index b3c0b857..f754bfe4 100644 --- a/doc/howto/index.rst +++ b/doc/howto/index.rst @@ -12,8 +12,20 @@ understand and adapt the steps to fit your specific requirements. ----- -How do I...? -============ +Getting started with Autoinstall +================================ .. toctree:: :maxdepth: 1 + + Autoinstall quick-start guide + Autoinstall quick-start guide for s390x + + +Found a problem? +================ + +.. toctree:: + :maxdepth: 1 + + report-bugs diff --git a/doc/howto/report-bugs.rst b/doc/howto/report-bugs.rst new file mode 100644 index 00000000..6bf7fa4d --- /dev/null +++ b/doc/howto/report-bugs.rst @@ -0,0 +1,58 @@ +.. _report-bugs: + +How to report a problem +*********************** + +We always hope, of course, that every install 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 +up to date as the installer changes. + +Update Subiquity +================ + +The first thing to do is to update your Subiquity snap. Not only because we +fix issues that cause failures over time but also because we've been working on +features to make failure reporting easier. + + + +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). + +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 +the error tracker are non-interactive and anonymous, so they are useful for +tracking which kinds of errors are affecting most users, but they do not give +us a way to ask you to help diagnose the failure. + +Create Launchpad bug report +=========================== + +You can create a Launchpad bug report, which lets us establish this kind +of two way communication, based on the contents of a crash report by using the +standard ``apport-cli`` tool that is part of Ubuntu. Copy the crash report to +another system, run: + +.. code-block:: bash + + apport-cli /path/to/report.crash + +and follow the prompts. + +You can also run ``apport-cli`` in the installer environment by switching to a +shell but ``apport`` won't be able to open a browser to allow you to complete +the report so you'll have to type the URL by hand on another machine. + +.. note:: + + Bugs for the Subiquity autoinstaller are `tracked in Launchpad `_. + + + diff --git a/doc/index.rst b/doc/index.rst index 489cbafa..4e194e4d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -76,6 +76,7 @@ constructive feedback. :hidden: :maxdepth: 2 + Introduction to Autoinstall tutorial/index howto/index reference/index diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/intro-to-autoinstall.rst similarity index 100% rename from doc/tutorial/intro-to-autoinstall.rst rename to doc/intro-to-autoinstall.rst diff --git a/doc/reference/autoinstall-reference.rst b/doc/reference/autoinstall-reference.rst index d6ac70cd..b5314bc5 100644 --- a/doc/reference/autoinstall-reference.rst +++ b/doc/reference/autoinstall-reference.rst @@ -3,184 +3,1013 @@ Autoinstall configuration reference manual ****************************************** -.. _ai-active-directory: +The autoinstall file is YAML. At top level it must be a mapping containing the +keys described in this document. Unrecognized keys are ignored. -active-directory -================ +.. _ai-schema: -stub - -.. _ai-apt: - -apt -======= - -stub - -.. _ai-codecs: - -codecs +Schema ====== -stub +Autoinstall configs are +:doc:`validated against a JSON schema` before they are +used. -.. _ai-debconf-selections: +.. _ai-command-lists: -debconf-selections -================== - -stub - -.. _ai-early-commands: - -early-commands -============== - -stub - -.. _ai-error-commands: - -error-commands -============== - -stub - -.. _ai-identity: - -identity -======== - -stub - -.. _ai-interactive-sections: - -interactive-sections -==================== - -stub - -.. _ai-kernel: - -kernel -====== - -stub - -.. _ai-keyboard: - -keyboard -======== - -stub - -.. _ai-late-commands: - -late-commands +Command lists ============= -stub +Several config 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 +it is ignored). -.. _ai-locale: +.. _ai-top-level-keys: -locale -====== - -stub - -.. _ai-network: - -network -======= - -stub - -.. _ai-oem: - -oem -=== - -stub - -.. _ai-packages: - -packages -======== - -stub - -.. _ai-proxy: - -proxy -===== - -stub - -.. _ai-refresh-installer: - -refresh-installer -================= - -stub - -.. _ai-reporting: - -reporting -========= - -stub - -.. _ai-shutdown: - -shutdown -======== - -stub - -.. _ai-snaps: - -snaps -===== - -stub - -.. _ai-ssh: - -ssh -=== - -stub - -.. _ai-storage: - -storage -======= - -stub - -.. _ai-ubuntu-pro: - -ubuntu-pro -========== - -stub - -.. _ai-updates: - -updates -======= - -stub - -.. _ai-user-data: - -user-data -========= - -stub +Top-level keys +============== .. _ai-version: version -======= +------- -stub +* **type:** integer +* **default:** no default + +A future-proofing config file version field. Currently this must be "1". + +.. _ai-interactive-sections: + +interactive-sections +-------------------- + +* **type:** list of strings +* **default:** [] + +A list of config keys to still show in the UI. So for example: + +.. code-block:: yaml + + version: 1 + interactive-sections: + - network + identity: + 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. + +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 +indicates if a given section can be interactive or not. + +If there are any interactive sections at all, the :ref:`ai-reporting` key is +ignored. + +.. _ai-early-commands: + +early-commands +-------------- + +* **type:** :ref:`command list` +* **default:** no commands +* **can be interactive:** no + +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 +provided) and the file will be re-read after the ``early-commands`` have run to +allow them to alter the config if necessary. + +.. _ai-locale: + +locale +------ + +* **type:** string +* **default:** ``en_US.UTF-8`` +* **can be interactive:** yes, always interactive if any section is + +The locale to configure for the installed system. + +.. _ai-refresh-installer: + +refresh-installer +----------------- + +* **type:** mapping +* **default:** see below +* **can be interactive:** yes + +Controls whether the installer updates to a new version available in the given +channel before continuing. + +The mapping contains keys: + +update +~~~~~~ + +* **type:** boolean +* **default:** ``false`` + +Whether to update or not. + +channel +~~~~~~~ + +* **type:** string +* **default:** ``"stable/ubuntu-$REL"`` + +The channel to check for updates. + +.. _ai-keyboard: + +keyboard +-------- + +* **type:** mapping, see below +* **default:** US English keyboard +* **can be interactive:** yes + +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` +configuration file. See +`its manual page `_ +for more details. + +The mapping contains keys: + +layout +~~~~~~ + +* **type:** string +* **default:** ``"us"`` + +Corresponds to the ``XKBLAYOUT`` setting. + +variant +~~~~~~~ + +* **type:** string +* **default:** ``""`` + +Corresponds to the ``XKBVARIANT`` setting. + +toggle +~~~~~~ + +* **type:** string or null +* **default:** ``null`` + +Corresponds to the value of ``grp:`` option from the ``XKBOPTIONS`` setting. +Acceptable values are (but note that the installer does not validate these): +``caps_toggle``, ``toggle``, ``rctrl_toggle``, ``rshift_toggle``, +``rwin_toggle``, ``menu_toggle``, ``alt_shift_toggle``, ``ctrl_shift_toggle``, +``ctrl_alt_toggle``, ``alt_caps_toggle``, ``lctrl_lshift_toggle``, +``lalt_toggle``, ``lctrl_toggle``, ``lshift_toggle``, ``lwin_toggle``, +``sclk_toggle`` + +The version of Subiquity released with 20.04 GA does not accept ``null`` for +this field due to a bug. + +.. _ai-source: + +source +------ + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** yes + +search_drivers +~~~~~~~~~~~~~~ + +* **type:** boolean +* **default:** ``true`` + +Whether the installer should search for available third-party drivers. When +set to ``false``, it disables the drivers :ref:`screen and section`. + +id +~~ + +* **type:** string +* **default:** identifier of the first available source. + +Identifier of the source to install (e.g., ``"ubuntu-server-minimal"``). + +.. _ai-network: + +network +------- + +* **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 +disables any interface that does not receive an address. + +For example, to run DHCPv6 on a particular NIC: + +.. code-block:: yaml + + network: + version: 2 + ethernets: + enp0s31f6: + dhcp6: true + +Note that because of a bug, the version of Subiquity released with 20.04 GA +forces you to write this with an extra ``network:`` key like so: + +.. code-block:: yaml + + network: + network: + version: 2 + ethernets: + enp0s31f6: + dhcp6: true + +Later versions support this syntax too for compatibility but if you can +assume a newer version you should use the former. + +.. _ai-proxy: + +proxy +----- + +* **type:** URL or ``null`` +* **default:** no proxy +* **can be interactive:** yes + +The proxy to configure both during installation and for ``apt`` and for +``snapd`` in the target system. + +.. _ai-apt: + +apt +--- + +* **type:** mapping +* **default:** see below +* **can be interactive:** yes + +APT configuration, used both during the install and once booted into the target +system. + +This section historically used the same format as curtin, +`which is documented here `_. +Nonetheless, some key differences with the format supported by curtin have been introduced: + +- 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 + when the ``primary`` section is wrapped in the ``mirror-selection`` section. + +- The ``fallback`` key controls what Subiquity should do if no primary mirror + is usable. + +- The ``geoip`` key controls whether a geoip lookup is done to determine the + correct country mirror. + +The default is: + +.. code-block:: yaml + + apt: + preserve_sources_list: false + mirror-selection: + primary: + - country-mirror + - arches: [i386, amd64] + uri: "http://archive.ubuntu.com/ubuntu" + - arches: [s390x, arm64, armhf, powerpc, ppc64el, riscv64] + uri: "http://ports.ubuntu.com/ubuntu-ports" + fallback: abort + geoip: true + + +mirror-selection +~~~~~~~~~~~~~~~~ + +if the ``primary`` section is contained within the ``mirror-selection`` +section, the automatic mirror selection is enabled. This is the default in new installations. + +primary (when placed inside the ``mirror-selection`` section): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* **type:** custom, see below + +In the new format, the ``primary`` section expects a list of mirrors, which +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" + * ``arches``: An optional list of architectures supported by the mirror. By + default, this list contains the current CPU architecture. + +fallback +~~~~~~~~ + +* **type:** string (enumeration) +* **default:** abort + +Controls what Subiquity should do if no primary mirror is usable. Supported +values are: + +* ``abort`` -> abort the installation +* ``offline-install`` -> revert to an offline installation +* ``continue-anyway`` -> attempt to install the system anyway (not recommended, + the installation will certainly fail) + +geoip +~~~~~ + +* **type:** boolean +* **default:** ``true`` + +If geoip is true and one of the candidate primary mirrors has the special +value ``country-mirror``, a request is made to ``https://geoip.ubuntu.com/lookup``. +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 +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. + +If you just want to specify a mirror, you can use a configuration like this: + +.. code-block:: yaml + + apt: + mirror-selection: + primary: + - uri: YOUR_MIRROR_GOES_HERE + - country-mirror + - uri: http://archive.ubuntu.com/ubuntu + +To add a ppa: + +.. code-block:: yaml + + apt: + sources: + curtin-ppa: + source: ppa:curtin-dev/test-archive + +.. _ai-storage: + +storage +------- + +* **type:** mapping, see below +* **default:** use "lvm" layout in a single disk system, no default in a + multiple disk system +* **can be interactive:** yes + +Storage configuration is a complex topic and the description of the desired +configuration in the autoinstall file can also be complex. The installer +supports "layouts"; simple ways of expressing common configurations. + +Supported layouts +~~~~~~~~~~~~~~~~~ + +The three supported layouts at the time of writing are "lvm", "direct", and "zfs". + +.. code-block:: yaml + + storage: + layout: + name: lvm + storage: + layout: + name: direct + storage: + layout: + name: zfs + + +By default these will install to the largest disk in a system, but you can +supply a match spec (see below) to indicate which disk to use: + +.. code-block:: yaml + + storage: + layout: + name: lvm + match: + serial: CT* + storage: + layout: + name: direct + match: + ssd: true + +.. note:: + Match spec -- using "``match: {}``" will match an arbitrary disk + +When using the "lvm" layout, LUKS encryption can be enabled by supplying a +password. + +.. code-block:: yaml + + storage: + layout: + name: lvm + password: LUKS_PASSPHRASE + + +The default is to use the ``lvm`` layout. + +Sizing-policy +~~~~~~~~~~~~~ + +The lvm layout will, by default, attempt to leave room for snapshots and +further expansion. A sizing-policy key may be supplied to control this +behavior. + +* **type:** string (enumeration) +* **default:** scaled + +Supported values are: + +* ``scaled`` -> adjust space allocated to the root LV based on space available + to the VG +* ``all`` -> allocate all remaining VG space to the root LV + +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 + +Example with no size scaling and a passphrase: + +.. code-block:: yaml + + storage: + layout: + name: lvm + sizing-policy: all + password: LUKS_PASSPHRASE + +Action-based config +~~~~~~~~~~~~~~~~~~~ + +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. + +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: + +.. code-block:: yaml + + storage: + swap: + size: 0 + config: + - type: disk + id: disk0 + serial: ADATA_SX8200PNP_XXXXXXXXXXX + - type: partition + ... + + +The extensions to the curtin syntax are around disk selection and +partition/logical volume sizing. + +Disk selection extensions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Curtin supported identifying disks by serial (e.g. +``Crucial_CT512MX100SSD1_14250C57FECE``) or by path (e.g. ``/dev/sdc``) and the +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 +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. + +A match spec supports the following keys: + +* ``model: foo``: matches a disk where ``ID_VENDOR=foo`` in udev, supporting + globbing +* ``path: foo``: matches a disk based on path (e.g. ``/dev/sdc``), supporting + globbing (the globbing support distinguishes this from specifying path: foo + directly in the disk action) +* ``id_path: foo``: matches a disk where ``ID_PATH=foo`` in udev, supporting + globbing +* ``devpath: foo``: matches a disk where ``DEVPATH=foo`` in udev, supporting + globbing +* ``serial: foo``: matches a disk where ``ID_SERIAL=foo`` in udev, supporting + globbing (the globbing support distinguishes this from specifying serial: foo + directly in the disk action) +* ``ssd: true|false``: matches a disk that is or is not an SSD (vs. a rotating + drive) +* ``size: largest|smallest``: take the largest or smallest disk rather than an + arbitrary one if there are multiple matches (support for ``smallest`` added + in version 20.06.1) + +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 +to not overwrite the installer itself! + +So for example, to match an arbitrary disk it is simply: + +.. code-block:: yaml + + - type: disk + id: disk0 + +To match the largest SSD: + +.. code-block:: yaml + + - type: disk + id: big-fast-disk + match: + ssd: true + size: largest + +To match a Seagate drive: + +.. code-block:: yaml + + - type: disk + id: data-disk + match: + model: Seagate + + +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: + +* You can specify the size using the "1G", "512M" syntax supported in the + installer UI. +* You can specify the size as a percentage of the containing disk (or RAID), + e.g. "50%". +* For the last partition specified for a particular device, you can specify + the size as "-1" to indicate that the partition should fill the remaining + space. + +.. code-block:: yaml + + - type: partition + id: boot-partition + device: root-disk + size: 10% + - type: partition + id: root-partition + size: 20G + - type: partition + id: data-partition + device: root-disk + size: -1 + +.. _ai-identity: + +identity +-------- + +* **type:** mapping, see below +* **default:** no default +* **can be interactive:** yes + +Configure the initial user for the system. This is the only config key that +must be present (unless the :ref:`user-data section ` is present, +in which case it is optional). + +A mapping that can contain keys, all of which take string values: + +realname +~~~~~~~~ + +The real name for the user. This field is optional. + +username +~~~~~~~~ + +The user name to create. + +hostname +~~~~~~~~ + +The hostname for the system. + +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 +`passwd `_ +expects. Depending on the special characters in the password hash, quoting may +be required, so it's safest to just always include the quotes around the hash. + +Several tools can generate the crypted password, such as ``mkpasswd`` from the +``whois`` package, or ``openssl passwd``. + +Example: + +.. code-block:: yaml + + identity: + realname: 'Ubuntu User' + username: ubuntu + password: '$6$wdAcoXrU039hKYPd$508Qvbe7ObUnxoj15DRCkzC3qO7edjH0VV7BPNRDYK4QR8ofJaEEF2heacn0QgD.f8pO8SNp83XNdWG6tocBM1' + hostname: ubuntu + +.. _ai-active-directory: + +active-directory +---------------- + +* **type:** mapping, see below +* **default:** no default +* **can be interactive:** yes + +Accepts data required to join the target system in an Active Directory domain. + +A mapping that can contain keys, all of which take string values: + +admin-name +~~~~~~~~~~ + +A domain account name with privilege to perform the join operation. That +account's password will be requested during runtime. + +domain-name +~~~~~~~~~~~ + +The Active Directory domain to join. + +.. _ai-ubuntu-pro: + +ubuntu-pro +---------- + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** yes + +token +~~~~~ + +* **type:** string +* **default:** no token + +A contract token to attach to an existing Ubuntu Pro subscription. + +.. _ai-ssh: + +ssh +--- + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** yes + +Configure SSH for the installed system. A mapping that can contain keys: + +install-server +~~~~~~~~~~~~~~ + +* **type:** boolean +* **default:** ``false`` + +Whether to install OpenSSH server in the target system. + +authorized-keys +~~~~~~~~~~~~~~~ + +* **type:** list of strings +* **default:** ``[]`` + +A list of SSH public keys to install in the initial user's account. + +allow-pw +~~~~~~~~ + +* **type:** boolean +* **default:** ``true`` if ``authorized_keys`` is empty, ``false`` otherwise + +.. _ai-codecs: + +codecs +------ + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** no + +Configure whether common restricted packages (including codecs) from +[multiverse] should be installed. + +install +~~~~~~~ + +* **type:** boolean +* **default:** ``false`` + +Whether to install the ubuntu-restricted-addons package. + +.. _ai-drivers: + +drivers +------- + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** yes + +install +~~~~~~~ + +* **type:** boolean +* **default:** ``false`` + +Whether to install the available third-party drivers. + +.. _ai-oem: + +oem +--- + +* **type:** mapping, see below +* **default:** see below +* **can be interactive:** no + +install +~~~~~~~ + +* **type:** boolean or string (special value ``auto``) +* **default:**: ``auto`` + +Whether to install the available OEM meta-packages. The special value ``auto`` +-- which is the default -- enables the installation on ubuntu-desktop but not +on ubuntu-server. This option has no effect on core boot classic. + +.. _ai-snaps: + +snaps +----- + +* **type:** list +* **default:** install no extra snaps +* **can be interactive:** yes + +A list of snaps to install. Each snap is represented as a mapping with required +``name`` and optional ``channel`` (defaulting to ``stable``) and classic +(defaulting to ``false``) keys. For example: + +.. code-block: yaml + + snaps: + - name: etcd + channel: edge + classic: false + +.. _ai-debconf-selections: + +debconf-selections +------------------ + +* **type:** string +* **default:** no config +* **can be interactive:** no + +The installer will update the target with debconf set-selection values. Users +will need to be familiar with the package debconf options. + +.. _ai-packages: + +packages +-------- + +* **type:** list +* **default:** no packages +* **can be interactive:** no + +A list of packages to install into the target system. More precisely, a list of +strings to pass to "``apt-get install``", so this includes things like task +selection (``dns-server^``) and installing particular versions of a package +(``my-package=1-1``). + +.. _ai-kernel: + +kernel +------ + +* **type:** mapping (mutually exclusive), see below +* **default:** default kernel +* **can be interactive:** no + +Which kernel gets installed. Either the name of the package or the name of the +flavor must be specified. + +package +~~~~~~~ + +**type:** string + +The name of the package, e.g., ``linux-image-5.13.0-40-generic`` + +flavor +~~~~~~ + +* **type:** string + +The flavor of the kernel, e.g., ``generic`` or ``hwe``. + +.. _ai-timezone: + +timezone +-------- + +* **type:** string +* **default:** no timezone +* **can be interactive:** no + +The timezone to configure on the system. The special value "geoip" can be used +to query the timezone automatically over the network. + +.. _ai-updates: + +updates +------- + +* **type:** string (enumeration) +* **default:** ``security`` +* **can be interactive:** no + +The type of updates that will be downloaded and installed after the system +install. Supported values are: + +* ``security`` -> download and install updates from the -security pocket +* ``all`` -> also download and install updates from the -updates pocket + +.. _ai-shutdown: + +shutdown +-------- + +* **type:** string (enumeration) +* **default:** ``reboot`` +* **can be interactive:** no + +Request the system to power off or reboot automatically after the installation +has finished. Supported values are: + +* ``reboot`` +* ``poweroff`` + +.. _ai-late-commands: + +late-commands +------------- + +* **type:** :ref:`command list` +* **default:** no commands +* **can be interactive:** no + +Shell commands to run after the install 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 +released with 20.04 GA you need to specify this as +``curtin in-target --target=/target -- $shell_command``) to run in the target +system (similar to how plain ``in-target`` can be used in +``d-i preseed/late_command``). + +.. _ai-error-commands: + +error-commands +-------------- + +* **type:** :ref:`command list` +* **default:** no commands +* **can be interactive:** no + +Shell commands to run after the install 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. + +.. _ai-reporting: + +reporting +--------- + +* **type:** mapping +* **default:** ``type: print`` which causes output on tty1 and any configured + serial consoles +* **can be interactive:** no + +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 +`that used by curtin `_. + +Each key in the ``reporting`` mapping in the config defines a destination, +where the ``type`` sub-key is one of: + +**The rsyslog reporter does not yet exist** + +* **print**: print progress information on tty1 and any configured serial + 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 + same `configuration as curtin `_. +* **none**: do not report progress. Only useful to inhibit the default output. + +Examples: + +The default configuration is: + +.. code-block:: yaml + + reporting: + builtin: + type: print + +Report to rsyslog: + +.. code-block:: yaml + + reporting: + central: + type: rsyslog + destination: @192.168.0.1 + + +Suppress the default output: + +.. code-block:: yaml + + reporting: + builtin: + type: none + +Report to a curtin-style webhook: + +.. code-block:: yaml + + reporting: + hook: + type: webhook + endpoint: http://example.com/endpoint/path + consumer_key: "ck_foo" + consumer_secret: "cs_foo" + token_key: "tk_foo" + token_secret: "tk_secret" + level: INFO + + +.. _ai-user-data: + +user-data +--------- + +* **type:** mapping +* **default:** ``{}`` +* **can be interactive:** no + +Provide cloud-init user data which will be merged with the user data the +installer produces. If you supply this, you don't need to supply an +:ref:`identity section ` (but then it's your responsibility to +make sure that you can log into the installed system!). diff --git a/doc/reference/autoinstall-schema.rst b/doc/reference/autoinstall-schema.rst new file mode 100644 index 00000000..1b8bf0a9 --- /dev/null +++ b/doc/reference/autoinstall-schema.rst @@ -0,0 +1,589 @@ +.. _autoinstall_schema: + +Autoinstall schema +****************** + +The server installer validates the provided autoinstall config against a +:ref:`JSON schema`. + +How the config 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 +happens instead is that some sections are loaded, validated, and applied +first, before all other sections are validated. In detail: + +1. The reporting section is loaded, validated and applied. +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. + +This is so that validation errors in most sections can be reported via the +reporting and error-commands configuration, as all other errors are. + +.. _autoinstall_JSON_schema: + +Schema +====== + +The `JSON schema`_ for autoinstall data is as follows: + +.. code-block:: JSON + + "type": "object", + "properties": { + "version": { + "type": "integer", + "minimum": 1, + "maximum": 1 + }, + "early-commands": { + "type": "array", + "items": { + "type": [ + "string", + "array" + ], + "items": { + "type": "string" + } + } + }, + "reporting": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "type": { + "type": "string" + } + }, + "required": [ + "type" + ], + "additionalProperties": true + } + }, + "error-commands": { + "type": "array", + "items": { + "type": [ + "string", + "array" + ], + "items": { + "type": "string" + } + } + }, + "user-data": { + "type": "object" + }, + "packages": { + "type": "array", + "items": { + "type": "string" + } + }, + "debconf-selections": { + "type": "string" + }, + "locale": { + "type": "string" + }, + "refresh-installer": { + "type": "object", + "properties": { + "update": { + "type": "boolean" + }, + "channel": { + "type": "string" + } + }, + "additionalProperties": false + }, + "kernel": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "flavor": { + "type": "string" + } + }, + "oneOf": [ + { + "type": "object", + "required": [ + "package" + ] + }, + { + "type": "object", + "required": [ + "flavor" + ] + } + ] + }, + "keyboard": { + "type": "object", + "properties": { + "layout": { + "type": "string" + }, + "variant": { + "type": "string" + }, + "toggle": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "layout" + ], + "additionalProperties": false + }, + "source": { + "type": "object", + "properties": { + "search_drivers": { + "type": "boolean" + }, + "id": { + "type": "string" + } + } + }, + "network": { + "oneOf": [ + { + "type": "object", + "properties": { + "version": { + "type": "integer", + "minimum": 2, + "maximum": 2 + }, + "ethernets": { + "type": "object", + "properties": { + "match": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "macaddress": { + "type": "string" + }, + "driver": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "wifis": { + "type": "object", + "properties": { + "match": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "macaddress": { + "type": "string" + }, + "driver": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "bridges": { + "type": "object" + }, + "bonds": { + "type": "object" + }, + "tunnels": { + "type": "object" + }, + "vlans": { + "type": "object" + } + }, + "required": [ + "version" + ] + }, + { + "type": "object", + "properties": { + "network": { + "type": "object", + "properties": { + "version": { + "type": "integer", + "minimum": 2, + "maximum": 2 + }, + "ethernets": { + "type": "object", + "properties": { + "match": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "macaddress": { + "type": "string" + }, + "driver": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "wifis": { + "type": "object", + "properties": { + "match": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "macaddress": { + "type": "string" + }, + "driver": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "bridges": { + "type": "object" + }, + "bonds": { + "type": "object" + }, + "tunnels": { + "type": "object" + }, + "vlans": { + "type": "object" + } + }, + "required": [ + "version" + ] + } + }, + "required": [ + "network" + ] + } + ] + }, + "ubuntu-pro": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 24, + "maxLength": 30, + "pattern": "^C[1-9A-HJ-NP-Za-km-z]+$", + "description": "A valid token starts with a C and is followed by 23 to 29 Base58 characters.\nSee https://pkg.go.dev/github.com/btcsuite/btcutil/base58#CheckEncode" + } + } + }, + "ubuntu-advantage": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 24, + "maxLength": 30, + "pattern": "^C[1-9A-HJ-NP-Za-km-z]+$", + "description": "A valid token starts with a C and is followed by 23 to 29 Base58 characters.\nSee https://pkg.go.dev/github.com/btcsuite/btcutil/base58#CheckEncode" + } + }, + "deprecated": true, + "description": "Compatibility only - use ubuntu-pro instead" + }, + "proxy": { + "type": [ + "string", + "null" + ], + "format": "uri" + }, + "apt": { + "type": "object", + "properties": { + "preserve_sources_list": { + "type": "boolean" + }, + "primary": { + "type": "array" + }, + "mirror-selection": { + "type": "object", + "properties": { + "primary": { + "type": "array", + "items": { + "anyOf": [ + { + "type": "string", + "const": "country-mirror" + }, + { + "type": "object", + "properties": { + "uri": { + "type": "string" + }, + "arches": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "uri" + ] + } + ] + } + } + } + }, + "geoip": { + "type": "boolean" + }, + "sources": { + "type": "object" + }, + "disable_components": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "universe", + "multiverse", + "restricted", + "contrib", + "non-free" + ] + } + }, + "preferences": { + "type": "array", + "items": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "pin": { + "type": "string" + }, + "pin-priority": { + "type": "integer" + } + }, + "required": [ + "package", + "pin", + "pin-priority" + ] + } + }, + "fallback": { + "type": "string", + "enum": [ + "abort", + "continue-anyway", + "offline-install" + ] + } + } + }, + "storage": { + "type": "object" + }, + "identity": { + "type": "object", + "properties": { + "realname": { + "type": "string" + }, + "username": { + "type": "string" + }, + "hostname": { + "type": "string" + }, + "password": { + "type": "string" + } + }, + "required": [ + "username", + "hostname", + "password" + ], + "additionalProperties": false + }, + "ssh": { + "type": "object", + "properties": { + "install-server": { + "type": "boolean" + }, + "authorized-keys": { + "type": "array", + "items": { + "type": "string" + } + }, + "allow-pw": { + "type": "boolean" + } + } + }, + "snaps": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "channel": { + "type": "string" + }, + "classic": { + "type": "boolean" + } + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "active-directory": { + "type": "object", + "properties": { + "admin-name": { + "type": "string" + }, + "domain-name": { + "type": "string" + } + }, + "additionalProperties": false + }, + "codecs": { + "type": "object", + "properties": { + "install": { + "type": "boolean" + } + } + }, + "drivers": { + "type": "object", + "properties": { + "install": { + "type": "boolean" + } + } + }, + "oem": { + "type": "object", + "properties": { + "install": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "const": "auto" + } + ] + } + }, + "required": [ + "install" + ] + }, + "timezone": { + "type": "string" + }, + "updates": { + "type": "string", + "enum": [ + "security", + "all" + ] + }, + "late-commands": { + "type": "array", + "items": { + "type": [ + "string", + "array" + ], + "items": { + "type": "string" + } + } + }, + "shutdown": { + "type": "string", + "enum": [ + "reboot", + "poweroff" + ] + } + }, + "required": [ + "version" + ], + "additionalProperties": true + } + +Regeneration +============ + +The schema above can be regenerated by running ``make schema`` in a Subiquity +source checkout. + +.. LINKS + +.. _JSON schema: https://json-schema.org/ diff --git a/doc/reference/index.rst b/doc/reference/index.rst index ab5afb94..fc2a0d87 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -5,16 +5,13 @@ Our reference section contains support information for Subiquity. This includes details on the network requirements, API definitions, support matrices and so on. +----- + Autoinstall reference manual ============================ - .. toctree:: :maxdepth: 1 - autoinstall-reference.rst - ------ - -.. toctree:: - :maxdepth: 1 + Autoinstall configuration + Autoinstall JSON schema diff --git a/doc/tutorial/basic-server-installation.rst b/doc/tutorial/basic-server-installation.rst new file mode 100644 index 00000000..19c657c3 --- /dev/null +++ b/doc/tutorial/basic-server-installation.rst @@ -0,0 +1,123 @@ +Basic server installation +************************* + +This chapter provides an overview of how to install Ubuntu Server Edition. You +can also refer to this guide on +:ref:`how to operate the installer ` for more +information on using the installer, and to this +:doc:`screen-by-screen reference guide ` for more +information about each of the installer screens. + +Preparing to install +==================== + +This section explains various aspects to consider before starting the +installation. + +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, +etc. This version supports four 64-bit architectures: + +* amd64 (Intel/AMD 64-bit) +* arm64 (64-bit ARM) +* ppc64el (POWER8 and POWER9) +* s390x (IBM Z and LinuxONE) + +The recommended system requirements are: + +* CPU: 1 gigahertz or better +* RAM: 1 gigabyte or more +* Disk: a minimum of 2.5 gigabytes + +Perform a system back up +------------------------ + +Before installing Ubuntu Server Edition you should make sure all data on the +system is backed up. + +If this is not the first time an operating system has been installed on your +computer, it is likely you will need to re-partition your disk to make room +for Ubuntu. + +Any time you partition your disk, you should be prepared to lose everything on +the disk should you make a mistake or something goes wrong during partitioning. +The programs used in installation are quite reliable, most have seen years of +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" +download. Note that the server download includes the installer. + +There are platform-specific how-to guides for installations on: + +* `s390x LPAR `_ +* `z/VM `_ +* `ppc64el `_ + +Create a bootable USB +--------------------- + +There are many ways to boot the installer but the simplest and most common way +is to +`create a bootable USB stick `_ +to boot the system to be installed with +(`tutorials for other operating systems `_ +are also available). + +Perform the installation +======================== + +Now that you have prepared your install medium, you are ready to install. + +Boot the installer +------------------ + +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. + +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. + +If you are still having problems, check out the +`Ubuntu Community documentation on booting from +CD/DVD `_. + +After a few moments, the installer will start in its language selection screen. + +.. image:: figures/basic-installation-start-screen.png + :alt: Welcome screen of the Server installer showing the language selection options + +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: + +* 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 +* 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 +* Select restart when this is complete, and log in using the username and + password provided diff --git a/doc/tutorial/figures/basic-installation-start-screen.png b/doc/tutorial/figures/basic-installation-start-screen.png new file mode 100644 index 00000000..845d68d2 Binary files /dev/null and b/doc/tutorial/figures/basic-installation-start-screen.png differ diff --git a/doc/tutorial/figures/sbs-complete.png b/doc/tutorial/figures/sbs-complete.png new file mode 100644 index 00000000..12577b33 Binary files /dev/null and b/doc/tutorial/figures/sbs-complete.png differ diff --git a/doc/tutorial/figures/sbs-confirm-storage.png b/doc/tutorial/figures/sbs-confirm-storage.png new file mode 100644 index 00000000..8eb6cec6 Binary files /dev/null and b/doc/tutorial/figures/sbs-confirm-storage.png differ diff --git a/doc/tutorial/figures/sbs-identity.png b/doc/tutorial/figures/sbs-identity.png new file mode 100644 index 00000000..40d85c8b Binary files /dev/null and b/doc/tutorial/figures/sbs-identity.png differ diff --git a/doc/tutorial/figures/sbs-keyboard.png b/doc/tutorial/figures/sbs-keyboard.png new file mode 100644 index 00000000..2686cca5 Binary files /dev/null and b/doc/tutorial/figures/sbs-keyboard.png differ diff --git a/doc/tutorial/figures/sbs-language.png b/doc/tutorial/figures/sbs-language.png new file mode 100644 index 00000000..845d68d2 Binary files /dev/null and b/doc/tutorial/figures/sbs-language.png differ diff --git a/doc/tutorial/figures/sbs-logs.png b/doc/tutorial/figures/sbs-logs.png new file mode 100644 index 00000000..a19fc530 Binary files /dev/null and b/doc/tutorial/figures/sbs-logs.png differ diff --git a/doc/tutorial/figures/sbs-mirror.png b/doc/tutorial/figures/sbs-mirror.png new file mode 100644 index 00000000..f635521d Binary files /dev/null and b/doc/tutorial/figures/sbs-mirror.png differ diff --git a/doc/tutorial/figures/sbs-network.png b/doc/tutorial/figures/sbs-network.png new file mode 100644 index 00000000..6d915b5a Binary files /dev/null and b/doc/tutorial/figures/sbs-network.png differ diff --git a/doc/tutorial/figures/sbs-proxy.png b/doc/tutorial/figures/sbs-proxy.png new file mode 100644 index 00000000..769659c0 Binary files /dev/null and b/doc/tutorial/figures/sbs-proxy.png differ diff --git a/doc/tutorial/figures/sbs-refresh.png b/doc/tutorial/figures/sbs-refresh.png new file mode 100644 index 00000000..f63bf93a Binary files /dev/null and b/doc/tutorial/figures/sbs-refresh.png differ diff --git a/doc/tutorial/figures/sbs-snaps.png b/doc/tutorial/figures/sbs-snaps.png new file mode 100644 index 00000000..d2ee4842 Binary files /dev/null and b/doc/tutorial/figures/sbs-snaps.png differ diff --git a/doc/tutorial/figures/sbs-ssh.png b/doc/tutorial/figures/sbs-ssh.png new file mode 100644 index 00000000..cf7ffa6e Binary files /dev/null and b/doc/tutorial/figures/sbs-ssh.png differ diff --git a/doc/tutorial/figures/sbs-storage.png b/doc/tutorial/figures/sbs-storage.png new file mode 100644 index 00000000..44956b1b Binary files /dev/null and b/doc/tutorial/figures/sbs-storage.png differ diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index faefeab3..08cd5074 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -11,8 +11,8 @@ capable of. ----- -Introduction to autoinstall -=========================== +For Ubuntu Server +================= This tutorial introduces the core concepts of autoinstall and is recommended as the first step. @@ -20,4 +20,6 @@ the first step. .. toctree:: :maxdepth: 1 - intro-to-autoinstall.rst + basic-server-installation + screen-by-screen + diff --git a/doc/tutorial/screen-by-screen.rst b/doc/tutorial/screen-by-screen.rst new file mode 100644 index 00000000..4afdf9e1 --- /dev/null +++ b/doc/tutorial/screen-by-screen.rst @@ -0,0 +1,174 @@ +Screen-by-screen installer +************************** + +The installer is designed to be easy to use without documentation. However, +this guide provides more information on each of the screens of the installer to +help walk you through an installation. + +Language selection +================== + +.. image:: figures/sbs-language.png + :alt: + +This screen selects the language for the installer and the default language +for the installed system. + +More languages can be displayed if you +`connect via SSH `_. + +Refresh +======= + +.. image:: figures/sbs-refresh.png + :alt: + +This screen is shown if there is an update available for the installer. This +allows you to get any improvements and bug fixes made since release. + +If you choose to update, the new version will be downloaded and the installer +will restart at the same point of the installation. + +Keyboard +======== + +.. image:: figures/sbs-keyboard.png + :alt: + +Choose the layout and variant of keyboard attached to the system, if any. When +running in a virtual terminal, it is possible to guess the layout and variant +by answering questions about the keyboard. + +Zdev (s390x only) +================= + +.. code-block:: + + ==================================================================== + Zdev setup + ==================================================================== + ID ONLINE NAMES ^ + │ + generic-ccw │ + 0.0.0009 > │ + 0.0.000c > │ + 0.0.000d > │ + 0.0.000e > │ + │ + dasd-eckd │ + 0.0.0190 > │ + 0.0.0191 > │ + 0.0.019d > │ + 0.0.019e >┌────────────┐ + 0.0.0200 >│< (close) │ + 0.0.0300 >│ Enable │ + 0.0.0400 >│ Disable │ + 0.0.0592 >└────────────┘ v + + [ Continue ] + [ Back ] + + +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. + +Network +======= + +.. image:: figures/sbs-network.png + :alt: + +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. + +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 +installation. + +Proxy +===== + +.. image:: figures/sbs-proxy.png + :alt: + +The proxy configured on this screen is used for accessing the package +repository and the snap store both in the installer environment and in the +installed system. + +Mirror +====== + +.. image:: figures/sbs-mirror.png + :alt: + +The installer will attempt to use ``geoip`` to look up an appropriate default +package mirror for your location. If you want or need to use a different +mirror, enter its URL here. + +Storage +======= + +.. image:: figures/sbs-storage.png + :alt: + +Storage configuration is a complicated topic and :ref:`has its own page for documentation `. + +.. image:: figures/sbs-confirm-storage.png + :alt: + +Once the storage configuration is confirmed, the install begins in the +background. + +Identity +======== + +.. image:: figures/sbs-identity.png + :alt: + +The default user will be an administrator, able to use ``sudo`` (this is why a +password is needed, even if SSH public key access is enabled on the next +screen). + +SSH +=== + +.. image:: figures/sbs-ssh.png + :alt: + +A default Ubuntu install 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. + +You can import keys for the default user from GitHub or Launchpad. + +If you import a key, then password authentication is disabled by default but it +can be re-enabled again at a later time if you wish. + +Snaps +===== + +.. image:: figures/sbs-snaps.png + :alt: + +If a network connection is enabled, a selection of snaps that are useful in a +server environment are presented and can be selected for installation. + +Installation logs +================= + +.. image:: figures/sbs-logs.png + :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 +security updates installed, the installer waits for confirmation before +restarting. + +.. image:: figures/sbs-complete.png + :alt: +