Provided by: xen-tools_4.2.1-1_all bug

NAME

       xen-create-image - Easily create new Xen instances with networking and OpenSSH.

SYNOPSIS

         Help Options:

          --help       Show the help information for this script.

          --manual     Read the manual, and examples, for this script.

          --verbose    Show useful debugging information.

          --version    Show the version number and exit.

         Size / General options:

          --accounts   Copy all non-system accounts to the guest image

          --admins     Specify that some administrators should be created for
                       this image, using xen-shell.

          --boot       Boot the new instance after creating it.

          --cache=bool Cache .deb files on the host when installing the new
                       guest with the debootstrap tool. Accepted values:
                       "yes" (default) and "no".

          --cachedir=/path/to/cache/directory
                       Override the default .deb cache directory. Defaults to
                       /var/cache/apt/archives/ if it exists (i.e. on Debian
                       and Ubuntu) and /var/cache/xen-tools/archives/ else
                       (i.e. on Fedora and CentOS).

          --config=file
                       Read the specified file in addition to the global
                       configuration file.

          --copyhosts  Copy entries from the dom0's /etc/hosts file to the guest

          --copy-cmd   NOP:  Ignored.

          --debootstrap-cmd=/path/to/command
                       Specify which debootstrap command is used. Defaults to
                       debootstrap if both, debootstrap and cdebootstrap are
                       installed. Specifying the path is optional.

          --disk_device=diskname
                       Use specified device name for virtual devices instead of
                       the default value "xvda".

          --extension=ext
                       Specify the suffix to give the Xen configuration
                       file. (Default value: ".cfg")

          --force      Force overwriting existing images. This will remove
                       existing images or LVM volumes which match those which
                       are liable to be used by the new invocation.

          --fs=fs      Specify the filesystem type to use for the new guest.
                       Valid choices are 'ext2', 'ext3', 'ext4', 'reiserfs',
                       'xfs' or 'btrfs'. (Note: pygrub *DOES NOT* support xfs)

          --genpass=1  Generate a random root password (default, set to 0 to turn off)

          --genpass_len=N
                       Override the default password length of 8 and generate a
                       random password of length N. Note: this only works in
                       conjunction with --genpass

          --hash_method=algorithm
                       Override the default hashing method of sha256 and use the
                       provided algorithm. Can be : md5, sha256 or sha512

          --hooks=1    Specify whether to run hooks after the image is created.

          --ide        Use IDE names for virtual devices (i.e. hda not xvda)

          --image=str  Specify whether to create "sparse" or "full" disk images.
                       Full images are mandatory when using LVM, so this setting
                       is ignored in that case.

          --image-dev=/path/to/device
                       Specify a physical/logical volume for the disk image.

          --initrd=/path/to/initrd
                       Specify the initial ramdisk. If an image is specified it
                       must exist.

          --install=1  Specify whether to install the guest system or not.

          --keep       Don't delete our images if installation fails.

          --kernel=/path/to/kernel
                       Set the path to the kernel to use for domU. If a
                       kernel is specified it must exist.

          --memory=size
                       Setup the amount of memory allocated to the new instance.

          --modules=/path/to/modules
                       Set 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.

          --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 Specify 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.  Parameters
                       fs, size, swap and noswap are ignored when using this
                       option.

          --password=passphrase
                       Set the root password for the new guest.

          --passwd     Ask for a root password interactively during setup.
                       NOTE:  This overrides --genpass --password

          --pygrub     DomU should be booted using pygrub.

          --role=role  Run 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"
                       Pass the named string literally to any role script.
                       This is useful for site-specific roles.

          --roledir=/path/to/directory
                       Specify the directory which contains the role scripts.
                       This defaults to /etc/xen-tools/role.d/

          --scsi       Use SCSI names for virtual devices (i.e. sda not xvda)

          --serial_device=serialname
                       Install a getty on the specified serial device instead
                       of the default device.

          --size=size  Set the size of the primary disk image.

          --swap=size  Set the size of the swap partition.

          --swap-dev=/path/to/device
                       Specify a physical/logical volume for swap usage.

          --tar-cmd    NOP: Ignored.

          --vcpus=num
                       Set the number of vcpus that the new instance will have
                       instead of the default value of "1".

         Installation options:

          --arch=arch  Pass the given architecture to debootstrap, rinse,
                       or rpmstrap when installing the system.  This argument
                       is ignored for other install methods.

          --dist=dist  Specify the distribution you wish to install.

          --install-method=method
                       Specify 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
                       Specify the source path to use when installing via
                       a copy or tarball installation.

          --mirror=url Setup the mirror to use when installing via
                       debootstrap. (Default value: mirror used in
                       /etc/apt/sources.list or for Debian
                       "http://cdn.debian.net/debian/" and for Ubuntu
                       "http://archive.ubuntu.com/ubuntu/")

                       The above mentioned Debian mirror hostname uses GeoIP
                       to choose a more or less close Debian mirror. See
                       http://wiki.debian.org/DebianGeoMirror for details.

          --template=tmpl
                       Specify 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
                       Setup the broadcast address for the new instance.

          --dhcp       The guest will be configured to fetch its networking
                       details via DHCP.

          --gateway=gw Setup the network gateway for the new instance.

          --ip=123.456.789.ABC
                       Setup the IP address of the machine, multiple IPs are
                       allowed.  When specifying more than one IP the first
                       one is setup 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
                       Specify the MAC address to use for a given interface.
                       This is only valid for the first IP address specified,
                       or for DHCP usage.  (ie. you can add multiple --ip
                       flags, but the specific MAC address will only be used
                       for the first interface.)

          --netmask=123.456.789.ABC
                       Setup the netmask for the new instance.

          --nameserver="123.456.789.ABC 123.456.789.DEF"
                       Setup the nameserver of the machine, multiple space
                       separated nameservers are allowed.
                       If not provided, Dom0's /etc/resolv.conf will be copied
                       to guest.

          --vifname=vifname
                       Optionally, set a specific vif name for the new instance.

         Mandatory options:

          --dir=/path/to/directory
                       Specify where the output images should go.
                       Subdirectories will be created for each guest
                       If you do not wish to use loopback images specify --lvm
                       or --evms.  (These three options are mutually exclusive.)

          --evms=lvm2/container
                       Specify the container to save images within, i.e. '--evms
                       lvm2/mycontainer'.  If you do not wish to use EVMS specify
                       --dir or --lvm.  (These three options are mutually exclusive.)

          --hostname=host.example.org
                       Set the hostname of the new guest system.  Ideally
                       this will be fully-qualified since several of the hook
                       scripts will expect to be able to parse a domain name
                       out of it for various purposes.

          --lvm=vg     Specify the volume group to save images within.
                       If you do not wish to use LVM specify --dir or --evms.
                       (These three options are mutually exclusive.)

NOTES

         This script is a wrapper around three distinct external tools which
        complete various aspects of the new system installation.

       xt-install-image Install a new distribution.
       xt-customize-image Run a collection of hook scripts to customise the freshly installed
       system.
       xt-create-xen-config Create a Xen configuration file in so that xm can start the new
       domain.

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

DESCRIPTION

         xen-create-image is a simple script which allows you to create new
        Xen instances easily.  The new image will be given two volumes.  These
        volumes will be stored upon the host as either loopback files, or
        LVM logical volumes:

          1.  An image for the systems root disk.
          2.  An image for the systems 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.

         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.

         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
         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.

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.

         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.

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 with 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.

         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.

            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.

         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

         The new guest images may be installed in several different ways:

         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.

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.

         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.

         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.

         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 distrubtions only. They are included
        primarily as examples of the kind of things you could accomplish.

         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 allong as additional arguments.

         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.

         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

        Steve Kemp, http://www.steve.org.uk/
        Axel Beckert, http://noone.org/abe/
        Dmitry Nedospasov, http://nedos.net/
        StA~Xphane Jourdois

LICENSE

       Copyright (c) 2005-2009 by Steve Kemp, (c) 2010 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.