The NoCloud seed

user-data + meta-data for contributors

For each system make writes a user-data file from the picked template and a two-line meta-data file, packs both with xorriso into a seed ISO labelled cidata, and attaches it as a read-only CD-ROM to the provisioning boot only.

On the map: first boot

▶ Watch this deck — 7 scenes, ~5 min

Worth seeing first

01 A disk that tells the image who it is

THE SEED the downloaded cloud image host name? users? what to run? a cloud's metadata service none on your own machine cloud-init, NoCloud a disk labelled cidata user-data meta-data image-garden makes that disk, a small ISO, for every system it builds
A downloaded Ubuntu 24.04 cloud image asks for its host name, users and commands; on your own machine there is no cloud to answer; cloud-init's NoCloud data source reads a disk labelled cidata holding user-data and meta-data instead, and image-garden makes that seed ISO for every system it builds

A cloud image expects a cloud to configure it. cloud-init's NoCloud data source reads a disk labelled cidata instead, and image-garden makes one for every system.

Boot ubuntu-cloud-24.04.x86_64 straight from the download and it waits for a cloud to tell it who it is: its host name, its users, what to run. On your own machine there's no cloud to ask. cloud-init has an answer for that, the NoCloud data source. It looks for a disk labelled cidata with two files on it, user-data and meta-data, and reads them as if a cloud had sent them. image-garden makes exactly that disk, a small ISO image, for every system it builds. This deck follows it from the two files to the one boot that reads it.

Details and sources

Details

  • The seed ISO is made from the user-data and meta-data files with xorriso -as genisoimage -volid cidata (010-qemu.mk:263-279).
  • Every system from data/*.ini gets a meta-data and a user-data rule (rulegen.py:461-471); the image rule takes the seed as its second prerequisite and boots with it (rulegen.py:601-609).
  • The user-data limits cloud-init to the NoCloud data source for any later run: datasource_list: [NoCloud] in /etc/cloud/cloud.cfg.d/99-image-garden.cfg (010-qemu.mk:221-230).
  • Derived from cloud-init's behaviour, not from image-garden: NoCloud finds its data on a filesystem labelled cidata holding files named user-data and meta-data.

02 Two files, each from a template for contributors

TWO FILES the meta-data template ubuntu, 24.04 ubuntu-cloud-24.04.x86_64.meta-data the picked template ubuntu-cloud-24.04.x86_64.user-data the most specific one defined ubuntu, ubuntu, 24.04 group, user, release echo "$${USER_DATA}" | tee $@ so the whole file is in the build log both depend on the make files the user-data also on .image-garden.mk: an edit writes it again
The meta-data template, expanded with the group ubuntu and the release 24.04, becomes ubuntu-cloud-24.04.x86_64.meta-data; the picked user-data template, expanded with ubuntu, ubuntu and 24.04, becomes the .user-data file; the recipe echoes each through tee into the build log; both depend on the make files and the user-data also on .image-garden.mk

X.meta-data comes from the meta-data template with group and release; X.user-data from the picked template with group, user name and release. Both are echoed through tee, so they appear in the build log.

Both files are written by make, and each comes from a template. For the meta-data, make expands the meta-data template with two values: the group, ubuntu, and the release, 24.04. For the user-data, it first picks a template, the most specific one defined, then expands it with three: the group, a user name, which is the group again, and the release. The text lands in an exported variable, and the recipe echoes it into the file through tee, so the whole user-data shows up in the build log. Both files depend on the make files, and the user-data also on your .image-garden.mk, so an edit there writes it again.

Details and sources

Details

  • The generated rules for a system from data/*.ini: X.meta-data: export META_DATA = $(call CLOUD_INIT_META_DATA_TEMPLATE,{img.group},{img.release}) and X.user-data: export USER_DATA = $(call $(call PICK_CLOUD_INIT_USER_DATA_TEMPLATE_FOR,{img.group.name_upper},{img.release}),{img.group},{img.group},{img.release}); each recipe runs echo "$${…}" | tee $@, then touch --reference= the newest prerequisite (rulegen.py:461-471).
  • The meta-data depends on $(MAKEFILE_LIST); the user-data on $(MAKEFILE_LIST) and $(wildcard $(GARDEN_PROJECT_DIR)/.image-garden.mk) (rulegen.py:462, rulegen.py:468).
  • A named instance passes its base system's group and release and its instance name to the meta-data template, and the instance name as a fourth argument to the user-data template (020-instances.mk:67-79).
  • The second argument is the name of the user the template creates; for every system it is the group (010-qemu.mk:205-211).
  • The picker is PICK_CLOUD_INIT_USER_DATA_TEMPLATE_FOR (010-qemu.mk:293-298); see how a template is chosen.

03 The meta-data is two lines

META-DATA ubuntu-cloud-24.04.x86_64.meta-data instance-id: iid-ubuntu-24-04 local-hostname: ubuntu-24-04 group and release, joined by dashes: ubuntu and 24.04, the dot becomes a dash ubuntu-cloud-24.04@webserver ubuntu-24-04-webserver an instance adds its name ubuntu-core-24+tpm ubuntu-core-24-tpm a plus becomes a dash ubuntu-cloud-24.04.x86_64.user-data hostname: ubuntu-24-04 127.0.0.1 ubuntu-24-04 the same name, made the same way appended to /etc/hosts one name for the guest, whichever file cloud-init reads it from
The meta-data of ubuntu-cloud-24.04.x86_64 is instance-id: iid-ubuntu-24-04 and local-hostname: ubuntu-24-04, made from the group and the release with the dot turned into a dash. The instance ubuntu-cloud-24.04@webserver is called ubuntu-24-04-webserver, and ubuntu-core-24+tpm is called ubuntu-core-24-tpm. The user-data sets hostname: ubuntu-24-04 and maps it to 127.0.0.1 in /etc/hosts, so the guest has one name in both files.

instance-id: iid-ubuntu-24-04 and local-hostname: ubuntu-24-04: group, release and instance, with dots and pluses turned into dashes. The user-data's hostname is the same name.

The meta-data is short: two lines. For our system they set instance-id to iid-ubuntu-24-04, and local-hostname to ubuntu-24-04. That name is built from the group and the release, with the dot turned into a dash, because a host name can't have a dot inside one of its parts. A named instance adds its own name, so the webserver instance is ubuntu-24-04-webserver. A plus becomes a dash too: ubuntu-core-24+tpm is called ubuntu-core-24-tpm. The user-data builds the same name the same way, for its hostname line, and maps it to 127.0.0.1 in the hosts file. So whichever file cloud-init takes the name from, the guest gets the same one.

Details and sources

Details

  • The meta-data template is #cloud-config, instance-id: iid-$(call CLOUD_INIT_HOSTNAME,…) and local-hostname: $(call CLOUD_INIT_HOSTNAME,…), called with the group, the release and, for a named instance, the instance name (010-qemu.mk:99-106).
  • CLOUD_INIT_HOSTNAME joins group, release and instance with dashes and turns dots and pluses into dashes, "not allowed in a host name label" (010-qemu.mk:94-97).
  • The callers: a system from data/*.ini passes {img.group},{img.release} (rulegen.py:461), a named instance its base system's group and release and its own name (020-instances.mk:68), and Ubuntu Core ubuntu-core and the release with its modifiers, such as 24+tpm (050-ubuntu-core.mk:111, :121).
  • The user-data's hostname: and the 127.0.0.1 line of /root/hosts.APPEND use the same function with the same values (010-qemu.mk:196, 010-qemu.mk:231-235); the first runcmd command appends that line to /etc/hosts (010-qemu.mk:238-240). The Ubuntu Core template's hostname: does the same (050-ubuntu-core.mk:141).
  • Run for this deck, with GARDEN_ARCH=x86_64 in a scratch project that defines the webserver instance: image-garden make wrote iid-ubuntu-24-04/ubuntu-24-04, iid-ubuntu-24-04-webserver/ubuntu-24-04-webserver, iid-ubuntu-core-24-tpm/ubuntu-core-24-tpm and, for Gentoo, which has no release, iid-gentoo/gentoo; the user-data hostname: lines matched.
  • Derived from cloud-init's behaviour: NoCloud reads instance-id and local-hostname from the meta-data, and a hostname: in the user-data sets the host name; here both say the same.

04 What the user-data holds

THE USER-DATA ubuntu-cloud-24.04.x86_64.user-data timezone: Europe/Warsaw power_state: poweroff, delay now hostname: ubuntu-24-04 Provisioning runs once the previous scene ssh_pwauth: true $(call EXTRA_CLOUD_INIT_APT_CONFIG,…) $(call PKGPROXY_CLOUD_INIT_BOOTCMD,…) SSH logins and apt sources Changing what cloud-init does What pkgproxy adds to user-data users: root, ubuntu The users every system gets write_files: sshd, cloud.cfg.d, hosts SSH logins and apt sources runcmd: … touch cloud-init.disabled Provisioning runs once each part has its own deck
The common user-data template from top to bottom: timezone, power_state, hostname, ssh_pwauth, the apt and pkgproxy hooks, users root and ubuntu, write_files with an SSH snippet, a cloud-init config and a hosts line, and runcmd ending with touching cloud-init.disabled; each part points to the deck that explains it

The common template, top to bottom: time zone, power_state, hostname, ssh_pwauth, the apt and pkgproxy hooks, users, write_files and runcmd.

The user-data is longer, and it's worth seeing whole once. From the top: the Warsaw time zone, then a power state that turns the machine off when cloud-init is done, and the host name. Password logins for SSH come next, then two hooks, one for apt settings and one for pkgproxy's early setup. Then the users, root and ubuntu. A few files follow: an SSH snippet, a cloud-init config and a hosts line. Last comes a list of commands that put those files in place, switch apt sources to plain http, and disable cloud-init. Each part has its own deck, and the drawing shows which.

Details and sources

Details

  • The common template, BASE_CLOUD_INIT_USER_DATA_TEMPLATE (010-qemu.mk:187-247), in order: timezone: Europe/Warsaw (189), power_state (190-195), hostname (196), ssh_pwauth: true (197), the EXTRA_CLOUD_INIT_APT_CONFIG hook (198), pkgproxy's bootcmd (199), users (200-211), write_files (212-237, ending with pkgproxy's injected files and the EXTRA_CLOUD_INIT_FILES hook), runcmd (238-246).
  • The apt hook is empty unless something defines it; image-garden itself defines it for end-of-life Ubuntu releases (050-ubuntu.mk:26-28). pkgproxy's bootcmd and runcmd parts are empty when no pkgproxy is reachable from the guest (010-qemu.mk:156-185).
  • The apt command rewrites https:// to http:// in every *.list and *.sources file under /etc/apt (010-qemu.mk:244); see SSH logins and apt sources.
  • The panel shortens the YAML: power_state also sets message, timeout: 0 and condition: true; users is a list of two maps.
  • The full template is in this deck's reference below.

05 Packing the two files into an ISO

THE SEED ISO $ xorriso -as genisoimage -input-charset utf-8 \ -volid cidata \ lower case: 2014 to 2025 cidata -joliet -rock -graft-points \ names kept as they are user-data=ubuntu-cloud-24.04.x86_64.user-data \ meta-data=ubuntu-cloud-24.04.x86_64.meta-data ubuntu-cloud-24.04.x86_64.user-data ubuntu-cloud-24.04.x86_64.meta-data user-data meta-data -output ubuntu-cloud-24.04.x86_64.seed.iso \ ubuntu-cloud-24.04.x86_64.seed.iso
xorriso in genisoimage mode packs ubuntu-cloud-24.04.x86_64.user-data and .meta-data into an ISO with the volume label cidata and Joliet and Rock Ridge names; graft points store them as plain user-data and meta-data; the output is ubuntu-cloud-24.04.x86_64.seed.iso

xorriso -as genisoimage -volid cidata -joliet -rock -graft-points user-data=X.user-data meta-data=X.meta-data writes X.seed.iso.

Both files go into one small ISO image, made by xorriso pretending to be genisoimage. The volume label is cidata, in lower case, and the comment beside the rule says that works on systems from 2014 and from 2025 alike. Joliet and Rock Ridge extensions keep the file names as they are. The neat part is graft points. On disk, each file's name starts with the whole system name, but cloud-init wants them called just user-data and meta-data. So the command grafts each fixed name in the ISO onto the file on disk. Out comes the seed, one per system, next to the image it will prepare.

Details and sources

Details

  • The rule %.seed.iso: %.user-data %.meta-data runs $(XORRISO) -as genisoimage -input-charset utf-8 -output $@ -volid cidata -joliet -rock -graft-points user-data=$(word 1,$^) meta-data=$(word 2,$^) (010-qemu.mk:268-278).
  • The comment above it: "-graft-points allows us to have different (fixed) name in the ISO and different (variable) names in the local file system", and the label "cidata", lowercase, "works across both 2014-era and 2025-era systems" (010-qemu.mk:263-267).
  • XORRISO defaults to xorriso on the PATH, and make stops with "program xorriso is required" without it (000-garden.mk:20).
  • clean removes *.seed.iso, *.meta-data and *.user-data (010-qemu.mk:300-302).
  • Compatibility links without the architecture (X.seed.iso to X.ARCH.seed.iso, and the same for user-data and meta-data) remain for projects that used the names of image-garden 0.3 and 0.4 (010-qemu.mk:251-261).
  • Derived: -joliet and -rock add the Joliet and Rock Ridge extensions, which keep long, lowercase file names that plain ISO 9660 would not.

06 Attached to one boot only

ONE BOOT the provisioning boot, run by make QEMU the overlay, .qcow2 ubuntu-cloud-24.04.x86_64.seed.iso raw · read-only · media=cdrom · virtio-blk cloud-init reads it, powers off every later boot: the .run script QEMU the overlay, .qcow2 the seed: just a file user-data changed: a new seed, prepared again
In the provisioning boot, QEMU gets the overlay and the seed ISO as a raw, read-only CD-ROM on virtio-blk; cloud-init reads it and powers off; every later boot through the .run script attaches only the overlay, so the seed is just a file; a changed user-data makes a new seed and a new provisioning boot

The provisioning boot adds -drive file=X.seed.iso,format=raw,readonly=true,media=cdrom on virtio-blk. The .run script never attaches the seed.

The seed is used exactly once. The rule that makes the prepared image lists it as a prerequisite, creates the overlay, then boots QEMU with the seed as a second drive: raw, read-only, marked as a CD-ROM, on a virtio block device. cloud-init finds the cidata label, reads both files, does its work and powers the machine off. The .run script you get afterwards has no such drive. It boots the overlay and nothing else, so the seed is just a file on disk from then on. Change the user-data, though, and make writes a new seed and prepares the image again.

Details and sources

Details

  • For an x86_64 EFI system the image rule is X.qcow2: <download> X.seed.iso X.efi-code.qcow2 X.efi-vars.qcow2; it runs qemu-img create -f qcow2 -b <download> -F qcow2 X.qcow2 64G, then the QEMU command line with -drive file=X.seed.iso,format=raw,id=drive1,if=none,readonly=true,media=cdrom -device virtio-blk,drive=drive1, piped through tee X.qcow2.log (rulegen.py:601-609). The BIOS and other architectures' rules attach the seed the same way.
  • The .run script's storage option is only the overlay: -drive file=X.qcow2,…,media=disk … -device virtio-blk,drive=drive0,bootindex=0 (010-qemu-x86_64.mk:59-108).
  • The Ubuntu Core systems attach the same drive as a SCSI CD-ROM on virtio-scsi-pci instead (050-ubuntu-core.mk:37-53); see Ubuntu Core images.
  • A changed user-data is newer than the seed, and the seed newer than X.qcow2, so make remakes both: see an edit rebuilds the images.

07 Where to go from here

ROADS The NoCloud seed Provisioning runs once what the boot does The users root and ubuntu SSH and apt logins, NoCloud, http Picking a template to change the user-data Per-distribution quirks Amazon Linux 2, Gentoo, old Ubuntu
Roads from this deck: provisioning runs once, the users every system gets, SSH logins and apt sources, how a user-data template is chosen, and what differs per distribution

Next: what the provisioning boot does, the users, SSH and apt, how a template is chosen, and the per-distribution quirks.

Two files from templates, packed into a disk labelled cidata, read in one boot. What that boot does with them has its own deck, and so does each big part of the user-data: the two users, and the SSH, cloud-init and apt changes. If you want to change the user-data, start with how a template is chosen. A few distributions get a different template, and the quirks deck says which and why. The full common template is in the reference below the deck.

Details and sources

Read more

Basis of the statements on this page

Read in mk/010-qemu.mk, mk/020-instances.mk, mk/050-ubuntu-core.mk, rulegen.py and data/*.ini of image-garden at the commit this map describes ("code"). The meta-data and host names in the table were produced by running image-garden make for those systems from an export of that commit, with GARDEN_ARCH=x86_64 and a project that defines the webserver instance ("run"). How cloud-init reads a NoCloud seed is cloud-init's behaviour, not image-garden's ("derived").

Files per system

FileMade byContents
X.meta-dataecho through tee (rulegen.py:461-465)the meta-data template with group and release
X.user-dataecho through tee (rulegen.py:467-471)the picked user-data template with group, user name and release
X.seed.isoxorriso -as genisoimage … -volid cidata (010-qemu.mk:268-278)user-data and meta-data
X.seed.iso, X.user-data, X.meta-data without the architectureln -sf (010-qemu.mk:251-261)links kept for the names of image-garden 0.3 and 0.4

X is the system name with its architecture, such as ubuntu-cloud-24.04.x86_64. The seed is attached only to the provisioning boot (rulegen.py:601-609).

Values for a few systems

Systeminstance-idlocal-hostname and user-data hostnameuser
ubuntu-cloud-24.04.x86_64iid-ubuntu-24-04ubuntu-24-04ubuntu
debian-cloud-13.x86_64iid-debian-13debian-13debian
fedora-cloud-42.x86_64iid-fedora-42fedora-42fedora
gentoo-cloud.x86_64 (no release)iid-gentoogentoogentoo
ubuntu-cloud-24.04@webserver.x86_64iid-ubuntu-24-04-webserverubuntu-24-04-webserverubuntu
ubuntu-core-24+tpm.x86_64iid-ubuntu-core-24-tpmubuntu-core-24-tpmubuntu

The meta-data template

From 010-qemu.mk:94-106; $1 is the group, $2 the release and $3 a named instance's name. CLOUD_INIT_HOSTNAME makes the same name for the user-data:

CLOUD_INIT_HOSTNAME = $(subst +,-,$(subst .,-,$(strip $1$(if $(value 2),-$(value 2))$(if $(value 3),-$(value 3)))))

#cloud-config
instance-id: iid-$(call CLOUD_INIT_HOSTNAME,$1,$(value 2),$(value 3))
local-hostname: $(call CLOUD_INIT_HOSTNAME,$1,$(value 2),$(value 3))

CLOUD_INIT_META_DATA_TEMPLATE is set to it and may be redefined in .image-garden.mk.

The common user-data template

BASE_CLOUD_INIT_USER_DATA_TEMPLATE, from 010-qemu.mk:187-247. $1 is the group, $2 the user name (the group again), $(value 3) the release and $(value 4) a named instance:

#cloud-config
timezone: Europe/Warsaw
power_state:
  delay: now
  mode: poweroff
  message: Powering off
  timeout: 0
  condition: true
hostname: $(call CLOUD_INIT_HOSTNAME,$1,$(value 3),$(value 4))
ssh_pwauth: true
$(call EXTRA_CLOUD_INIT_APT_CONFIG,$1,$(value 3))
$(call PKGPROXY_CLOUD_INIT_BOOTCMD,$1)
users:
- name: root
  plain_text_passwd: root
  lock_passwd: false
  shell: /bin/bash
- name: $2
  groups: users
  gecos: $2 User
  plain_text_passwd: $2
  sudo: ["ALL=(ALL) NOPASSWD:ALL"]
  lock_passwd: false
  shell: /bin/bash
write_files:
# Use /root/foo.APPEND in case /etc is a read-only fs.
- path: /root/sshd_config.APPEND
  permissions: '0600'
  content: |
    # image-garden: allow interactive login with password authentication.
    UsePam yes
    # image-garden: allow root to log in over ssh.
    PermitRootLogin yes
- path: /etc/cloud/cloud.cfg.d/99-image-garden.cfg
  permissions: '0600'
  content: |
    # image-garden: allow interactive login with password authentication.
    # Use only none and no-cloud data sources to avoid probing cloud-specific
    # network services.
    ssh_pwauth: true
    # Instruct cloud-init not to look for cloud APIs.
    datasource_list:
    - NoCloud
- path: /root/hosts.APPEND
  permissions: '0644'
  content: |
    # image-garden: ensure hostname resolves to localhost
    127.0.0.1 $(call CLOUD_INIT_HOSTNAME,$1,$(value 3),$(value 4))
$(INJECTED_CLOUD_INIT_FILES)
$(call EXTRA_CLOUD_INIT_FILES,$1,$(value 3))
runcmd:
- cat /root/hosts.APPEND >> /etc/hosts
- rm -f /root/hosts.APPEND
- cat /root/sshd_config.APPEND >> /etc/ssh/sshd_config
- rm /root/sshd_config.APPEND
- sed -i -e 's/^PermitRootLogin prohibit-password/#PermitRootLogin prohibit-password/' /etc/ssh/sshd_config || true
- if [ -d /etc/apt ]; then find /etc/apt -type f \( -name '*.list' -o -name '*.sources' \) -exec sed -i -e 's|https://|http://|g' {} \; ; fi
$(call PKGPROXY_CLOUD_INIT_RUNCMD,$1)
- touch /etc/cloud/cloud-init.disabled
PartDeck
power_state, touch /etc/cloud/cloud-init.disabledProvisioning runs once
usersThe users every system gets
ssh_pwauth, sshd_config.APPEND, 99-image-garden.cfg, the apt sedSSH logins and apt sources
EXTRA_CLOUD_INIT_APT_CONFIG, EXTRA_CLOUD_INIT_FILESChanging what cloud-init does
PKGPROXY_CLOUD_INIT_BOOTCMD, INJECTED_CLOUD_INIT_FILES, PKGPROXY_CLOUD_INIT_RUNCMDWhat pkgproxy adds to user-data
replaced for Amazon Linux 2, Gentoo; apt hook for old UbuntuWhat differs per distribution
replaced for Ubuntu CoreUbuntu Core images

Roads from here

RUNTIME · make rules and the CLI

FIRST BOOT · cloud-init changes