feat: Add support for building systemd system extensions (#734)

* feat: Add support for building systemd system extensions

Sysexts are not containers and therefore do not necessarily need to
include all their dependencies. Exactly how much to include ultimately
depends on how the sysext is intended to be used. To give the spec
author full control over this, only the built package and the
dependencies explicitly listed in the spec are installed to the sysext.
These are extracted rather than installed by the package manager.

For now, the generated sysext is a bare erofs filesystem rather than a
partitioned disk image.

This adds `/sysext` to the azlinux3 and noble targets. These are the
only targets with a new enough erofs-utils to include tar support.

/etc can only be included in confexts rather than sysexts. For now, move
anything in /etc (except systemd) to /usr/share/NAME/etc and copy that
data back again at runtime with systemd-tmpfiles. This is what Flatcar
does.

Any systemd services are automatically started when the sysext is
attached thanks to a drop-in against multi-user.target.

Signed-off-by: James Le Cuirot <jlecuirot@microsoft.com>

* Use a new "sysext" dependency type for sysexts rather than "runtime"

This allows existing specs to be extended for sysext use rather than
having to create new ones just to avoid unwanted runtime dependencies.

Signed-off-by: James Le Cuirot <jlecuirot@microsoft.com>

* Run the tests for sysext targets

Like the package targets, this builds a container to run the tests in
and then throws it away. It is not feasible to test the sysext itself.

Signed-off-by: James Le Cuirot <jlecuirot@microsoft.com>

* docs: Add system extension documentation

Signed-off-by: James Le Cuirot <jlecuirot@microsoft.com>

* Temporarily move */sysext targets to */testing/sysext while experimental

---------

Signed-off-by: James Le Cuirot <jlecuirot@microsoft.com>

Author: chewi

deps.go

@@ -31,6 +31,10 @@ type PackageDependencies struct {
 	// Recommends is the list of packages recommended to install with the generated package.
 	// Note: Not all package managers support this (e.g. rpm)
 	Recommends map[string]PackageConstraints `yaml:"recommends,omitempty" json:"recommends,omitempty"`
+	// Sysext is the list of packages to include in the generated system
+	// extension. No dependency resolution is performed when generating system
+	// extensions, so all required dependencies must be explicitly listed here.
+	Sysext map[string]PackageConstraints `yaml:"sysext,omitempty" json:"sysext,omitempty"`
 
 	// Test lists any extra packages required for running tests
 	// These packages are only installed for tests which have steps that require

docs/spec.schema.json

@@ -1259,6 +1259,16 @@
 					],
 					"description": "Runtime is the list of packages required to install/run the package."
 				},
+				"sysext": {
+					"additionalProperties": {
+						"$ref": "#/$defs/PackageConstraints"
+					},
+					"type": [
+						"object",
+						"null"
+					],
+					"description": "Sysext is the list of packages to include in the generated system\nextension. No dependency resolution is performed when generating system\nextensions, so all required dependencies must be explicitly listed here."
+				},
 				"test": {
 					"items": {
 						"type": [

packaging/linux/deb/template_control.go

@@ -57,10 +57,10 @@ func formatVersionConstraint(v string) string {
 	}
 }
 
-// appendConstraints takes an input list of packages and returns a new list of
+// AppendConstraints takes an input list of packages and returns a new list of
 // packages with the constraints appended for use in a debian/control file.
 // The output list is sorted lexicographically.
-func appendConstraints(deps map[string]dalec.PackageConstraints) []string {
+func AppendConstraints(deps map[string]dalec.PackageConstraints) []string {
 	if deps == nil {
 		return nil
 	}
@@ -144,7 +144,7 @@ func (w *controlWrapper) depends(buf *strings.Builder, depsSpec *dalec.PackageDe
 		rtDeps[miscDeps] = dalec.PackageConstraints{}
 	}
 
-	deps := appendConstraints(rtDeps)
+	deps := AppendConstraints(rtDeps)
 	fmt.Fprintln(buf, multiline("Depends", deps))
 }
 
@@ -159,7 +159,7 @@ func (w *controlWrapper) recommends(buf *strings.Builder, depsSpec *dalec.Packag
 		return
 	}
 
-	deps := appendConstraints(depsSpec.Recommends)
+	deps := AppendConstraints(depsSpec.Recommends)
 	fmt.Fprintln(buf, multiline("Recommends", deps))
 }
 
@@ -170,7 +170,7 @@ func (w *controlWrapper) BuildDeps() fmt.Stringer {
 
 	var deps []string
 	if depsSpec != nil {
-		deps = appendConstraints(depsSpec.Build)
+		deps = AppendConstraints(depsSpec.Build)
 	}
 
 	deps = append(deps, fmt.Sprintf("debhelper-compat (= %s)", DebHelperCompat))
@@ -196,7 +196,7 @@ func (w *controlWrapper) Replaces() fmt.Stringer {
 		return b
 	}
 
-	ls := appendConstraints(replaces)
+	ls := AppendConstraints(replaces)
 
 	fmt.Fprintln(b, multiline("Replaces", ls))
 	return b
@@ -209,7 +209,7 @@ func (w *controlWrapper) Conflicts() fmt.Stringer {
 		return b
 	}
 
-	ls := appendConstraints(conflicts)
+	ls := AppendConstraints(conflicts)
 	fmt.Fprintln(b, multiline("Conflicts", ls))
 	return b
 }
@@ -221,7 +221,7 @@ func (w *controlWrapper) Provides() fmt.Stringer {
 		return b
 	}
 
-	ls := appendConstraints(provides)
+	ls := AppendConstraints(provides)
 	fmt.Fprintln(b, multiline("Provides", ls))
 	return b
 }

packaging/linux/deb/template_control_test.go

@@ -65,8 +65,8 @@ func TestAppendConstraints(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			if got := appendConstraints(tt.deps); !reflect.DeepEqual(got, tt.want) {
-				t.Errorf("appendConstraints() = %v, want %v", got, tt.want)
+			if got := AppendConstraints(tt.deps); !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("AppendConstraints() = %v, want %v", got, tt.want)
 			}
 		})
 	}

packaging/linux/rpm/template.go

@@ -241,7 +241,7 @@ func (w *specWrapper) Recommends() fmt.Stringer {
 // NOTE: This is very basic and does not handle things like grouped constraints
 // Given this is just trying to shim things to allow either the rpm format or the deb format
 // in its basic form, this is sufficient for now.
-func formatVersionConstraint(v string) string {
+func FormatVersionConstraint(v string) string {
 	prefix, suffix, ok := strings.Cut(v, " ")
 	if !ok {
 		if len(prefix) >= 1 {
@@ -274,7 +274,7 @@ func writeDep(b *strings.Builder, kind, name string, constraints dalec.PackageCo
 		}
 
 		for _, c := range constraints.Version {
-			fmt.Fprintf(b, "%s: %s %s\n", kind, name, formatVersionConstraint(c))
+			fmt.Fprintf(b, "%s: %s %s\n", kind, name, FormatVersionConstraint(c))
 		}
 	}
 

targets/linux/build_sysext.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+
+set -euxo pipefail
+
+NAME=$1
+VERSION=$2
+ARCH=$3
+
+# Map Docker/Go arch to systemd arch.
+case ${ARCH} in
+	arm|arm64|mips64|ppc64|s390x|sparc64|riscv64) : ;;
+	mipsle|mips64le|ppc64le) ARCH=${ARCH%le}-le ;;
+	386) ARCH=x86 ;;
+	amd64) ARCH=x86-64 ;;
+	loong64) ARCH=loongarch64 ;;
+	*)
+		echo "Unsupported architecture: ${ARCH}" >&2
+		exit 1 ;;
+esac
+
+TMPDIR=$(mktemp -d)
+trap 'rm -rf -- "${TMPDIR}"' EXIT
+mkdir -p "${TMPDIR}"/usr/lib/extension-release.d
+
+cat > "${TMPDIR}/usr/lib/extension-release.d/extension-release.${NAME}" <<-EOF
+ID=_any
+ARCHITECTURE=${ARCH}
+EXTENSION_RELOAD_MANAGER=1
+EOF
+
+cd /input
+shopt -s extglob nullglob
+
+# Sysexts cannot include /etc, so move that data to /usr/share/${NAME}/etc and
+# copy it to /etc at runtime.
+for ITEM in etc/!(systemd); do
+	mkdir -p "${TMPDIR}"/usr/lib/tmpfiles.d
+	echo "C+ /${ITEM} - - - - /usr/share/${NAME}/${ITEM}" >> "${TMPDIR}/usr/lib/tmpfiles.d/10-${NAME}.conf"
+done
+
+# Automatically start any systemd services when the sysext is attached.
+for ITEM in usr/lib/systemd/system/!(*@*).service; do
+	ITEM=${ITEM##*/}
+	mkdir -p "${TMPDIR}"/usr/lib/systemd/system/multi-user.target.d
+	cat > "${TMPDIR}/usr/lib/systemd/system/multi-user.target.d/10-${NAME}-${ITEM%.service}.conf" <<-EOF
+	[Unit]
+	Upholds=${ITEM}
+	EOF
+done
+
+tar \
+	--create \
+	--owner=root:0 \
+	--group=root:0 \
+	--exclude=etc/systemd \
+	--xattrs-exclude=^btrfs. \
+	--transform="s:^(bin|sbin|lib|lib64)/:usr/\1/:x" \
+	--transform="s:^etc\b:usr/share/${NAME//:/\\:}/etc:x" \
+	?(usr)/ ?(etc)/ ?(opt)/ ?(bin)/ ?(sbin)/ ?(lib)/ ?(lib64)/ \
+	--directory="${TMPDIR}" \
+	usr/ \
+	| \
+	mkfs.erofs \
+		--tar=f \
+		-zlz4hc \
+		"/output/${NAME}-${VERSION}-${ARCH}.raw"

targets/linux/deb/distro/distro.go

@@ -39,6 +39,9 @@ type Config struct {
 	// that are not inthe base worker config.
 	// A prime example of this is adding Debian backports on debian distributions.
 	ExtraRepos []dalec.PackageRepositoryConfig
+
+	// erofs-utils 1.7+ is required for tar support.
+	SysextSupported bool
 }
 
 func (cfg *Config) BuildImageConfig(ctx context.Context, sOpt dalec.SourceOpts, spec *dalec.Spec, platform *ocispecs.Platform, targetKey string) (*dalec.DockerImageSpec, error) {
@@ -117,5 +120,12 @@ func (cfg *Config) Handle(ctx context.Context, client gwclient.Client) (*gwclien
 		Description: "Builds the worker image.",
 	})
 
+	if cfg.SysextSupported {
+		mux.Add("testing/sysext", linux.HandleSysext(cfg), &targets.Target{
+			Name:        "testing/sysext",
+			Description: "Builds a systemd system extension image.",
+		})
+	}
+
 	return mux.Handle(ctx, client)
 }

targets/linux/deb/distro/install.go

@@ -197,3 +197,50 @@ func (d *Config) InstallTestDeps(sOpt dalec.SourceOpts, targetKey string, spec *
 		).Root()
 	}
 }
+
+func (d *Config) DownloadDeps(worker llb.State, sOpt dalec.SourceOpts, spec *dalec.Spec, targetKey string, constraints map[string]dalec.PackageConstraints, opts ...llb.ConstraintsOpt) llb.State {
+	if constraints == nil {
+		return llb.Scratch()
+	}
+
+	opts = append(opts, dalec.ProgressGroup("Downloading dependencies"))
+
+	scriptPath := "/tmp/dalec/internal/deb/download.sh"
+	const scriptSrc = `#!/usr/bin/env bash
+set -euxo pipefail
+cd /output
+
+# Make sure any cached data from local repos is purged since this should not
+# be shared between builds.
+rm -f /var/lib/apt/lists/_*
+apt autoclean -y
+apt update
+
+# Use APT to resolve the constraints and download just the requested packages
+# without the sub-dependencies. Ideally, we would resolve all the constraints
+# together and match the packages by name, but the resolved name is often
+# different. We therefore have to resolve each constraint in turn and assume
+# that the last Inst line corresponds to the requested package. This should be
+# the case when recommends and suggests are omitted.
+for CONSTRAINT; do
+	apt satisfy -y -s --no-install-recommends --no-install-suggests "${CONSTRAINT}" |
+		tac |
+		sed -n -r 's/^Inst ([^ ]+) \(([^ ]+).*/\1=\2/p;T;q' |
+		xargs -t apt download
+done
+`
+
+	scriptFile := llb.Scratch().File(
+		llb.Mkfile("download.sh", 0o755, []byte(scriptSrc)),
+		dalec.WithConstraints(opts...),
+	)
+
+	return worker.Run(
+		llb.Args(append([]string{scriptPath}, deb.AppendConstraints(constraints)...)),
+		llb.AddMount(scriptPath, scriptFile, llb.SourcePath("download.sh"), llb.Readonly),
+		llb.AddMount("/var/lib/dpkg", llb.Scratch(), llb.Tmpfs()),
+		llb.AddEnv("DEBIAN_FRONTEND", "noninteractive"),
+		dalec.WithMountedAptCache(d.AptCachePrefix),
+		dalec.WithConstraints(opts...),
+	).AddMount("/output", llb.Scratch())
+}

targets/linux/deb/distro/pkg.go

@@ -245,3 +245,20 @@ func (cfg *Config) HandleSourcePkg(ctx context.Context, client gwclient.Client)
 		return ref, nil, nil
 	})
 }
+
+func (c *Config) ExtractPkg(ctx context.Context, client gwclient.Client, worker llb.State, sOpt dalec.SourceOpts, spec *dalec.Spec, targetKey string, debSt llb.State, opts ...llb.ConstraintsOpt) llb.State {
+	depDebs := llb.Scratch()
+	deps := spec.GetPackageDeps(targetKey)
+	if deps != nil {
+		depDebs = c.DownloadDeps(worker, sOpt, spec, targetKey, deps.Sysext, opts...)
+	}
+
+	opts = append(opts, dalec.ProgressGroup("Extracting DEBs"))
+
+	return worker.Run(
+		llb.Args([]string{"find", "/input", "-name", "*.deb", "-exec", "dpkg-deb", "--verbose", "--extract", "{}", "/output", ";"}),
+		llb.AddMount("/input/build", debSt),
+		llb.AddMount("/input/deps", depDebs),
+		dalec.WithConstraints(opts...),
+	).AddMount("/output", llb.Scratch())
+}

targets/linux/deb/distro/worker.go

@@ -84,3 +84,11 @@ func (cfg *Config) Worker(sOpt dalec.SourceOpts, opts ...llb.ConstraintsOpt) (ll
 		).Root()
 	return base, nil
 }
+
+func (cfg *Config) SysextWorker(worker llb.State, opts ...llb.ConstraintsOpt) llb.State {
+	return worker.Run(
+		dalec.WithConstraints(opts...),
+		AptInstall([]string{"erofs-utils"}, opts...),
+		dalec.WithMountedAptCache(cfg.AptCachePrefix),
+	).Root()
+}