Image format in simplestreams

I’m trying to understand how the images provided via simplestreams in Incus work, and I found that several “file types” are supported: disk1.img, disk-kvm.img, uefi1.img, root.tar.xz and squashfs. I assume root.tar.xz and squashfs are for containers, though it’s not clear to me when one would be used over the other. The other three are presumably for VMs, but of those the linuxcontainers image server only uses disk-kvm.img, and I can’t figure out if the other two are just names for the same that aren’t used anymore, or if they are different formats of some kind, and if so, when they would be used.

Based on the distrobuilder docs, .tar.xz (or whatever compression format) is for LXC while .squashfs is for Incus: How to build images - distrobuilder documentation

There is also this if you’re interested in serving Simplestreams: Default image server - Incus documentation and this for the protocol specification: incus/shared/simplestreams at main · lxc/incus · GitHub

The incus.tar.xz file is the metadata file. Both types of images have such metadata.

$ mkdir DISTROBUILDER
$ cd DISTROBUILDER/
$ mkdir ALPINE_CONTAINER
$ mkdir ALPINE_VIRTUALMACHINE
$ cd ALPINE_CONTAINER/
$ incus image export images:alpine/edge
Image exported successfully!                   
$ ls -l
total 3288
-rw-rw-r-- 1 user user     892 Ιουν 18 22:08 incus.tar.xz
-rw-rw-r-- 1 user user 3362816 Ιουν 18 22:08 rootfs.squashfs
$ cd ..
$ cd ALPINE_VIRTUALMACHINE/
$ incus image export --vm images:alpine/edge
Image exported successfully!                   
$ ls -l
total 134276
-rw-rw-r-- 1 user user 137494528 Ιουν 18 22:09 disk.qcow2
-rw-rw-r-- 1 user user       892 Ιουν 18 22:09 incus.tar.xz
$
$ tar xvfa incus.tar.xz 
metadata.yaml
templates/
templates/hostname.tpl
templates/hosts.tpl
templates/inittab.tpl
$ cat metadata.yaml 
architecture: x86_64
creation_date: 1750251670
expiry_date: 1752843670
properties:
  architecture: x86_64
  description: Alpinelinux edge x86_64 (20250618_13:00)
  name: alpinelinux-edge-x86_64-default-20250618_13:00
  os: alpinelinux
  release: edge
  serial: "20250618_13:00"
  variant: default
templates:
  /etc/hostname:
    when:
    - create
    - copy
    create_only: false
    template: hostname.tpl
    properties: {}
  /etc/hosts:
    when:
    - create
    - copy
    create_only: false
    template: hosts.tpl
    properties: {}
  /etc/inittab:
    when:
    - create
    - copy
    create_only: false
    template: inittab.tpl
    properties: {}
$ cd ../ALPINE_CONTAINER/
$ tar xvfa incus.tar.xz 
metadata.yaml
templates/
templates/hostname.tpl
templates/hosts.tpl
templates/inittab.tpl
user@user-desktop:~/DISTROBUILDER/ALPINE_CONTAINER$ cat metadata.yaml 
architecture: x86_64
creation_date: 1750251670
expiry_date: 1752843670
properties:
  architecture: x86_64
  description: Alpinelinux edge x86_64 (20250618_13:00)
  name: alpinelinux-edge-x86_64-default-20250618_13:00
  os: alpinelinux
  release: edge
  serial: "20250618_13:00"
  variant: default
templates:
  /etc/hostname:
    when:
    - create
    - copy
    create_only: false
    template: hostname.tpl
    properties: {}
  /etc/hosts:
    when:
    - create
    - copy
    create_only: false
    template: hosts.tpl
    properties: {}
  /etc/inittab:
    when:
    - create
    - copy
    create_only: false
    template: inittab.tpl
    properties: {}
$ cd ..
$ diff -u ALPINE_CONTAINER/metadata.yaml ALPINE_VIRTUALMACHINE/metadata.yaml 
$

I understand those things, the only thing I am (currently) confused about is what is the distinction between squashfs and root.tar.xz for containers, and disk1.img, disk-kvm.img and uefi1.img for virtual machines. Apart from their ftype properties being different and their combined hashes being stored in different properties on the incus.tar.xz item, they don’t seem to be treated differently at all.
If squashfs is used by incus for container rootfs and root.tar.xz is used by lxc for container rootfs, that would maybe explain why the linuxcontainers repository has both. As far as I can tell, incus is just as happy with a root.tar.xz file, though it seems to use squashfs if one is available.
But for disk1.img, uefi1.img and disk-kvm.img it’s not clear at all, whether these are meaningfully different. Since the linuxcontainers repo doesn’t have any except disk-kvm.img I can’t see if they are different formats or anything.

This comment by Graber should clear things up: [Own Image Server] The requested image couldn't be found - #2 by stgraber

1 Like

awesome, thank you!