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
- From a system's name to a running VM — the path one system takes from a name to a running VM
01 Gentoo in the garden
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 withURLProgram,URLPattern,LocalFilenameTemplate,SHA256SUMS=@URL@.sha256andBoot=efi, and noRelease=(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-cloudandopencloudos-cloud-9but nogentoo-cloud(image-garden.1:211-245).
Read more
02 Finding the latest build
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 witharm64and.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 togentoo-cloud.x86_64.filename(rulegen.py:546-591). - The checksum file,
IMAGE.qcow2.sha256, is also PGP-signed and holdsHASH 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).
Read more
03 SSH, switched on by hand
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.", thenGENTOO_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 lastruncmditem,touch /etc/cloud/cloud-init.disabled(010-qemu.mk:238-247).- The picker tries the group and release, then the group (
GENTOO_), thenCLOUD_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 everymk/*.mk(see per-distribution quirks). - Known discrepancy: Quirk templates start from the base template. A project that redefines
CLOUD_INIT_USER_DATA_TEMPLATEdoes not change Gentoo, whose template starts fromBASE_CLOUD_INIT_USER_DATA_TEMPLATE.
Read more
04 Users, host name and pkgproxy
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, andgentoo/gentooin theusersgroup withsudo: ["ALL=(ALL) NOPASSWD:ALL"]and bash (010-qemu.mk:200-211). Whether the image ships sudo is not in the tree.--queryreports both (010-qemu.mk:84-87); spread-demo namesgentoo/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/hostsline, the snap script fromruncmd(every group butalpine), no apt script (onlydebianandubuntu), andGOPROXYin/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
emergefetches distfiles from Gentoo's mirrors is Portage's behaviour (derived).
Read more
05 Worth knowing when you test on it
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.txtgave 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.urldepends 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).distcleanremoves only the file the.filenamenames (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=falsewith animage-garden.mkbuilt from this tree: the recipe's pipeline ends inawk, so make wrote an empty.urland went on; the filename rule printed "URL for gentoo-cloud.x86_64 does not match URLPattern" but ends intee, so it wrote an empty.filenameand 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
- CI:
x86_64: [others]hasgentoo-cloud(.gitlab-ci.yml:811-817); its spread run goes through spread-demo'smake spread-gentoo-cloud, which only prints that message (tests/ci/run-systems.sh:104-116).aarch64: [others]has onlyalpine-cloud-3(.gitlab-ci.yml:889-895).
Read more
06 Where to go from here
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
| System | Arch | Boot | Release | URL program reads | Cached as | Checksum |
|---|---|---|---|---|---|---|
gentoo-cloud.x86_64 | x86_64 | efi | none | https://distfiles.gentoo.org/releases/amd64/autobuilds/latest-di-amd64-cloudinit.txt, line 6 | gentoo-cloud-STAMP.x86_64.qcow2 | @URL@.sha256 |
gentoo-cloud.aarch64 | aarch64 | efi | none | https://distfiles.gentoo.org/releases/arm64/autobuilds/latest-di-arm64-cloudinit.txt, line 6 | gentoo-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/:
| File | What |
|---|---|
gentoo-cloud.ARCH.url | the URL the program printed; made again when a makefile changes |
gentoo-cloud.ARCH.filename | gentoo-cloud-STAMP.ARCH.qcow2 |
gentoo-cloud-STAMP.ARCH.qcow2 | the image, one per build fetched |
gentoo-cloud-STAMP.ARCH.qcow2.sha256sums | Gentoo's signed checksum file |
gentoo-cloud.ARCH.qcow2 | a 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
| Item | Value |
|---|---|
| Template | GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE: the base template plus systemctl enable --now sshd.service (050.gentoo.mk:4-8) |
| Users | root/root; gentoo/gentoo, group users, passwordless sudo |
| Host name | gentoo |
| pkgproxy | /etc/hosts line, snap setup script (runcmd), GOPROXY in /etc/environment; no apt step; Portage not set up |
Testing on it
| Item | Value |
|---|---|
| Size | about 1.2 GB for x86_64 (run, 21 November 2026) |
| spread | upstream spread cannot connect; spread-demo skips it (spread-demo/Makefile:7-13) |
| image-garden CI | x86_64: [others] with Alpine and Arch; no aarch64 job (.gitlab-ci.yml:811-817, .gitlab-ci.yml:889-895) |
| Man page | lists 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
- Running spread on image-garden — spread and the garden backend
FIRST BOOT · cloud-init changes
- What differs per distribution — Gentoo's template beside Amazon Linux 2 and old Ubuntu
- SSH logins and apt sources — how password and root logins over SSH are opened up
BUILD TIME · data and rules
- URLProgram and local file names — for contributors, the program that finds the build and the cached name, step by step
- Every image has a checksum — for contributors, how every download is checked