1OZ-INSTALL(1)               General Commands Manual              OZ-INSTALL(1)
2
3
4

NAME

6       oz-install - tool to automatically install operating systems into files
7
8

SYNOPSIS

10       oz-install [OPTIONS] <tdl-file>
11
12

DESCRIPTION

14       This  is  a  tool  to automatically install operating system into files
15       that represent disk images.  The input is an XML file representing  the
16       operating  system  and  packages  to  be installed.  By default (and by
17       design), the first stage of the install  only  installs  a  JEOS  (Just
18       Enough  Operating System); customization, including the installation of
19       additional packages can also be done, but requires additional flags.
20
21       Note that oz-install does the actual installation using  a  combination
22       of  KVM  and  libvirt, so both of these must be available (and working)
23       for oz-install to have a chance to succeed.
24
25

OPTIONS

27       -a <auto>
28              Use the user-provided auto installation file auto.  By  default,
29              Oz will use a hard-coded auto-installation file (kickstart, pre‐
30              seed, sif, etc) to do  a  basic  OS  installation.   Using  this
31              option, the user can provide an alternate auto-installation file
32              to do the install.   The  caveat  is  that  user-provided  auto-
33              installation files are more likely to cause installation errors,
34              so this option should be used with caution.
35
36       -b <disk_bus>
37              Use disk_bus for the storage device while doing the install.  By
38              default,  Oz  has built-in knowledge of the appropriate disk bus
39              to use while installing each guest operating system (ide or vir‐
40              tio).  This option allows the user to override that default with
41              their own choice.
42
43       -c <config>
44              Get the configuration from config file config,  instead  of  the
45              default /etc/oz/oz.cfg.  If neither one exists, Oz will use sen‐
46              sible defaults.  The config file is in standard ini format;  for
47              an  explanation  of the sections and keys, see the CONFIGURATION
48              FILE section.
49
50       -d <loglevel>
51              Turn on debugging output to level loglevel.  The log levels are:
52
53              0 - errors only (this is the default)
54
55              1 - errors and warnings
56
57              2 - errors, warnings, and information
58
59              3 - all messages
60
61              4 - all messages, prepended with the level and classname
62
63       -f     Force the generation of new installation media.  By default, oz-
64              install  will  always try to use a locally cached version of the
65              oz-modified install media if it is available.  Failing that, oz-
66              install will try to use a locally cached version of the pristine
67              install media if it is available.  You  can  use  this  flag  to
68              force  it  to  always  download  and  regenerate the oz-modified
69              install media, even if it has a local version available.
70
71       -g     Generate the ICICLE (a package manifest,  with  some  additional
72              metadata) after the installation is complete.
73
74       -h     Print a short help message.
75
76       -i <icicle>
77              If oz-install has been instructed to generate an ICICLE (see the
78              -g option), then it will normally write the ICICLE XML  to  std‐
79              out.  To have oz-install write the ICICLE to a file instead, use
80              the -i option.  Note that it is an error to specify  -i  without
81              -g.
82
83       -m <mac_address>
84              Use  mac_address for the network device while doing the install.
85              The default value is autogenerated by Oz. This option allows the
86              user to override this behaviour.
87
88       -n <network_device>
89              Use  network_device  for  the  network  device  while  doing the
90              install.  By default, Oz has built-in knowledge of the appropri‐
91              ate  network device to use while installing each guest operating
92              system (ne2k_pci, rtl8139, virtio).  This option allows the user
93              to override that default with their own choice.
94
95       -p     Cleanup  old guests before installation.  By default, if a guest
96              with the same libvirt UUID, libvirt name,  or  diskimage  exists
97              prior  to  Oz  starting  installation,  Oz  will abort.  If this
98              option is used, then Oz will undefine the libvirt guest with the
99              same name or UUID and delete the diskimage, so it should be used
100              with caution.
101
102       -s <disk>
103              Write the disk image to disk, rather than the default of the TDL
104              name.
105
106       -t <timeout>
107              Terminate  the  installation  of  the  guest  in timeout seconds
108              rather than the oz default.  This value should be  increased  if
109              running  on  slow  storage or running multiple oz-install opera‐
110              tions on the same machine.
111
112              Please note that there is a  separate  termination  action  that
113              occurs if 300 seconds elapses with no disk activity to the oper‐
114              ating system.  This timer value is not configurable.
115
116       -u     Customize the image after installation.  This generally installs
117              additional packages onto the disk image after installation.
118
119       -x <xmlfile>
120              Oz  will  normally  generate  a  libvirt XML file in the current
121              working directory suffixed with the date and  time.   Specifying
122              the -x option allows the filename to be overridden.
123
124

CONFIGURATION FILE

126       The  Oz  configuration file is in standard INI format with several sec‐
127       tions.  If any section or configuration key is missing, Oz will  use  a
128       sensible  default.   For  true/false  configuration keys, the values of
129       "true", "True", "yes", or "Yes" can be used to turn the option on,  and
130       "false",  "False",  "no", or "No" can be used to turn the behavior off.
131       The configuration file should have the following form:
132
133
134           [paths]
135           output_dir = /var/lib/libvirt/images
136           data_dir = /var/lib/oz
137           screenshot_dir = .
138           sshprivkey = /etc/oz/id_rsa-icicle-gen
139
140           [libvirt]
141           uri = qemu:///system
142           type = kvm
143           bridge_name = virbr0
144           cpus = 1
145           memory = 1024
146           image_type = raw
147
148           [cache]
149           original_media = yes
150           modified_media = no
151           jeos = no
152
153           [icicle]
154           safe_generation = no
155
156       The paths section defines the paths that Oz will use for storing  data.
157       The  output_dir  key describes where to store the images after they are
158       built, and the data_dir key describes where to cache install media  and
159       use  temporary  storage.   Both  locations must have a decent amount of
160       free disk space in order for Oz to work properly.   The  screenshot_dir
161       key  describes  where to store screenshots of failed installs. The ssh‐
162       privkey key describes where the ssh keys are stored, which are required
163       by Oz to do customization of the image.
164
165       The  libvirt  section  allows some manipulation of how Oz uses libvirt.
166       The uri key describes the libvirt URI to use to do the guest  installa‐
167       tion.   The  type  key defines what type of virtualization to use.  The
168       bridge_name key defines which bridge Oz should place the guests that it
169       launches  on.  The cpus key defines how many cpus should be used inside
170       the virtual machine.  The  memory  key  defines  how  much  memory  (in
171       megabytes)  should  be used inside the virtual machine.  The image_type
172       key defines which output disk type should be  used;  this  can  be  any
173       value that libvirt supports.
174
175       The  cache section allows some manipulation of how Oz caches data.  The
176       caching of data in Oz is a tradeoff between installation time and stor‐
177       age  space.   The  original_media  key  tells  Oz to cache the original
178       installation media so that it does not have to  download  it  the  next
179       time  an install for the same operating system is requested.  The modi‐
180       fied_media key tells Oz to cache the oz-modified installation media  so
181       that  it  does  not  have  to  download  and modify it the next time an
182       install for the same operating system is requested.  The jeos key tells
183       Oz  to  cache  the installed operating system after installation.  This
184       can significantly speed up subsequent installation of the same  operat‐
185       ing  system,  with the additional downside of the operating system get‐
186       ting out-of-date with respect to security updates.  Use with care.
187
188       The icicle section allows some manipulation of how Oz generates  ICICLE
189       output.   ICICLE is a package manifest that can optionally be generated
190       at the end of installs.  The safe_generation key  controls  whether  Oz
191       uses  a  throwaway  overlay file while generating the ICICLE.  If it is
192       set to "no" (the default), then Oz will boot up the guest at the end of
193       the  install  and  run the appropriate commands to generate the ICICLE.
194       If it is set to "yes", then Oz will use a throwaway overlay file  while
195       generating  the  ICICLE.  After the ICICLE is generated, Oz will delete
196       the backing file, leaving the original disk image pristine.
197
198

SEE ALSO

200       oz-generate-icicle(1), oz-customize(1),  oz-cleanup-cache(1),  oz-exam‐
201       ples(1)
202
203

AUTHOR

205       Chris Lalancette <clalancette@gmail.com>
206
207
208
209oz-install                         Aug 2011                      OZ-INSTALL(1)
Impressum