xen-create-image

Langue: en

Autres versions - même langue

Version: 2008-11-06 (ubuntu - 08/07/09)

Section: 8 (Commandes administrateur)

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       Cache .deb files on the host when installing the new guest
                 with the debootstrap tool.
 
    --config      Read the specified file in addition to the global
                 configuration file.
 
    --copy-cmd    NOP:  Ignored.
 
    --debootstrap-cmd    NOP: Ignored.
 
    --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          Specify the filesystem type to use for the new guest.
                  Valid choices are 'ext2', 'ext3', 'reiserfs', or 'xfs'.
 
    --image       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    Specify a physical/logical volume for the disk image.
 
    --initrd      Specify the initial ramdisk
                  If an image is specified it must exist.
 
    --keep        Don't delete our images if installation fails.
 
    --kernel      Set the path to the kernel to use for domU.
                  If a kernel is specified it must exist.
 
    --memory      Setup the amount of memory allocated to the new instance.
 
    --modules     Set the path to the kernel modules to use for domU.
                  If modules are specified they must exist.
 
    --output      Specify the output directory to create the xen configuratoin
                 file within.
 
    --install     Specify whether to install the guest system or not.
 
    --hooks       Specify whether to run hooks after the image is created.
 
    --partitions  Use a specific partition layout configuration file.
                 Not supported with the image-dev and swap-dev options.
                 Parameters fs, size, swap and noswap are ignored when
                 using this option.
 
    --passwd      Ask for a root password during setup.
                  NOTE:  This is done interactively.
 
    --role        Run the specified role script(s) post-install.
                 Role scripts are discussed later in this manpage.
 
    --role-args   Pass the named string literally to any role script.
                 This is useful for site-specific roles.
 
    --roledir     Specify the directory which contains the role scripts.
                  This defaults to /etc/xen-tools/role.d/
 
    --size        Set the size of the primary disk image.
 
    --tar-cmd     NOP: Ignored.
 
    --extension   Specify the suffix to give the Xen configuration file.
 
    --swap        Set the size of the swap partition.
 
    --swap-dev    Specify a physical/logical volume for swap usage.
 
    --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.
 
    --ide         Use IDE names for virtual devices (i.e. hda not sda)
 
 
   Installation options:
 
    --arch            Pass the given architecture to debootstrap, rinse,
                     or rpmstrap when installing the system.  This argument
                     is ignored for other install methods.
 
    --dist            Specify the distribution you wish to install.
 
    --install-method  Specify the installation method to use.
 
    --install-source  Specify the source path to use when installing via
                     a copy or tarball installation.
 
    --mirror          Setup the mirror to use when installing via debootstrap.
 
    --template        Specify which template file to use when creating the
                     Xen configuration file.
 
 
 
   Networking options:
 
    --dhcp        The guest will be configured to fetch its networking
                 details via DHCP.
 
    --gateway     Setup the network gateway for the new instance.
 
    --ip          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         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     Setup the netmask for the new instance.
 
    --broadcast   Setup the broadcast address for the new instance.
 
 
 
   Mandatory options:
 
    --dir         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.)
 
    --lvm         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.)
 
    --evms        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    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.
 
 

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

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       = sarge    # 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", "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 recieve 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 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.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 \
           --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 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.
 
   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 upon the host you may do so with
  apt-get, as you'd expect:
 
   apt-get clean
 
   (This feature can be disabled with the command line flag --cache=no,
  or by the matching setting in the configuration file.)
 
 

ROLES

   Currently there are some roles scripts included which work for
  the Debian Sarge and Etch 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.
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
   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
 
 

AUTHOR

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

LICENSE

Copyright (c) 2005-2007 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.