virt-install(1)

1VIRT-INSTALL(1)          Virtual Machine Install Tools         VIRT-INSTALL(1)
2
3
4

NAME

6       virt-install - provision new virtual machines
7

SYNOPSIS

9       virt-install [OPTION]...
10

DESCRIPTION

12       virt-install is a command line tool for provisioning new virtual
13       machines using the "libvirt" hypervisor management library. The tool
14       supports both text based & graphical installations, using serial con‐
15       sole, SDL graphics or a VNC client/server pair. The guest can be con‐
16       figured with one or more virtual disks and network interfaces plumbed
17       through to the host.
18
19       The installation media can be held locally or remotely on NFS, HTTP,
20       FTP servers. In the latter case "virt-install" will fetch the minimal
21       files necessary to kick off the installation process, allowing the
22       guest to fetch the rest of the OS distribution as needed.
23
24       Given suitable command line arguments, "virt-install" is capable of
25       running completely unattended, with the guest 'kickstarting' itself
26       too. This allows for easy automation of guest installs. A companion
27       tool "virt-clone(1)" is provided for cloning pre-existing guests if
28       their installation cannot be easily automated from pristine media.
29

OPTIONS

31       Any of the options can be omitted, in which case "virt-install" will
32       run interactively prompting for input as required.
33
34       -h, --help
35           Show the help message and exit
36
37       -n NAME, --name=NAME
38           Name of the new guest virtual machine instance. This must be unique
39           amongst all guests known to the hypervisor on this machine, includ‐
40           ing those not currently active. To re-define an existing guest, use
41           the virsh(1) tool to shut it down & delete it prior to running
42           "virt-install". This parameter will be prompted for if omitted on
43           the command line.
44
45       -r MEMORY, --ram=MEMORY
46           Memory to allocate for guest instance in megabytes. If the hypervi‐
47           sor does not have enough free memory, it is usual for it to auto‐
48           matically take memory away from the host operating system to sat‐
49           isfy this allocation. This parameter will be prompted for if omit‐
50           ted on the command line.
51
52       -u UUID, --uuid=UUID
53           UUID for the guest; if none is given a random UUID will be gener‐
54           ated. If you specify UUID, you should use a 32-digit hexadecimal
55           number. UUID are intended to be unique across the entire data cen‐
56           ter, and indeed world. Bear this in mind if manually specifying a
57           UUID
58
59       --vcpus=VCPUS
60           Number of virtual cpus to configure for the guest. Not all hypervi‐
61           sors support SMP guests, in which case this argument will be
62           silently ignored
63
64       --check-cpu
65           Check that the number virtual cpus requested does not exceed physi‐
66           cal CPUs and warn if they do.
67
68       --cpuset=CPUSET
69           Set which physical cpus the guest can use. "CPUSET" is a comma
70           seperated list of numbers, which can also be specified in ranges.
71           Example:
72
73               0,2,3,5     : Use processors 0,2,3 and 5
74               1-3,5,6-8   : Use processors 1,2,3,5,6,7 and 8
75
76       -f DISKFILE, --file=DISKFILE
77           Path to the file, disk partition, or logical volume to use as the
78           backing store for the guest's virtual disk. If the path does not
79           exist, then "--file-size" option should also be specified, allowing
80           the disk to be created. This parameter can be repeated multiple
81           times to add many disk. This parameter will be prompted for if
82           omitted on the command line.
83
84       -s DISKSIZE, --file-size=DISKSIZE
85           Size of the file to create for the guest virtual disk, if the path
86           given to "--file" does not already exist. The size is to be speci‐
87           fied in gigabytes, with fractional numbers allowed. The storage for
88           the file will not be pre-allocated unless the "--nonsparse" option
89           is also specified. This parameter will be prompted for if omitted
90           on the command line & a new file is to be created.
91
92       --nonsparse
93           Request creation of a non-sparse file for the guest virtual disk.
94           The initial time taken to fully-allocate the guest virtual disk
95           will be usually by balanced by faster install times inside the
96           guest. Thus use of this optional is recommended to ensure consis‐
97           tently high performance and to avoid I/O errors in the guest should
98           the host filesystem fill up.
99
100       --nodisks
101           Request a virtual machine without any local disk storage, typically
102           used for running 'Live CD' images or installing to network storage
103           (iSCSI or NFS root).  This disables all interactive prompts for
104           disk setup.
105
106       -m MAC, --mac=MAC
107           Fixed MAC address for the guest; If this parameter is omitted, or
108           the value "RANDOM" is specified a suitable address will be randomly
109           generated. For Xen virtual machines it is required that the first 3
110           pairs in the MAC address be the sequence '00:16:3e', while for QEMU
111           or KVM virtual machines it must be '54:52:00'.
112
113       -b BRIDGE, --bridge=BRIDGE
114           Bridge device to connect the guest NIC to. This parameter is depre‐
115           cated in favour of the "--network" parameter.
116
117       -w NETWORK, --network=NETWORK
118           Connect the guest to the host network. The value for "NETWORK" can
119           take one of 3 formats:
120
121           bridge:BRIDGE
122               Connect to a bridge device in the host called "BRIDGE". Use
123               this option if the host has static networking config & the
124               guest requires full outbound and inbound connectivity  to/from
125               the LAN. Also use this if live migration will be used with this
126               guest.
127
128           network:NAME
129               Connect to a virtual network in the host called "NAME". Virtual
130               networks can be listed, created, deleted using the "virsh" com‐
131               mand line tool. In an unmodified install of "libvirt" there is
132               usually a virtual network with a name of "default". Use a vir‐
133               tual network if the host has dynamic networking (eg NetworkMan‐
134               ager), or using wireless. The guest will be NATed to the LAN by
135               whichever connection is active.
136
137           user
138               Connect to the LAN using SLIRP. Only use this if running a QEMU
139               guest as an unprivileged user. This provides a very limited
140               form of NAT.
141
142           If this option is omitted a single NIC will be created in the
143           guest. If there is a bridge device in the host with a physical
144           interface enslaved, that will be used for connectivity. Failing
145           that, the virtual network called "default" will be used. This
146           option can be specified multiple times to setup more than one NIC.
147
148       --vnc
149           Setup a virtual console in the guest and export it as a VNC server
150           in the host. Unless the "--vncport" parameter is also provided, the
151           VNC server will run on the first free port number at 5900 or above.
152           The actual VNC display allocated can be obtained using the "vncdis‐
153           play" command to "virsh". If neither this, nor the "--sdl" or
154           "--nographics" parameters are specified, this will be prompted for.
155
156       --vncport=VNCPORT
157           Request a permanent, statically assigned port number for the guest
158           VNC console. Use of this option is discouraged as other guests may
159           automatically choose to run on this port causing a clash.
160
161       --sdl
162           Setup a virtual console in the guest and display an SDL window in
163           the host to render the output. If the SDL window is closed the
164           guest may be unconditionally terminated.
165
166       --nographics
167           Disable all interactive prompts for the guest virtual console. No
168           graphical console will be allocated for the guest. A text based
169           console will always be available on the first serial port (or
170           equivalent paravirtualised console device).
171
172       --noautoconsole
173           Don't automatically try to connect to the guest console. The
174           default behaviour is to launch a VNC client to display the graphi‐
175           cal console, or to run the "virsh" "console" command to display the
176           text console. Use of this parameter will disable this behaviour.
177
178       -k KEYMAP, --keymap=KEYMAP
179           Request that the virtual console be configured to run with a non-
180           English keyboard layout.
181
182       --accelerate
183           When installing a QEMU guest, make use of the KVM or KQEMU kernel
184           acceleration capabilities if available. Use of this option is rec‐
185           ommended unless a guest OS is known to be incompatible with the
186           accelerators. The KVM accelerator is preferred over KQEMU if both
187           are available.
188
189       --connect=CONNECT     Connect to hypervisor with URI
190           Connect to a non-default hypervisor. The default connection is cho‐
191           sen based on the following rules:
192
193           xen If running on a host with the Xen kernel (checks against
194               /proc/xen)
195
196           qemu:///system
197               If running on a bare metal kernel as root
198
199           qemu:///session
200               If running on a bare metal kernel as non-root
201
202           It is only necessary to provide the "--connect" argument if this
203           default prioritization is incorrect, eg if wanting to use QEMU
204           while on a Xen kernel.
205
206       --livecd
207           Specify that the installation media is a live CD and thus the guest
208           needs to be configured to boot off the CDROM device permanently. It
209           may be desirable to also use the "--nodisks" flag in combination.
210
211       -v, --hvm             This guest should be a fully virtualized guest
212           Request the use of full virtualization, if both para & full virtu‐
213           alization are available on the host. This parameter may not be
214           available if connecting to a Xen hypervisor on a machine without
215           hardware virtualization support. This parameter is implied if con‐
216           necting to a QEMU based hypervisor.
217
218       -c CDROM, --cdrom=CDROM
219           File to use a virtual CD-ROM device for fully virtualized guests.
220           It can be path to an ISO image, or to a CDROM device. It can also
221           be a URL from which to fetch/access a minimal boot ISO image. The
222           URLs take the same format as described for the "--location" argu‐
223           ment. If this parameter is omitted then the "--location" argument
224           must be given to specify a location for the kernel and initrd, or
225           the "--pxe" argument used to install from the network.
226
227       --pxe
228           Use the PXE boot protocol to load the initial ramdisk and kernel
229           for starting the guest installation process. If this parameter is
230           omitted then either the "--location" or "--cdrom" arguments must be
231           given to specify a location for the kernel and initrd.
232
233       --os-type=OS_TYPE
234           Optimize the guest configuration for a type of operating system.
235           This will attempt to pick the most suitable ACPI & APIC settings,
236           optimally supported mouse drivers and generally accommodate other
237           operating system quirks. The valid operating system types are
238
239           linux
240               Linux 2.x series
241
242           windows
243               Microsoft Windows 9x or later
244
245           unix
246               Traditional UNIX BSD or SysV derivatives
247
248           other
249               Operating systems not in one of the 3 prior groups
250
251       --os-variant=OS_VARIANT
252           Further optimize the guest configuration for a specific operating
253           system variant. This parameter is optional. The valid variants are
254
255           linux
256               rhel2.1
257                   Red Hat Enterprise Linux 2.1
258
259               rhel3
260                   Red Hat Enterprise Linux 3
261
262               rhel4
263                   Red Hat Enterprise Linux 4
264
265               rhel5
266                   Red Hat Enterprise Linux 5
267
268               centos5
269                   Cent OS 5
270
271               fedora5
272                   Fedora Core 5
273
274               fedora6
275                   Fedora Core 6
276
277               fedora7
278                   Fedora 7
279
280               sles10
281                   Suse Linux Enterprise Server 10.x
282
283               generic26
284                   Generic Linux 2.6.x kernel
285
286               generic24
287                   Generic Linux 2.4.x kernel
288
289           windows
290               winxp
291                   Microsoft Windows XP
292
293               win2k
294                   Microsoft Windows 2000
295
296               win2k3
297                   Microsoft Windows 2003
298
299               vista
300                   Microsoft Windows Vista
301
302           unix
303               solaris9
304                   Sun Solaris 9
305
306               solaris10
307                   Sun Solaris 10
308
309               freebsd6
310                   Free BSD 6.x
311
312               openbsd4
313                   Open BSD 4.x
314
315           other
316               msdos
317                   Microsoft DOS
318
319               netware4
320                   Novell Netware 4
321
322               netware5
323                   Novell Netware 5
324
325               netware6
326                   Novell Netware 6
327
328       --noapic
329           Override the OS type / variant to disables the APIC setting for
330           fully virtualized guest.
331
332       --noacpi
333           Override the OS type / variant to disables the ACPI setting for
334           fully virtualized guest.
335
336       --arch=ARCH
337           Request a non-native CPU architecture for the guest virtual
338           machine.  The option is only currently available with QEMU guests,
339           and will not enable use of acceleration. If omitted, the host CPU
340           architecture will be used in the guest.
341
342       -p, --paravirt
343           This guest should be a paravirtualized guest. If the host supports
344           both para & full virtualization, and neither this parameter nor the
345           "--hvm" are specified, this will be prompted for interactively.
346
347       -l LOCATION, --location=LOCATION
348           Installation source for guest virtual machine kernel+initrd pair.
349           This is required for paravirtualized guests. Fully virtualized
350           guests must use either "--location" to specify a kernel+initrd, or
351           the "--cdrom" parameter to specify an ISO/CDROM image. The "LOCA‐
352           TION" can take one of the following forms:
353
354           DIRECTORY
355               Path to a local directory containing an installable distribu‐
356               tion image
357
358           nfs:host:/path
359               An NFS server location containing an installable distribution
360               image
361
362           http://host/path
363               An HTTP server location containing an installable distribution
364               image
365
366           ftp://host/path
367               An FTP server location containing an installable distribution
368               image
369
370       -x EXTRA, --extra-args=EXTRA
371           Additional kernel command line arguments to pass to the installer
372           when performing a guest install from a kernel+initrd.
373
374       -d, --debug
375           Print debugging information to the terminal when running the
376           install process.  The debugging information is also stored in
377           "$HOME/.virtinst/virt-install.log" even if this parameter is omit‐
378           ted.
379

EXAMPLES

381       Install a paravirtualized Xen guest, 500 MB of RAM, a 5 GB of disk, and
382       Fedora Core 6 from a web server, in text-only mode:
383
384         # virt-install \
385              --paravirt \
386              --name demo \
387              --ram 500 \
388              --file /var/lib/xen/images/demo.img \
389              --file-size 6 \
390              --nographics \
391              --location http://download.fedora.redhat.com/pub/fedora/linux/core/6/x86_64/os/
392
393       Install a QEMU guest, with a real partition, for a different architec‐
394       ture using SDL graphics, using a local ISO image:
395
396         # virt-install \
397              --connect qemu:///system \
398              --name demo \
399              --ram 500 \
400              --file /dev/hdc \
401              --network bridge:eth1 \
402              --arch ppc64 \
403              --sdl \
404              --cdrom /root/boot.iso
405
406       Install a QEMU guest, with a real partition, for a different architec‐
407       ture using SDL graphics, using a remote kernel and initrd pair:
408
409         # virt-install \
410              --connect qemu:///system \
411              --name demo \
412              --ram 500 \
413              --file /dev/hdc \
414              --network bridge:eth1 \
415              --arch ppc64 \
416              --sdl \
417              --location http://download.fedora.redhat.com/pub/fedora/linux/core/6/x86_64/os/
418
419       Install a KVM guest, using LVM partition, virtual networking, booting
420       from the host CDROM, using VNC server/viewer
421
422         # virt-install \
423              --connect qemu:///system \
424              --name demo
425              --ram 500 \
426              --file /dev/HostVG/DemoVM \
427              --network network:default \
428              --accelerate \
429              --vnc \
430              --cdrom /dev/cdrom
431
432       Run a Live CD image under Xen fullyvirt, in diskless environment
433
434         # virt-install \
435              --hvm \
436              --name demo \
437              --ram 500 \
438              --nodisk \
439              --livecd \
440              --vnc \
441              --cdrom /root/fedora7live.iso
442

AUTHOR

444       Written by Daniel P. Berrange, Hugh Brock, Jeremy Katz and a team of
445       many other contributors. See the AUTHORS file in the source distribu‐
446       tion for the complete list of credits.
447

BUGS

449       Report bugs to the mailing list "http://www.redhat.com/mail‐
450       man/listinfo/et-mgmt-tools" or directly to BugZilla
451       "http://bugzilla.redhat.com/bugzilla/" against the "Fedora" product,
452       and the "python-virtinst" component.
453

COPYRIGHT

455       Copyright (C) 2006-2007 Red Hat, Inc, and various contributors.  This
456       is free software. You may redistribute copies of it under the terms of
457       the GNU General Public License "http://www.gnu.org/licenses/gpl.html".
458       There is NO WARRANTY, to the extent permitted by law.
459