.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "XEN-CREATE-IMAGE 8" .TH XEN-CREATE-IMAGE 8 "2023-02-06" "4.9.2" "Perl Programmers Reference Guide" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" xen\-create\-image \- Easily create new Xen instances with networking and OpenSSH. .SH "SYNOPSIS" .IX Header "SYNOPSIS" xen-create-image \-\-hostname= .SH "EXAMPLES" .IX Header "EXAMPLES" xen-create-image \-\-hostname=some\-domu \-\-dist=wheezy \-\-lvm=vg0 .PP xen-create-image \-\-hostname=some\-domu \-\-dist=precise \-\-dir=/srv/xen .PP See below for more specific examples: \s-1LOOPBACK EXAMPLES, LVM EXAMPLE\s0 and \s-1EVMS EXAMPLE.\s0 .SH "OPTIONS" .IX Header "OPTIONS" .Vb 1 \& Help Options: \& \& \-\-help Show the help information for this script. \& \& \-\-manual Read the manual, and examples, for this script. \& \& \-\-(no)verbose (Don\*(Aqt) show more of what xen\-create\-image is \& currently doing. \& \& \-\-dumpconfig Show current configuration. \& \& \-\-version Show the version number and exit. \& \& \& \& Size / General options: \& \& \-\-(no)accounts \& (Don\*(Aqt) copy all non\-system accounts to the guest \& image \& \& \-\-admins Specify that some administrators should be created for \& this image, using xen\-shell. \& \& \-\-(no)boot (Don\*(Aqt) 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. \& \& \-\-(no)copyhosts \& (Don\*(Aqt) copy entries from the dom0\*(Aqs /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") \& \& \-\-(no)force (Don\*(Aqt) 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 \*(Aqext2\*(Aq, \*(Aqext3\*(Aq, \*(Aqext4\*(Aq, \*(Aqreiserfs\*(Aq, \& \*(Aqxfs\*(Aq or \*(Aqbtrfs\*(Aq. (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. \& \& \-\-(no)keep (Don\*(Aqt) keep our images if installation fails. It \& maybe unmounted, though. \& \& \-\-keyring=/path/to/keyring \& Set the path to the keyring debootstrap should use. \& \& \-\-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. As suffix recognized size units are "M", \& "MB", "G" and "GB" (case does not matter). If there\*(Aqs \& no unit given, megabytes are assumed. \& \& \-\-maxmem=size \& Setup the maximum amount of memory that can be allocated \& to the new instance. As suffix recognized size units are "M", \& "MB", "G" and "GB" (case does not matter). If there\*(Aqs \& no unit given, megabytes are assumed. \& Required for dynamic memory ballooning. \& \& \-\-modules=/path/to/modules \& Set the path to the kernel modules to use for domU. \& If modules are specified they must exist. \& \& \-\-nohosts Don\*(Aqt 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. \& Note: This overrides \-\-genpass \& \& \-\-(no)passwd (Don\*(Aqt) ask for a root password interactively during \& setup. NOTE: This overrides \-\-genpass \-\-password. \& \& \-\-(no)pygrub DomU should (not) 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\*(Aqs 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. \& \& \-\-finalrole=role \& Similar to role scripts. Run the specified role \& script(s) after cfg file creation. \& \& \-\-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. \& \& \-\-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 \& 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://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/ \& Specify a proxy to be used by debootstrap, and within \& the guest. Needs the same syntax as APT\*(Aqs \& Acquire::http::Proxy. See apt.conf(5). \& \& \-\-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. \& \& \-\-(no)dhcp The guest will (not) 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.) \& \& \-\-randommac Creates a random MAC address. \& \& \-\-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\*(Aqs /etc/resolv.conf will be copied to guest. \& \& \-\-vifname=vifname \& Optionally, set a specific vif name for the new \& instance. \& \& \-\-vlan=1 OpenvSwitch related, optionally you can specify a vlan \& where the virtual machine has connectivity. \& \& \& \& 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, \-\-evms or \-\-zpool. (These four options are \& mutually exclusive.) \& \& \-\-evms=lvm2/container \& Specify the container to save images within, \& i.e. \*(Aq\-\-evms lvm2/mycontainer\*(Aq. If you do not wish to \& use EVMS specify \-\-dir, \-\-lvm or \-\-zpool. (These four \& 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, \-\-evms or \& \-\-zpool. (These three options are mutually exclusive.) \& \& \-\-lvm_thin=thin pool \& Specify the thin pool name on which thin LVM volumes \& are created. \& \& This enables thin provisioned LVM volumes. Note that \& you need a LVM version which supports this. \& \& \-\-zpool=pool Specify the ZFS pool to save images within. A new ZFS \& volume will be created for each guest. \& If you do not wish to use ZFS specify \-\-dir, \-\-evms or \& \-\-lvm. (These four options are mutually exclusive.) .Ve .SH "NOTES" .IX Header "NOTES" .Vb 2 \& This script is a wrapper around three distinct external tools which \& complete various aspects of the new system installation. .Ve .IP "\fBxt-install-image\fR Install a new distribution." 8 .IX Item "xt-install-image Install a new distribution." .PD 0 .IP "\fBxt-customize-image\fR Run a collection of hook scripts to customise the freshly installed system." 8 .IX Item "xt-customize-image Run a collection of hook scripts to customise the freshly installed system." .IP "\fBxt-create-xen-config\fR Create a Xen configuration file in so that xm/xl can start the new domain." 8 .IX Item "xt-create-xen-config Create a Xen configuration file in so that xm/xl can start the new domain." .PD .PP .Vb 2 \& The result of invoking these three scripts, and some minor glue between \& them, is a simple means of creating new Xen guest domains. .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" .Vb 4 \& 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". .Ve .SH "CONFIGURATION" .IX Header "CONFIGURATION" .Vb 2 \& 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 \*(Aq#\*(Aq character. Otherwise the format is \*(Aqkey = value\*(Aq. \& \& A sample configuration file would look like this: .Ve .PP .Vb 5 \& # \& # Output directory. Images are stored beneath this directory, one \& # subdirectory per hostname. \& # \& dir = /home/xen \& \& # \& # LVM users should disable the \*(Aqdir\*(Aq 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 .Ve .PP .Vb 2 \& 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. .Ve .SH "NETWORKING AUTO-SETUP" .IX Header "NETWORKING AUTO-SETUP" .Vb 3 \& We\*(Aqve 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 \*(Aq\-\-ip=auto\*(Aq 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: .Ve .PP .Vb 2 \& rm /etc/xen\-tools/ips.txt \& for i in $(seq 100 200) ; do echo 192.168.1.$i >> /etc/xen\-tools/ips.txt ; done .Ve .PP .Vb 1 \& Now you can create a guest with the command: .Ve .PP .Vb 1 \& xen\-create\-image \-\-ip=auto \-\-hostname=blah [\-\-dist=...] .Ve .PP .Vb 4 \& The first time this ran the machine would receive an IP address \& from the pool which we\*(Aqve 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. .Ve .SH "PARTITIONING" .IX Header "PARTITIONING" .Vb 2 \& By default all new guests are created with two "volumes", one \& for the root filesystem and one for the new system\*(Aqs 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. .Ve .SH "XEN CONFIGURATION FILE" .IX Header "XEN CONFIGURATION FILE" .Vb 3 \& 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. .Ve .SH "LOOPBACK EXAMPLES" .IX Header "LOOPBACK EXAMPLES" .Vb 2 \& 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 \e \& \-\-dir=/home/xen \-\-hostname=vm01.my.flat \& \& This next example sets up a host which has the name \*(Aqvm02.my.flat\*(Aq and \& IP address 192.168.1.200, with the gateway address of 192.168.1.1 \& \& xen\-create\-image \-\-size=2Gb \-\-swap=128Mb \e \& \-\-ip=192.168.1.200 \e \& \-\-netmask=255.255.255.0 \& \-\-gateway=192.168.1.1 \e \& \-\-nameserver=192.168.1.1 \e \& \-\-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 \*(Aq/domains/\*(Aq subdirectory will be created if necessary. .Ve .SH "LVM EXAMPLE" .IX Header "LVM EXAMPLE" .Vb 3 \& 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 \e \& \-\-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 .Ve .SH "EVMS EXAMPLE" .IX Header "EVMS EXAMPLE" .Vb 3 \& 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 \e \& \-\-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 .Ve .SH "INSTALLATION METHODS" .IX Header "INSTALLATION METHODS" .Vb 1 \& 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. .Ve .SH "INSTALLATION SPEEDUPS" .IX Header "INSTALLATION SPEEDUPS" .Vb 4 \& After performing your first installation you can customize it, or \& use it untouched, as a new installation source. By doing this you\*(Aqll \& 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 \e \& \-\-lvm=myvolumegroup \-\-hostname=vm01.my.flat \e \& \-\-install\-method=tar \-\-install\-source=/path/to/tar.file.tar \& \& The advantage of the tarfile approach is that you\*(Aqll 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 \e \& \-\-lvm=myvolumegroup \-\-hostname=vm01.my.flat \e \& \-\-install\-method=copy \-\-install\-source=/path/to/copy/from .Ve .SH "DEBOOTSTRAP CACHING" .IX Header "DEBOOTSTRAP CACHING" .Vb 2 \& 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\*(Aqs 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. .Ve .SH "ROLES" .IX Header "ROLES" .Vb 3 \& 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. \& \& The supplied scripts are: .Ve .IP "builder Setup the new virtual images with commonly used packages for rebuilding Debian packages from their source." 8 .IX Item "builder Setup the new virtual images with commonly used packages for rebuilding Debian packages from their source." .PD 0 .IP "cfengine Install cfengine2 on the virtual image and copy the cfengine configuration from Dom0." 8 .IX Item "cfengine Install cfengine2 on the virtual image and copy the cfengine configuration from Dom0." .IP "editor Allows generalised editing of files for guests." 8 .IX Item "editor Allows generalised editing of files for guests." .PD 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. .Sp For example if we have the following sed file: .Sp .Vb 1 \& /etc/xen\-tools/sed.d/etc/ssh/sshd_config.sed .Ve .Sp 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. .IP "gdm Install an X11 server, using \s-1VNC\s0 and \s-1GDM\s0" 8 .IX Item "gdm Install an X11 server, using VNC and GDM" .PD 0 .IP "minimal Customise the generated images to remove some packages." 8 .IX Item "minimal Customise the generated images to remove some packages." .IP "puppet Install puppet on the virtual image and copy the cfengine configuration from Dom0." 8 .IX Item "puppet Install puppet on the virtual image and copy the cfengine configuration from Dom0." .IP "tmpfs Sets up /tmp, /var/run and /var/lock as tmpfs in the DomU." 8 .IX Item "tmpfs Sets up /tmp, /var/run and /var/lock as tmpfs in the DomU." .IP "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." 8 .IX Item "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." .IP "xdm Install an X11 server, using \s-1VNC\s0 and \s-1XDM\s0" 8 .IX Item "xdm Install an X11 server, using VNC and XDM" .PD .PP .Vb 5 \& If you\*(Aqd like to include your own role scripts you\*(Aqll 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. .Ve .SH "THE SKELETON DIRECTORY" .IX Header "THE SKELETON DIRECTORY" .Vb 3 \& 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: .Ve .PP .Vb 4 \& 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 .Ve .SH "AUTHORS" .IX Header "AUTHORS" .Vb 4 \& Steve Kemp, https://steve.fi/ \& Axel Beckert, https://axel.beckert.ch/ \& Dmitry Nedospasov, http://www.nedos.net/ \& Ste\*'phane Jourdois .Ve .SH "LICENSE" .IX Header "LICENSE" Copyright (c) 2005\-2009 by Steve Kemp, (c) 2010\-2013 by The Xen-Tools Development Team. All rights reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The \s-1LICENSE\s0 file contains the full text of the license.