Add customize command

The customize command can be used to customize a pre-built installer
image (right now only ISO supported).

Use single call to xorriso to map files onto the ISO.

Write a grubenv to /boot/grub2/grubenv with extra_cmdline parameter used
by grub_live.cfg.

Also overwrite /LiveOS/setup.sh with file provided in --config and map
the passed in --overlay over /

Signed-off-by: Fredrik Lönnegren <[email protected]>

Author: frelon

cmd/elemental/main.go

@@ -33,6 +33,7 @@ func main() {
 		cmd.GlobalFlags(),
 		cmd.Setup,
 		cmd.NewBuildCommand(appName, action.Build),
+		cmd.NewCustomizeCommand(appName, action.Customize),
 		cmd.NewVersionCommand(appName))
 
 	if err := application.Run(os.Args); err != nil {

docs/customizing-installers.md

@@ -0,0 +1,17 @@
+# Customizing installers
+
+Elemental installer images can be customized using the `elemental3 customize` command.
+
+The following command takes an input (./build/installer.iso) and generates a
+new installer2.iso in the output directory including a new config-script, an
+overlay and some extra kernel cmdline parameters:
+
+```sh
+./build/elemental3 customize \
+    --input ./build/installer.iso
+    --output ./build
+    --name installer2
+    --cmdline="console=ttyS0"
+    --config ./examples/elemental/install/config.sh
+    --overlay tar:./build/overlays.tar.gz
+```

internal/cli/action/customize.go

@@ -0,0 +1,96 @@
+/*
+Copyright © 2025 SUSE LLC
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package action
+
+import (
+	"fmt"
+	"os/signal"
+	"syscall"
+
+	"github.com/urfave/cli/v2"
+
+	"github.com/suse/elemental/v3/internal/cli/cmd"
+	"github.com/suse/elemental/v3/pkg/deployment"
+	"github.com/suse/elemental/v3/pkg/installermedia"
+	"github.com/suse/elemental/v3/pkg/sys"
+)
+
+func Customize(ctx *cli.Context) error {
+	if ctx.App.Metadata == nil || ctx.App.Metadata["system"] == nil {
+		return fmt.Errorf("error setting up initial configuration")
+	}
+	s := ctx.App.Metadata["system"].(*sys.System)
+	args := &cmd.CustomizeArgs
+	logger := s.Logger()
+
+	ctxCancel, cancelFunc := signal.NotifyContext(ctx.Context, syscall.SIGTERM, syscall.SIGINT)
+	defer cancelFunc()
+
+	logger.Info("Customizing image")
+
+	media := installermedia.NewISO(ctxCancel, s)
+
+	err := digestCustomizeSetup(args, media)
+	if err != nil {
+		return fmt.Errorf("invalid customize setup: %w", err)
+	}
+
+	err = media.Customize()
+	if err != nil {
+		return fmt.Errorf("failed customizing installer media: %w", err)
+	}
+
+	s.Logger().Info("Customize complete")
+
+	return nil
+}
+
+func digestCustomizeSetup(flags *cmd.CustomizeFlags, media *installermedia.ISO) error {
+	if flags.Overlay != "" {
+		src, err := deployment.NewSrcFromURI(flags.Overlay)
+		if err != nil {
+			return fmt.Errorf("invalid overlay data URI (%s) to add into the customization: %w", flags.Overlay, err)
+		}
+		media.OverlayTree = src
+	}
+
+	if flags.ConfigScript != "" {
+		media.CfgScript = flags.ConfigScript
+	}
+
+	if flags.Name != "" {
+		media.Name = flags.Name
+	}
+
+	if flags.OutputDir != "" {
+		media.OutputDir = flags.OutputDir
+	}
+
+	if flags.Label != "" {
+		media.Label = flags.Label
+	}
+
+	if flags.KernelCmdline != "" {
+		media.KernelCmdLine = flags.KernelCmdline
+	}
+
+	if flags.InputFile != "" {
+		media.InputFile = flags.InputFile
+	}
+	return nil
+}

internal/cli/cmd/customize.go

@@ -0,0 +1,80 @@
+/*
+Copyright © 2025 SUSE LLC
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/urfave/cli/v2"
+)
+
+type CustomizeFlags struct {
+	InputFile     string
+	OutputDir     string
+	Name          string
+	Target        string
+	Description   string
+	ConfigScript  string
+	Overlay       string
+	Label         string
+	KernelCmdline string
+}
+
+var CustomizeArgs CustomizeFlags
+
+func NewCustomizeCommand(appName string, action func(*cli.Context) error) *cli.Command {
+	return &cli.Command{
+		Name:      "customize",
+		Usage:     "Customize installer artifact",
+		UsageText: fmt.Sprintf("%s customize", appName),
+		Action:    action,
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:        "input",
+				Usage:       "Path to local image to customize",
+				Destination: &CustomizeArgs.InputFile,
+			},
+			&cli.StringFlag{
+				Name:        "config",
+				Usage:       "Path to installer media config script",
+				Destination: &CustomizeArgs.ConfigScript,
+			},
+			&cli.StringFlag{
+				Name:        "output",
+				Usage:       "Location for the temporary builtime files and the resulting image",
+				Destination: &CustomizeArgs.OutputDir,
+				Required:    true,
+			},
+			&cli.StringFlag{
+				Name:        "name",
+				Usage:       "Name of the resulting image file",
+				Destination: &CustomizeArgs.Name,
+			},
+			&cli.StringFlag{
+				Name:        "overlay",
+				Usage:       "URI of the data to include in installer media",
+				Destination: &CustomizeArgs.Overlay,
+			},
+			&cli.StringFlag{
+				Name:        "cmdline",
+				Usage:       "Kernel command line to boot the installer media",
+				Destination: &CustomizeArgs.KernelCmdline,
+			},
+		},
+	}
+}

pkg/bootloader/grubtemplates/grub_live.cfg

@@ -2,9 +2,11 @@ set default=0
 set timeout=5
 set timeout_style=menu
 
+load_env --file (${root})/boot/grub2/grubenv
+
 menuentry "{{.DisplayName}}" --class os --unrestricted {
 	echo Loading kernel...
-	linux ($root){{.Linux}} cdroot {{.CmdLine}}
+	linux ($root){{.Linux}} cdroot {{.CmdLine}} ${extra_cmdline}
 	echo Loading initrd...
 	initrd ($root){{.Initrd}}
-}
+}

pkg/installermedia/iso.go

@@ -45,6 +45,7 @@ const (
 	isoBootCatalog = "boot.catalog"
 	isoMountPoint  = "/run/initramfs/live"
 	installerCfg   = "setup.sh"
+	xorriso        = "xorriso"
 
 	SquashfsPath = isoMountPoint + "/" + liveDir + "/" + squashfsImg
 )
@@ -59,6 +60,7 @@ type ISO struct {
 	OutputDir     string
 	Label         string
 	KernelCmdLine string
+	InputFile     string
 
 	s          *sys.System
 	ctx        context.Context
@@ -168,6 +170,61 @@ func (i ISO) Build(d *deployment.Deployment) (err error) {
 	return nil
 }
 
+// Customize repacks an existing installer with more artifacts.
+func (i *ISO) Customize() (err error) {
+	err = i.sanitizeCustomize()
+	if err != nil {
+		return fmt.Errorf("cannot proceed with customize due to inconsistent setup: %w", err)
+	}
+
+	cleanup := cleanstack.NewCleanStack()
+	defer func() { err = cleanup.Cleanup(err) }()
+
+	tempDir, err := vfs.TempDir(i.s.FS(), "/tmp", "elemental-installer")
+	if err != nil {
+		return fmt.Errorf("could note create working directory for installer ISO build: %w", err)
+	}
+	cleanup.Push(func() error { return i.s.FS().RemoveAll(tempDir) })
+
+	ovDir := filepath.Join(tempDir, "overlay")
+	err = vfs.MkdirAll(i.s.FS(), ovDir, vfs.FilePerm)
+	if err != nil {
+		return fmt.Errorf("could note create working directory for installer ISO build: %w", err)
+	}
+
+	grubEnvPath := filepath.Join(tempDir, "grubenv")
+	err = i.writeGrubEnv(grubEnvPath, map[string]string{"extra_cmdline": i.KernelCmdLine})
+	if err != nil {
+		return fmt.Errorf("error writing %s: %s", grubEnvPath, err.Error())
+	}
+
+	m := map[string]string{
+		grubEnvPath: "/boot/grub2/grubenv",
+	}
+
+	if i.CfgScript != "" {
+		m[i.CfgScript] = filepath.Join("/LiveOS", installerCfg)
+	}
+
+	if i.OverlayTree != nil {
+		unpacker, err := unpack.NewUnpacker(
+			i.s, i.OverlayTree,
+			append(i.unpackOpts, unpack.WithRsyncFlags(rsync.OverlayTreeSyncFlags()...))...,
+		)
+		if err != nil {
+			return fmt.Errorf("could not initate overlay unpacker: %w", err)
+		}
+		_, err = unpacker.Unpack(i.ctx, ovDir)
+		if err != nil {
+			return fmt.Errorf("overlay unpack failed: %w", err)
+		}
+
+		m[ovDir] = "/"
+	}
+
+	return i.mapFiles(i.InputFile, i.outputFile, m)
+}
+
 // sanitize checks the current public attributes of the ISO object
 // and checks if they are good enough to proceed with an ISO build.
 func (i *ISO) sanitize() error {
@@ -199,6 +256,65 @@ func (i *ISO) sanitize() error {
 	return nil
 }
 
+// sanitizeCustomize checks the current public attributes of the ISO object
+// and checks if they are good enough to proceed with an ISO build.
+func (i *ISO) sanitizeCustomize() error {
+	if i.Label == "" {
+		return fmt.Errorf("undefined label for the installer filesystem")
+	}
+
+	if i.OutputDir == "" {
+		return fmt.Errorf("undefined output directory")
+	}
+
+	if i.Name == "" {
+		return fmt.Errorf("undefined name of the installer media")
+	}
+
+	if ok, _ := vfs.Exists(i.s.FS(), i.InputFile); !ok {
+		return fmt.Errorf("target input file %s does not exist", i.InputFile)
+	}
+
+	i.outputFile = filepath.Join(i.OutputDir, fmt.Sprintf("%s.iso", i.Name))
+	if ok, _ := vfs.Exists(i.s.FS(), i.outputFile); ok {
+		return fmt.Errorf("target output file %s is an already existing file", i.outputFile)
+	}
+
+	return nil
+}
+
+func (i ISO) mapFiles(inputFile, outputFile string, fileMap map[string]string) error {
+	args := []string{"-indev", inputFile, "-outdev", outputFile, "-boot_image", "any", "replay"}
+
+	for f, m := range fileMap {
+		args = append(args, "-map", f, m)
+	}
+
+	_, err := i.s.Runner().RunContext(i.ctx, xorriso, args...)
+	if err != nil {
+		return fmt.Errorf("failed creating the installer ISO image: %w", err)
+	}
+
+	return nil
+}
+
+func (i ISO) writeGrubEnv(file string, vars map[string]string) error {
+	arr := make([]string, len(vars)+2)
+
+	arr[0] = file
+	arr[1] = "set"
+
+	j := 2
+	for k, v := range vars {
+		arr[j] = fmt.Sprintf("%s=%s", k, v)
+
+		j++
+	}
+
+	_, err := i.s.Runner().Run("grub2-editenv", arr...)
+	return err
+}
+
 // prepareRoot arranges the root directory tree that will be used to build the ISO's
 // squashfs image. It essentially extracts OS OCI images to the given location.
 func (i ISO) prepareRoot(rootDir string) error {
@@ -225,7 +341,7 @@ func (i ISO) prepareRoot(rootDir string) error {
 
 	err = selinux.Relabel(i.ctx, i.s, rootDir)
 	if err != nil {
-		return fmt.Errorf("SELinux labelling failed: %w", err)
+		i.s.Logger().Warn("Error selinux relabelling: %s", err.Error())
 	}
 	return nil
 }
@@ -367,21 +483,20 @@ func (i ISO) addInstallationAssets(targetDir string, d *deployment.Deployment) e
 
 // burnISO creates the ISO image from the prepared data
 func (i ISO) burnISO(isoDir, output, efiImg string) error {
-	cmd := "xorriso"
 	args := []string{
 		"-volid", "LIVE", "-padding", "0",
 		"-outdev", output, "-map", isoDir, "/", "-chmod", "0755", "--",
 	}
 	args = append(args, xorrisoBootloaderArgs(efiImg)...)
 
-	_, err := i.s.Runner().RunContext(i.ctx, cmd, args...)
+	_, err := i.s.Runner().RunContext(i.ctx, xorriso, args...)
 	if err != nil {
 		return fmt.Errorf("failed creating the installer ISO image: %w", err)
 	}
 
 	checksum, err := calcFileChecksum(i.s.FS(), output)
 	if err != nil {
-		return fmt.Errorf("could not comput ISO's checksum: %w", err)
+		return fmt.Errorf("could not compute ISO's checksum: %w", err)
 	}
 
 	checksumFile := fmt.Sprintf("%s.sha256", output)