Provided by: oz_0.17.0-5.2_all bug

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.

SEE ALSO

       oz-generate-icicle(1), oz-customize(1), oz-cleanup-cache(1), oz-examples(1)

AUTHOR

       Chris Lalancette <clalancette@gmail.com>