From b94abacdfb1694e10e766a612473424f47815c62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Fri, 8 Mar 2024 17:06:36 +0100 Subject: [PATCH] ubuntu-image docs fixes & updates. --- doc/.custom_wordlist.txt | 1 + doc/reference/ubuntu-image.rst | 193 +++++++++++++-------------------- 2 files changed, 78 insertions(+), 116 deletions(-) diff --git a/doc/.custom_wordlist.txt b/doc/.custom_wordlist.txt index c9df0e694..9a01c2840 100644 --- a/doc/.custom_wordlist.txt +++ b/doc/.custom_wordlist.txt @@ -77,6 +77,7 @@ realname rootfs rsyslog runtime +snapd subvolume subvolumes superset diff --git a/doc/reference/ubuntu-image.rst b/doc/reference/ubuntu-image.rst index 33faa43d3..5d0221d79 100644 --- a/doc/reference/ubuntu-image.rst +++ b/doc/reference/ubuntu-image.rst @@ -4,16 +4,37 @@ ubuntu-image syntax and options ``ubuntu-image`` is a program for generating bootable disk images. It supports building snap_-based and classical preinstalled Ubuntu images. +Installing ``ubuntu-image`` +--------------------------- + +The ``ubuntu-image`` tool is distributed as a snap package through the Snap Store: `ubuntu-image `_. Install it either from a Snap-enabled software store provided by your distribution, or by running this command with ``sudo`` or as the ``root`` user: + +.. code-block:: + + snap install ubuntu-image --classic + +Note that you need have the snap daemon installed. See `Installing the daemon `_ for instructions for your distribution. + + Snap-based images ----------------- -Snap-based images are built from a *model assertion*, which is a YAML file describing a particular combination of core, kernel, and gadget snaps, along with other declarations, signed with a digital signature asserting its authenticity. The assets defined in the model assertion uniquely describe the device for which the image is built. +Snap-based images are built from a *model assertion*, which is a YAML file describing a particular combination of core, kernel, and gadget snaps, along with other declarations, signed with a digital signature asserting its authenticity. The assets defined in the model assertion uniquely describe the device for which the image is built. See `model assertion`_ for details. Classical images ---------------- -Classical images are built from a local `gadget tree`_ path. The `gadget tree`_ is a primed `gadget snap`_ containing a ``gadget.yaml`` file in the ``meta`` directory and all the necessary bootloader gadget bits built. For instance, a `gadget tree`_ can be prepared by fetching a specially tailored `gadget snap`_ source and running ``snapcraft prime`` on it, with the resulting tree being stored in the ``prime/`` directory. +Classical images are built from an image-definition YAML file, which defines the image content and resulting output format. Key elements of this configuration are the following sections: + +``gadget`` + Defines how to get the gadget required to build boot assets and the partition layout. + +``rootfs`` + Defines the parameters to build the content of the rootfs. + +``artifacts`` + Defines the types of artefacts to create, including the actual images, manifest files, and others. The ``gadget.yaml`` file @@ -27,12 +48,14 @@ As part of the model assertion, a `gadget snap`_ is specified. The gadget conta * Whether the volume contains a bootloader and if so, what kind of bootloader. -Note that ``ubuntu-image`` communicates with the Snap Store using the ``snap prepare-image`` sub-command. The model-assertion file is passed to ``snap prepare-image``, which handles downloading the appropriate gadget and any extra snaps. See the :manualpage:`snap(8) manual page ` for additional details. +Note that ``ubuntu-image`` communicates with the Snap Store using the ``Prepare()`` function from the snapd library. The model-assertion file is passed to the function, which handles downloading the appropriate gadget and any extra snaps. Basic syntax ------------ +The ``ubuntu-image`` tool requires administrative privileges. Run it with ``sudo`` or as the ``root`` user. Note that the tool does not check whether it's executed with sufficient rights or not. + .. code-block:: yaml ubuntu-image snap [options] model.assertion @@ -51,6 +74,50 @@ General options Show the program version number and exit. +Common options +~~~~~~~~~~~~~~ + +There are two general operational modes to ``ubuntu-image``. The usual mode is to run the tool giving the required model-assertion file as a required positional argument, generating a disk image file. These options are useful in this mode of operation. + +The second mode of operation is provided for debugging and testing purposes. It allows you to run the internal state machine step by step and is described in more detail below. + +-d, --debug + Enable debugging output. + +--verbose + Enable verbose output. + +--quiet + Only print error messages. Suppress all other output. + +-O DIRECTORY, --output-dir DIRECTORY + Write generated disk-image files to this directory. The files will be named after the ``gadget.yaml`` volume names, with the ``.img`` suffix appended. If not given, the value of the ``--workdir`` flag is used if specified. If neither ``--output-dir`` nor ``--workdir`` is used, the image(s) will be placed in the current working directory. This option replaces, and cannot be used with, the deprecated ``--output`` option. + +-w DIRECTORY, --workdir DIRECTORY + The working directory in which to download and unpack all the source files for the image. This directory can exist or not, and it is not removed after this program exits. If not given, a temporary working directory is used instead, which *is* deleted after this program exits. Use ``--workdir`` if you want to be able to resume a partial state-machine run. The ``gadget.yaml`` file is copied to the working directory after it's downloaded. + +-i SIZE, --image-size SIZE + The size of the generated disk-image files. If this size is smaller than the minimum calculated size of the volume, a warning is issued and ``--image-size`` is ignored. The value is the size in bytes, with allowable suffixes ``M`` for MiB and ``G`` for GiB. + + An extended syntax is supported for ``gadget.yaml`` files that specify multiple volumes (i.e. disk images). In that case, a single ``SIZE`` argument is used for all the defined volumes, with the same rules for ignoring values that are too small. You can specify the image size for a single volume using an indexing prefix on the ``SIZE`` parameter, where the index is either a volume name or an integer index starting at zero. For example, to set the image size only on the second volume, which might be called ``sdcard`` in ``gadget.yaml``, use: ``--image-size 1:8G`` (the number ``1`` index indicates the second volume; volumes are 0-indexed). Or use ``--image-size sdcard:8G``. + + You can also specify multiple volume sizes by separating them with commas, and you can mix and match integer indices and volume-name indices. Thus, if ``gadget.yaml`` names three volumes, and you want to set all three to different sizes, you can use ``--image-size 0:2G,sdcard:8G,eMMC:4G``. + + In the case of ambiguities, the size hint is ignored, and the calculated size for the volume is used instead. + +--disk-info DISK-INFO-CONTENTS + File to be used as ``.disk/info`` on the root file system of the image. This file can contain useful information about the target image, such as image identification data, system name, build timestamp, etc. + +-c CHANNEL, --channel CHANNEL + The default Snap channel to use while preseeding the image. + +--sector-size SIZE + When creating the disk-image file, use the given sector size. This can be either 512 or 4096 (4k sector size), defaulting to 512. + +--validation= + Controls whether validations should be ignored or enforced. + + Options of the ``snap`` command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -68,11 +135,8 @@ These are the options for defining the contents of snap-based images. They can --factory-image Hint that the image is meant to boot in a device factory. ---validation= - Control whether validations should be ignored or enforced. - ---snap SNAP - Install an extra snap. This is passed through to ``snap prepare-image``. The snap argument can include additional information about the channel and/or risk with the following syntax: ``=``. Note that this flag will cause an error if the model assertion has a grade higher than dangerous. +--snap + Install an extra snap or snaps. The snap argument can include additional information about the channel or risk with the following syntax: ``=``. Note that this flag causes an error if the model assertion has a grade higher than dangerous. --revision Install a specific revision of a snap rather than the latest available in a particular channel. The snap specified with ``SNAP_NAME`` must be included either in the model assertion or as an argument to ``--snap``. If both a revision and channel are provided, the revision specified is installed in the image, and updates come from the specified channel. @@ -95,44 +159,6 @@ These are the options for defining the contents of classical preinstalled Ubuntu Path to the image-definition file. This file defines all of the customisation required when building the image. This positional argument must be given for this mode of operation. -Common options -~~~~~~~~~~~~~~ - -There are two general operational modes to ``ubuntu-image``. The usual mode is to run the script giving the required model-assertion file as a required positional argument, generating a disk image file. These options are useful in this mode of operation. - -The second mode of operation is provided for debugging and testing purposes. It allows you to run the internal state machine step by step and is described in more detail below. - --d, --debug - Enable debugging output. - ---verbose - Enable verbose output. - ---quiet - Only print error messages. Suppress all other output. - --O DIRECTORY, --output-dir DIRECTORY - Write generated disk-image files to this directory. The files will be named after the ``gadget.yaml`` volume names, with the ``.img`` suffix appended. If not given, the value of the ``--workdir`` flag is used if specified. If neither ``--output-dir`` nor ``--workdir`` is used, the image(s) will be placed in the current working directory. This option replaces, and cannot be used with, the deprecated ``--output`` option. - --i SIZE, --image-size SIZE - The size of the generated disk-image files. If this size is smaller than the minimum calculated size of the volume, a warning is issued and ``--image-size`` is ignored. The value is the size in bytes, with allowable suffixes ``M`` for MiB and ``G`` for GiB. - - An extended syntax is supported for ``gadget.yaml`` files that specify multiple volumes (i.e. disk images). In that case, a single ``SIZE`` argument is used for all the defined volumes, with the same rules for ignoring values that are too small. You can specify the image size for a single volume using an indexing prefix on the ``SIZE`` parameter, where the index is either a volume name or an integer index starting at zero. For example, to set the image size only on the second volume, which might be called ``sdcard`` in ``gadget.yaml``, use: ``--image-size 1:8G`` (the number ``1`` index indicates the second volume; volumes are 0-indexed). Or use ``--image-size sdcard:8G``. - - You can also specify multiple volume sizes by separating them with commas, and you can mix and match integer indices and volume-name indices. Thus, if ``gadget.yaml`` names three volumes, and you want to set all three to different sizes, you can use ``--image-size 0:2G,sdcard:8G,eMMC:4G``. - - In the case of ambiguities, the size hint is ignored, and the calculated size for the volume is used instead. - ---disk-info DISK-INFO-CONTENTS - File to be used as ``.disk/info`` on the root file system of the image. This file can contain useful information about the target image, such as image identification data, system name, build timestamp, etc. - --c CHANNEL, --channel CHANNEL - The default Snap channel to use while preseeding the image. - ---sector-size SIZE - When creating the disk-image file, use the given sector size. This can be either 512 or 4096 (4k sector size), defaulting to 512. - - State-machine options ~~~~~~~~~~~~~~~~~~~~~ @@ -140,14 +166,11 @@ State-machine options ``ubuntu-image`` internally runs a state machine to create the disk image. These are some options for controlling this state machine. Other than ``--workdir``, these options are mutually exclusive. When ``--until`` or ``--thru`` is given, the state machine can be resumed later with ``--resume``, but ``--workdir`` must be given in that case since the state is saved in a ``ubuntu-image.json`` file in the working directory. --w DIRECTORY, --workdir DIRECTORY - The working directory in which to download and unpack all the source files for the image. This directory can exist or not, and it is not removed after this program exits. If not given, a temporary working directory is used instead, which *is* deleted after this program exits. Use ``--workdir`` if you want to be able to resume a partial state-machine run. The ``gadget.yaml`` file is copied to the working directory after it's downloaded. - -u STEP, --until STEP - Run the state machine until the given ``STEP``, non-inclusively. ``STEP`` is the name of a state-machine method. See the `List of steps`_. + Run the state machine until the given ``STEP``, non-inclusively. ``STEP`` is the name of a state-machine method. -t STEP, --thru STEP - Run the state machine until the given ``STEP``, inclusively. ``STEP`` is the name of a state-machine method. See the `List of steps`_. + Run the state machine until the given ``STEP``, inclusively. ``STEP`` is the name of a state-machine method. -r, --resume Continue the state machine from the previously saved state. It returns an error if there is no previous state. @@ -162,76 +185,14 @@ Files used by ``ubuntu-image`` * `cloud-config`_ -Environment variables ---------------------- +Environment variable +-------------------- -The following environment variables are recognised by ``ubuntu-image``. +The following environment variable is recognised by ``ubuntu-image``. ``UBUNTU_IMAGE_PRESERVE_UNPACK`` When set, the variable specifies the directory for preserving a pristine copy of the unpacked gadget contents. The directory must exist, and an ``unpack`` directory will be created under this directory. The full contents of the ``/unpack`` directory after the ``snap prepare-image`` sub-command has run is copied here. -There are a few other environment variables used for building and testing only. - - -.. _list of steps: - -List of steps -------------- - -The names of steps that can be used with ``--until`` and ``--thru`` for each image type are listed below. - -Classical-image steps -~~~~~~~~~~~~~~~~~~~~~ - -State machines are dynamically created for classical-image builds based on the contents of the image definition. The list of all possible states is as follows: - -#. ``make_temporary_directories`` -#. ``parse_image_definition`` -#. ``calculate_states`` -#. ``build_gadget_tree`` -#. ``prepare_gadget_tree`` -#. ``load_gadget_yaml`` -#. ``create_chroot`` -#. ``germinate`` -#. ``add_extra_ppas`` -#. ``install_packages`` -#. ``clean_extra_ppas`` -#. ``verify_artifact_names`` -#. ``customize_cloud_init`` -#. ``customize_fstab`` -#. ``manual_customization`` -#. ``preseed_image`` -#. ``clean_rootfs`` -#. ``populate_rootfs_contents`` -#. ``generate_disk_info`` -#. ``calculate_rootfs_size`` -#. ``populate_bootfs_contents`` -#. ``populate_prepare_partitions`` -#. ``make_disk`` -#. ``generate_package_manifest`` - -To check the steps that are going to be used for a specific image-definition file, use the ``--print-states`` flag. - -Snap-image steps -~~~~~~~~~~~~~~~~ - -#. ``make_temporary_directories`` -#. ``prepare_image`` -#. ``load_gadget_yaml`` -#. ``populate_rootfs_contents`` -#. ``generate_disk_info`` -#. ``calculate_rootfs_size`` -#. ``populate_bootfs_contents`` -#. ``populate_prepare_partitions`` -#. ``make_disk`` -#. ``generate_snap_manifest`` - - -Additional resources --------------------- - -* :manualpage:`snap(8) manual page ` - .. |gadgetyaml| replace:: ``gadget.yaml``