XEN-CREATE-IMAGE(8)

📦
version 4.9.2 · 4 versions
, in debian bookworm, ubuntu noble

💖 xen-create-image(8) 💖

okay bestie, welcome to the manual page for xen-create-image, straight outta the Perl Programmers Reference Guide. She's a section 8 (system admin) girlie and she's here to make your life so much easier. 🫶

✨ NAME ✨

xen-create-image — literally the easiest way to spin up brand-new Xen instances, networking and OpenSSH included, no cap. 🎀

🌸 SYNOPSIS 🌸

xen-create-image --hostname=<hostname> <further options>

🦋 EXAMPLES 🦋

Obsessed with how simple this is. Look:

xen-create-image --hostname=some-domu --dist=wheezy --lvm=vg0
xen-create-image --hostname=some-domu --dist=precise --dir=/srv/xen

And if you want the extra detailed tea, scroll down to LOOPBACK EXAMPLES, LVM EXAMPLE and EVMS EXAMPLE below. iykyk. 💅

👑 OPTIONS 👑

💅 Help Options

  • --help — shows you the help info for this script. your lil emergency contact. 🆘
  • --manual — reads you the manual and the examples for this script. she's thorough.
  • --(no)verbose — (don't) spill more about what xen-create-image is doing right now. main character narration, honestly.
  • --dumpconfig — dumps the current configuration so you can see what's what. 👀
  • --version — shows the version number and then dips. bye bestie. 👋

🌈 Size / General options

  • --(no)accounts — (don't) copy all the non-system accounts over to the guest image. bringing the whole friend group.
  • --admins — says that some administrators should be created for this image, using xen-shell.
  • --(no)boot — (don't) boot the new instance right after creating it. no pressure, she can wait. 😴
  • --cache=bool — caches .deb files on the host when installing the new guest with the debootstrap tool. accepted values: "yes" (the default, periodt) and "no".
  • --cachedir=/path/to/cache/directory — overrides the default .deb cache directory. it defaults to /var/cache/apt/archives/ if that exists (aka on Debian and Ubuntu) and /var/cache/xen-tools/archives/ otherwise (aka on Fedora and CentOS).
  • --config=file — reads the file you name in addition to the global configuration file. the more the merrier. 💖
  • --(no)copyhosts — (don't) copy the entries from the dom0's /etc/hosts file over to the guest.
  • --copy-cmd — NOP: ignored. she's just standing there. 💀
  • --debootstrap-cmd=/path/to/command — picks which debootstrap command gets used. defaults to debootstrap if both debootstrap and cdebootstrap are installed. specifying the path is optional.
  • --disk_device=diskname — uses the device name you give for virtual devices instead of the default value "xvda".
  • --extension=ext — the suffix to give the Xen configuration file. (default value: ".cfg")
  • --(no)force — (don't) force overwriting existing images. ⚠️ heads up: this will remove existing images or LVM volumes which match those that are liable to be used by the new invocation. so like, be sure, bestie.
  • --fs=fs — the filesystem type for the new guest. valid choices are 'ext2', 'ext3', 'ext4', 'reiserfs', 'xfs' or 'btrfs'. (note: pygrub DOES NOT support xfs) 🚨
  • --genpass=1 — generates a random root password (default; set it to 0 to turn it off).
  • --genpass_len=N — overrides the default password length of 8 and generates a random password of length N. note: this only works in conjunction with --genpass.
  • --hash_method=algorithm — overrides the default hashing method of sha256 and uses the algorithm you provide. can be: md5, sha256 or sha512.
  • --hooks=1 — says whether to run hooks after the image is created.
  • --ide — uses IDE names for virtual devices (so hda, not xvda). vintage vibe. 🙈
  • --image=str — whether to create "sparse" or "full" disk images. full images are mandatory when using LVM, so this setting just gets ignored in that case.
  • --image-dev=/path/to/device — a physical/logical volume for the disk image.
  • --initrd=/path/to/initrd — the initial ramdisk. if an image is specified it must exist, fr fr.
  • --install=1 — says whether to install the guest system or not.
  • --(no)keep — (don't) keep our images if installation fails. it maybe is unmounted, though. 😭
  • --keyring=/path/to/keyring — sets the path to the keyring debootstrap should use.
  • --kernel=/path/to/kernel — sets the path to the kernel to use for domU. if a kernel is specified it must exist.
  • --memory=size — sets the amount of memory allocated to the new instance. recognized size unit suffixes are "M", "MB", "G" and "GB" (case does not matter). if there's no unit given, megabytes are assumed.
  • --maxmem=size — sets the maximum amount of memory that can be allocated to the new instance. recognized size unit suffixes are "M", "MB", "G" and "GB" (case does not matter). if there's no unit given, megabytes are assumed. required for dynamic memory ballooning. 🎈
  • --modules=/path/to/modules — sets the path to the kernel modules to use for domU. if modules are specified they must exist.
  • --nohosts — don't touch /etc/hosts on the dom0. hands off. 🙅
  • --noswap — do not create a swap partition. when this option is used the system will not have a swap entry added to its /etc/fstab file either.
  • --output=dir — the output directory to create the xen configuration file within.
  • --partitions=file — use a specific partition layout configuration file. see /etc/xen-tools/partitions.d/sample-server for an example partitioning configuration. ⚠️ not supported with the image-dev and swap-dev options. the parameters fs, size, swap and noswap are ignored when using this option.
  • --password=passphrase — sets the root password for the new guest. note: this overrides --genpass.
  • --(no)passwd — (don't) ask for a root password interactively during setup. NOTE: this overrides --genpass --password. so like, pick your fighter. 💅
  • --(no)pygrub — domU should (not) be booted using pygrub.
  • --role=role — runs the specified role script(s) post-install. role scripts are discussed later in this manpage. can be an absolute path. otherwise it's relative to the value of --roledir.
  • --role-args="--arg1 --arg2" — passes the named string literally to any role script. this is useful for site-specific roles.
  • --finalrole=role — similar to role scripts. runs the specified role script(s) after cfg file creation.
  • --roledir=/path/to/directory — the directory which contains the role scripts. this defaults to /etc/xen-tools/role.d/.
  • --scsi — uses SCSI names for virtual devices (so sda, not xvda).
  • --serial_device=serialname — installs a getty on the specified serial device instead of the default device.
  • --size=size — sets the size of the primary disk image.
  • --swap=size — sets the size of the swap partition.
  • --swap-dev=/path/to/device — a physical/logical volume for swap usage.
  • --tar-cmd — NOP: ignored. she said nothing, she knows nothing. 💀
  • --dontformat — do not format the devices specified for installation. useful if you want tighter control over the filesystem creation. requires the filesystems to be created beforehand.
  • --vcpus=num — sets the number of vcpus that the new instance will have, instead of the default value of "1".

🧚 Installation options

  • --arch=arch — passes the given architecture to debootstrap, rinse, or rpmstrap when installing the system. this argument is ignored for other install methods.
  • --dist=dist — the distribution you wish to install. 🍓
  • --install-method=method — the installation method to use. valid methods are:
    • debootstrap
    • cdebootstrap
    • rinse
    • rpmstrap (deprecated)
    • tar (needs --install-source=tarball.tar)
    • copy (needs --install-source=/path/to/copy/from)

(default value for Debian and Ubuntu: debootstrap)

  • --install-source=/path/to/tarball — the source path to use when installing via a copy or tarball installation.
  • --mirror=url — sets up the mirror to use when installing via debootstrap. (default value: mirror used in /etc/apt/sources.list or, for Debian, http://deb.debian.org/debian/ and for Ubuntu, http://archive.ubuntu.com/ubuntu/)

the above mentioned Debian mirror hostname automatically tries to choose a more or less close Debian mirror. see http://deb.debian.org/ for details.

  • --apt_proxy=protocol://hostname:port/ — a proxy to be used by debootstrap, and within the guest. needs the same syntax as APT's Acquire::http::Proxy. see apt.conf(5).
  • --template=tmpl — which template file to use when creating the Xen configuration file.

🎀 Networking options

  • --bridge=brname — optionally, set a specific bridge for the new instance. this can be especially useful when running multiple bridges on a dom0.
  • --broadcast=123.456.789.ABC — sets up the broadcast address for the new instance.
  • --(no)dhcp — the guest will (not) be configured to fetch its networking details via DHCP.
  • --gateway=gw — sets up the network gateway for the new instance.
  • --ip=123.456.789.ABC — sets up the IP address of the machine; multiple IPs are allowed. when specifying more than one IP, the first one is set up as the "system" IP, and the additional ones are added as aliases.
⚠️ note that Xen 3.x supports a maximum of three vif statements per guest. this option conflicts with --dhcp.
  • --mac=AA:BB:CC:DD:EE:FF — tells it which MAC address to slap on a given interface. Heads up tho: this only works for the first IP address you specify, or for DHCP usage. (Like, you can add multiple --ip flags, but the specific MAC address only gets used for the first interface. iykyk. 💅)
  • --randommac — literally just makes a random MAC address for you. chaos but cute.
  • --netmask=123.456.789.ABC — sets up the netmask for the new instance.
  • --nameserver="123.456.789.ABC 123.456.789.DEF" — sets up the nameserver of the machine. You can list multiple ones, space separated, no biggie. ✨ If you don't provide this, Dom0's /etc/resolv.conf gets copied over to the guest. so it inherits the vibe.
  • --vifname=vifname — optionally sets a specific vif name for the new instance.
  • --vlan=1 — this one's OpenvSwitch related 🫶 and optionally lets you specify a vlan where the virtual machine has connectivity.

✨ Mandatory options ✨

these ones? not optional bestie. you need them.

  • --dir=/path/to/directory — tells it where the output images should go. Subdirectories get created for each guest, one per hostname. If you don't wanna use loopback images, go for --lvm, --evms or --zpool instead. (These four options are mutually exclusive, so pick ONE. 💀)
  • --evms=lvm2/container — specifies the container to save images within, like --evms lvm2/mycontainer. If you don't wanna use EVMS, use --dir, --lvm or --zpool instead. (These four options are mutually exclusive.)
  • --hostname=host.example.org — sets the hostname of the new guest system. Ideally this should be fully-qualified because several of the hook scripts will expect to be able to parse a domain name out of it for various purposes. so like, give it the whole thing, not just the nickname. 👑
  • --lvm=vg — specifies the volume group to save images within. If you don't wanna use LVM, use --dir, --evms or --zpool instead. (These three options are mutually exclusive.)
  • --lvm_thin=thin pool — specifies the thin pool name on which thin LVM volumes get created. This enables thin provisioned LVM volumes. Fair warning: you need a LVM version that actually supports this, so check first fr fr.
  • --zpool=pool — specifies the ZFS pool to save images within. A brand new ZFS volume gets created for each guest. If you don't wanna use ZFS, use --dir, --evms or --lvm instead. (These four options are mutually exclusive.)

🌸 NOTES 🌸

This script is basically a wrapper around three distinct external tools that each handle different aspects of the new system installation. the holy trinity 💖

  • xt-install-image — installs a new distribution.
  • xt-customize-image — runs a collection of hook scripts to customise the freshly installed system.
  • xt-create-xen-config — creates a Xen configuration file so that xm/xl can start the new domain.

The result of invoking these three scripts, plus some minor glue between them, is a simple means of creating new Xen guest domains. iconic behaviour honestly.

🦋 DESCRIPTION 🦋

xen-create-image is a simple script that lets you create new Xen instances easily. The new image gets given two volumes, and those volumes are stored upon the host as either loopback files, or LVM logical volumes:

  1. An image for the system's root disk.
  2. An image for the system's swap device.

The new virtual installations will be configured with networking, have OpenSSH installed upon it, and have most of its basic files setup correctly. ready to go, no cap.

If you wish you can configure arbitrary partitioning schemes, rather than being restricted to just the two standard volumes. For more details on this please see the later section in this manual "PARTITIONING".

If you wish to install additional packages or do any additional configuration of your new guests, please read the section on "ROLES". 🌈

🎀 CONFIGURATION 🎀

To reduce the length of the command line, each of the supported options may be specified inside a configuration file. because typing out 40 flags is giving carpal tunnel 💅

The global configuration file read for options is:

/etc/xen-tools/xen-tools.conf

The configuration file may contain comments which begin with the hash # character. Otherwise the format is key = value.

A sample configuration file would look like this:

#
#  Output directory.  Images are stored beneath this directory, one
# subdirectory per hostname.
#
dir = /home/xen

#
#  LVM users should disable the 'dir' setting above, and instead
# specify the name of the volume group to use.
#
# lvm = myvolume

#
#  EVMS users should disable the dir setting above and instead specify
# a container.  For example, if you have an lvm2 container named box,
# put lvm2/box.  This is how it is named in the evms interface.
#
#  Warning... this has not been tested with anything but lvm2 but should
# be generalizable.
#
# evms= lvm2/myvolume

#
#  Disk and Sizing options.
#
size       = 2Gb      # Disk image size.
image      = full     # Allocate the full disk size immediately.
memory     = 128Mb    # Memory size
maxmem     = 512Mb    # Memory size
swap       = 128Mb    # Swap size
fs         = ext3     # use EXT3 filesystems
dist       = stable   # Default distribution to install.

#
# Kernel options.
#
kernel      = /boot/vmlinuz-`uname -r`
initrd      = /boot/initrd.img-`uname -r`

#
# Networking options.
#
gateway    = 192.168.1.1
broadcast  = 192.168.1.255
netmask    = 255.255.255.0

#
# Installation method:
# One of "copy", "debootstrap", "cdebootstrap", "rinse", "rpmstrap", or "tar".
#
install-method = debootstrap

Using this configuration file, a new image may be created with the following command:

xen-create-image --hostname=vm03.my.flat --ip=192.168.1.201

This makes use of loopback images stored beneath /home/xen and will be installed via the debootstrap command. so easy it's lowkey unfair. ✨

💜 NETWORKING AUTO-SETUP 💜

We've already seen how the "gateway" and "netmask" options can be used to specify the networking options of the freshly created Xen guests.

One other useful shortcut is the use of an automatic IP address. You can specify --ip=auto and the system will choose and use an IP address from those listed in /etc/xen-tools/ips.txt. autopilot mode activated 🦋

For example, if you wished to have Xen guests automatically take an address from the range 192.168.1.100-192.168.1.200 you would first prepare the system by running this:

rm /etc/xen-tools/ips.txt
for i in $(seq 100 200) ; do echo 192.168.1.$i >> /etc/xen-tools/ips.txt ; done

Now you can create a guest with the command:

xen-create-image --ip=auto --hostname=blah [--dist=...]

The first time this ran, the machine would receive an IP address from the pool which we've created. This IP would be marked as used, and would no longer be available. If all the IP addresses are taken then the system will fail. 💀 so like, keep an eye on that pool bestie.

🌈 PARTITIONING 🌈

By default, all new guests are created with two "volumes", one for the root filesystem and one for the new system's swap.

If you wish you may specify an alternative partitioning scheme. Simply create a file inside the directory /etc/xen-tools/partitions.d/ specifying your partition layout. (Use the existing file sample-server as a template.)

Now when you create a new image, specify the name of this file as an argument to the --partition option. 🎀

👑 XEN CONFIGURATION FILE 👑

Once a new image has been created, an appropriate configuration file for Xen will be saved in the directory /etc/xen by default. However, you may change the output directory with the --output flag.

The configuration file is built up using the template file /etc/xen-tools/xm.tmpl — which is a file processed via the Text::Template perl module. perl module moment, periodt.

If you wish to modify the files which are generated, please make your changes to that input file.

Alternatively, you can create multiple configuration files and specify the one to use with the --template option. ✨

🫶 LOOPBACK EXAMPLES 🫶

The following will create a 2Gb disk image, along with a 128Mb swap file, with Debian Stable setup and running via DHCP. a lil baby vm, precious.

xen-create-image --size=2Gb --swap=128Mb --dhcp --dist=stable \
     --dir=/home/xen --hostname=vm01.my.flat

This next example sets up a host which has the name vm02.my.flat and IP address 192.168.1.200, with the gateway address of 192.168.1.1:

xen-create-image --size=2Gb --swap=128Mb \
     --ip=192.168.1.200 \
     --netmask=255.255.255.0
     --gateway=192.168.1.1 \
     --nameserver=192.168.1.1 \
     --dir=/home/xen --hostname=vm02.my.flat

The directory specified for the output will be used to store the volumes which are produced. To avoid clutter, each host will have its images stored beneath the specified directory, named after the hostname. organized queen energy 💅

For example, the images created above will be stored as:

$dir/domains/vm01.my.flat/
$dir/domains/vm01.my.flat/disk.img
$dir/domains/vm01.my.flat/swap.img

$dir/domains/vm02.my.flat/
$dir/domains/vm02.my.flat/disk.img
$dir/domains/vm02.my.flat/swap.img

The /domains/ subdirectory will be created if necessary.

💖 LVM EXAMPLE 💖

If you wish to use an LVM volume group instead of a pair of loopback images as shown above, you can instead use the --lvm argument to specify one.

xen-create-image --size=2Gb --swap=128Mb --dhcp \
     --lvm=myvolumegroup --hostname=vm01.my.flat

The given volume group will have two new logical volumes created within it:

${hostname}-swap
${hostname}-disk

The disk image may be mounted, as you would expect, with the following command:

mkdir -p /mnt/foo
mount /dev/myvolumegroup/vm01.my.flat-disk /mnt/foo

🍓 EVMS EXAMPLE 🍓

If you wish to use an EVMS storage container instead of a pair of loopback images as shown above, you can instead use the --evms argument to specify one. The below example assumes an lvm2 container.

xen-create-image --size=2Gb --swap=128Mb --dhcp \
     --evms=lvm2/myvolumegroup --hostname=vm01.my.flat

The given storage container will have two new EVMS volumes created within it:

${hostname}-swap
${hostname}-disk

The disk image may be mounted, as you would expect, with the following command:

mkdir -p /mnt/foo
mount /dev/evms/vm01.my.flat-disk /mnt/foo

💾 INSTALLATION METHODS 💾

okay so bestie, your new guest images can be installed in a few different ways, and it's giving choose-your-own-adventure:

  1. Using the [c]debootstrap command, which must be installed and present.
  2. Using the rpmstrap command, which must be installed and present.
  3. using the rinse command, which must be installed and present.
  4. By copying an existing installation.
  5. By untarring a file containing a previous installation.

These different methods can be selected by either the command line arguments, or settings in the configuration file. Only one installation method may be specified at a time; they are mutually-exclusive. no mixing, babe.

🚀 INSTALLATION SPEEDUPS 🚀

After performing your first installation you can customize it, or use it untouched, as a new installation source. By doing this you'll achieve a significant speedup, even above using the debootstrap caching support. it's giving speedrun strats.

There are two different ways you can use the initial image as source for a new image:

  1. By tarring it up and using the tar-file as an installation source.
  2. By mounting the disk image of the first system and doing a literal copy.

Tarring up a pristine, or customised, image will allow you to install with a command such as:

xen-create-image --size=2Gb --swap=128Mb --dhcp \
     --lvm=myvolumegroup --hostname=vm01.my.flat \
     --install-method=tar --install-source=/path/to/tar.file.tar

The advantage of the tarfile approach is that you'll not need to keep a disk image mounted if you were to use the --copy argument to create a new image using the old one as source:

xen-create-image --size=2Gb --swap=128Mb --dhcp \
     --lvm=myvolumegroup --hostname=vm01.my.flat \
     --install-method=copy --install-source=/path/to/copy/from

📦 DEBOOTSTRAP CACHING 📦

When installing new systems with the debootstrap tool there is a fair amount of network overhead. ugh, the bandwidth bills.

To minimize this the .deb files which are downloaded into the new instance are cached by default upon the host, in the directory /var/cache/apt/archives or, if this does not exist, in /var/cache/xen-tools/archives. This can be overridden with the --cache-dir command-line and configuration option.

This feature can be disabled with the command line flag --cache=no, or by the matching setting in the configuration file.

When a new image is created these packages are copied into the new image - before the debootstrap process runs - this should help avoid expensive network reading. iconic behavior, honestly.

If you wish to clean the host's apt cache (/var/cache/apt/archivees) you may do so with apt-get, namely:

apt-get clean

If you set your cache directory to anything else, simply rm the contents of the directory.

🎭 ROLES 🎭

Currently there are some roles scripts included which work for the Debian and Ubuntu distributions only. They are included primarily as examples of the kind of things you could accomplish. cute little starter pack energy.

The supplied scripts are:

  • builder — Setup the new virtual images with commonly used packages for rebuilding Debian packages from their source.
  • cfengine — Install cfengine2 on the virtual image and copy the cfengine configuration from Dom0.
  • editor — Allows generalised editing of files for guests. This script works via a skeleton directory containing small sed files which will contain edits to be applied to an arbitrary tree of files upon the new domU.

For example if we have the following sed file:

/etc/xen-tools/sed.d/etc/ssh/sshd_config.sed

this will be applied to /etc/ssh/sshd_config upon the new guest if it exists. If the file encoded in the name doesn't exist then it will be ignored.

  • gdm — Install an X11 server, using VNC and GDM
  • minimal — Customise the generated images to remove some packages.
  • puppet — Install puppet on the virtual image and copy the cfengine configuration from Dom0.
  • tmpfs — Sets up /tmp, /var/run and /var/lock as tmpfs in the DomU.
  • udev — Install udev in the DomU. Most distributions install udev by default nowadays, so this role is probably only interesting for legacy systems which need udev anyway.
  • xdm — Install an X11 server, using VNC and XDM

If you'd like to include your own role scripts you'll need to create a file in /etc/xen-tools/role.d, and then specify the name of that file with --role=filename. Additionally you may pass options to your role-script with the --role-args flag.

For example the script /etc/xen-tools/role.d/gdm would be used by executing with --role=gdm.

Role scripts are invoked with the directory containing the installed system as their first argument, and anything passed as a role-arg will be passed along as additional arguments.

NOTE: Role scripts are invoked before the config file generation. If you need access to the config file from within your role, use --finalrole.
NOTE: Multiple role scripts may be invoked if you separate their names with commas.

📁 THE SKELETON DIRECTORY 📁

Any files present in the directory /etc/xen-tools/skel will be copied across to each new guest image. The role of this directory is analogous to the /etc/skel directory. it's giving template magic.

A typical use for this would be to copy a public key across to each new system. You could do this by running:

mkdir -p /etc/xen-tools/skel/root/.ssh
chmod -R 700 /etc/xen-tools/skel/root
cp /root/.ssh/id_rsa.pub /etc/xen-tools/skel/root/.ssh/authorized_keys2
chmod 644 /etc/xen-tools/skel/root/.ssh/authorized_keys2

👑 AUTHORS 👑

📜 LICENSE 📜

Copyright (c) 2005-2009 by Steve Kemp, (c) 2010-2013 by The Xen-Tools Development Team. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.

and that's the tea, bestie 💅 this was XEN-CREATE-IMAGE(8) from version 4.9.2, dated 2023-02-06. now go make some iconic VMs, mwah 💖✨

📦 where this page comes from