Skip to main content

​
Overview

Modifying a cloud image offline — before uploading — allows you to install packages, configure software, inject files, and set system parameters without needing to launch an instance. This approach produces consistent, repeatable golden images for deployment. All modifications are performed on a copy of the image using libguestfs tools.
Prerequisites
  • A Linux workstation or build server with libguestfs-tools installed
  • A base cloud image in QCOW2 or RAW format (see Get Cloud Images)
  • Root or sudo access on the build host
  • Sufficient disk space: at least 3x the image size for safe modification
Always work on a copy of the image, not the original. If a modification fails or produces an unusable image, the original remains intact.

​
Tools Reference

​
Modify with virt-customize

virt-customize applies changes to an image from the command line without mounting it. It is the fastest method for automatable, scripted modifications.

Install libguestfs-tools

Install on Ubuntu / Debian
Install on CentOS / AlmaLinux / Rocky Linux

Copy the base image

Create a working copy of the image

Install packages

Install software into the image using the native package manager:
Install packages with virt-customize
The --update flag runs a full package upgrade before installing the specified packages.

Inject an SSH key

Pre-authorize an SSH public key for the default user:
Inject SSH public key

Run a configuration script

Execute a shell script inside the image to perform complex configuration:
Run a script inside the image

Set the root password

Setting a root password is only appropriate for testing or emergency access images. Production images should rely on SSH key injection via cloud-init.
Set a root password

​
Modify with guestfish

guestfish provides an interactive shell for directly editing files inside an image. Use it for one-off edits, configuration file changes, or inspecting image contents.

Open the image in guestfish

Open image in interactive mode
At the ><fs> prompt, run:
Mount the root filesystem

Edit a configuration file

Use the edit command to open a file in your default editor:
Edit a file inside the image
Or write content directly with write:
Write content to a file

Copy files into the image

Upload a local file into the image:
Copy local file into the image

Exit and close

Exit guestfish
Changes are written to the image file when guestfish exits.

​
Mount with guestmount

guestmount mounts the image filesystem as a local directory, enabling standard filesystem tools (cp, vim, chmod) to operate on image contents.

Create a mount point

Create a temporary mount directory

Mount the image

Mount the image read-write
The -i flag auto-detects the root filesystem.

Make modifications

The image contents are accessible as a regular directory:
Edit a file in the mounted image

Unmount when complete

Unmount the image
All changes are written to the image file. Verify with guestfish if needed.

​
Generalize with virt-sysprep

Before distributing or uploading an image as a golden template, use virt-sysprep to remove machine-specific identifiers. This ensures each launched instance is treated as a fresh system rather than a clone of the build host.
Generalize the image for distribution
virt-sysprep removes:
  • Machine ID (/etc/machine-id)
  • Shell history files
  • Temporary files and package caches
  • Log files
  • NetworkManager connection caches
Use --operations defaults,-ssh-hostkeys to keep cloud-init’s SSH key regeneration intact. The -ssh-hostkeys exclusion prevents virt-sysprep from removing keys that cloud-init would regenerate anyway.

​
Next Steps

Image Requirements

Verify your modified image meets all Polystack Compute compatibility requirements.

Convert Formats

Convert VMDK, VHD, or RAW images to QCOW2 after modification.

Upload an Image

Upload the customized image to the Polystack Image Service.

Image Properties

Tag uploaded images with OS metadata and hardware requirements.