Provided by: xen-tools_0.8.5-1_all bug

NAME

       xen-create-image - Create a new virtual Debian installation for Xen.

SYNOPSIS

         xen-create-image [options]

         Help Options:
          --debug    Show useful debugging information.
          --help     Show this scripts help information.
          --manual   Read this scripts manual.
          --version  Show the version number and exit.

         Size / General options:
          --boot        Boot the new instance after creating it.
          --debootstrap Pass anything named here onto debootstrap.
          --dir         Specify where the output images should go.
          --dist        Specify the distribution you wish to install: Sarge/Etch/Sid.
          --fs          Specify the filesystem type to use.
          --kernel      Set the path to the kernel to use for dom U.
          --memory      Setup the amount of memory allocated to the instance.
          --mirror      Setup the mirror to use when installing Sarge.
          --passwd      Ask for a root password during setup.
          --role        Run a role-specific script, post-install.
          --size        Set the size of the primary disk image.
          --swap        Set the size of the swap partition.

         Networking options:
          --dhcp      Setup the image to get an IP address via DHCP
          --gateway   Setup the iamge’s network gateway.
          --ip        Setup the ip
          --netmask   Setup the netmask

         Mandatory options:

          --hostname  Set the images hostname.

OPTIONS

       --boot Start the new virtual instance as soon as the installation has
       finished.
       --debug Show the commands this script executes as an aid to debugging.
       --debootstrap Anything specified after this will be passed onto the
       debootstrap command executed.
       --dhcp Specify that the virtual image should use DHCP to obtain its
       networking information.  Conflicts with --ip.
       --dir Specify the root directory beneath which the image should be
       saved.  Subdirectories will be created for each virtual image.
       --dist Specify the distribution to install, defaults to ’sarge’.
       --fs Specify the filesystem the image should be given.  Valid options
       are ’ext3’, ’xfs’, or ’reiserfs’.
       --gateway Specify the gateway address for the virtual image, only
       useful if DHCP is not used.
       --help Show the brief help information.
       --hostname Set the hostname of the new instance.
       --ip Set the IP address for the virtual image.  Conflicts with --dhcp
       --kernel Set the path to the kernel to use for the image.
       --manual Read the manual, with examples.
       --memory Specify the amount of memory the virtual image should be
       allocated.  Defaults to 96Mb.
       --mirror Specify the mirror to use to the installation of Sarge,
       defaults to http://ftp.us.debian.org/debian
       --netmask Set the netmask the virtual image should use.
       --passwd Setup a password for the root account of the virtual machine.
       --role Run a single, specific, role-script once the image has been
       setup.
       --size Specify the size of the primary drive to give the virtual image.
       The size may be suffixed with either Mb, or Gb.
       --swap Specify the size of the virtual swap partition to create.  The
       size may be suffixed with either Mb, or Gb.
       --version Show the version number and exit.

EXAMPLES

         The following will create a 2Gb disk image, along with a 128Mb
        swap file with Debian Sarge setup and running via DHCP.

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

         This next example sets up a host which has the name ’vm02’ 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 \
                 --dir=/home/xen --hostname=vm02

         To save time these command line options may be specified in the
        configuration file discussed later.

         The directory specified for the output will be used to store the files
        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.

DESCRIPTION

         xen-create-image is a simple script which allows you to create new
        Xen instances of Debian Sarge.  The new image will be comprised of
        two seperate files:

          1.  One disk image which will be treated as the primary disk drive.
          2.  One swap image.

         The image will have OpenSSH installed upon it, and an appropriate
        /etc/inittab file created, along with copies of the hosts password
        and shadow files.

CONFIGURATION

         To reduce the length of the command line each of the options may
        be specified inside a configuration file.

         The script will check a global configuration file for options, the
        file 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

        #
        #  Disk and Sizing options.
        #
        size       = 2Gb      # Disk image size.
        memory     = 128Mb    # Memory size
        swap       = 128Mb    # Swap size
        filesystem = ext3     # use EXT3 filesystems
        dist       = sarge    # Default distribution to install.

        #
        # Kernel options.
        #
        kernel     = /boot/vmlinuz-2.6.12-xenU

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

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

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

CACHING

         Because the virtual systems are installed with the debootstrap
        tool there can be a lot of network overhead.

         To minimize this the .deb files which are downloaded into the
        new instance are cached upon the host in the directory
        /var/cache/apt/archives.

         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 cache run on the host:

         apt-get clean

CUSTOMIZATION

         If you wish to add new packages to the image automatically you may
        take advantage of the ’--debootstrap’ option which allows you to
        pass flags to the debootstrap command.

         For the following command causes three new packages to be added
        to the base image:

             xen-create-image --debootstrap=’--include=screen,sudo,less’

         An alternative is to use the hook directory to run a script
        for each new image you create.

         Alternatively you make take advantage of the role support - to
        easily create different types of images for different roles.

HOOKS

         After the image has been installed using debootstrap there is
        the chance for you to run arbitary scripts upon the new host
        before it is unmounted.

         To do this place executable scripts inside the "hook directory"
        /etc/xen-tools/hook.d/.

         Each executable script in this directory will be executed in turn
        and given the name of the mount point the image is available at as
        its single argument.

         The scripts will also have a complete copy of the configuration
        options set in its environment.  For example the IP address would
        be set in $ip, the mirror in $mirror, etc.

         A script could copy some the kernel modules to the new system, and
        install a package, for example:

        #!/bin/sh

        prefix=$1

        # Copy modules
        mkdir -p ${prefix}/lib/modules
        cp -R /lib/modules/2.6.12.6-xen/ ${prefix}/lib/modules

        # Install the package ’module-init-tools’
        DEBIAN_FRONTEND=noninteractive chroot $prefix /usr/bin/apt-get --yes --force-yes install module-init-tools

         The hook scripts are used extensively by this script to setup the
        base system.  If you’re looking at extending the processing of new
        images it is recommended you examine the default hooks.

ROLES

         The scripts which are included in the hook directory are executed
        for every single image you create.  This can allow you to make global
        changes to the generated image very easily, however it doesn’t allow
        you to do different thigns for different types of images.

         Instead the "role" scripts are used for that purpose.  If you
        give an argument "--role=foo" then the script /etc/xen-tools/role.d/foo
        will be executed once the image has been created, after the hooks
        have run.

         This allows you to create different customizations for particular
        image types.  Several role scripts have been included to provide
        examples of different customizations:

       gdm Install an X11 server, using VNC and GDM
       minimal Customise the generated images to remove some packages.
       xdm Install an X11 server, using VNC and XDM

AUTHOR

        Steve
        --
        http://www.steve.org.uk/

        $Id: xen-create-image,v 1.79 2006/01/07 23:23:12 steve Exp $

CONTRIBUTORS

         Contributors to this code:

       Radu Spineanu

LICENSE

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

       readConfigurationFile

         Read the configuration file specified.

       parseCommandLineArguments

         Parse the arguments specified upon the command line.

       checkArguments

         Check that the arguments the user has specified are complete and
        make sense.

       printWideMessage

         Print a message, ensuring the width is as wide as the console.

       runCommand

         Run a command, and if debugging is turned on then display it
        to the user along with output.

         Otherwise hide all output.

       runCommandWithProgress

         Run a command whilst immediately writing the output to the console.

         This is a cheap hack to give a sense of ’progress’.

       getTerminalSize

         Find and return the size and width of the current terminal.

         This function makes use of the Term::Size module if available, if
        it is not installed then we return the standard size of 80x25.

       runHooks

         When the image has been created, but before the temporary image
        is unmounted, each executable script inside the hook directory will
        be executed.

         (The scripts are executed "in order" which might be useful for users
        who wish to ensure some actions occur before others.)

         The scripts will be given single argument: the name of the directory
        within which the image is mounted.

         The rest of the configuration variables will be passed via
        environmental variables.

       copyDebFiles

         This function will copy all the .deb files from one directory
        to another, giving a "progress indicator" of sorts.