virt-builder(1)

📦

version 1.57.3 · 15 versions

🦋 virt-builder(1) — Virtualization Support 🦋

okay so this is the virt-builder(1) page, and the manual it lives in is Virtualization Support. Buckle up, bestie — we're building VMs and customizing them like it's a group project where everyone actually shows up. 💖

🌸 NAME 🌸

virt-builder — build virtual machine images quickly. Short name section, absolutely iconic. ✨

✨ SYNOPSIS ✨

virt-builder os-version
   [-o|--output DISKIMAGE] [--size SIZE] [--format raw|qcow2]
   [--arch ARCHITECTURE] [--attach ISOFILE]
   [--append-line FILE:LINE] [--chmod PERMISSIONS:FILE]
   [--chown UID:GID:PATH] [--commands-from-file FILENAME]
   [--copy SOURCE:DEST] [--copy-in LOCALPATH:REMOTEDIR]
   [--delete PATH] [--edit FILE:EXPR] [--firstboot SCRIPT]
   [--firstboot-command 'CMD+ARGS'] [--firstboot-install PKG,PKG..]
   [--hostname HOSTNAME] [--inject-blnsvr METHOD]
   [--inject-qemu-ga METHOD] [--inject-virtio-win METHOD]
   [--install PKG,PKG..] [--link TARGET:LINK[:LINK..]] [--mkdir DIR]
   [--move SOURCE:DEST] [--password USER:SELECTOR]
   [--root-password SELECTOR] [--run SCRIPT]
   [--run-command 'CMD+ARGS'] [--scrub FILE]
   [--ssh-inject USER[:SELECTOR]] [--tar-in TARFILE:REMOTEDIR]
   [--timezone TIMEZONE] [--touch FILE] [--truncate FILE]
   [--truncate-recursive PATH] [--uninstall PKG,PKG..] [--update]
   [--upload FILE:DEST] [--write FILE:CONTENT] [--no-logfile]
   [--password-crypto md5|sha256|sha512] [--no-selinux-relabel]
   [--selinux-relabel] [--selinux-relabel-at-boot]
   [--selinux-relabel-exclude DIR]

virt-builder -l|--list [--long] [--list-format short|long|json] [os-version]

virt-builder --notes os-version

virt-builder --print-cache

virt-builder --cache-all-templates

virt-builder --delete-cache

virt-builder --get-kernel DISKIMAGE
   [--format raw|qcow2] [--output OUTPUTDIR]

💖 DESCRIPTION 💖

Virt-builder is the tool for quickly building new virtual machines. You can build a whole variety of VMs for local or cloud use, usually in a few minutes or less. It also has so many ways to customize those VMs. Everything runs from the command line and nothing requires root privileges, so automation and scripting stay simple. Slay. 💅

Important vibe check: virt-builder does not install guests from scratch. It takes cleanly prepared, digitally signed OS templates and customizes them. That approach is used because it's much faster. But if you need fresh installs, you may want to look at virt-install(1) and oz-install(1). 🫶

The easiest way to get started is by looking at the examples in the next section. Yes bestie, we're going straight to the examples. ✨

🛍️ EXAMPLES 🛍️

🧚 List the virtual machines available

virt-builder --list

will list out the operating systems available to install. A selection of freely redistributable OSes is available as standard. You can add your own too (see below). 👑

After choosing a guest from the list, you may want to see if there are any installation notes:

virt-builder --notes fedora-41

🛠️ Build a virtual machine

virt-builder fedora-41

will build a Fedora 41 image for the same architecture as virt-builder (so running it from an i686 installation will try to build an i686 image, if available). This will have all default configuration (minimal size, no user accounts, random root password, only the bare minimum installed software, etc.). Very "default settings, no notes" energy. 😌

You do not need to run this command as root. 🫶

The first time this runs it has to download the template over the network, but this gets cached (see "CACHING").

The name of the output file is derived from the template name, so above it will be fedora-41.img. You can change the output filename using the -o option:

virt-builder fedora-41 -o mydisk.img

You can also use the -o option to write to existing devices or logical volumes.

virt-builder fedora-41 --format qcow2

As above, but write the output in qcow2 format to fedora-41.qcow2.

virt-builder fedora-41 --size 20G

As above, but the output size will be 20 GB. The guest OS is resized as it is copied to the output (automatically, using virt-resize(1)).

virt-builder fedora-41 --arch i686

As above, but using an i686 template, if available.

🔐 Setting the root password

virt-builder fedora-41 --root-password file:/tmp/rootpw

Create a Fedora 41 image. The root password is taken from the file /tmp/rootpw.

Note if you don't set --root-password then the guest is given a random root password which is printed on stdout. Surprise credentials, but make it secure. 🎀

You can also create user accounts. See "USERS AND PASSWORDS" below.

🏷️ Set the hostname

virt-builder fedora-41 --hostname virt.example.com

Set the hostname to "virt.example.com".

📦 Installing software

To install packages from the ordinary (guest) software repository (eg. dnf or apt):

virt-builder fedora-41 --install "inkscape,@Xfce Desktop"

(In Fedora, "@" is used to install groups of packages. On Debian you would install a meta-package instead.)

To update the installed packages to the latest version:

virt-builder debian-7 --update

🎨 Customizing the installation

There are many options that let you customize the installation. These include: --run/--run-command, which run a shell script or command while the disk image is being generated and lets you add or edit files that go into the disk image. --firstboot/--firstboot-command, which let you add scripts/commands that are run the first time the guest boots. --edit to edit files. --upload to upload files.

For example:

cat <<'EOF' > /tmp/dnf-update.sh
dnf -y --best update
EOF

virt-builder fedora-41 --firstboot /tmp/dnf-update.sh

or simply:

virt-builder fedora-41 --firstboot-command 'dnf -y --best update'

which makes the dnf(8) "update" command run once the first time the guest boots.

Or:

virt-builder fedora-41 \
  --edit '/etc/dnf/dnf.conf:
            s/gpgcheck=1/gpgcheck=0/'

which edits /etc/dnf/dnf.conf inside the disk image (during disk image creation, long before boot).

You can combine these options, and have multiple options of all types. Go off, customization queen. 👑

💅 OPTIONS 💅

--help — Display help. The "help me help you" option. 🙈
--arch ARCHITECTURE — Use the specified architecture for the output image. This means there must be sources providing the requested template for the requested architecture. See also "ARCHITECTURE". 🏗️
--attach ISOFILE — During the customization phase, the given disk is attached to the libguestfs appliance. This is used to provide extra software repositories or other data for customization.

You probably want to ensure the volume(s) or filesystems in the attached disks are labelled (or use an ISO volume name) so that you can mount them by label in your run-scripts:

mkdir /tmp/mount
mount LABEL=EXTRA /tmp/mount

You can have multiple --attach options, and the format can be any disk format (not just an ISO).

See also: --run, "Installing packages at build time from a side repository", genisoimage(1), virt-make-fs(1). 🧚

--attach-format FORMAT — Specify the disk format for the next --attach option. The "FORMAT" is usually "raw" or "qcow2". Use "raw" for ISOs. 🫶
--cache DIR — Sets the directory to use/check for cached template files. If not set, defaults to either $XDG_CACHE_HOME/virt-builder/ or $HOME/.cache/virt-builder/. Cache vibes only. 🎀
--no-cache — Disables template caching. No cache, no problem. 💅
--cache-all-templates — Download all templates to the cache and then exit. See "CACHING".

Note this doesn't cache everything. More templates might be uploaded. Also this doesn't cache packages (the --install, --update options). ⭐

--check-signature — Check the digital signature of the OS template. The default is to check the signature and exit if it is not correct. See also --fingerprint. 🔍
--no-check-signature — Don't check the digital signature of the OS template. Using --no-check-signature bypasses this check. See also --fingerprint. 🚨
--colors, --colours — Use ANSI colour sequences to colourize messages. This is the default when the output is a tty. If the output of the program is redirected to a file, ANSI colour sequences are disabled unless you use this option. Make it pretty. 🌈
--curl CURL — Specify an alternate curl(1) binary. You can also use this to add curl parameters, for example to disable https certificate checks:

virt-builder --curl "curl --insecure" [...]

--delete-cache — Delete the template cache. See "CACHING". Bye-bye cache. 👋
--no-delete-on-failure — Don't delete the output file on failure to build. You can use this to debug failures to run scripts. See "DEBUGGING BUILDS" for ways to debug images.

The default is to delete the output file if virt-builder fails (or, for example, some script that it runs fails). 🧐

--fingerprint 'AAAA BBBB ...' — Check that the index and templates are signed by the key with the given fingerprint. (The fingerprint is a long string, usually written as 10 groups of 4 hexadecimal digits).

You can give this option multiple times. If you have multiple source URLs, then you can have either no fingerprint, one fingerprint or multiple fingerprints. If you have multiple, then each must correspond 1-1 with a source URL. 🔑

--format qcow2, --format raw — For ordinary builds, this selects the output format. The default is raw.

With --get-kernel this specifies the input format.

To create an old-style qcow2 file (for compatibility with RHEL 6 or very old qemu < 1.1), after running virt-builder, use this command:

qemu-img amend -f qcow2 -o compat=0.10 output.qcow2

--get-kernel IMAGE — This option extracts the kernel and initramfs from a previously built disk image called "IMAGE" (in fact it works for any VM disk image, not just ones built using virt-builder).

🚨 Deprecated alert: this method is deprecated. There is a separate tool for this, virt-get-kernel(1), which has more options for the file extraction.

The kernel and initramfs are written to the current directory, unless you also specify the --output "outputdir" directory name.

The format of the disk image is automatically detected unless you specify it by using the --format option.

In the case where the guest contains multiple kernels, the one with the highest version number is chosen. To extract arbitrary kernels from the disk image, see guestfish(1). To extract the entire /boot directory of a guest, see virt-copy-out(1). 🌸

--gpg GPG — Specify an alternate gpg(1) (GNU Privacy Guard) binary. By default virt-builder looks for either "gpg2" or "gpg" in the $PATH.

You can also use this to add gpg parameters, for example to specify an alternate home directory:

virt-builder --gpg "gpg --homedir /tmp" [...]

-l [os-version], --list [os-version], --list --list-format format [os-version], --list --long [os-version] — okay bestie, this is the "show me what's out there" flag 💅. With no guest named, it lists all the available templates; name one and you only get that one.

And you can pick how the list looks with --list-format:

short — the default, prints just the template identifier and, right next to it, its short description. Clean, minimal, iconic.
long — a whole textual list with the deets of the available sources, then the deets of the available templates. The full story ✨.
json — a JSON object with the details of the available sources and the details of the available templates. For when you're feeding it to another program 🫶.

The "version" key in the main object is the "compatibility version", and it gets bumped every single time the resulting JSON output is incompatible with previous versions (like, the structure changed, or non-optional keys aren't there anymore). So watch that key fr fr.

Also, --long is literally just a shorthand for the "long" format. Slay.

See also: --source, --notes, and "SOURCES OF TEMPLATES".

--machine-readable, --machine-readable=format — this one makes the output all machine-friendly so other programs can parse it without crying 😭. Peep "MACHINE READABLE OUTPUT" below for the whole vibe.
-m MB, --memsize MB — changes how much memory gets allocated to --run scripts. Bump this up if your --run scripts or the --install option are running out of memory (we've all been there 💀).

Wanna know the default? Run this:

guestfish get-memsize

--network, --no-network — turns network access from the guest on or off during the installation. Enabled is the default, so use --no-network to disable it 🙈.

Heads up: the network only allows outgoing connections and has other minor limitations. See "NETWORK" in virt-rescue(1).

And if you use --no-network, certain other options like --install will not work. Not a vibe.

Also important: this does not affect whether the guest can access the network once it's booted, because that's controlled by your hypervisor or cloud environment and has literally nothing to do with virt-builder.

Generally speaking you should not use --no-network. But here are some reasons you might:

Because the libguestfs backend you're using doesn't support the network. (See: "BACKEND" in guestfs(3)).
Any software you need to install comes from an attached ISO, so you don't need the network.
You don't want untrusted guest code trying to access your host network when running virt-builder. This is particularly an issue when you don't trust the source of the operating system templates. (See "SECURITY" below).
You don't have a host network (eg. in secure/restricted environments).

--no-sync — don't sync the output file on exit.

By default virt-builder fsyncs the output file or disk image when it exits.

Why? Because qemu/KVM's default caching mode is none or directsync, both of which bypass the host page cache. So these would not work correctly if you immediately started the guest after running virt-builder — they would not see the complete output file. (And ngl, you should not use these caching modes — they are fundamentally broken for this and other reasons 💀.)

But if you are not using these broken caching modes, you can use --no-sync to skip this unnecessary sync and gain considerable extra performance. Speeeed 🔥.

--notes os-version — lists any notes associated with this guest, then exits. Note: it does not do the install, it's just here for the tea 🍵.
-o filename, --output filename — writes the output to filename. If you don't specify this option, the output filename is generated by taking the os-version string and adding .img (for raw format) or .qcow2 (for qcow2 format).

Fun fact: the output filename could be a device, partition or logical volume 👀.

And when it's used with --get-kernel, this option specifies the output directory instead.

--print-cache — prints info about the template cache. See "CACHING".
-q, --quiet — don't print ordinary progress messages. Silencio 🤫.
--size SIZE — picks the size of the output disk, and the size can be written with common names like 32G (32 gigabytes) etc.

Virt-builder will resize filesystems inside the disk image automatically. So convenient 💖.

If the size is not specified, one of two things happens: if the output is a file, the size is the same as the template. If the output is a device, partition, etc, then the size of that device is used.

Wanna specify size in bytes? The number must be followed by the lowercase letter b, eg. --size 10737418240b.

--smp N — enables N ≥ 2 virtual CPUs for --run scripts to use. Go off, multicore 👑
--source URL — sets the source URL to look for indexes.

You can give this option multiple times to specify multiple sources 🎀.

See also "SOURCES OF TEMPLATES" below.

Careful bestie: you should not point --source to sources that you don't trust (unless the source is signed by someone you do trust). See also the --no-network option. Trust issues are real 💀.

--no-warn-if-partition — don't emit a warning if the output device is a partition. This warning exists to save you from a super common user error when writing to a USB key or external drive: you should normally write to the whole device (--output /dev/sdX), not to a partition on the device (--output /dev/sdX1). Use this option to suppress that warning if you know what you're doing 😌.
-v, --verbose — enables debug messages and/or produces verbose output.

When reporting bugs, use this option and attach the complete output to your bug report. The maintainers will love you for it fr fr 🫶.

-V, --version — displays the version number and exits. Short and sweet ✨.
--wrap — wraps error, warning, and informative messages. This is the default when the output is a tty. But if the output of the program is redirected to a file, wrapping is disabled unless you use this option.
-x — enables tracing of libguestfs API calls. Detective mode 🔍.

🎀 Customization options 🎀

--append-line FILE:LINE — appends a single line of text to FILE. If the file doesn't already end with a newline, one gets added before the appended line. Also, a newline is added to the end of the LINE string automatically. Iconic behavior honestly.

For example (assuming ordinary shell quoting), this command:

--append-line '/etc/hosts:10.0.0.1 foo'

will add either "10.0.0.1 foo⏎" or "⏎10.0.0.1 foo⏎" to the file — the latter only if the existing file does not already end with a newline.

"⏎" represents a newline character, which is guessed by looking at the existing content of the file, so this command does the right thing for files using Unix or Windows line endings. It also works for empty or non-existent files. Versatile queen 👑.

Wanna insert several lines? Just use the same option several times:

--append-line '/etc/hosts:10.0.0.1 foo'
--append-line '/etc/hosts:10.0.0.2 bar'

And to insert a blank line before the appended line, do:

--append-line '/etc/hosts:'
--append-line '/etc/hosts:10.0.0.1 foo'

--chmod PERMISSIONS:FILE — changes the permissions of FILE to PERMISSIONS.

Note: PERMISSIONS by default would be decimal, unless you prefix it with 0 to get octal — so use 0700 not 700. This trips people up every time, don't let it be you 😭.

--chown UID:GID:PATH — changes the owner user and group ID of a file or directory in the guest. But like, note:
- Only numeric UIDs and GIDs will work, and these may not be the same inside the guest as on the host.
- This will not work with Windows guests.

For example:

virt-customize --chown '0:0:/var/log/audit.log'

🦋 REFERENCE 🦋

INSTALLING PACKAGES

There are several approaches to installing packages or applications in the guest, and they all have different trade-offs. Like, there's no single "correct" one — it depends on what you're doing, iykyk.

Installing packages at build time

So this is the first approach, and here we go 👇 (the deets continue in the next bit 💖)

If the guest OS you're installing is lowkey the same vibe as the host OS (like, both Linux, bestie), and libguestfs can do network connections, then --install is literally right there:

virt-builder fedora-41 --install inkscape

It uses the guest's own package manager + the host's network connection. Chef's kiss. 💅

✨ Updating packages at build time

Wanna refresh the packages already sitting in the template while you build? Slay, do this:

virt-builder fedora-41 --update

Most of the templates that ship with virt-builder come with a very minimal snack of packages — the community calls it a "JEOS" or "Just Enough Operating System" — and those are up to date as of when the template got created, but ngl they could be hella stale by the time you actually install an OS from that template. This option updates those template packages. 🫶

✨ Installing packages at first boot

Another way (and honestly a whole different vibe) is installing the packages when the guest first boots:

virt-builder fedora-41 --firstboot-install inkscape

This one uses the guest's package manager and the guest's network connection.

The downsides? Two of them, and they're real: first boot will take the guest a LOT longer, and there's basically nothing you can do if package installation fails (like, say, a network problem means the guest can't reach the package repositories). 😭

✨ Installing packages at build time from a side repository

If the software you want isn't in the guest's main package repository, you can add a side repository. Usually this shows up as an ISO (CD disk image) file stuffed with extra packages. Iconic.

You can make that disk image with either genisoimage(1) or virt-make-fs(1). For genisoimage, a command like this:

genisoimage -o extra-packages.iso -R -J -V EXTRA cdcontents/

Then create a script that mounts the ISO and sets up the repository. For dnf, create /tmp/install.sh containing:

mkdir /tmp/mount
mount LABEL=EXTRA /tmp/mount

cat <<'EOF' > /etc/yum.repos.d/extra.repo
[extra]
name=extra
baseurl=file:///tmp/mount
enabled=1
EOF

dnf -y install famousdatabase

For apt, create /tmp/install.sh containing:

mkdir /tmp/mount
mount LABEL=EXTRA /tmp/mount

apt-cdrom -d=/tmp/mount add
apt-get -y install famousdatabase

Then use the --attach option to attach the CD / disk image, and the --run option to run the script:

virt-builder fedora-41 \
  --attach extra-packages.iso \
  --run /tmp/install.sh

🎀 USERS AND PASSWORDS 🎀

The --root-password option is what you use to change the root password (otherwise a random password gets used, surprise 🎁). It takes a password SELECTOR in one of the following formats:

--root-password file:FILENAME — reads the root password from FILENAME. The whole first line of that file is the replacement password, and any other lines are ignored. You should create the file with mode 0600 so nobody else can read it. 🔒
--root-password password:PASSWORD — sets the root password to the literal string PASSWORD.

Note: this is not secure, since any user on the same machine can see the cleartext password using ps(1). Fr fr, be careful.

--root-password random — picks a random password, which gets printed on stdout. The password has approximately 120 bits of randomness. This is the default.
--root-password disabled — the root account password is disabled. It's like putting * in the password field.
--root-password locked:file:FILENAME
--root-password locked:password:PASSWORD
--root-password locked:random — the root account is locked, but a password is placed on the account anyway. If it's first unlocked (using passwd -u), then logins will use the given password. 🗝️
--root-password locked
--root-password locked:disabled — the root account is locked and the password is disabled.

✨ Creating user accounts

To create user accounts, use the useradd(8) command with --firstboot-command like this:

virt-builder --firstboot-command \
   'useradd -m -p "" rjones ; chage -d 0 rjones'

That command up there creates an rjones account with no password, and forces the user to set a password when they first log in. There are other ways to manage passwords too — useradd(8) has the details if you're curious. 💖

🦋 KEYBOARD LAYOUT 🦋

Okay so here's the thing: there are SO many different ways to set the keyboard layout across Linux distributions that virt-builder doesn't yet even attempt to have a simple command line option. So this section is me walking you through setting the keyboard for some common Linux distros. You got this. ✨

Keyboard layout with systemd

For distros that use systemd localectl, use a command like this:

virt-builder fedora-41 \
  --firstboot-command 'localectl set-keymap uk'

See localectl(1) and https://www.happyassassin.net/2013/11/23/keyboard-layouts-in-fedora-20-and-previously/ for more details.

Keyboard layout using /etc/sysconfig/keyboard

For RHEL ≤ 6, Fedora ≤ 18 and similar, upload or modify the keyboard configuration file using the --upload, --write or --edit options. Like this:

virt-builder centos-6 \
  --edit '/etc/sysconfig/keyboard: s/^KEYTABLE=.*/KEYTABLE="uk"/'

The format of this file can be found documented in many places online. 🌈

Keyboard layout with Debian-derived distros

For Debian-derived distros using /etc/default/keyboard, upload or modify the keyboard file using the --upload, --write or --edit options. For example:

virt-builder debian-8 \
  --edit '/etc/default/keyboard: s/^XKBLAYOUT=.*/XKBLAYOUT="gb"/'

See https://wiki.debian.org/Keyboard.

🌸 LANGUAGE 🌸

Most Linux distributions support multiple locale settings, so you can have guest messages printed in another language such as Russian. Multilingual queen behavior. 👑

But there's no single setting that controls it, because extra packages may need to be installed to support console and X fonts, plus keyboard input methods. The packages required, and their configuration, is highly distro-specific, and honestly it's outside the scope of virt-builder to do all that. Not its job, bestie.

This section has examples for some common Linux distributions.

Setting Japanese in Fedora 41

virt-builder fedora-41 \
  --size 20G \
  --update \
  --install @japanese-support \
  --install @xfce \
  --install xorg-x11-server-Xorg,xorg-x11-drivers,rsyslog \
  --link /usr/lib/systemd/system/graphical.target:/etc/systemd/system/default.target \
  --firstboot-command 'localectl set-locale LANG=ja_JP.utf8' \
  --firstboot-command 'localectl set-keymap jp' \
  --firstboot-command 'systemctl isolate graphical.target'

Setting Japanese in Debian 8 (Jessie)

Note that although this enables Japanese in the text console too, it's unlikely you'll see properly rendered Japanese there. No cap. However, Japanese is properly rendered in X applications and terminals. ✨

pkgs=locales,xfce4,\
ibus,ibus-anthy,\
fonts-ipafont-gothic,fonts-ipafont-mincho,\
fonts-takao-mincho,\
xfonts-intl-japanese,xfonts-intl-japanese-big,\
iceweasel-l10n-ja,manpages-ja

virt-builder debian-8 \
  --size 20G \
  --install $pkgs \
  --edit '/etc/locale.gen: s,^#\s*ja,ja,' \
  --write '/etc/default/locale:LANG="ja_JP.UTF-8"' \
  --run-command "locale-gen"

💀 LOG FILE 💀

Scripts and package installation that runs at build time (--run, --run-command, --install, --update, but not firstboot) gets logged in one of these locations:

/tmp/builder.log — on Linux, BSD, and other non-Windows guests.
C:\Temp\builder.log — on Windows, DOS guests.
/builder.log — if /tmp or C:\Temp is missing.

If you don't want the log file showing up in the final image, then use the --no-logfile command line option. Poof, gone. 🪄

🔑 SSH KEYS 🔑

The --ssh-inject option injects ssh keys for users in the guest so they can log in without supplying a password. So convenient, we love her. 💜

The SELECTOR part of the option value is optional; in that case, --ssh-inject "USER" means we look in the current user's ~/.ssh directory to find the default public ID file, and that key gets uploaded. "default public ID" is the default_ID_file file described in ssh-copy-id(1).

If specified, the SELECTOR can be in one of the following formats:

--ssh-inject USER:file:FILENAME — reads the ssh key from FILENAME. FILENAME is usually a .pub file.
--ssh-inject USER:string:KEY_STRING — uses the specified KEY_STRING. KEY_STRING is usually a public string like ssh-rsa AAAA.... user@localhost.

In any case, the ~USER/.ssh directory and the ~USER/.ssh/authorized_keys file will be created if they don't already exist. 🫶

⭐ INSTALLATION PROCESS ⭐

When you invoke virt-builder, installation proceeds as follows:

The template image is downloaded.

If the template image is present in the cache, the cached version is used instead. (See "CACHING".)

The template signature is checked.
The template is uncompressed to a tmp file.
The template image is resized into the destination, using virt-resize(1).
Extra disks are attached (--attach).
A new random seed is generated for the guest.
Guest customization is performed, in the order specified on the command line.
SELinux relabelling is done unless disabled with --no-selinux-relabel.

👑 IMPORTING THE DISK IMAGE 👑

Importing into libvirt

Import the disk image into libvirt using virt-install(1)'s --import option:

virt-install --import \
  --name guest --ram 2048 \
  --disk path=disk.img,format=raw --os-variant fedora27

Notes, bestie, please read them:

You must specify the correct format. The format is raw unless you used virt-builder's --format option.
--os-variant is highly recommended, because it'll present optimum devices so the guest runs as efficiently as possible. To get a list of all variants, do:

osinfo-query os

The tool above is provided by the libosinfo package.

You can run virt-install as root or non-root. Each works slightly differently because libvirt manages a different set of virtual machines for each user. In particular virt-manager normally shows the root-owned VMs, whereas Boxes shows the user-owned VMs, and other tools probably work differently as well. Everyone's got their own main character energy. 💅

Importing into OpenStack

Import the image into Glance (the OpenStack image store) by doing:

glance image-create --name fedora-41-image --file fedora-41.img \
  --disk-format raw --container-format bare \
  --is-public True

The --file parameter is the virt-builder-generated disk image. It should match virt-builder's --output option. The --disk-format parameter should match virt-builder's --format option (or raw if you didn't use that option). The --container-format should always be bare, since virt-builder doesn't put images into containers. Periodt. 🎀

Obviously once you've uploaded it you're gonna want to look at it, bestie — and you can peek at all the properties of your image with:

glance image-show fedora-41-image

Then to boot up an actual instance of your image on a Nova compute node, do this:

nova boot fedora-41-server --image fedora-41-image \
  --flavor m1.medium

Use nova flavor-list to list possible machine flavors, and nova list to list running instances. Yeah. That's it. You're computing in the cloud now ✨

Booting directly using qemu or KVM

Okay so real talk 💀 — the qemu command line is, like, not very stable and not very easy to use, so if you can possibly use libvirt, do that instead. But if you're built different and want to raw-dog it, a command line similar to the following could be used to boot the virtual machine:

qemu-system-x86_64 \
  -machine accel=kvm:tcg \
  -cpu max \
  -m 2048 \
  -drive file=disk.img,format=raw,if=virtio

And just like with libvirt, it is very important that the correct format is chosen 😤. It will be raw unless the --format option was used. Not "probably raw." raw. Periodt.

🎭 CONFIGURATION MANAGEMENT

Puppet

To enable the Puppet agent inside a guest, you install the package, point the configuration at your Puppetmaster, and make sure the agent actually runs at boot. A typical virt-builder command would be:

virt-builder fedora-41 \
  --hostname client.example.com \
  --update \
  --install puppet \
  --append-line '/etc/puppet/puppet.conf:[agent]' \
  --append-line '/etc/puppet/puppet.conf:server = puppetmaster.example.com/' \
  --run-command 'systemctl enable puppet'

The precise instructions vary according to the Linux distro though — it's giving "every distro has opinions" energy 🙈. For further information see: https://docs.puppet.com/puppet/latest/install_pre.html

🐛 DEBUGGING BUILDS

If virt-builder itself fails, then enable debugging (-v) and report a bug (see the BUGS section below 🫶).

If virt-builder fails because some script or package it is installing fails, try using --no-delete-on-failure to preserve the output file, and then keep reading this section, because we got you.

If virt-builder is successful but the image doesn't work, here are some things to try:

Use virt-rescue

Run virt-rescue(1) on the disk image:

virt-rescue -a disk.img

This gives you a rescue shell 🐚. You can mount the filesystems from the disk image on /sysroot and examine them using ordinary Linux commands. You can also chroot into the guest to reinstall the bootloader. The virt-rescue man page has a lot more information and examples, so go read it.

Use guestfish

Run guestfish(1) on the disk image:

guestfish -a disk.img -i

Use guestfish commands like ll /directory and cat /file to examine directories and files. Chef's kiss for poking around 🔥

Use guestmount

Mount the disk image safely on the host using FUSE and guestmount(1):

mkdir /tmp/mp
guestmount -a disk.img -i /tmp/mp
cd /tmp/mp

To unmount the disk image do:

fusermount -u /tmp/mp

Add a serial console

If the guest hangs during boot, it can be helpful to add a serial console to the guest, and direct kernel messages to the serial console. Adding the serial console will involve looking at the documentation for your hypervisor (sorry, that part's on them 💀). To direct kernel messages to the serial console, add the following on the kernel command line:

console=tty0 console=ttyS0,115200

📦 SOURCES OF TEMPLATES

So like, where do templates even come from? virt-builder reads the available sources from configuration files with the .conf extension, located in the following paths:

$XDG_CONFIG_HOME/virt-builder/repos.d/ ($XDG_CONFIG_HOME is $HOME/.config if not set).
$VIRT_BUILDER_DIRS/virt-builder/repos.d/ (where $VIRT_BUILDER_DIRS means any of the directories in that environment variable, or just /etc if not set).

Each .conf file in those paths has a simple text format like the following:

[libguestfs.org]
uri=http://libguestfs.org/download/builder/index.asc
gpgkey=file:///etc/xdg/virt-builder/repos.d/libguestfs.gpg

The part in square brackets is the repository identifier, which is used as unique identifier 👑

The following fields can appear:

uri=URI — the URI of the index file which this repository refers to. This field is required.
gpgkey=URI — this optional field represents the URI (although only file:// URIs are accepted) of the key used to sign the index file. If not present, the index file referred by uri=.. is not signed.
proxy=MODE — this optional field specifies the proxy mode, to be used when downloading the index file of this repository. The possible values are:
- no, off — no proxy is being used at all, even overriding the system configuration.
- system — the proxy used is the system one.
- anything else — specifies the actual proxy configuration to be used, overriding the system configuration.

If not present, the assumed value is to respect the proxy settings of the system (i.e. as if system would be specified).

format=FORMAT — this optional field specifies the format of the repository. The possible values are:
- native — the native format of the virt-builder repository. See also "Creating and signing the index file" below.
- simplestreams — the URI represents the root of a Simple Streams v1.0 tree of metadata. For more information about Simple Streams, see also https://launchpad.net/simplestreams.

If not present, the assumed value is native.

For serious virt-builder use, you may want to create your own repository of templates. Main character energy 🎀

Libguestfs.org repository

Out of the box, virt-builder downloads the file http://libguestfs.org/download/builder/index.asc, which is an index of available templates plus some information about each one, wrapped up in a digital signature 🔏. The command virt-builder --list lists out the information in this index file.

The templates hosted on libguestfs.org were created using shell scripts, kickstart files and preseed files which can be found in the libguestfs source tree, in builder/templates.

Setting up the repository

You can set up your own site containing an index file and some templates, and then point virt-builder at the site by creating a .conf file pointing to it.

Heads up bestie: if your index is signed, you will need to properly fill gpgkey=.. in your .conf file, making sure to deploy also the GPG key file. Don't skip this, it's literally the whole vibe check.

virt-builder --source https://example.com/builder/index.asc \
   --fingerprint 'AAAA BBBB ...' \
   --list

You can host this on any web or FTP server, or a local or network filesystem. Whatever slays for you 💅

Setting up a GPG key

If you don't have a GnuPG key, you will need to set one up. (Strictly speaking this is optional, but if your index and template files are not signed then virt-builder users will have to use the --no-check-signature flag every time they use virt-builder. Yeah. Every. Single. Time. 😭)

To create a key, see the GPG manual http://www.gnupg.org/gph/en/manual.html

Export your GPG public key:

gpg --export -a "you@example.com" > pubkey

Create the templates

There are many ways to create the templates. For example you could clone existing guests (see virt-sysprep(1)), or you could install a guest by hand (virt-install(1)). To see how the templates were created for virt-builder, look at the scripts in builder/templates.

virt-builder supports any image format (e.g. raw, qcow2, etc) as template, both as-is, and compressed as XZ 🌸. This way, existing images (e.g. cleaned using virt-sysprep(1)) can be used as templates.

For best results when compressing the templates, use the following xz options (see nbdkit-xz-plugin(1) for further explanation):

xz --best --block-size=16777216 disk

Creating and signing the index file

The index file has a simple text format (shown here without the digital signature):

[fedora-41]
name=Fedora® 41
osinfo=fedora41
arch=x86_64
file=fedora-41.xz
checksum[sha512]=...
format=raw
size=6442450944
compressed_size=148947524
expand=/dev/sda3

[fedora-42]
name=Fedora® 42
osinfo=fedora42
arch=x86_64
file=fedora-42.xz
checksum[sha512]=...
revision=3
format=raw
size=4294967296
compressed_size=172190964
expand=/dev/sda3

The part in square brackets is the "os-version", which is the same string that is used on the virt-builder command line to build that OS. So like, it has to match, fr fr.

Note that newlines in the index file are not significant. Blank lines between sections are optional and are only included for readability. You may use any number of blank lines (or none at all) to separate sections. Zero. None. Go feral 🦋

The index file creation and signature can be eased with the virt-builder-repository(1) tool.

After preparing the index file in the correct format, clearsign it using the following command:

gpg --clearsign --armor index

This will create the final file called index.asc which can be uploaded to the server (and is the uri=.. URL). As noted above, signing the index file is optional, but recommended. Do the recommended thing, bestie 🫶

The following fields can appear:

name=NAME — the user-friendly name of this template. This is displayed in the --list output but is otherwise not significant.
osinfo=ID — this optional field maps the operating system to the associated libosinfo ID. virt-builder does not use it (yet).
arch=ARCH — the architecture of the operating system installed within the template. This field is required.
file=PATH — the path (relative to the index) of the xz-compressed template.

Note that absolute paths or URIs are not permitted here. This is because virt-builder has a "same origin" policy for templates so they cannot come from other servers. No smuggling templates in from some rando server, sorry 🚫

sig=PATH — this option is deprecated. Use the checksum field instead.

The path (relative to the index) of the GPG detached signature of the xz file.

Note that absolute paths or URIs are not permitted here. This is because virt-builder has a "same origin" policy for templates so they cannot come from other servers.

The file can be created as follows:

gpg --detach-sign --armor -o disk.xz.sig disk.xz

checksum[sha512]=7b882fe9b82eb0fef... — the SHA-512 checksum of the file specified in file=.. is checked after it is downloaded. To work out the signature, do:

sha512sum disk.xz

Note if you use this, you don't need to sign the file, ie. don't use sig. This option overrides sig.

checksum=7b882fe9b82eb0fef... — checksum is an alias for checksum[sha512].

💖 quick heads-up bestie: if you're talking to a server that's still on virt-builder = 1.24.0, you literally have to use checksum, because that version throws a whole parse error tantrum when it sees square brackets and numbers in a field key. Fixed in virt-builder ≥ 1.24.1, so if you're modern you're fine. 🫶

revision=N — this is just an integer that babysits the template cache ✨. Bump the revision number and clients go "oh wait new drop" and re-download the template even if they already have a copy sitting in their cache. The revision number is optional — leave it out and it defaults to 1. iykyk.
format=raw, format=qcow2 — this tells everyone what format the disk image is in; and if it's compressed, it's the format before the compression, bestie. Leave it out and the format gets autodetected, but ngl it's way better to just be explicit about what you meant. 🔊

Real talk: this is the source format, which is not the same thing as the --format option (that's the requested output format). virt-builder does the glow-up conversion on the fly from source format to whatever output format you asked for. 💅

size=NNN — the virtual size of the image in bytes. That's the size when it's uncompressed, okay? So if you're using a non-raw format like qcow2, it means the virtual disk size, not the size of the qcow2 file itself. This field is required — no size, no slay. 🚨

Also, virt-builder uses this as the minimum size users can request via the --size option, or as the default size if there's no --size option at all.

compressed_size=NNN — the actual size of the disk image in bytes, i.e. what was specified in file=.... This is purely for info (it shows up when you use the long and json formats of --list). 🎀
expand=/dev/sdaX — when the image gets expanded to its final size, this tells virt-resize(1) to expand the named partition in the guest image so it fills up all the available space. Works exactly like the virt-resize --expand option. You should usually put the device name of the guest's root filesystem here. Using it is a good idea but not required — skip the field and virt-resize just makes an extra partition at the end of the disk to cover the free space, which is, and I cannot stress this enough, much less user-friendly. 😭
lvexpand=/dev/VolGroup/LogVol — when the image gets expanded to its final size, this tells virt-resize(1) to expand the named logical volume in the guest image to fill up all available space. Works like the virt-resize --lv-expand option. If the guest uses LVM2 you should usually put the LV of the guest's root filesystem here. If the guest doesn't use LVM2, or its root filesystem isn't on an LV, do not use this one. 🙅‍♀️
notes=NOTES — any notes that go with this image, especially stuff describing what packages are in the image, how the image was prepped, and licensing info. This shows up in --notes and --list --long modes.

You can do multi-line notes by indenting each new line with at least one character of whitespace (even on blank lines):

notes=This image was prepared using
 the following kickstart script:
                             <-- one space at beginning of line
 part /boot --fstype ext3
 ...

hidden=true — the hidden flag stops the template from being listed by the --list option (but it's still installable, don't worry). This one's for test images. 🙈
aliases=ALIAS1 ALIAS2 ... — optional field listing aliases for the image, separated by spaces. Example: an alias could always point to the latest version of a certain image, leaving old versions available in the index instead of updating the same image (see the revision field). 👑

🦋 Running virt-builder against multiple sources

Okay so you can use multiple sources with virt-builder, and the recommended way is to deploy .conf files pointing at the index files. Another way is to just specify the sources using multiple --source and/or --fingerprint options:

virt-builder \
  --source http://example.com/s1/index.asc \
  --source http://example.com/s2/index.asc

You can provide N or 1 fingerprints. If you provide N fingerprints, then N = number of sources, and there's a 1-1 correspondence between each source and each fingerprint:

virt-builder \
  --source http://example.com/s1/index.asc --fingerprint '0123 ...' \
  --source http://example.com/s2/index.asc --fingerprint '9876 ...'

If you provide just 1 fingerprint, that same fingerprint gets used for all sources. But — and this is the loud part — you must provide at least 1 fingerprint. ✨

🌸 Licensing of templates

Be aware of the licensing of the images you distribute, bestie. For open source guests, drop a link to the source code in the notes field and comply with the other requirements (eg. around trademarks). Not optional, it's giving legal. 💅

💜 Formal specification of the index file

The index file format has a formal specification, defined by the flex scanner and bison parser used to parse the file. You can find it in these files in the libguestfs source tree:

builder/index-scan.l
builder/index-parse.y

There's also a tool called virt-index-validate(1) that validates the index file and makes sure it's correct. 🎀

Note that the parser and the tool can work on either the signed or the unsigned index file (ie. index or index.asc).

The index is always encoded in UTF-8. No cap. 🌈

🧚 CACHING 🧚

Caching templates

Since templates are usually very large, downloaded templates get cached in the user's home directory. The cache lives at $XDG_CACHE_HOME/virt-builder/ or $HOME/.cache/virt-builder. 🍓

You can print out info about the cache directory — including which guests are currently cached — by doing:

virt-builder --print-cache

Want to free up space? Delete the cache, it's literally one command:

virt-builder --delete-cache

And you can download all the (current) templates to the local cache like this:

virt-builder --cache-all-templates

To disable the template cache entirely, use --no-cache. 🙅‍♀️

Only templates are cached. The index and detached digital signatures are not cached. Just so you know. 💀

Caching packages

virt-builder uses curl(1) to download files, and it also uses the current http_proxy (etc) settings when installing packages (--install, --update). So you probs want to set those environment variables to maximize the amount of local caching that happens. See ENVIRONMENT VARIABLES and curl(1). ✨

Local mirrors

To boost both speed and reliability of installing packages, you can set up a local mirror of the target distribution and point the guest package manager at it. Big brain move, honestly. 🧠

Using a local mirror with Fedora

To install a Fedora guest using a local mirror:

virt-builder fedora-41 \
  --edit '/etc/yum.repos.d/fedora.repo:
      s{.*baseurl=.*}{baseurl=http://example.com/mirror/};
      s{.*metalink=.*}{};
  ' \
  --edit '/etc/yum.repos.d/fedora-updates.repo:
      s{.*baseurl=.*}{baseurl=http://example.com/mirror-updates/};
      s{.*metalink=.*}{};
  ' \
  --run-command 'dnf -y update' \
  --install 'pkg1,pkg2,...'

Using a local mirror with Debian

Assuming you're using apt-proxy to mirror the repository, you should create a new sources.list file pointing to your proxy (see https://help.ubuntu.com/community/AptProxy) and then do:

virt-builder debian-8 \
  --upload sources.list:/etc/apt/sources.list \
  --run-command 'apt-get -y update' \
  --install 'pkg1,pkg2,...'

🔐 DIGITAL SIGNATURES 🔐

virt-builder uses GNU Privacy Guard (GnuPG or gpg) to verify that the index and templates haven't been tampered with. Periodt. 🫶

The source points to an index file, which is optionally signed.

virt-builder downloads the index and checks that the signature is valid and that the signer's fingerprint matches the specified fingerprint (ie. the one specified in gpgkey=.. in the .conf, or with --fingerprint — in that order). 👑

For checking against the built-in public key/fingerprint, this requires importing the public key into the user's local gpg keyring (that's just the way that gpg works, bestie, don't shoot the messenger 😭).

When a template is downloaded, its signature is checked in exactly the same way. ✨

Although the signatures are optional, if you don't have them then virt-builder users will have to use --no-check-signature on the command line. This prevents an attacker from replacing the signed index file with an unsigned one and having virt-builder silently work without checking the signature. In any case it is highly recommended that you always create signed index and templates. 💅

🖥️ ARCHITECTURE 🖥️

virt-builder can build a guest for any architecture no matter what the host architecture is. Like, an x86-64 guest on an ARM host. Iconic. 💜

But certain options may not work — specifically options that require running commands in the guest during the build process: --install, --update, --run, --run-command. You may need to replace these with their firstboot-equivalents. 🌸

An x86-64 host building 32 bit i686 guests should work without any special steps. Slay. ✨

🛡️ SECURITY 🛡️

virt-builder does not need to run as root (in fact, should not be run as root), and doesn't use setuid, sudo or any similar mechanism. We love a low-privilege queen. 👑

--install, --update, --run and --run-command are implemented using an appliance (a small virtual machine) so these commands do not run on the host. If you're using the libguestfs libvirt backend and have SELinux enabled, then the virtual machine is additionally encapsulated in an SELinux container (sVirt). 🎀

However — these options will have access to the host's network, and since the template may contain untrusted code, that code might try to access host network resources which it should not. You can use --no-network to prevent this. 🚨

Firstboot commands run in the context of the guest when it's booted, so the security of your hypervisor / cloud should be considered. Fr fr. 😭

virt-builder injects a random seed into every guest which it builds. This helps ensure that TCP sequence numbers, UUIDs, ssh host keys etc. are truly random when the guest boots. 🔥

You should check digital signatures and not ignore any signing errors. That's the whole point, bestie. 💅

👯 CLONES 👯

If you want to create many new guests of the same type, it is so tempting to run virt-builder once and then copy the output file. Do not do this. 😤 You should run virt-builder once for each new guest you need.

The reason? Each clone needs to have (at least) a separate random seed, and possibly other unique features (such as filesystem UUIDs) in future versions of virt-builder. So no bulk-copying your way out of this one. 🙈

Another thing you should not do is boot the guest and then clone the booted disk image. Why? Because some guests cook up unique machine IDs, SSH host keys and all that jazz the very first time they boot — and you do not want your clones walking around with duplicate identities. That's giving identity theft, bestie. 🙈

🚀 PERFORMANCE

Okay so the single most important thing for good performance is caching. Templates get downloaded into the cache the first time they're used, or if you pass --cache-all-templates. Scroll up to "CACHING" for the whole tea. 💅

Packages needed for --install and --update are downloaded using the host's network connection. So if you set the http_proxy, https_proxy and ftp_proxy environment variables to point at a local web cache, you can make sure they only ever get downloaded once. You can also try a local package repository, though ngl that can be complex to set up and it varies depending on which Linux distro you're installing. 😭

Using `--no-sync`

Use --no-sync. But please read the caveats in the "OPTIONS" section above first, because if you don't use it correctly it can cause disk corruption. Not cute. 💀

Skipping virt-resize

Virt-builder can skip the virt-resize step under certain conditions, which makes it much faster. The conditions are:

the output must be a regular file (not a block device), and
the user did not use the --size option, and
the output format is the same as the template format (usually raw).

pxzcat

Virt-builder uses an internal implementation of pxzcat (parallel xzcat) if liblzma was found at build time. If liblzma was not found at build time, regular xzcat is used instead, which is single-threaded. Sad but true. 🐌

🛡️ SELINUX

Guests that use SELinux (hello Fedora and Red Hat Enterprise Linux 👋) require that every single file has a correct SELinux label.

Virt-builder doesn't know how to give new files a label, so there are two possible strategies it can use to make sure everything gets labelled properly:

Automatic relabeling

This runs setfiles(8) right before finalizing the guest, which sets the SELinux labels correctly inside the disk image.

This is the recommended method. ✨ Periodt.

Using `--no-selinux-relabel --touch /.autorelabel`

Guest templates may already contain a file called /.autorelabel, or you can touch it yourself.

For guests that use SELinux, this causes restorecon(8) to run at first boot. Guests will reboot themselves once the first time you use them — which is normal and harmless, don't panic. 🫶

💀 DEPRECATED OPTIONS

In version 1.56 the subscription-manager options were removed. Gone. Not coming back.

--sm-credentials
--sm-register — instead, use --run='subscription-manager register --username=USER --password=PASS'
--sm-unregister — instead, use --run='subscription-manager unregister'
--sm-attach — instead, use --run='subscription-manager attach ...'
--sm-remove — instead, use --run='subscription-manager remove --all'

🤖 MACHINE READABLE OUTPUT

The --machine-readable option makes the output more machine-friendly, which is iconic when you're calling virt-builder from other programs, GUIs, etc. 👑

Use the option on its own to query the capabilities of the virt-builder binary. Typical output looks like this:

 $ virt-builder --machine-readable
 virt-builder
 arch
 config-file
 customize
 json-list
 pxzcat

A list of features is printed, one per line, and the program exits with status 0. Easy.

It's also possible to specify a format string for controlling the output — see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).

🌈 ENVIRONMENT VARIABLES

For other environment variables that affect all libguestfs programs, see "ENVIRONMENT VARIABLES" in guestfs(3).

"http_proxy", "https_proxy", "no_proxy" — set the proxy for downloads. Fun fact: these environment variables (and more) are actually interpreted by curl(1), not virt-builder. Take it up with curl. 💅
"HOME" — used to determine the location of the template cache, and the location of the user' sources. See "CACHING" and "SOURCES OF TEMPLATES".
"VIRT_TOOLS_DATA_DIR" — this can point to the directory containing data files used for Windows firstboot installation.

Normally you don't need to set this. If it's not set, a compiled-in default gets used (something like /usr/share/virt-tools).

This directory may contain the following files:

rhsrvany.exe — this is the RHSrvAny Windows binary, used to install a "firstboot" script in Windows guests. It's required if you intend to use the --firstboot or --firstboot-command options with Windows guests.

pvvxsvc.exe — this is a Windows binary shipped with SUSE VMDP, used to install a "firstboot" script in Windows guests. It's required if you intend to use the --firstboot or --firstboot-command options with Windows guests.

"XDG_CACHE_HOME" — used to determine the location of the template cache. See "CACHING".
"XDG_CONFIG_HOME" — used to determine the location of the user' sources. See "SOURCES OF TEMPLATES".
"VIRT_BUILDER_DIRS" — used to determine the location of the system sources. See "SOURCES OF TEMPLATES".

🎯 EXIT STATUS

This program returns 0 if successful, or non-zero if there was an error. Simple as that. ✨

👑 AUTHOR

Richard W.M. Jones http://people.redhat.com/~rjones/

🎀 COPYRIGHT

📜 LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Okay so that's the legal bit and it's not the fun part, but it is the part that says you're free to share and remix this — so honestly? Iconic behaviour. 🫶

🐛 BUGS

To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

When reporting a bug, please supply:

The version of libguestfs.
Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
Describe the bug accurately and give a way to reproduce it.
Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report.

and that's the whole page bestie!! 💖✨ This little beauty is from guestfs-tools-1.57.3, dated 2026-09-16, and it's virt-builder(1) — go build yourself a cute little guest, ily, mwah 🎀🦋💜

📦 where this page comes from

centos-stream 10: guestfs-tools 1.57.3-1.el10 · GPL-2.0-or-later AND LGPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms