Ubuntu Manpage: ubuntu-image - Generate a bootable disk image

Provided by: ubuntu-image_2.2+22.04ubuntu3_amd64

NAME

       ubuntu-image - Generate a bootable disk image

SYNOPSIS

       ubuntu-image snap [options] model.assertion

       ubuntu-image classic [options] GADGET_TREE_URI

DESCRIPTION

ubuntu-image is a program for generating a variety of bootable disk images. It currently
supports building snap based and classic preinstalled Ubuntu 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.

As part of the model assertion, a gadget snap is specified. The gadget contains a
gadget.yaml file which contains the exact description of the disk image's contents, in
YAML format. The gadget.yaml file describes such things as the names of all the volumes
to be produced [1], the structures [2] within the volume, whether the volume contains a
bootloader and if so what kind of bootloader, etc.

Note that ubuntu-image communicates with the snap store using the snap prepare-image
subcommand. The model assertion file is passed to snap prepare-image which handles
downloading the appropriate gadget and any extra snaps. See that command's documentation
for additional details.

Classic images are built from a local gadget tree path. The gadget tree is nothing more
than 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 easily prepared
by fetching a specially tailored gadget snap source and running snapcraft prime on it,
with the resulting tree ending up in the prime/ directory.

The actual rootfs for a classic image is created by live-build with arguments passed as
per the optional arguments to ubuntu-image. The livecd-rootfs configuration from the host
system is used.

OPTIONS

-h, --help
Show the program's message and exit.

--version
Show the program's version number and exit.

Snap command options
These are the options for defining the contents of snap-based images. Can only be used
when the ubuntu-image snap command is used.

model_assertion
Path to the model assertion file. This positional argument must be given for this
mode of operation.

--cloud-init USER-DATA-FILE
cloud-config data to be copied to the image.

--disable-console-conf
Disable console-conf on the resulting image.

--factory-image
Hint that the image is meant to boot in a device factory.

--validation=<ignore|enforce>
Control whether validations should be ignored or enforced.

Classic command options
These are the options for defining the contents of classic preinstalled Ubuntu images.
Can only be used when the ubuntu-image classic command is used.

GADGET_TREE_URI
An URI to the gadget tree to be used to build the image. This positional argument
must be given for this mode of operation. Must be a local path.

-p PROJECT, --project PROJECT
Project name to be passed on to livecd-rootfs. Mutually exclusive with --filesystem

-f FILESYSTEM, --filesystem FILESYSTEM
Unpacked Ubuntu filesystem to be copied to the system partition. Mutually
exclusive with --project.

-s SUITE, --suite SUITE
Distribution name to be passed on to livecd-rootfs.

-a CPU-ARCHITECTURE, --arch CPU-ARCHITECTURE
CPU architecture to be passed on to livecd-rootfs. Default value is the
architecture of the host.

--subproject SUBPROJECT
Sub-project name to be passed on livecd-rootfs.

--subarch SUBARCH
Sub-architecture to be passed on to livecd-rootfs.

--with-proposed
Defines if the image should be built with -proposed enabled. This is passed
through to livecd-rootfs.

--extra-ppas EXTRA_PPAS
Extra ppas to install. This is passed through to livecd-rootfs.

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.

-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 .img suffix appended. If not given, the current
working directory is used. 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 will be issued and --image-size
will be 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 which specify multiple
volumes (i.e. disk images). In that case, a single SIZE argument will be used for
all the defined volumes, with the same rules for ignoring values which 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 the gadget.yaml, you could use: --image-size 1:8G
since the 1-th index names the second volume (volumes are 0-indexed). Or you could
use --image-size sdcard:8G.

You can also specify multiple volume sizes by separating them with commas, and you
can mix and match integer indexes and volume name indexes. Thus, if the
gadget.yaml named three volumes, and you wanted to set all three to different
sizes, you could 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 will be used instead.

--image-file-list FILENAME
Print to FILENAME, a list of the file system paths to all the disk images created
by the command, if any.

--hooks-directory DIRECTORY
Directories in which scripts for build-time hooks will be located. This flag must
be specified once for each hook directory. ubuntu-image will look for hooks in
hooks_directory/name_of_hooks_step.d and a script with the name
hooks_directory/name_of_hooks_step. Currently the only supported hooks step is
populate_rootfs_contents.

--disk-info DISK-INFO-CONTENTS
File to be used as .disk/info on the image's rootfs. This file can contain useful
information about the target image, like image identification data, system name,
build timestamp etc.

--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: <snap>=<channel|risk>

-c CHANNEL, --channel CHANNEL
The snap channel to use.

--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
CAUTION!:
The options described here are primarily for debugging and testing purposes and should
not be considered part of the stable, public API. State machine step numbers and names
can change between releases.

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.pck 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. As an added bonus, 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. The list of all steps can be found in the STEPS section of
this document.

-t STEP, --thru STEP
Run the state machine through the given STEP, inclusively. STEP is the name of a
state machine method. The list of all steps can be found in the STEPS section of
this document.

-r, --resume
Continue the state machine from the previously saved state. It is an error if
there is no previous state.

FILES

       gadget.yaml
              https://github.com/snapcore/snapd/wiki/Gadget-snap#gadget.yaml

       model assertion
              https://developer.ubuntu.com/en/snappy/guides/prepare-image/

       gadget tree (example)
              https://github.com/snapcore/pc-amd64-gadget

       cloud-config
              https://help.ubuntu.com/community/CloudInit

ENVIRONMENT

       The following environment variables are recognized by ubuntu-image.

       UBUNTU_IMAGE_PRESERVE_UNPACK
              When set, this names a 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  <workdir>/unpack  directory  after
              the snap prepare-image subcommand has run will be copied here.

       UBUNTU_IMAGE_LIVECD_ROOTFS_AUTO_PATH
              ubuntu-image  uses  livecd-rootfs  configuration files for its live-build runs.  If
              this variable is set, ubuntu-image  will  use  the  configuration  files  from  the
              selected  path  for  its auto configuration.  Otherwise it will attempt to localize
              livecd-rootfs through a call to dpkg.

       UBUNTU_IMAGE_QEMU_USER_STATIC_PATH
              In  case  of  classic  image  cross-compilation  for  a   different   architecture,
              ubuntu-image will attempt to use the qemu-user-static emulator with live-build.  If
              set, ubuntu-image will use the selected path for the cross-compilation.   Otherwise
              it will attempt to find a matching emulator binary in the current $PATH.

       There are a few other environment variables used for building and testing only.

HOOKS

       During  image  build  at  certain  stages of the build process the user can execute custom
       scripts modifying its contents or otherwise affecting the process itself.  Whenever a hook
       is  to  be fired, the directories as listed in the --hooks-directory parameter are scanned
       for matching scripts.  There can be multiple scripts for a  specific  hook  defined.   The
       HookManager  will  first  look  for executable files in <hookdir>/<name-of-the-hook>.d and
       execute them in an alphanumerical order.  Finally the <hookdir>/<name-of-the-hook> file is
       executed if existing.

       Hook  scripts  can  have  various  additional  data  passed  onto them through environment
       variables depending on the hook being fired.

       Currently supported hooks:

       post-populate-rootfs
              Executed  after  the  rootfs  directory  has  been   populated,   allowing   custom
              modification  of  its  contents.   Added  in  version  1.2.   Environment variables
              present:

                 UBUNTU_IMAGE_HOOK_ROOTFS
                        Includes the absolute path to the rootfs contents.

STEPS

       The names of steps that can be used with --until and --thru for each image type are listed
       below

   Classic image steps
       1.  make_temporary_directories

       2.  prepare_gadget_tree

       3.  run_live_build

       4.  load_gadget_yaml

       5.  populate_rootfs_contents

       6.  populate_rootfs_contents_hooks

       7.  generate_disk_info

       8.  calculate_rootfs_size

       9.  populate_bootfs_contents

       10. populate_prepare_partitions

       11. make_disk

       12. generate_manifest

       13. finish

   Snap image steps
       1.  make_temporary_directories

       2.  prepare_image

       3.  load_gadget_yaml

       4.  populate_rootfs_contents

       5.  populate_rootfs_contents_hooks

       6.  generate_disk_info

       7.  calculate_rootfs_size

       8.  populate_bootfs_contents

       9.  populate_prepare_partitions

       10. make_disk

       11. generate_manifest

       12. finish

NOTES

       Sometimes,  for  various reasons, ubuntu-image may perform specific workarounds that might
       require some explanation to understand the reasoning behind them.

   Classic swapfile manual unsparsing
       When building a classic image, if ubuntu-image notices the existence of a /swapfile on the
       image's  rootfs,  it will proactively attempt to unsparse it.  The reason for that is that
       ubuntu-image assumes that the /swapfile file will be used as  a  swapfile  on  the  target
       system,  and  due to undocumented behavior of mkfs.ext4 -d large empty files are converted
       into sparse files automatically during filesystem population.  This essentially makes such
       files  unusable  as  swapfiles.  So just in case, ubuntu-image does an in-place dd call of
       the hard-coded path swapfile to ensure it's no longer sparse.

FOOTNOTES

       [1]  Volumes are roughly analogous to disk images.

       [2]  Structures define the  layout  of  the  volume,  including  partitions,  Master  Boot
            Records, or any other relevant content.

AUTHOR

       Barry  Warsaw  <barry@ubuntu.com>,  Łukasz  'sil2100'  Zemczak <lukasz.zemczak@ubuntu.com>
       William 'jawn-smith' Wilson <william.wilson@canonical.com>

COPYRIGHT

       2016-2021 Canonical Ltd.