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 creating new KVM or Xen virtual
13       machines using the "libvirt" hypervisor management library. See the
14       EXAMPLES section at the end of this document to quickly get started.
15
16       virt-install tool supports both text based & graphical installations,
17       using VNC or SDL graphics, or a text serial console. The guest can be
18       configured to use one or more virtual disks, network interfaces, audio
19       devices, physical USB or PCI devices, among others.
20
21       The installation media can be held locally or remotely on NFS, HTTP,
22       FTP servers. In the latter case "virt-install" will fetch the minimal
23       files necessary to kick off the installation process, allowing the
24       guest to fetch the rest of the OS distribution as needed. PXE booting,
25       and importing an existing disk image (thus skipping the install phase)
26       are also supported.
27
28       Given suitable command line arguments, "virt-install" is capable of
29       running completely unattended, with the guest 'kickstarting' itself
30       too. This allows for easy automation of guest installs. An interactive
31       mode is also available with the --prompt option, but this will only ask
32       for the minimum required options.
33

OPTIONS

35       Most options are not required. Minimum requirements are --name, --ram,
36       guest storage (--disk or --nodisks), and an install option.
37
38       -h, --help
39         Show the help message and exit
40
41       --connect=CONNECT
42         Connect to a non-default hypervisor. The default connection is chosen
43         based on the following rules:
44
45         xen If running on a host with the Xen kernel (checks against
46             /proc/xen)
47
48         qemu:///system
49             If running on a bare metal kernel as root (needed for KVM
50             installs)
51
52         qemu:///session
53             If running on a bare metal kernel as non-root
54
55             It is only necessary to provide the "--connect" argument if this
56             default prioritization is incorrect, eg if wanting to use QEMU
57             while on a Xen kernel.
58
59   General Options
60       General configuration parameters that apply to all types of guest
61       installs.
62
63       -n NAME, --name=NAME
64         Name of the new guest virtual machine instance. This must be unique
65         amongst all guests known to the hypervisor on the connection,
66         including those not currently active. To re-define an existing guest,
67         use the virsh(1) tool to shut it down ('virsh shutdown') & delete
68         ('virsh undefine') it prior to running "virt-install".
69
70       -r MEMORY, --ram=MEMORY
71         Memory to allocate for guest instance in megabytes. If the hypervisor
72         does not have enough free memory, it is usual for it to automatically
73         take memory away from the host operating system to satisfy this
74         allocation.
75
76       --arch=ARCH
77         Request a non-native CPU architecture for the guest virtual machine.
78         If omitted, the host CPU architecture will be used in the guest.
79
80       --machine=MACHINE
81         The machine type to emulate. This will typically not need to be
82         specified for Xen or KVM, but is useful for choosing machine times of
83         more exotic architectures.
84
85       -u UUID, --uuid=UUID
86         UUID for the guest; if none is given a random UUID will be generated.
87         If you specify UUID, you should use a 32-digit hexadecimal number.
88         UUID are intended to be unique across the entire data center, and
89         indeed world. Bear this in mind if manually specifying a UUID
90
91       --vcpus=VCPUS[,maxvcpus=MAX][,sockets=#][,cores=#][,threads=#]
92         Number of virtual cpus to configure for the guest. If 'maxvcpus' is
93         specified, the guest will be able to hotplug up to MAX vcpus while
94         the guest is running, but will startup with VCPUS.
95
96         CPU topology can additionally be specified with sockets, cores, and
97         threads.  If values are omitted, the rest will be autofilled
98         prefering sockets over cores over threads.
99
100       --cpuset=CPUSET
101         Set which physical cpus the guest can use. "CPUSET" is a comma
102         separated list of numbers, which can also be specified in ranges.
103         Example:
104
105             0,2,3,5     : Use processors 0,2,3 and 5
106             1-3,5,6-8   : Use processors 1,2,3,5,6,7 and 8
107
108         If the value 'auto' is passed, virt-install attempts to automatically
109         determine an optimal cpu pinning using NUMA data, if available.
110
111       --cpu MODEL[,+feature][,-feature][,match=MATCH][,vendor=VENDOR]
112         Configure the CPU model and CPU features exposed to the guest. The
113         only required value is MODEL, which is a valid CPU model as listed in
114         libvirt's cpu_map.xml file.
115
116         Specific CPU features can be specified in a number of ways: using one
117         of libvirt's feature policy values force, require, optional, disable,
118         or forbid, or with the shorthand '+feature' and '-feature', which
119         equal 'force=feature' and 'disable=feature' respectively
120
121         Some examples:
122
123         --cpu core2duo,+x2apic,disable=vmx
124           Expose the core2duo CPU model, force enable x2apic, but do not
125           expose vmx
126
127         --cpu host
128           Expose the host CPUs configuration to the guest. This enables the
129           guest to take advantage of many of the host CPUs features (better
130           performance), but may cause issues if migrating the guest to a host
131           without an identical CPU.
132
133       --description
134         Human readable text description of the virtual machine. This will be
135         stored in the guests XML configuration for access by other
136         applications.
137
138       --security type=TYPE[,label=LABEL]
139         Configure domain security driver settings. Type can be either
140         'static' or 'dynamic'. 'static' configuration requires a security
141         LABEL. Specifying LABEL without TYPE implies static configuration.
142
143   Installation Method options
144       -c CDROM, --cdrom=CDROM
145         File or device use as a virtual CD-ROM device for fully virtualized
146         guests.  It can be path to an ISO image, or to a CDROM device. It can
147         also be a URL from which to fetch/access a minimal boot ISO image.
148         The URLs take the same format as described for the "--location"
149         argument. If a cdrom has been specified via the "--disk" option, and
150         neither "--cdrom" nor any other install option is specified, the
151         "--disk" cdrom is used as the install media.
152
153       -l LOCATION, --location=LOCATION
154         Installation source for guest virtual machine kernel+initrd pair.
155         The "LOCATION" can take one of the following forms:
156
157         DIRECTORY
158             Path to a local directory containing an installable distribution
159             image
160
161         nfs:host:/path or nfs://host/path
162             An NFS server location containing an installable distribution
163             image
164
165         http://host/path
166             An HTTP server location containing an installable distribution
167             image
168
169         ftp://host/path
170             An FTP server location containing an installable distribution
171             image
172
173         Some distro specific url samples:
174
175         Fedora/Red Hat Based
176             http://download.fedoraproject.org/pub/fedora/linux/releases/10/Fedora/i386/os/
177
178         Debian/Ubuntu
179             http://ftp.us.debian.org/debian/dists/etch/main/installer-amd64/
180
181         Suse
182             http://download.opensuse.org/distribution/11.0/repo/oss/
183
184         Mandriva
185             ftp://ftp.uwsg.indiana.edu/linux/mandrake/official/2009.0/i586/
186
187       --pxe
188         Use the PXE boot protocol to load the initial ramdisk and kernel for
189         starting the guest installation process.
190
191       --import
192         Skip the OS installation process, and build a guest around an
193         existing disk image. The device used for booting is the first device
194         specified via "--disk" or "--file".
195
196       --livecd
197         Specify that the installation media is a live CD and thus the guest
198         needs to be configured to boot off the CDROM device permanently. It
199         may be desirable to also use the "--nodisks" flag in combination.
200
201       -x EXTRA, --extra-args=EXTRA
202         Additional kernel command line arguments to pass to the installer
203         when performing a guest install from "--location". One common usage
204         is specifying an anaconda kickstart file for automated installs, such
205         as --extra-args "ks=http://myserver/my.ks"
206
207       --initrd-inject=PATH
208         Add PATH to the root of the initrd fetched with "--location". This
209         can be used to run an automated install without requiring a network
210         hosted kickstart file:
211
212         --initrd-injections=/path/to/my.ks --extra-args "ks=file:/my.ks"
213
214       --os-type=OS_TYPE
215         Optimize the guest configuration for a type of operating system (ex.
216         'linux', 'windows'). This will attempt to pick the most suitable ACPI
217         & APIC settings, optimally supported mouse drivers, virtio, and
218         generally accommodate other operating system quirks.
219
220         By default, virt-install will attempt to auto detect this value from
221         the install media (currently only supported for URL installs).
222         Autodetection can be disabled with the special value 'none'
223
224         See "--os-variant" for valid options.
225
226       --os-variant=OS_VARIANT
227         Further optimize the guest configuration for a specific operating
228         system variant (ex. 'fedora8', 'winxp'). This parameter is optional,
229         and does not require an "--os-type" to be specified.
230
231         By default, virt-install will attempt to auto detect this value from
232         the install media (currently only supported for URL installs).
233         Autodetection can be disabled with the special value 'none'.
234
235         Valid values are:
236
237         windows
238             win7
239                 Microsoft Windows 7
240
241             vista
242                 Microsoft Windows Vista
243
244             winxp64
245                 Microsoft Windows XP (x86_64)
246
247             winxp
248                 Microsoft Windows XP
249
250             win2k
251                 Microsoft Windows 2000
252
253             win2k8
254                 Microsoft Windows Server 2008
255
256             win2k3
257                 Microsoft Windows Server 2003
258
259         unix
260             openbsd4
261                 OpenBSD 4.x
262
263             freebsd8
264                 FreeBSD 8.x
265
266             freebsd7
267                 FreeBSD 7.x
268
269             freebsd6
270                 FreeBSD 6.x
271
272         solaris
273             solaris9
274                 Sun Solaris 9
275
276             solaris10
277                 Sun Solaris 10
278
279             opensolaris
280                 Sun OpenSolaris
281
282         other
283             netware6
284                 Novell Netware 6
285
286             netware5
287                 Novell Netware 5
288
289             netware4
290                 Novell Netware 4
291
292             msdos
293                 MS-DOS
294
295             generic
296                 Generic
297
298         linux
299             debiansqueeze
300                 Debian Squeeze
301
302             debianlenny
303                 Debian Lenny
304
305             debianetch
306                 Debian Etch
307
308             fedora15
309                 Fedora 15
310
311             fedora14
312                 Fedora 14
313
314             fedora13
315                 Fedora 13
316
317             fedora12
318                 Fedora 12
319
320             fedora11
321                 Fedora 11
322
323             fedora10
324                 Fedora 10
325
326             fedora9
327                 Fedora 9
328
329             fedora8
330                 Fedora 8
331
332             fedora7
333                 Fedora 7
334
335             fedora6
336                 Fedora Core 6
337
338             fedora5
339                 Fedora Core 5
340
341             mes5.1
342                 Mandriva Enterprise Server 5.1 and later
343
344             mes5
345                 Mandriva Enterprise Server 5.0
346
347             mandriva2010
348                 Mandriva Linux 2010 and later
349
350             mandriva2009
351                 Mandriva Linux 2009 and earlier
352
353             rhel6
354                 Red Hat Enterprise Linux 6
355
356             rhel5.4
357                 Red Hat Enterprise Linux 5.4 or later
358
359             rhel5
360                 Red Hat Enterprise Linux 5
361
362             rhel4
363                 Red Hat Enterprise Linux 4
364
365             rhel3
366                 Red Hat Enterprise Linux 3
367
368             rhel2.1
369                 Red Hat Enterprise Linux 2.1
370
371             sles11
372                 Suse Linux Enterprise Server 11
373
374             sles10
375                 Suse Linux Enterprise Server
376
377             ubuntuoneiric
378                 Ubuntu 11.10 (Oneiric Ocelot)
379
380             ubuntunatty
381                 Ubuntu 11.04 (Natty Narwhal)
382
383             ubuntumaverick
384                 Ubuntu 10.10 (Maverick Meerkat)
385
386             ubuntulucid
387                 Ubuntu 10.4 (Lucid Lynx)
388
389             ubuntukarmic
390                 Ubuntu 9.10 (Karmic Koala)
391
392             ubuntujaunty
393                 Ubuntu 9.04 (Jaunty Jackalope)
394
395             ubuntuintrepid
396                 Ubuntu 8.10 (Intrepid Ibex)
397
398             ubuntuhardy
399                 Ubuntu 8.04 LTS (Hardy Heron)
400
401             virtio26
402                 Generic 2.6.25 or later kernel with virtio
403
404             generic26
405                 Generic 2.6.x kernel
406
407             generic24
408                 Generic 2.4.x kernel
409
410         none
411             No OS version specified (disables autodetect)
412
413       --boot=BOOTOPTS
414         Optionally specify the post-install VM boot configuration. This
415         option allows specifying a boot device order, permanently booting off
416         kernel/initrd with option kernel arguments, and enabling a BIOS boot
417         menu (requires libvirt 0.8.3 or later)
418
419         --boot can be specified in addition to other install options (such as
420         --location, --cdrom, etc.) or can be specified on it's own. In the
421         latter case, behavior is similar to the --import install option:
422         there is no 'install' phase, the guest is just created and launched
423         as specified.
424
425         Some examples:
426
427         --boot cdrom,fd,hd,network,menu=on
428           Set the boot device priority as first cdrom, first floppy, first
429           harddisk, network PXE boot. Additionally enable BIOS boot menu
430           prompt.
431
432         --boot kernel=KERNEL,initrd=INITRD,kernel_args="console=/dev/ttyS0"
433           Have guest permanently boot off a local kernel/initrd pair, with
434           the specified kernel options.
435
436   Storage Configuration
437       --disk=DISKOPTS
438         Specifies media to use as storage for the guest, with various
439         options. The general format of a disk string is
440
441             --disk opt1=val1,opt2=val2,...
442
443         To specify media, the command can either be:
444
445             --disk /some/storage/path,opt1=val1
446
447         or explicitly specify one of the following arguments:
448
449         path
450             A path to some storage media to use, existing or not. Existing
451             media can be a file or block device. If installing on a remote
452             host, the existing media must be shared as a libvirt storage
453             volume.
454
455             Specifying a non-existent path implies attempting to create the
456             new storage, and will require specifyng a 'size' value. If the
457             base directory of the path is a libvirt storage pool on the host,
458             the new storage will be created as a libvirt storage volume. For
459             remote hosts, the base directory is required to be a storage pool
460             if using this method.
461
462         pool
463             An existing libvirt storage pool name to create new storage on.
464             Requires specifying a 'size' value.
465
466         vol An existing libvirt storage volume to use. This is specified as
467             'poolname/volname'.
468
469         Other available options:
470
471         device
472             Disk device type. Value can be 'cdrom', 'disk', or 'floppy'.
473             Default is 'disk'. If a 'cdrom' is specified, and no install
474             method is chosen, the cdrom is used as the install media.
475
476         bus Disk bus type. Value can be 'ide', 'scsi', 'usb', 'virtio' or
477             'xen'.  The default is hypervisor dependent since not all
478             hypervisors support all bus types.
479
480         perms
481             Disk permissions. Value can be 'rw' (Read/Write), 'ro'
482             (Readonly), or 'sh' (Shared Read/Write). Default is 'rw'
483
484         size
485             size (in GB) to use if creating new storage
486
487         sparse
488             whether to skip fully allocating newly created storage. Value is
489             'true' or 'false'. Default is 'true' (do not fully allocate).
490
491             The initial time taken to fully-allocate the guest virtual disk
492             (spare=false) will be usually by balanced by faster install times
493             inside the guest. Thus use of this option is recommended to
494             ensure consistently high performance and to avoid I/O errors in
495             the guest should the host filesystem fill up.
496
497         cache
498             The cache mode to be used. The host pagecache provides cache
499             memory.  The cache value can be 'none', 'writethrough', or
500             'writeback'.  'writethrough' provides read caching. 'writeback'
501             provides read and write caching.
502
503         format
504             Image format to be used if creating managed storage. For file
505             volumes, this can be 'raw', 'qcow2', 'vmdk', etc. See format
506             types in <http://libvirt.org/storage.html> for possible values.
507             This is often mapped to the driver_type value as well.
508
509             With libvirt 0.8.3 and later, this option should be specified if
510             reusing and existing disk image, since libvirt does not
511             autodetect storage format as it is a potential security issue.
512             For example, if reusing and existing qcow2 image, you will want
513             to specify format=qcow2, otherwise the hypervisor may not be able
514             to read your disk image.
515
516         driver_name
517             Driver name the hypervisor should use when accessing the
518             specified storage. Typically does not need to be set by the user.
519
520         driver_type
521             Driver format/type the hypervisor should use when accessing the
522             specified storage. Typically does not need to be set by the user.
523
524         io  Disk IO backend. Can be either "threads" or "native".
525
526         See the examples section for some uses. This option deprecates
527         "--file", "--file-size", and "--nonsparse".
528
529       --nodisks
530         Request a virtual machine without any local disk storage, typically
531         used for running 'Live CD' images or installing to network storage
532         (iSCSI or NFS root).
533
534       -f DISKFILE, --file=DISKFILE
535         This option is deprecated in favor of "--disk path=DISKFILE".
536
537       -s DISKSIZE, --file-size=DISKSIZE
538         This option is deprecated in favor of "--disk ...,size=DISKSIZE,..."
539
540       --nonsparse
541         This option is deprecated in favor of "--disk ...,sparse=false,..."
542
543   Networking Configuration
544       -w NETWORK, --network=NETWORK,opt1=val1,opt2=val2
545         Connect the guest to the host network. The value for "NETWORK" can
546         take one of 3 formats:
547
548         bridge=BRIDGE
549             Connect to a bridge device in the host called "BRIDGE". Use this
550             option if the host has static networking config & the guest
551             requires full outbound and inbound connectivity  to/from the LAN.
552             Also use this if live migration will be used with this guest.
553
554         network=NAME
555             Connect to a virtual network in the host called "NAME". Virtual
556             networks can be listed, created, deleted using the "virsh"
557             command line tool. In an unmodified install of "libvirt" there is
558             usually a virtual network with a name of "default". Use a virtual
559             network if the host has dynamic networking (eg NetworkManager),
560             or using wireless. The guest will be NATed to the LAN by
561             whichever connection is active.
562
563         user
564             Connect to the LAN using SLIRP. Only use this if running a QEMU
565             guest as an unprivileged user. This provides a very limited form
566             of NAT.
567
568         If this option is omitted a single NIC will be created in the guest.
569         If there is a bridge device in the host with a physical interface
570         enslaved, that will be used for connectivity. Failing that, the
571         virtual network called "default" will be used. This option can be
572         specified multiple times to setup more than one NIC.
573
574         Other available options are:
575
576         model
577             Network device model as seen by the guest. Value can be any nic
578             model supported by the hypervisor, e.g.: 'e1000', 'rtl8139',
579             'virtio', ...
580
581         mac Fixed MAC address for the guest; If this parameter is omitted, or
582             the value "RANDOM" is specified a suitable address will be
583             randomly generated. For Xen virtual machines it is required that
584             the first 3 pairs in the MAC address be the sequence '00:16:3e',
585             while for QEMU or KVM virtual machines it must be '52:54:00'.
586
587       --nonetworks
588         Request a virtual machine without any network interfaces.
589
590       -b BRIDGE, --bridge=BRIDGE
591         This parameter is deprecated in favour of "--network
592         bridge=bridge_name".
593
594       -m MAC, --mac=MAC
595         This parameter is deprecated in favour of "--network
596         NETWORK,mac=12:34..."
597
598   Graphics Configuration
599       If no graphics option is specified, "virt-install" will default to
600       --vnc if the DISPLAY environment variable is set, otherwise
601       --nographics is used.
602
603       --graphics TYPE,opt1=arg1,opt2=arg2,...
604         Specifies the graphical display configuration. This does not
605         configure any virtual hardware, just how the guest's graphical
606         display can be accessed.  Typically the user does not need to specify
607         this option, virt-install will try and choose a useful default, and
608         launch a suitable connection.
609
610         General format of a graphical string is
611
612             --graphics TYPE,opt1=arg1,opt2=arg2,...
613
614         For example:
615
616             --graphics vnc,password=foobar
617
618         The supported options are:
619
620         type
621             The display type. This is one of:
622
623             vnc
624
625             Setup a virtual console in the guest and export it as a VNC
626             server in the host. Unless the "port" parameter is also provided,
627             the VNC server will run on the first free port number at 5900 or
628             above. The actual VNC display allocated can be obtained using the
629             "vncdisplay" command to "virsh" (or virt-viewer(1) can be used
630             which handles this detail for the use).
631
632             sdl
633
634             Setup a virtual console in the guest and display an SDL window in
635             the host to render the output. If the SDL window is closed the
636             guest may be unconditionally terminated.
637
638             spice
639
640             Export the guest's console using the Spice protocol. Spice allows
641             advanced features like audio and USB device streaming, as well as
642             improved graphical performance.
643
644             Using spice graphic type will work as if those arguments were
645             given:
646
647                 --video qxl --channel spicevmc
648
649             none
650
651             No graphical console will be allocated for the guest. Fully
652             virtualized guests (Xen FV or QEmu/KVM) will need to have a text
653             console configured on the first serial port in the guest (this
654             can be done via the --extra-args option). Xen PV will set this up
655             automatically. The command 'virsh console NAME' can be used to
656             connect to the serial device.
657
658         port
659             Request a permanent, statically assigned port number for the
660             guest console. This is used by 'vnc' and 'spice'
661
662         tlsport
663             Specify the spice tlsport.
664
665         listen
666             Address to listen on for VNC/Spice connections. Default is
667             typically 127.0.0.1 (localhost only), but some hypervisors allow
668             changing this globally (for example, the qemu driver default can
669             be changed in /etc/libvirt/qemu.conf).  Use 0.0.0.0 to allow
670             access from other machines. This is use by 'vnc' and 'spice'
671
672         keymap
673             Request that the virtual VNC console be configured to run with a
674             specific keyboard layout. If the special value 'local' is
675             specified, virt-install will attempt to configure to use the same
676             keymap as the local system. A value of 'none' specifically defers
677             to the hypervisor. Default behavior is hypervisor specific, but
678             typically is the same as 'local'. This is used by 'vnc'
679
680         password
681             Request a VNC password, required at connection time. Beware, this
682             info may end up in virt-install log files, so don't use an
683             important password. This is used by 'vnc' and 'spice'
684
685         passwordvalidto
686             Set an expiration date for password. After the date/time has
687             passed, all new graphical connections are denyed until a new
688             password is set.  This is used by 'vnc' and 'spice'
689
690             The format for this value is YYYY-MM-DDTHH:MM:SS, for example
691             2011-04-01T14:30:15
692
693       --vnc
694         This option is deprecated in favor of "--graphics vnc,..."
695
696       --vncport=VNCPORT
697         This option is deprecated in favor of "--graphics vnc,port=PORT,..."
698
699       --vnclisten=VNCLISTEN
700         This option is deprecated in favor of "--graphics
701         vnc,listen=LISTEN,..."
702
703       -k KEYMAP, --keymap=KEYMAP
704         This option is deprecated in favor of "--graphics
705         vnc,keymap=KEYMAP,..."
706
707       --sdl
708         This option is deprecated in favor of "--graphics sdl,..."
709
710       --nographics
711         This option is deprecated in favor of "--graphics none"
712
713       --noautoconsole
714         Don't automatically try to connect to the guest console. The default
715         behaviour is to launch a VNC client to display the graphical console,
716         or to run the "virsh" "console" command to display the text console.
717         Use of this parameter will disable this behaviour.
718
719   Virtualization Type options
720       Options to override the default virtualization type choices.
721
722       -v, --hvm
723         Request the use of full virtualization, if both para & full
724         virtualization are available on the host. This parameter may not be
725         available if connecting to a Xen hypervisor on a machine without
726         hardware virtualization support. This parameter is implied if
727         connecting to a QEMU based hypervisor.
728
729       -p, --paravirt
730         This guest should be a paravirtualized guest. If the host supports
731         both para & full virtualization, and neither this parameter nor the
732         "--hvm" are specified, this will be assumed.
733
734       --virt-type
735         The hypervisor to install on. Example choices are kvm, qemu, xen, or
736         kqemu.  Availabile options are listed via 'virsh capabilities' in the
737         <domain> tags.
738
739       --accelerate
740         Prefer KVM or KQEMU (in that order) if installing a QEMU guest. This
741         behavior is now the default, and this option is deprecated. To
742         install a plain QEMU guest, use '--virt-type qemu'
743
744       --noapic
745         Override the OS type / variant to disables the APIC setting for fully
746         virtualized guest.
747
748       --noacpi
749         Override the OS type / variant to disables the ACPI setting for fully
750         virtualized guest.
751
752   Device Options
753       --host-device=HOSTDEV
754         Attach a physical host device to the guest. Some example values for
755         HOSTDEV:
756
757         --host-device pci_0000_00_1b_0
758           A node device name via libvirt, as shown by 'virsh nodedev-list'
759
760         --host-device 001.003
761           USB by bus, device (via lsusb).
762
763         --host-device 0x1234:0x5678
764           USB by vendor, product (via lsusb).
765
766         --host-device 1f.01.02
767           PCI device (via lspci).
768
769       --soundhw MODEL
770         Attach a virtual audio device to the guest. MODEL specifies the
771         emulated sound card model. Possible values are ich6, ac97, es1370,
772         sb16, pcspk, or default. 'default' will be AC97 if the hypervisor
773         supports it, otherwise it will be ES1370.
774
775         This deprecates the old boolean --sound model (which still works the
776         same as a single '--soundhw default')
777
778       --watchdog MODEL[,action=ACTION]
779         Attach a virtual hardware watchdog device to the guest. This requires
780         a daemon and device driver in the guest. The watchdog fires a signal
781         when the virtual machine appears to hung. ACTION specifies what
782         libvirt will do when the watchdog fires. Values are
783
784         reset
785             Forcefully reset the guest (the default)
786
787         poweroff
788             Forcefully power off the guest
789
790         pause
791             Pause the guest
792
793         none
794             Do nothing
795
796         shutdown
797             Gracefully shutdown the guest (not recommended, since a hung
798             guest probably won't respond to a graceful shutdown)
799
800         MODEL is the emulated device model: either i6300esb (the default) or
801         ib700.  Some examples:
802
803         Use the recommended settings:
804
805         --watchdog default
806
807         Use the i6300esb with the 'poweroff' action
808
809         --watchdog i6300esb,action=poweroff
810
811       --parallel=CHAROPTS
812       --serial=CHAROPTS
813         Specifies a serial device to attach to the guest, with various
814         options. The general format of a serial string is
815
816             --serial type,opt1=val1,opt2=val2,...
817
818         --serial and --parallel devices share all the same options, unless
819         otherwise noted. Some of the types of character device redirection
820         are:
821
822         --serial pty
823             Pseudo TTY. The allocated pty will be listed in the running
824             guests XML description.
825
826         --serial dev,path=HOSTPATH
827             Host device. For serial devices, this could be /dev/ttyS0. For
828             parallel devices, this could be /dev/parport0.
829
830         --serial file,path=FILENAME
831             Write output to FILENAME.
832
833         --serial pipe,path=PIPEPATH
834             Named pipe (see pipe(7))
835
836         --serial tcp,host=HOST:PORT,mode=MODE,protocol=PROTOCOL
837             TCP net console. MODE is either 'bind' (wait for connections on
838             HOST:PORT) or 'connect' (send output to HOST:PORT), default is
839             'connect'. HOST defaults to '127.0.0.1', but PORT is required.
840             PROTOCOL can be either 'raw' or 'telnet' (default 'raw'). If
841             'telnet', the port acts like a telnet server or client.  Some
842             examples:
843
844             Connect to localhost, port 1234:
845
846             --serial tcp,host=:1234
847
848             Wait for connections on any address, port 4567:
849
850             --serial tcp,host=0.0.0.0:4567,mode=bind
851
852             Wait for telnet connection on localhost, port 2222. The user
853             could then connect interactively to this console via 'telnet
854             localhost 2222':
855
856             --serial tcp,host=:2222,mode=bind,protocol=telnet
857
858         --serial udp,host=CONNECT_HOST:PORT,bind_host=BIND_HOST:BIND_PORT
859             UDP net console. HOST:PORT is the destination to send output to
860             (default HOST is '127.0.0.1', PORT is required).
861             BIND_HOST:BIND_PORT is the optional local address to bind to
862             (default BIND_HOST is 127.0.0.1, but is only set if BIND_PORT is
863             specified). Some examples:
864
865             Send output to default syslog port (may need to edit
866             /etc/rsyslog.conf accordingly):
867
868             --serial udp,host=:514
869
870             Send output to remote host 192.168.10.20, port 4444 (this output
871             can be read on the remote host using 'nc -u -l 4444'):
872
873             --serial udp,host=192.168.10.20:4444
874
875         --serial unix,path=UNIXPATH,mode=MODE
876             Unix socket, see unix(7). MODE has similar behavior and defaults
877             as --serial tcp,mode=MODE
878
879       --channel
880         Specifies a communication channel device to connect the guest and
881         host machine. This option uses the same options as --serial and
882         --parallel for specifying the host/source end of the channel. Extra
883         'target' options are used to specify how the guest machine sees the
884         channel.
885
886         Some of the types of character device redirection are:
887
888         --channel SOURCE,target_type=guestfwd,target_address=HOST:PORT
889             Communication channel using QEMU usermode networking stack. The
890             guest can connect to the channel using the specified HOST:PORT
891             combination.
892
893         --channel SOURCE,target_type=virtio[,name=NAME]
894             Communication channel using virtio serial (requires 2.6.34 or
895             later host and guest). Each instance of a virtio --channel line
896             is exposed in the guest as /dev/vport0p1, /dev/vport0p2, etc.
897             NAME is optional metadata, and can be any string, such as
898             org.linux-kvm.virtioport1.  If specified, this will be exposed in
899             the guest at /sys/class/virtio-ports/vport0p1/NAME
900
901         --channel spicevmc,target_type=virtio[,name=NAME]
902             Communication channel for QEMU spice agent, using virtio serial
903             (requires 2.6.34 or later host and guest). NAME is optional
904             metadata, and can be any string, such as the default
905             com.redhat.spice.0 that specifies how the guest will see the
906             channel.
907
908       --console
909         Connect a text console between the guest and host. Certain guest and
910         hypervisor combinations can automatically set up a getty in the
911         guest, so an out of the box text login can be provided
912         (target_type=xen for xen paravirt guests, and possibly
913         target_type=virtio in the future).
914
915         Example:
916
917         --console pty,target_type=virtio
918             Connect a virtio console to the guest, redirected to a PTY on the
919             host.  For supported guests, this exposes /dev/hvc0 in the guest.
920             See http://fedoraproject.org/wiki/Features/VirtioSerial for more
921             info. virtio console requires libvirt 0.8.3 or later.
922
923       --video=VIDEO
924         Specify what video device model will be attached to the guest. Valid
925         values for VIDEO are hypervisor specific, but some options for recent
926         kvm are cirrus, vga, or vmvga (vmware).
927
928   Miscellaneous Options
929       --autostart
930         Set the autostart flag for a domain. This causes the domain to be
931         started on host boot up.
932
933       --print-xml
934         If the requested guest has no install phase (--import, --boot), print
935         the generated XML instead of defining the guest. By default this WILL
936         do storage creation (can be disabled with --dry-run).
937
938         If the guest has an install phase, you will need to use --print-step
939         to specify exactly what XML output you want. This option implies
940         --quiet.
941
942       --print-step
943         Acts similarly to --print-xml, except requires specifying which
944         install step to print XML for. Possible values are 1, 2, 3, or all.
945         Stage 1 is typically booting from the install media, and stage 2 is
946         typically the final guest config booting off hardisk. Stage 3 is only
947         relevant for windows installs, which by default have a second install
948         stage. This option implies --quiet.
949
950       --noreboot
951         Prevent the domain from automatically rebooting after the install has
952         completed.
953
954       --wait=WAIT
955         Amount of time to wait (in minutes) for a VM to complete its install.
956         Without this option, virt-install will wait for the console to close
957         (not neccessarily indicating the guest has shutdown), or in the case
958         of --noautoconsole, simply kick off the install and exit. Any
959         negative value will make virt-install wait indefinitely, a value of 0
960         triggers the same results as noautoconsole. If the time limit is
961         exceeded, virt-install simply exits, leaving the virtual machine in
962         its current state.
963
964       --force
965         Prevent interactive prompts. If the intended prompt was a yes/no
966         prompt, always say yes. For any other prompts, the application will
967         exit.
968
969       --dry-run
970         Proceed through the guest creation process, but do NOT create storage
971         devices, change host device configuration, or actually teach libvirt
972         about the guest.  virt-install may still fetch install media, since
973         this is required to properly detect the OS to install.
974
975       --prompt
976         Specifically enable prompting for required information. Default
977         prompting is off (as of virtinst 0.400.0)
978
979       --check-cpu
980         Check that the number virtual cpus requested does not exceed physical
981         CPUs and warn if they do.
982
983       -q, --quiet
984         Only print fatal error messages.
985
986       -d, --debug
987         Print debugging information to the terminal when running the install
988         process.  The debugging information is also stored in
989         "$HOME/.virtinst/virt-install.log" even if this parameter is omitted.
990

EXAMPLES

992       Install a Fedora 13 KVM guest with virtio accelerated disk/network,
993       creating a new 8GB storage file, installing from media in the hosts
994       CDROM drive, auto launching a graphical VNC viewer
995
996         # virt-install \
997              --connect qemu:///system \
998              --virt-type kvm \
999              --name demo \
1000              --ram 500 \
1001              --disk path=/var/lib/libvirt/images/demo.img,size=8 \
1002              --graphics vnc \
1003              --cdrom /dev/cdrom \
1004              --os-variant fedora13
1005
1006       Install a Fedora 9 plain QEMU guest, using LVM partition, virtual
1007       networking, booting from PXE, using VNC server/viewer
1008
1009         # virt-install \
1010              --connect qemu:///system \
1011              --name demo \
1012              --ram 500 \
1013              --disk path=/dev/HostVG/DemoVM \
1014              --network network=default \
1015              --virt-type qemu
1016              --graphics vnc \
1017              --os-variant fedora9
1018
1019       Install a guest with a real partition, with the default QEMU hypervisor
1020       for a different architecture using SDL graphics, using a remote kernel
1021       and initrd pair:
1022
1023         # virt-install \
1024              --connect qemu:///system \
1025              --name demo \
1026              --ram 500 \
1027              --disk path=/dev/hdc \
1028              --network bridge=eth1 \
1029              --arch ppc64 \
1030              --graphics sdl \
1031              --location http://download.fedora.redhat.com/pub/fedora/linux/core/6/x86_64/os/
1032
1033       Run a Live CD image under Xen fullyvirt, in diskless environment
1034
1035         # virt-install \
1036              --hvm \
1037              --name demo \
1038              --ram 500 \
1039              --nodisks \
1040              --livecd \
1041              --graphics vnc \
1042              --cdrom /root/fedora7live.iso
1043
1044       Install a paravirtualized Xen guest, 500 MB of RAM, a 5 GB of disk, and
1045       Fedora Core 6 from a web server, in text-only mode, with old style
1046       --file options:
1047
1048         # virt-install \
1049              --paravirt \
1050              --name demo \
1051              --ram 500 \
1052              --file /var/lib/xen/images/demo.img \
1053              --file-size 6 \
1054              --graphics none \
1055              --location http://download.fedora.redhat.com/pub/fedora/linux/core/6/x86_64/os/
1056
1057       Create a guest from an existing disk image 'mydisk.img' using defaults
1058       for the rest of the options.
1059
1060         # virt-install \
1061              --name demo
1062              --ram 512
1063              --disk /home/user/VMs/mydisk.img
1064              --import
1065
1066       Test a custom kernel/initrd using an existing disk image, manually
1067       specifying a serial device hooked to a PTY on the host machine.
1068
1069         # virt-install \
1070              --name mykernel
1071              --ram 512
1072              --disk /home/user/VMs/mydisk.img
1073              --boot kernel=/tmp/mykernel,initrd=/tmp/myinitrd,kernel_args="console=ttyS0"
1074              --serial pty
1075

AUTHORS

1077       Written by Daniel P. Berrange, Hugh Brock, Jeremy Katz, Cole Robinson
1078       and a team of many other contributors. See the AUTHORS file in the
1079       source distribution for the complete list of credits.
1080

BUGS

1082       Please see http://virt-manager.org/page/BugReporting
1083

COPYRIGHT

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