Gentoo

rolling, a program URL for users

gentoo-cloud.x86_64 and gentoo-cloud.aarch64 find Gentoo's latest cloud image with a small program, cache it under its build stamp, check it against the .sha256 file next to it and boot with efi; Gentoo's template switches sshd on, pkgproxy sets up snapd and Go but not Portage, and upstream spread cannot connect.

On the map: systems

▶ Watch this deck — 6 scenes, ~5 min

Worth seeing first

01 Gentoo in the garden

GENTOO gentoo-cloud.x86_64 gentoo-cloud.aarch64 rolling, no release built like ubuntu-cloud-24.04.x86_64, but four things differ a program finds the URL each build has a new name and a directory of its own a large image over a gigabyte to download SSH switched on by hand the image ships its SSH service disabled upstream spread can't log in its SSH algorithms don't match
Two Gentoo systems, gentoo-cloud.x86_64 and gentoo-cloud.aarch64, rolling with no release. Four things differ from ubuntu-cloud-24.04.x86_64: a program finds the URL, the image is large, the SSH service is switched on by image-garden, and upstream spread cannot log in

Two systems, gentoo-cloud.x86_64 and gentoo-cloud.aarch64, rolling, with no release. Its URL comes from a program, its image is large, its SSH is switched on by hand, and upstream spread cannot connect.

Gentoo is the other rolling distribution image-garden knows, and it's the one with the most surprises. There are two systems, gentoo-cloud.x86_64 and gentoo-cloud.aarch64, with no release in their names. You build them like ubuntu-cloud-24.04.x86_64, but four things differ. Gentoo publishes each build under a new name, so a small program finds the URL. The image is large. Its SSH server is off until image-garden switches it on. And upstream spread can't log in to it. This deck takes each in turn, with what the first boot gives you, and what to watch for in your tests.

Details and sources

Details

  • data/gentoo.ini: Group=gentoo, Variant=cloud, sections [gentoo-cloud.x86_64] and [gentoo-cloud.aarch64], each with URLProgram, URLPattern, LocalFilenameTemplate, SHA256SUMS=@URL@.sha256 and Boot=efi, and no Release= (gentoo.ini:4-22).
  • The README: "Versions: Rolling release", "Architectures: x86\_64, aarch64", "Supported by image-garden but not compatible with upstream Spread (SSH crypto algorithm mismatch)" (README.md:651-655).
  • The SSH quirk is mk/050.gentoo.mk (050.gentoo.mk:4-8); the release notes that added Gentoo say spread's Go SSH client "is unable to connect to a started instance" (NEWS:610-612).
  • The man page's list of system names has archlinux-cloud and opencloudos-cloud-9 but no gentoo-cloud (image-garden.1:211-245).

02 Finding the latest build

FINDING THE LATEST BUILD latest-di-amd64-cloudinit.txt -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 # Latest as of … # ts=… 20261115T170104Z/di-amd64-cloudinit-20261115T170104Z.qcow2 1205665792 awk: line 6 https://distfiles.gentoo.org/releases/amd64/autobuilds/ 20261115T170104Z/di-amd64-cloudinit-20261115T170104Z.qcow2 gentoo-cloud.x86_64.url gentoo-cloud-20261115T170104Z.x86_64.qcow2 the cached name, with the build stamp from the address the image's address + .sha256 the signed checksum file Gentoo publishes next to each image
curl fetches Gentoo's latest-di-amd64-cloudinit.txt; awk takes its sixth line, the build's path, and puts the autobuilds address in front, which make writes to the .url file. The build stamp goes into the cached name, gentoo-cloud-STAMP.x86_64.qcow2, and the image is checked against the .sha256 file next to it

A program reads latest-di-amd64-cloudinit.txt and turns line six into the image's address; the image is cached as gentoo-cloud-STAMP.x86_64.qcow2 and checked against the .sha256 file next to it.

Gentoo builds its cloud image again and again, and each build lives in a directory named after the moment it was made. So image-garden has no fixed address for it. It runs a small program instead: curl fetches a text file that names the latest build, and awk turns its sixth line into a full address. The build stamp in that address then goes into the name of the cached image: gentoo-cloud, the stamp, then the architecture. The checksum is the file Gentoo publishes next to each image, at the address the program found with .sha256 on the end.

Details and sources

Details

  • x86_64: URLProgram=$(CURL) https://distfiles.gentoo.org/releases/amd64/autobuilds/latest-di-amd64-cloudinit.txt | awk 'NR==6 { print "https://distfiles.gentoo.org/releases/amd64/autobuilds/"$$1 }', URLPattern=…/autobuilds/([0-9]{8}T[0-9]{6}Z)/di-amd64-cloudinit-[0-9]{8}T[0-9]{6}Z\.qcow2$, LocalFilenameTemplate=gentoo-cloud-@1.x86_64.qcow2 (gentoo.ini:8-14). aarch64 is the same with arm64 and .aarch64 (gentoo.ini:16-22).
  • The text file is PGP-signed: line 6, after the armour header, a blank line and two comment lines, is the build's path and its size in bytes. The file on the slide is the one served on 21 November 2026 (run with curl); the program does not check the signature.
  • make writes the program's output to $GARDEN_DL_DIR/gentoo/gentoo-cloud.x86_64.url (rulegen.py:526-530) and the cached name to gentoo-cloud.x86_64.filename (rulegen.py:546-591).
  • The checksum file, IMAGE.qcow2.sha256, is also PGP-signed and holds HASH di-amd64-cloudinit-STAMP.qcow2. The helper looks for the cached name first and, not finding it, for the URL's last part (image-garden:508-515). Checking against it came with "Gentoo images are now verified against the SHA-256 checksum published next to each image" (NEWS:161-164).

03 SSH, switched on by hand

SSH, SWITCHED ON BY HAND # Gentoo ships ssh disabled out of the box, so enable it. define GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE $(BASE_CLOUD_INIT_USER_DATA_TEMPLATE) - systemctl enable --now sshd.service endef image-garden's make file for Gentoo gentoo-cloud.x86_64 gentoo-cloud.aarch64 the whole group # your .image-garden.mk define GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE … keep the systemctl line, or nobody logs in over SSH your CLOUD_INIT_USER_DATA_TEMPLATE Gentoo's template builds on image-garden's own template, not yours
A small make file of image-garden's defines GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE as the base template plus the runcmd line systemctl enable --now sshd.service, for the whole group, so both gentoo-cloud systems get it. A Gentoo template in your project must keep that line, and a common template you redefine does not reach Gentoo, whose template builds on image-garden's own

image-garden defines GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE: the base template plus systemctl enable --now sshd.service. A template of your own for Gentoo must keep that line.

Most cloud images start their SSH server on their own. Gentoo's doesn't: its SSH service ships disabled. So image-garden keeps a small make file for Gentoo, with a template of its own: the common one, plus one more runcmd line that enables the SSH service and starts it at once. It's named for the whole group, since Gentoo has no releases, so both architectures get it. If your project writes its own Gentoo template, keep that line, or the guest boots and nobody can log in over SSH. And note that it builds on image-garden's own template, not yours: a common template you redefine in your project doesn't reach Gentoo.

Details and sources

Details

  • mk/050.gentoo.mk: "Gentoo ships ssh disabled out of the box, so enable it.", then GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE = $(BASE_CLOUD_INIT_USER_DATA_TEMPLATE) plus - systemctl enable --now sshd.service (050.gentoo.mk:1-8). The extra line lands after the base template's last runcmd item, touch /etc/cloud/cloud-init.disabled (010-qemu.mk:238-247).
  • The picker tries the group and release, then the group (GENTOO_), then CLOUD_INIT_USER_DATA_TEMPLATE (010-qemu.mk:285-298); the user-data asks it with the upper-case group and the empty release (rulegen.py:467).
  • The file name has a dot where the others have a dash (050.gentoo.mk); the build takes every mk/*.mk (see per-distribution quirks).
  • Known discrepancy: Quirk templates start from the base template. A project that redefines CLOUD_INIT_USER_DATA_TEMPLATE does not change Gentoo, whose template starts from BASE_CLOUD_INIT_USER_DATA_TEMPLATE.

04 Users, host name and pkgproxy

USERS AND PKGPROXY Gentoo's template the common one, plus SSH gentoo-cloud.x86_64, gentoo-cloud.aarch64 root / root gentoo / gentoo sudo without a password host name gentoo no release to add pkgproxy in reach hosts line snap setup GOPROXY apt step Debian, Ubuntu only emerge Gentoo's mirrors uncached
Gentoo's template gives gentoo-cloud root with the password root, gentoo with the password gentoo and sudo without a password, and the host name gentoo. With a pkgproxy, the guest gets the hosts line, the snap setup and GOPROXY; the apt step is for Debian and Ubuntu only, so emerge fetches from Gentoo's mirrors, uncached

root/root and gentoo/gentoo with sudo, host name gentoo. pkgproxy adds its hosts line, the snap setup and GOPROXY; Portage is not set up.

Apart from SSH, Gentoo gets what every cloud system gets. There's root with the password root, and a user named gentoo, with the password gentoo and sudo without a password. The host name is just gentoo. When a pkgproxy is in reach, the guest learns its address, runs pkgproxy's snap setup script, and gets GOPROXY in its environment, so Go modules come through the cache. There's nothing for Portage. pkgproxy's package setup is for apt, and only Debian and Ubuntu run it. So every emerge in a test fetches its files from Gentoo's mirrors, uncached.

Details and sources

Details

  • The users come from the base template inside Gentoo's: root/root, and gentoo/gentoo in the users group with sudo: ["ALL=(ALL) NOPASSWD:ALL"] and bash (010-qemu.mk:200-211). Whether the image ships sudo is not in the tree. --query reports both (010-qemu.mk:84-87); spread-demo names gentoo/gentoo (spread-demo/spread.yaml:237-240).
  • Host name and meta-data local-hostname: gentoo, the group with no release (010-qemu.mk:94-104).
  • With a pkgproxy: the /etc/hosts line, the snap script from runcmd (every group but alpine), no apt script (only debian and ubuntu), and GOPROXY in /etc/environment (010-qemu.mk:127-180). pkgproxy serves apt, the snap store and Go modules (proxy/README.md:40-48); nothing configures Portage.
  • That emerge fetches distfiles from Gentoo's mirrors is Portage's behaviour (derived).

05 Worth knowing when you test on it

WORTH KNOWING a large image 1.2 GB gentoo-cloud.x86_64 0.57 GB archlinux-cloud.x86_64 the build moves a makefile changes ask for the latest a new build: downloaded, disk prepared the old image stays in the cache the question skips pkgproxy the program distfiles.gentoo.org a failed one leaves an empty .url delete it before you try again: dl/gentoo/gentoo-cloud.x86_64.url upstream spread can't connect spread-demo skips it: Spread cannot connect to sshd 10 in gentoo
Four things to know: the Gentoo image is over a gigabyte, about twice Arch's; a makefile change makes make ask for the latest build again, download a new one beside the old and prepare the disk again; that question goes to Gentoo's server directly, not through pkgproxy, and a failed one leaves an empty .url file to delete; upstream spread cannot connect, so spread-demo skips Gentoo

Over a gigabyte. A makefile change asks for the latest build again; a new one is downloaded beside the old. The question bypasses pkgproxy; after a failed one, delete gentoo-cloud.ARCH.url in the cache. Upstream spread cannot connect.

Some things to know before you lean on Gentoo. Its image is big, over a gigabyte, about twice Arch's, so the first download takes a while. The build moves: make asks for the latest one again whenever a makefile changes, after an upgrade or an edit to your .image-garden.mk. A new build is downloaded, your disk is prepared again, and the old image stays in the cache. That question goes to Gentoo directly, not through pkgproxy, and if it fails, make keeps the empty answer: delete the system's .url file and try again. Upstream spread can't connect to Gentoo's SSH, so the demo project skips it.

Details and sources

Details

  • Size: latest-di-amd64-cloudinit.txt gave 1205665792 bytes for the x86_64 image, and Arch's mirror 569933312 bytes for its image (run with curl on 21 November 2026). Both change with every build.
  • X.url depends on $(MAKEFILE_LIST), which includes .image-garden.mk (rulegen.py:526-530); a new URL gives a new cached name, and the system's link in the cache moves to it (rulegen.py:510-514). distclean removes only the file the .filename names (rulegen.py:486-492), so older builds stay until you delete them. See when upstream moves on.
  • The program runs $(CURL), image-garden's curl, straight at distfiles.gentoo.org (gentoo.ini:9, 000-garden.mk:21); only the image and checksum downloads ask pkgproxy first (image-garden:195-308).
  • A failed program, run here by setting CURL=false with an image-garden.mk built from this tree: the recipe's pipeline ends in awk, so make wrote an empty .url and went on; the filename rule printed "URL for gentoo-cloud.x86_64 does not match URLPattern" but ends in tee, so it wrote an empty .filename and make exited 0. A second make found both files up to date, and the download then failed with "curl: (3) URL rejected: No host part in the URL". Deleting $GARDEN_DL_DIR/gentoo/gentoo-cloud.ARCH.url (and .filename), or touching .image-garden.mk, makes make ask again.
  • spread-demo's Makefile skips gentoo-cloud: "Spread cannot connect to sshd 10 in gentoo", with a link to spread issue 243 (spread-demo/Makefile:7-13). The snap also carries spread-plus, a fork of spread (snap/snapcraft.yaml:46-58); whether it connects is not stated in the tree.

for contributors

In image-garden's CI

06 Where to go from here

ROADS Gentoo Finding the download the program, step by step Every image has a checksum how each download is checked Per-distro quirks Gentoo beside the other two SSH logins how they are opened up spread the garden backend Arch Linux the other rolling one
Roads from Gentoo: how the program finds the download, how each download is checked, per-distribution quirks, SSH logins, spread, and Arch Linux

Next: how the program finds the build, checksums, per-distribution quirks, SSH logins, spread, and Arch Linux.

So Gentoo is two systems, a program that finds the latest build, and one extra line that switches SSH on. From here, a deck for contributors follows that program step by step to the cache, and the checksums deck shows how every download is checked. The quirks deck sets Gentoo's template beside the other two exceptions, and the SSH deck shows how logins are opened up on every system. The spread deck explains the backend that can't reach Gentoo yet. And Arch is the other rolling distribution, with a fixed link instead of a program.

Details and sources

Read more

Basis of the statements on this page

Read in data/gentoo.ini, mk/050.gentoo.mk, mk/010-qemu.mk, rulegen.py, the image-garden script, spread-demo/, the README, NEWS, the man page and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). Gentoo's latest-di-amd64-cloudinit.txt, its checksum file and the image size were fetched on 21 November 2026, and a failed URL program was run with an image-garden.mk built from the tree and CURL=false ("run"). Portage's behaviour and what the image ships are "derived".

The systems

SystemArchBootReleaseURL program readsCached asChecksum
gentoo-cloud.x86_64x86_64efinonehttps://distfiles.gentoo.org/releases/amd64/autobuilds/latest-di-amd64-cloudinit.txt, line 6gentoo-cloud-STAMP.x86_64.qcow2@URL@.sha256
gentoo-cloud.aarch64aarch64efinonehttps://distfiles.gentoo.org/releases/arm64/autobuilds/latest-di-arm64-cloudinit.txt, line 6gentoo-cloud-STAMP.aarch64.qcow2@URL@.sha256

Image URL pattern: https://distfiles.gentoo.org/releases/ARCH/autobuilds/STAMP/di-ARCH-cloudinit-STAMP.qcow2, with ARCH amd64 or arm64 and STAMP like 20261115T170104Z. Source: gentoo.ini:4-22.

Files in the cache

In $GARDEN_DL_DIR/gentoo/:

FileWhat
gentoo-cloud.ARCH.urlthe URL the program printed; made again when a makefile changes
gentoo-cloud.ARCH.filenamegentoo-cloud-STAMP.ARCH.qcow2
gentoo-cloud-STAMP.ARCH.qcow2the image, one per build fetched
gentoo-cloud-STAMP.ARCH.qcow2.sha256sumsGentoo's signed checksum file
gentoo-cloud.ARCH.qcow2a link to the current build

After a failed URL program, delete gentoo-cloud.ARCH.url and gentoo-cloud.ARCH.filename before you try again: make keeps the empty files.

First boot

ItemValue
TemplateGENTOO_CLOUD_INIT_USER_DATA_TEMPLATE: the base template plus systemctl enable --now sshd.service (050.gentoo.mk:4-8)
Usersroot/root; gentoo/gentoo, group users, passwordless sudo
Host namegentoo
pkgproxy/etc/hosts line, snap setup script (runcmd), GOPROXY in /etc/environment; no apt step; Portage not set up

Testing on it

ItemValue
Sizeabout 1.2 GB for x86_64 (run, 21 November 2026)
spreadupstream spread cannot connect; spread-demo skips it (spread-demo/Makefile:7-13)
image-garden CIx86_64: [others] with Alpine and Arch; no aarch64 job (.gitlab-ci.yml:811-817, .gitlab-ci.yml:889-895)
Man pagelists no gentoo-cloud (image-garden.1:211-245)

Roads from here

SYSTEMS · distributions

  • Arch Linux — the other rolling distribution, with a fixed link

SPREAD · tests

FIRST BOOT · cloud-init changes

BUILD TIME · data and rules