Ubuntu Manpage: oz-install - tool to automatically install operating systems into files

NAME

       oz-install - tool to automatically install operating systems into files

SYNOPSIS

       oz-install [OPTIONS] <tdl-file>

DESCRIPTION

       This  is  a  tool to automatically install operating system into files that represent disk
       images.  The input is an XML file representing the operating system  and  packages  to  be
       installed.   By  default  (and  by design), the first stage of the install only installs a
       JEOS  (Just  Enough  Operating  System);  customization,  including  the  installation  of
       additional packages can also be done, but requires additional flags.

       Note  that oz-install does the actual installation using a combination of KVM and libvirt,
       so both of these must be available (and working)  for  oz-install  to  have  a  chance  to
       succeed.

OPTIONS

-a <auto>
Use the user-provided auto installation file auto. By default, Oz will use a hard-
coded auto-installation file (kickstart, preseed, sif, etc) to do a basic OS
installation. Using this option, the user can provide an alternate auto-
installation file to do the install. The caveat is that user-provided auto-
installation files are more likely to cause installation errors, so this option
should be used with caution.

-b <disk_bus>
Use disk_bus for the storage device while doing the install. By default, Oz has
built-in knowledge of the appropriate disk bus to use while installing each guest
operating system (ide or virtio). This option allows the user to override that
default with their own choice.

-c <config>
Get the configuration from config file config, instead of the default
/etc/oz/oz.cfg. If neither one exists, Oz will use sensible defaults. The config
file is in standard ini format; for an explanation of the sections and keys, see
the CONFIGURATION FILE section.

-d <loglevel>
Turn on debugging output to level loglevel. The log levels are:

0 - errors only (this is the default)

1 - errors and warnings

2 - errors, warnings, and information

3 - all messages

4 - all messages, prepended with the level and classname

-f Force the generation of new installation media. By default, oz-install will always
try to use a locally cached version of the oz-modified install media if it is
available. Failing that, oz-install will try to use a locally cached version of
the pristine install media if it is available. You can use this flag to force it
to always download and regenerate the oz-modified install media, even if it has a
local version available.

-g Generate the ICICLE (a package manifest, with some additional metadata) after the
installation is complete.

-h Print a short help message.

-i <icicle>
If oz-install has been instructed to generate an ICICLE (see the -g option), then
it will normally write the ICICLE XML to stdout. To have oz-install write the
ICICLE to a file instead, use the -i option. Note that it is an error to specify
-i without -g.

-m <mac_address>
Use mac_address for the network device while doing the install. The default value
is autogenerated by Oz. This option allows the user to override this behaviour.

-n <network_device>
Use network_device for the network device while doing the install. By default, Oz
has built-in knowledge of the appropriate network device to use while installing
each guest operating system (ne2k_pci, rtl8139, virtio). This option allows the
user to override that default with their own choice.

-p Cleanup old guests before installation. By default, if a guest with the same
libvirt UUID, libvirt name, or diskimage exists prior to Oz starting installation,
Oz will abort. If this option is used, then Oz will undefine the libvirt guest
with the same name or UUID and delete the diskimage, so it should be used with
caution.

-s <disk>
Write the disk image to disk, rather than the default of the TDL name.

-t <timeout>
Terminate the installation of the guest in timeout seconds rather than the oz
default. This value should be increased if running on slow storage or running
multiple oz-install operations on the same machine.

Please note that there is a separate termination action that occurs if 300 seconds
elapses with no disk activity to the operating system. This timer value is not
configurable.

-u Customize the image after installation. This generally installs additional
packages onto the disk image after installation.

-x <xmlfile>
Oz will normally generate a libvirt XML file in the current working directory
suffixed with the date and time. Specifying the -x option allows the filename to
be overridden.

CONFIGURATION FILE

The Oz configuration file is in standard INI format with several sections. If any section
or configuration key is missing, Oz will use a sensible default. For true/false
configuration keys, the values of "true", "True", "yes", or "Yes" can be used to turn the
option on, and "false", "False", "no", or "No" can be used to turn the behavior off. The
configuration file should have the following form:

[paths]
output_dir = /var/lib/libvirt/images
data_dir = /var/lib/oz
screenshot_dir = .
sshprivkey = /etc/oz/id_rsa-icicle-gen

[libvirt]
uri = qemu:///system
type = kvm
bridge_name = virbr0
cpus = 1
memory = 1024
image_type = raw

[cache]
original_media = yes
modified_media = no
jeos = no

[icicle]
safe_generation = no

The paths section defines the paths that Oz will use for storing data. The output_dir key
describes where to store the images after they are built, and the data_dir key describes
where to cache install media and use temporary storage. Both locations must have a decent
amount of free disk space in order for Oz to work properly. The screenshot_dir key
describes where to store screenshots of failed installs. The sshprivkey key describes
where the ssh keys are stored, which are required by Oz to do customization of the image.

The libvirt section allows some manipulation of how Oz uses libvirt. The uri key
describes the libvirt URI to use to do the guest installation. The type key defines what
type of virtualization to use. The bridge_name key defines which bridge Oz should place
the guests that it launches on. The cpus key defines how many cpus should be used inside
the virtual machine. The memory key defines how much memory (in megabytes) should be used
inside the virtual machine. The image_type key defines which output disk type should be
used; this can be any value that libvirt supports.

The cache section allows some manipulation of how Oz caches data. The caching of data in
Oz is a tradeoff between installation time and storage space. The original_media key
tells Oz to cache the original installation media so that it does not have to download it
the next time an install for the same operating system is requested. The modified_media
key tells Oz to cache the oz-modified installation media so that it does not have to
download and modify it the next time an install for the same operating system is
requested. The jeos key tells Oz to cache the installed operating system after
installation. This can significantly speed up subsequent installation of the same
operating system, with the additional downside of the operating system getting out-of-date
with respect to security updates. Use with care.

The icicle section allows some manipulation of how Oz generates ICICLE output. ICICLE is
a package manifest that can optionally be generated at the end of installs. The
safe_generation key controls whether Oz uses a throwaway overlay file while generating the
ICICLE. If it is set to "no" (the default), then Oz will boot up the guest at the end of
the install and run the appropriate commands to generate the ICICLE. If it is set to
"yes", then Oz will use a throwaway overlay file while generating the ICICLE. After the
ICICLE is generated, Oz will delete the backing file, leaving the original disk image
pristine.

AUTHOR