Arch Linux
rolling, x86_64 only for users
archlinux-cloud.x86_64, the one Arch Linux system, downloads the image behind Arch's images/latest link with the .SHA256 file next to it and boots with efi; the cache keeps the first build it fetched, the first boot uses the common template with an archlinux user, and pkgproxy sets up snapd and Go but not pacman.
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 One rolling image
One system, archlinux-cloud.x86_64: no release in the name, x86_64 only. image-garden make archlinux-cloud.x86_64.run builds it like any other.
Say your tool has to work on a distribution that never stands still. Arch Linux has no releases: it's rolling, and its cloud image is rebuilt as its packages move on. image-garden has exactly one Arch system, archlinux-cloud.x86_64. There's no release in the name, because there's no release to name, and there's only x86_64, because that's the only Arch image the data defines. You build it like ubuntu-cloud-24.04.x86_64, with one make command for its .run script. This deck shows where the image comes from, what the first boot gives you, and why the Arch you test today may not be the Arch you test next month.
Details and sources
Details
data/archlinux.inihas[META]withGroup=archlinuxandVariant=cloud, and one section,[archlinux-cloud.x86_64](archlinux.ini:4-12).- The README: "Versions: Rolling release (cloud image)", "Architectures: x86\_64 only" (README.md:627-630); the man page: "This system is only supported on the x86_64 CPU architecture" (image-garden.1:222-226).
- A section without
Release=gets a name with no release part: group, variant and architecture. How names are put together is in system names. - That Arch Linux is a rolling distribution whose cloud image is rebuilt from current packages is Arch's practice (derived); the README's "Rolling release" is the tree's statement.
02 A link to the latest build
The image is images/latest/Arch-Linux-x86_64-cloudimg.qcow2 on Arch's mirror, a name with no date; its checksum is the one-line .SHA256 file next to it. x86_64 only, UEFI boot, and no release in the system name.
So where does the Arch image come from? image-garden downloads it from a directory on Arch's mirror called latest, at a file whose name carries no date. Each time Arch publishes a new build, the file behind that name changes. Our Ubuntu 24.04 works the same way, through its current directory. The checksum file has the image's name with SHA256 on the end, and sits right next to it. It holds a single line, the hash and the file name, which image-garden reads like any checksum list. Arch is x86_64 and boots with UEFI. And the name, archlinux-cloud.x86_64, has no release in it at all, so nothing in the name says which build you'll get.
Details and sources
Details
- The section:
URL=https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-cloudimg.qcow2,SHA256SUMS=the same URL with.SHA256added,Arch=x86_64,Boot=efi, noRelease=(archlinux.ini:8-12). - The file is cached under the last part of its URL,
Arch-Linux-x86_64-cloudimg.qcow2, in$GARDEN_DL_DIR/archlinux/(rulegen.py:532-536, rulegen.py:782-792), and verified withdownload-with-sha256sums(rulegen.py:510-514). - The checksum file holds one line,
HASH Arch-Linux-x86_64-cloudimg.qcow2, thesha256sumformatfind_checksum_hashreads first (image-garden:75-91). The hash on the slide is the one served on 21 November 2026 (run with curl), shortened; it changes with every build. - The same directory also holds dated builds, such as
Arch-Linux-x86_64-cloudimg-20261115.625457.qcow2, with their own.SHA256files (directory listing, run on 21 November 2026). image-garden uses the undated name. Boot=efigives the x86_64 UEFI rules: a copy of the EDK2 code and a variable store per system (rulegen.py:593-610); see UEFI firmware per system.
Read more
03 What the first boot gives you
The common template: root/root and archlinux/archlinux with sudo, host name archlinux. pkgproxy adds its hosts line, the snap setup and GOPROXY; pacman is not set up.
There's no make file of Arch quirks in image-garden, so the first boot runs the common template, just like Ubuntu's. You get root with the password root, and a user named after the group, archlinux, with the password archlinux and sudo without a password. The host name is archlinux too, since there's no release to add. With a pkgproxy in reach, the guest learns pkgproxy's address, runs pkgproxy's snap setup script, and gets GOPROXY for Go. What it doesn't get is anything for pacman. The package step is apt's, for Debian and Ubuntu only, so Arch's packages come straight from its mirrors, uncached.
Details and sources
Details
- No
mk/file names Arch:ARCHLINUX_CLOUD_INIT_USER_DATA_TEMPLATEis not defined, so the picker falls back toCLOUD_INIT_USER_DATA_TEMPLATE, the common template (010-qemu.mk:285-298, 010-qemu.mk:249). The user-data passes the group,archlinux, as the second user (rulegen.py:467). - The users:
root/root, andarchlinux/archlinuxin theusersgroup withsudo: ["ALL=(ALL) NOPASSWD:ALL"]and bash (010-qemu.mk:200-211);--queryreports both (010-qemu.mk:84-87). spread-demo logs in asarchlinux/archlinux(spread-demo/spread.yaml:174-177). - The host name is the group and release joined by a dash, dots and pluses made dashes; with no release it is
archlinux(010-qemu.mk:94-104, 010-qemu.mk:196). - With a pkgproxy: the
/etc/hostsline,PKGPROXY_BOOTCMD_SETUP(apt) only fordebianandubuntu,PKGPROXY_RUNCMD_SETUP(snap) for every group butalpine, andGOPROXY="http://pkgproxy:PORT/go,direct"appended to/etc/environment(010-qemu.mk:127-180). pkgproxy caches apt, the snap store and Go modules (proxy/README.md:40-48); nothing configures pacman. - The snap setup script writes a snapd drop-in "also where snapd is installed later" (proxy/README.md:175-180). Whether the Arch cloud image ships snapd is not in the tree (derived: it does not).
Read more
04 The build you first fetched
The cache keeps Arch-Linux-x86_64-cloudimg.qcow2 and its .sha256sums; later builds reuse them. Delete both from dl/archlinux/ to start from Arch's newest build.
Here's what rolling means for your tests. The first make downloads the image and its checksum file into the cache, and keeps both. Clean your project and build again, or even upgrade image-garden, and make finds the image there, checks it against the kept checksum, and prepares your disk from the same build. Meanwhile Arch has moved on. So your prepared image ages, and a colleague who builds today starts from a newer Arch than yours. To move on, delete the image and its checksum file from the cache. Delete only the image, and the old checksum fails the new download, which then runs twice.
Details and sources
Details
- The download helper fetches the checksum file only when
FILE.sha256sumsis missing, and the image only whenFILEis missing; then it verifies the image against the kept checksum (image-garden:480-545). With a fixed name, nothing in the cache changes when Arch publishes a new build. - After an upgrade or an edit of
.image-garden.mk,X.urlis newer than the cache link (rulegen.py:521-524), so the download rule runs again (rulegen.py:510-514), and the helper verifies the kept image without fetching it. The user-data is remade too, so the disk is provisioned again, on the same build (derived from the rules; see the overlay). - On a failed check the helper removes the image and the checksum file and tries once more (image-garden:546-558).
image-garden make distcleanremoves the downloaded image,X.urlandX.filename, and leavesFILE.sha256sumsandFILE.lock(rulegen.py:486-492). Run with the helper from this tree andfile://URLs: with the old checksum file kept and a new image at the URL, the helper downloaded the image, failed the check, removed both files, fetched the new checksum file and downloaded the image a second time.- To take Arch's newest build, delete
Arch-Linux-x86_64-cloudimg.qcow2andArch-Linux-x86_64-cloudimg.qcow2.sha256sumsfrom$GARDEN_DL_DIR/archlinux/(~/.cache/image-garden/dl/archlinux/for a native install,~/snap/image-garden/common/cache/dl/archlinux/for the snap); the nextimage-garden makedownloads and provisions again. - A colleague with an empty cache gets whatever the link points at that day; through a pkgproxy the checksum file is asked of the origin each time (image-garden:195-210), so the same holds.
Read more
05 Worth knowing when you test on it
x86_64 only: emulated elsewhere, and left out of all there. No update at first boot: on an aged image, pacman -Syu before you install. Uncached by pkgproxy.
Three more things worth knowing. Arch is x86_64 only. On a 64-bit Arm machine you can still build it, but QEMU then emulates every instruction, so it's slow, and image-garden make all leaves it out there. The first boot asks for no updates, so the guest's package database is as old as your image. On an aged image, installing one package can fail because the mirrors have moved on: sync and upgrade first, and expect that to take a while. And pacman goes straight to Arch's mirrors, without pkgproxy, so every test run downloads its packages again.
Details and sources
Details
- Only
Arch=x86_64is defined (archlinux.ini:11).all::andfetchlist a system only whenGARDEN_ARCHis its architecture (rulegen.py:456-459, rulegen.py:480-484);image-garden make archlinux-cloud.x86_64.runstill works on another host, with TCG (six architectures). - The common template has no
package_updateorpackage_upgradekey (010-qemu.mk:187-247). That pacman on a stale package database may ask the mirrors for files they no longer carry, and thatpacman -Syurefreshes the database and upgrades first, is Arch's behaviour (derived). - pkgproxy has engines for apt, snapd and Go only (proxy/README.md:40-48).
- On a pkgproxy, the image itself is kept by its checksum, so each new Arch build is a new entry (image-garden:272-280).
for contributors
In image-garden's CI
- image-garden's CI job
x86_64: [others]testsalpine-cloud-3 archlinux-cloud gentoo-cloud, "6.5 minutes on novigrad" (.gitlab-ci.yml:811-817); no aarch64 job lists Arch.
Read more
06 Where to go from here
Next: the support matrix, the users, pkgproxy family by family, the cache, downloads, and Gentoo.
So Arch is one system, one link to the latest build, and a cache that holds on to the build you fetched first. From here, the support matrix sets Arch beside every other family. The users deck covers the accounts every system gets, and the pkgproxy deck what a guest is set up to cache, family by family. The cache deck shows what lives in the download directory and what you can delete. The download deck explains the check and the second try. And Gentoo is the other rolling distribution, with a different answer to the same problem.
Details and sources
Read more
Basis of the statements on this page
Read in data/archlinux.ini, rulegen.py, mk/010-qemu.mk, the image-garden script, proxy/README.md, the README, the man page and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). The checksum file's format, the dated builds next to the link and the image size were fetched from Arch's mirror on 21 November 2026, and the helper's double download with a stale checksum file was run with file:// URLs ("run"). Arch's own behaviour (rolling builds, pacman's package database, whether the image has snapd) is "derived".
The system
| System | Arch | Boot | Release | Image | Checksum |
|---|---|---|---|---|---|
archlinux-cloud.x86_64 | x86_64 | efi | none | https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-cloudimg.qcow2 | SHA256SUMS= the image URL + .SHA256 |
Source: archlinux.ini:4-12.
Download and cache
| Item | Value |
|---|---|
.url | the fixed URL, written by make (rulegen.py:521-524) |
| Local name | Arch-Linux-x86_64-cloudimg.qcow2, the URL's last part |
| Cache directory | $GARDEN_DL_DIR/archlinux/ |
| Checksum kept as | Arch-Linux-x86_64-cloudimg.qcow2.sha256sums |
| Checksum file format | one line, HASH NAME |
| Size | about 570 MB (run, 21 November 2026) |
| A newer build | delete the image and its .sha256sums from the cache |
First boot
| Item | Value |
|---|---|
| Template | the common template, CLOUD_INIT_USER_DATA_TEMPLATE (no Arch quirk) |
| Users | root/root; archlinux/archlinux, group users, passwordless sudo |
| Host name | archlinux |
--query | system.users.0 root, system.users.1 archlinux |
| pkgproxy | /etc/hosts line, snap setup script (runcmd), GOPROXY in /etc/environment; no apt step; pacman not set up |
| Updates | none asked for at first boot |
Sources: 010-qemu.mk:94-104, 010-qemu.mk:127-180, 010-qemu.mk:187-247, 010-qemu.mk:80-88.
Testing on it
| Item | Value |
|---|---|
| Hosts | x86_64 with KVM; elsewhere emulated (TCG), and left out of all and fetch |
| spread | archlinux-cloud with archlinux/archlinux in spread-demo (spread-demo/spread.yaml:174-177) |
| image-garden CI | x86_64: [others] with Alpine and Gentoo (.gitlab-ci.yml:811-817) |
Roads from here
SYSTEMS · distributions
- The support matrix — Arch beside every other family and architecture
- Gentoo — the other rolling distribution, whose URL is found by a program
RUNTIME · make rules and the CLI
- Where image-garden keeps its files — what lives in the download cache and what you can delete
- Downloading and checking images — how an image is fetched, verified and fetched again on a mismatch
FIRST BOOT · cloud-init changes
- The users every system gets — root and the group's user, on every system
PKGPROXY · caching for guests
- What pkgproxy adds to user-data — what pkgproxy sets up in a guest, family by family