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
- From a system's name to a running VM — the overlay and the one provisioning boot the seed is made for
01 A disk that tells the image who it is
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/*.inigets 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
cidataholding files nameduser-dataandmeta-data.
02 Two files, each from a template for contributors
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})andX.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 runsecho "$${…}" | tee $@, thentouch --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.
Read more
03 The meta-data is two lines
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,…)andlocal-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_HOSTNAMEjoins 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/*.inipasses{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 Coreubuntu-coreand the release with its modifiers, such as24+tpm(050-ubuntu-core.mk:111, :121). - The user-data's
hostname:and the127.0.0.1line of/root/hosts.APPENDuse the same function with the same values (010-qemu.mk:196, 010-qemu.mk:231-235); the firstruncmdcommand appends that line to/etc/hosts(010-qemu.mk:238-240). The Ubuntu Core template'shostname:does the same (050-ubuntu-core.mk:141). - Run for this deck, with
GARDEN_ARCH=x86_64in a scratch project that defines thewebserverinstance:image-garden makewroteiid-ubuntu-24-04/ubuntu-24-04,iid-ubuntu-24-04-webserver/ubuntu-24-04-webserver,iid-ubuntu-core-24-tpm/ubuntu-core-24-tpmand, for Gentoo, which has no release,iid-gentoo/gentoo; the user-datahostname:lines matched. - Derived from cloud-init's behaviour: NoCloud reads
instance-idandlocal-hostnamefrom the meta-data, and ahostname:in the user-data sets the host name; here both say the same.
Read more
04 What the user-data holds
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), theEXTRA_CLOUD_INIT_APT_CONFIGhook (198), pkgproxy'sbootcmd(199),users(200-211),write_files(212-237, ending with pkgproxy's injected files and theEXTRA_CLOUD_INIT_FILEShook),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
bootcmdandruncmdparts are empty when no pkgproxy is reachable from the guest (010-qemu.mk:156-185). - The apt command rewrites
https://tohttp://in every*.listand*.sourcesfile under/etc/apt(010-qemu.mk:244); see SSH logins and apt sources. - The panel shortens the YAML:
power_statealso setsmessage,timeout: 0andcondition: true;usersis a list of two maps. - The full template is in this deck's reference below.
05 Packing the two files into an 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-dataruns$(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).
XORRISOdefaults toxorrisoon thePATH, and make stops with "program xorriso is required" without it (000-garden.mk:20).cleanremoves*.seed.iso,*.meta-dataand*.user-data(010-qemu.mk:300-302).- Compatibility links without the architecture (
X.seed.isotoX.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:
-jolietand-rockadd the Joliet and Rock Ridge extensions, which keep long, lowercase file names that plain ISO 9660 would not.
Read more
06 Attached to one boot only
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 runsqemu-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 throughtee X.qcow2.log(rulegen.py:601-609). The BIOS and other architectures' rules attach the seed the same way. - The
.runscript'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-pciinstead (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.
Read more
07 Where to go from here
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
| File | Made by | Contents |
|---|---|---|
X.meta-data | echo through tee (rulegen.py:461-465) | the meta-data template with group and release |
X.user-data | echo through tee (rulegen.py:467-471) | the picked user-data template with group, user name and release |
X.seed.iso | xorriso -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 architecture | ln -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
| System | instance-id | local-hostname and user-data hostname | user |
|---|---|---|---|
ubuntu-cloud-24.04.x86_64 | iid-ubuntu-24-04 | ubuntu-24-04 | ubuntu |
debian-cloud-13.x86_64 | iid-debian-13 | debian-13 | debian |
fedora-cloud-42.x86_64 | iid-fedora-42 | fedora-42 | fedora |
gentoo-cloud.x86_64 (no release) | iid-gentoo | gentoo | gentoo |
ubuntu-cloud-24.04@webserver.x86_64 | iid-ubuntu-24-04-webserver | ubuntu-24-04-webserver | ubuntu |
ubuntu-core-24+tpm.x86_64 | iid-ubuntu-core-24-tpm | ubuntu-core-24-tpm | ubuntu |
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
| Part | Deck |
|---|---|
power_state, touch /etc/cloud/cloud-init.disabled | Provisioning runs once |
users | The users every system gets |
ssh_pwauth, sshd_config.APPEND, 99-image-garden.cfg, the apt sed | SSH logins and apt sources |
EXTRA_CLOUD_INIT_APT_CONFIG, EXTRA_CLOUD_INIT_FILES | Changing what cloud-init does |
PKGPROXY_CLOUD_INIT_BOOTCMD, INJECTED_CLOUD_INIT_FILES, PKGPROXY_CLOUD_INIT_RUNCMD | What pkgproxy adds to user-data |
| replaced for Amazon Linux 2, Gentoo; apt hook for old Ubuntu | What differs per distribution |
| replaced for Ubuntu Core | Ubuntu Core images |
Roads from here
RUNTIME · make rules and the CLI
- From a target name to a VM — where the seed sits among the files make builds
FIRST BOOT · cloud-init changes
- Provisioning runs once — what the provisioning boot does with the seed and why it runs once
- The users every system gets — the two accounts the user-data creates
- SSH logins and apt sources — the SSH, cloud-init and apt changes in the user-data
- How a user-data template is chosen — how the user-data template is picked
- What differs per distribution — the systems whose user-data differs