1VIRT-INSTALL(1) Virtual Machine Install Tools VIRT-INSTALL(1)
2
6 virt-install - provision new virtual machines
7
9 virt-install [OPTION]...
10
12 virt-install is a command line tool for creating new KVM, Xen, or Linux
13 container guests using the "libvirt" hypervisor management library.
14 See the EXAMPLES section at the end of this document to quickly get
15 started.
16 virt-install tool supports graphical installations using (for example)
18 VNC or SPICE, as well as text mode installs over serial console. The
19 guest can be configured to use one or more virtual disks, network
20 interfaces, audio devices, physical USB or PCI devices, among others.
21 The installation media can be held locally or remotely on NFS, HTTP,
23 FTP servers. In the latter case "virt-install" will fetch the minimal
24 files necessary to kick off the installation process, allowing the
25 guest to fetch the rest of the OS distribution as needed. PXE booting,
26 and importing an existing disk image (thus skipping the install phase)
27 are also supported.
28 Given suitable command line arguments, "virt-install" is capable of
30 running completely unattended, with the guest 'kickstarting' itself
31 too. This allows for easy automation of guest installs. An interactive
32 mode is also available with the --prompt option, but this will only ask
33 for the minimum required options.
34
36 Most options are not required. Minimum requirements are --name, --ram,
37 guest storage (--disk, --filesystem or --nodisks), and an install
38 option.
39 -h, --help
41 Show the help message and exit
42 --connect=CONNECT
44 Connect to a non-default hypervisor. The default connection is chosen
45 based on the following rules:
46 xen If running on a host with the Xen kernel (checks against
48 /proc/xen)
49 qemu:///system
51 If running on a bare metal kernel as root (needed for KVM
52 installs)
53 qemu:///session
55 If running on a bare metal kernel as non-root
56 It is only necessary to provide the "--connect" argument if this
58 default prioritization is incorrect, eg if wanting to use QEMU
59 while on a Xen kernel.
60 General Options
62 General configuration parameters that apply to all types of guest
63 installs.
64 -n NAME, --name=NAME
66 Name of the new guest virtual machine instance. This must be unique
67 amongst all guests known to the hypervisor on the connection,
68 including those not currently active. To re-define an existing guest,
69 use the virsh(1) tool to shut it down ('virsh shutdown') & delete
70 ('virsh undefine') it prior to running "virt-install".
71 -r MEMORY, --ram=MEMORY
73 Memory to allocate for guest instance in megabytes. If the hypervisor
74 does not have enough free memory, it is usual for it to automatically
75 take memory away from the host operating system to satisfy this
76 allocation.
77 --arch=ARCH
79 Request a non-native CPU architecture for the guest virtual machine.
80 If omitted, the host CPU architecture will be used in the guest.
81 --machine=MACHINE
83 The machine type to emulate. This will typically not need to be
84 specified for Xen or KVM, but is useful for choosing machine types of
85 more exotic architectures.
86 -u UUID, --uuid=UUID
88 UUID for the guest; if none is given a random UUID will be generated.
89 If you specify UUID, you should use a 32-digit hexadecimal number.
90 UUID are intended to be unique across the entire data center, and
91 indeed world. Bear this in mind if manually specifying a UUID
92 --vcpus=VCPUS[,maxvcpus=MAX][,sockets=#][,cores=#][,threads=#]
94 Number of virtual cpus to configure for the guest. If 'maxvcpus' is
95 specified, the guest will be able to hotplug up to MAX vcpus while
96 the guest is running, but will startup with VCPUS.
97 CPU topology can additionally be specified with sockets, cores, and
99 threads. If values are omitted, the rest will be autofilled
100 prefering sockets over cores over threads.
101 --cpuset=CPUSET
103 Set which physical cpus the guest can use. "CPUSET" is a comma
104 separated list of numbers, which can also be specified in ranges or
105 cpus to exclude. Example:
106 0,2,3,5 : Use processors 0,2,3 and 5
108 1-5,^3,8 : Use processors 1,2,4,5 and 8
109 If the value 'auto' is passed, virt-install attempts to automatically
111 determine an optimal cpu pinning using NUMA data, if available.
112 --numatune=NODESET,[mode=MODE]
114 Tune NUMA policy for the domain process. Example invocations
115 --numatune 1,2,3,4-7
117 --numatune \"1-3,5\",mode=preferred
118 Specifies the numa nodes to allocate memory from. This has the same
120 syntax as "--cpuset" option. mode can be one of 'interleave',
121 'preferred', or 'strict' (the default). See 'man 8 numactl' for
122 information about each mode.
123 The nodeset string must use escaped-quotes if specifying any other
125 option.
126 --cpu MODEL[,+feature][,-feature][,match=MATCH][,vendor=VENDOR]
128 Configure the CPU model and CPU features exposed to the guest. The
129 only required value is MODEL, which is a valid CPU model as listed in
130 libvirt's cpu_map.xml file.
131 Specific CPU features can be specified in a number of ways: using one
133 of libvirt's feature policy values force, require, optional, disable,
134 or forbid, or with the shorthand '+feature' and '-feature', which
135 equal 'force=feature' and 'disable=feature' respectively
136 Some examples:
138 --cpu core2duo,+x2apic,disable=vmx
140 Expose the core2duo CPU model, force enable x2apic, but do not
141 expose vmx
142 --cpu host
144 Expose the host CPUs configuration to the guest. This enables the
145 guest to take advantage of many of the host CPUs features (better
146 performance), but may cause issues if migrating the guest to a host
147 without an identical CPU.
148 --description
150 Human readable text description of the virtual machine. This will be
151 stored in the guests XML configuration for access by other
152 applications.
153 --security type=TYPE[,label=LABEL][,relabel=yes|no]
155 Configure domain security driver settings. Type can be either
156 'static' or 'dynamic'. 'static' configuration requires a security
157 LABEL. Specifying LABEL without TYPE implies static configuration. To
158 have libvirt automatically apply your static label, you must specify
159 relabel=yes.
160 Installation Method options
162 -c CDROM, --cdrom=CDROM
163 File or device use as a virtual CD-ROM device for fully virtualized
164 guests. It can be path to an ISO image, or to a CDROM device. It can
165 also be a URL from which to fetch/access a minimal boot ISO image.
166 The URLs take the same format as described for the "--location"
167 argument. If a cdrom has been specified via the "--disk" option, and
168 neither "--cdrom" nor any other install option is specified, the
169 "--disk" cdrom is used as the install media.
170 -l LOCATION, --location=LOCATION
172 Distribution tree installtion source. virt-install can recognize
173 certain distribution trees and fetches a bootable kernel/initrd pair
174 to launch the install.
175 With libvirt 0.9.4 or later, network URL installs work for remote
177 connections. virt-install will download kernel/initrd to the local
178 machine, and then upload the media to the remote host. This option
179 requires the URL to be accessible by both the local and remote host.
180 The "LOCATION" can take one of the following forms:
182 DIRECTORY
184 Path to a local directory containing an installable distribution
185 image
186 nfs:host:/path or nfs://host/path
188 An NFS server location containing an installable distribution
189 image
190 http://host/path
192 An HTTP server location containing an installable distribution
193 image
194 ftp://host/path
196 An FTP server location containing an installable distribution
197 image
198 Some distro specific url samples:
200 Fedora/Red Hat Based
202 http://download.fedoraproject.org/pub/fedora/linux/releases/10/Fedora/i386/os/
203 Debian/Ubuntu
205 http://ftp.us.debian.org/debian/dists/etch/main/installer-amd64/
206 Suse
208 http://download.opensuse.org/distribution/11.0/repo/oss/
209 Mandriva
211 ftp://ftp.uwsg.indiana.edu/linux/mandrake/official/2009.0/i586/
212 --pxe
214 Use the PXE boot protocol to load the initial ramdisk and kernel for
215 starting the guest installation process.
216 --import
218 Skip the OS installation process, and build a guest around an
219 existing disk image. The device used for booting is the first device
220 specified via "--disk" or "--filesystem".
221 --init=INITPATH
223 Path to a binary that the container guest will init. If a root
224 "--filesystem" is has been specified, virt-install will default to
225 /sbin/init, otherwise will default to /bin/sh.
226 --livecd
228 Specify that the installation media is a live CD and thus the guest
229 needs to be configured to boot off the CDROM device permanently. It
230 may be desirable to also use the "--nodisks" flag in combination.
231 -x EXTRA, --extra-args=EXTRA
233 Additional kernel command line arguments to pass to the installer
234 when performing a guest install from "--location". One common usage
235 is specifying an anaconda kickstart file for automated installs, such
236 as --extra-args "ks=http://myserver/my.ks"
237 --initrd-inject=PATH
239 Add PATH to the root of the initrd fetched with "--location". This
240 can be used to run an automated install without requiring a network
241 hosted kickstart file:
242 --initrd-inject=/path/to/my.ks --extra-args "ks=file:/my.ks"
244 --os-type=OS_TYPE
246 Optimize the guest configuration for a type of operating system (ex.
247 'linux', 'windows'). This will attempt to pick the most suitable ACPI
248 & APIC settings, optimally supported mouse drivers, virtio, and
249 generally accommodate other operating system quirks.
250 By default, virt-install will attempt to auto detect this value from
252 the install media (currently only supported for URL installs).
253 Autodetection can be disabled with the special value 'none'
254 See "--os-variant" for valid options.
256 --os-variant=OS_VARIANT
258 Further optimize the guest configuration for a specific operating
259 system variant (ex. 'fedora8', 'winxp'). This parameter is optional,
260 and does not require an "--os-type" to be specified.
261 By default, virt-install will attempt to auto detect this value from
263 the install media (currently only supported for URL installs).
264 Autodetection can be disabled with the special value 'none'.
265 If the special value 'list' is passed, virt-install will print the
267 full list of variant values and exit. The printed format is not a
268 stable interface, DO NOT PARSE IT.
269 If the special value 'none' is passed, no os variant is recorded and
271 OS autodetection is disabled.
272 Values for some recent OS options are:
274 win7 : Microsoft Windows 7 and later
276 vista : Microsoft Windows Vista
277 winxp64 : Microsoft Windows XP (x86_64)
278 winxp : Microsoft Windows XP
279 win2k8 : Microsoft Windows Server 2008 and later
280 win2k3 : Microsoft Windows Server 2003
281 freebsd8 : FreeBSD 8.x and later
282 generic : Generic
283 debianwheezy : Debian Wheezy and later
284 debiansqueeze : Debian Squeeze
285 debianlenny : Debian Lenny
286 fedora18 : Fedora 18 and later
287 fedora17 : Fedora 17
288 fedora16 : Fedora 16
289 fedora15 : Fedora 15
290 mageia1 : Mageia 1 and later
291 mes5.1 : Mandriva Enterprise Server 5.1 and later
292 rhel6 : Red Hat Enterprise Linux 6
293 rhel5.4 : Red Hat Enterprise Linux 5.4 or later
294 rhel4 : Red Hat Enterprise Linux 4
295 sles11 : Suse Linux Enterprise Server 11 and later
296 sles10 : Suse Linux Enterprise Server
297 opensuse12 : openSuse 12 and later
298 opensuse11 : openSuse 11
299 ubuntuquantal : Ubuntu 12.10 (Quantal Quetzal) and later
300 ubuntuprecise : Ubuntu 12.04 LTS (Precise Pangolin)
301 ubuntuoneiric : Ubuntu 11.10 (Oneiric Ocelot)
302 ubuntunatty : Ubuntu 11.04 (Natty Narwhal)
303 ubuntulucid : Ubuntu 10.04 LTS (Lucid Lynx)
304 ubuntuhardy : Ubuntu 8.04 LTS (Hardy Heron)
305 Use '--os-variant list' to see the full OS list
307 --boot=BOOTOPTS
309 Optionally specify the post-install VM boot configuration. This
310 option allows specifying a boot device order, permanently booting off
311 kernel/initrd with option kernel arguments, and enabling a BIOS boot
312 menu (requires libvirt 0.8.3 or later)
313 --boot can be specified in addition to other install options (such as
315 --location, --cdrom, etc.) or can be specified on it's own. In the
316 latter case, behavior is similar to the --import install option:
317 there is no 'install' phase, the guest is just created and launched
318 as specified.
319 Some examples:
321 --boot cdrom,fd,hd,network,menu=on
323 Set the boot device priority as first cdrom, first floppy, first
324 harddisk, network PXE boot. Additionally enable BIOS boot menu
325 prompt.
326 --boot kernel=KERNEL,initrd=INITRD,kernel_args="console=/dev/ttyS0"
328 Have guest permanently boot off a local kernel/initrd pair, with
329 the specified kernel options.
330 Storage Configuration
332 --disk=DISKOPTS
333 Specifies media to use as storage for the guest, with various
334 options. The general format of a disk string is
335 --disk opt1=val1,opt2=val2,...
337 To specify media, the command can either be:
339 --disk /some/storage/path,opt1=val1
341 or explicitly specify one of the following arguments:
343 path
345 A path to some storage media to use, existing or not. Existing
346 media can be a file or block device. If installing on a remote
347 host, the existing media must be shared as a libvirt storage
348 volume.
349 Specifying a non-existent path implies attempting to create the
351 new storage, and will require specifyng a 'size' value. If the
352 base directory of the path is a libvirt storage pool on the host,
353 the new storage will be created as a libvirt storage volume. For
354 remote hosts, the base directory is required to be a storage pool
355 if using this method.
356 pool
358 An existing libvirt storage pool name to create new storage on.
359 Requires specifying a 'size' value.
360 vol An existing libvirt storage volume to use. This is specified as
362 'poolname/volname'.
363 Other available options:
365 device
367 Disk device type. Value can be 'cdrom', 'disk', 'lun' or
368 'floppy'. Default is 'disk'. If a 'cdrom' is specified, and no
369 install method is chosen, the cdrom is used as the install media.
370 bus Disk bus type. Value can be 'ide', 'scsi', 'usb', 'virtio' or
372 'xen'. The default is hypervisor dependent since not all
373 hypervisors support all bus types.
374 perms
376 Disk permissions. Value can be 'rw' (Read/Write), 'ro'
377 (Readonly), or 'sh' (Shared Read/Write). Default is 'rw'
378 size
380 size (in GB) to use if creating new storage
381 sparse
383 whether to skip fully allocating newly created storage. Value is
384 'true' or 'false'. Default is 'true' (do not fully allocate)
385 unless it isn't supported by the underlying storage type.
386 The initial time taken to fully-allocate the guest virtual disk
388 (sparse=false) will be usually balanced by faster install times
389 inside the guest. Thus use of this option is recommended to
390 ensure consistently high performance and to avoid I/O errors in
391 the guest should the host filesystem fill up.
392 cache
394 The cache mode to be used. The host pagecache provides cache
395 memory. The cache value can be 'none', 'writethrough', or
396 'writeback'. 'writethrough' provides read caching. 'writeback'
397 provides read and write caching.
398 format
400 Image format to be used if creating managed storage. For file
401 volumes, this can be 'raw', 'qcow2', 'vmdk', etc. See format
402 types in <http://libvirt.org/storage.html> for possible values.
403 This is often mapped to the driver_type value as well.
404 With libvirt 0.8.3 and later, this option should be specified if
406 reusing an existing disk image, since libvirt does not autodetect
407 storage format as it is a potential security issue. For example,
408 if reusing an existing qcow2 image, you will want to specify
409 format=qcow2, otherwise the hypervisor may not be able to read
410 your disk image.
411 driver_name
413 Driver name the hypervisor should use when accessing the
414 specified storage. Typically does not need to be set by the user.
415 driver_type
417 Driver format/type the hypervisor should use when accessing the
418 specified storage. Typically does not need to be set by the user.
419 io Disk IO backend. Can be either "threads" or "native".
421 error_policy
423 How guest should react if a write error is encountered. Can be
424 one of "stop", "none", or "enospace"
425 serial
427 Serial number of the emulated disk device. This is used in linux
428 guests to set /dev/disk/by-id symlinks. An example serial number
429 might be: WD-WMAP9A966149
430 startup_policy
432 It defines what to do with the disk if the source file is not
433 accessible. See possible values in
434 <http://www.libvirt.org/formatdomain.html#elementsDisks>
435 See the examples section for some uses. This option deprecates
437 "--file", "--file-size", and "--nonsparse".
438 --filesystem
440 Specifies a directory on the host to export to the guest. The most
441 simple invocation is:
442 --filesystem /source/on/host,/target/point/in/guest
444 Which will work for recent QEMU and linux guest OS or LXC containers.
446 For QEMU, the target point is just a mounting hint in sysfs, so will
447 not be automatically mounted.
448 The following explicit options can be specified:
450 type
452 The type or the source directory. Valid values are 'mount' (the
453 default) or 'template' for OpenVZ templates.
454 mode
456 The access mode for the source directory from the guest OS. Only
457 used with QEMU and type=mount. Valid modes are 'passthrough' (the
458 default), 'mapped', or 'squash'. See libvirt domain XML
459 documentation for more info.
460 source
462 The directory on the host to share.
463 target
465 The mount location to use in the guest.
466 --nodisks
468 Request a virtual machine without any local disk storage, typically
469 used for running 'Live CD' images or installing to network storage
470 (iSCSI or NFS root).
471 -f DISKFILE, --file=DISKFILE
473 This option is deprecated in favor of "--disk path=DISKFILE".
474 -s DISKSIZE, --file-size=DISKSIZE
476 This option is deprecated in favor of "--disk ...,size=DISKSIZE,..."
477 --nonsparse
479 This option is deprecated in favor of "--disk ...,sparse=false,..."
480 Networking Configuration
482 -w NETWORK, --network=NETWORK,opt1=val1,opt2=val2
483 Connect the guest to the host network. The value for "NETWORK" can
484 take one of 4 formats:
485 bridge=BRIDGE
487 Connect to a bridge device in the host called "BRIDGE". Use this
488 option if the host has static networking config & the guest
489 requires full outbound and inbound connectivity to/from the LAN.
490 Also use this if live migration will be used with this guest.
491 network=NAME
493 Connect to a virtual network in the host called "NAME". Virtual
494 networks can be listed, created, deleted using the "virsh"
495 command line tool. In an unmodified install of "libvirt" there is
496 usually a virtual network with a name of "default". Use a virtual
497 network if the host has dynamic networking (eg NetworkManager),
498 or using wireless. The guest will be NATed to the LAN by
499 whichever connection is active.
500 type=direct,source=IFACE[,source_mode=MODE]
502 Direct connect to host interface IFACE using macvtap.
503 user
505 Connect to the LAN using SLIRP. Only use this if running a QEMU
506 guest as an unprivileged user. This provides a very limited form
507 of NAT.
508 If this option is omitted a single NIC will be created in the guest.
510 If there is a bridge device in the host with a physical interface
511 enslaved, that will be used for connectivity. Failing that, the
512 virtual network called "default" will be used. This option can be
513 specified multiple times to setup more than one NIC.
514 Other available options are:
516 model
518 Network device model as seen by the guest. Value can be any nic
519 model supported by the hypervisor, e.g.: 'e1000', 'rtl8139',
520 'virtio', ...
521 mac Fixed MAC address for the guest; If this parameter is omitted, or
523 the value "RANDOM" is specified a suitable address will be
524 randomly generated. For Xen virtual machines it is required that
525 the first 3 pairs in the MAC address be the sequence '00:16:3e',
526 while for QEMU or KVM virtual machines it must be '52:54:00'.
527 --nonetworks
529 Request a virtual machine without any network interfaces.
530 -b BRIDGE, --bridge=BRIDGE
532 This parameter is deprecated in favour of "--network
533 bridge=bridge_name".
534 -m MAC, --mac=MAC
536 This parameter is deprecated in favour of "--network
537 NETWORK,mac=12:34..."
538 Graphics Configuration
540 If no graphics option is specified, "virt-install" will default to
541 '--graphics vnc' if the DISPLAY environment variable is set, otherwise
542 '--graphics none' is used.
543 --graphics TYPE,opt1=arg1,opt2=arg2,...
545 Specifies the graphical display configuration. This does not
546 configure any virtual hardware, just how the guest's graphical
547 display can be accessed. Typically the user does not need to specify
548 this option, virt-install will try and choose a useful default, and
549 launch a suitable connection.
550 General format of a graphical string is
552 --graphics TYPE,opt1=arg1,opt2=arg2,...
554 For example:
556 --graphics vnc,password=foobar
558 The supported options are:
560 type
562 The display type. This is one of:
563 vnc
565 Setup a virtual console in the guest and export it as a VNC
567 server in the host. Unless the "port" parameter is also provided,
568 the VNC server will run on the first free port number at 5900 or
569 above. The actual VNC display allocated can be obtained using the
570 "vncdisplay" command to "virsh" (or virt-viewer(1) can be used
571 which handles this detail for the use).
572 spice
574 Export the guest's console using the Spice protocol. Spice allows
576 advanced features like audio and USB device streaming, as well as
577 improved graphical performance.
578 Using spice graphic type will work as if those arguments were
580 given:
581 --video qxl --channel spicevmc
583 none
585 No graphical console will be allocated for the guest. Fully
587 virtualized guests (Xen FV or QEmu/KVM) will need to have a text
588 console configured on the first serial port in the guest (this
589 can be done via the --extra-args option). Xen PV will set this up
590 automatically. The command 'virsh console NAME' can be used to
591 connect to the serial device.
592 port
594 Request a permanent, statically assigned port number for the
595 guest console. This is used by 'vnc' and 'spice'
596 tlsport
598 Specify the spice tlsport.
599 listen
601 Address to listen on for VNC/Spice connections. Default is
602 typically 127.0.0.1 (localhost only), but some hypervisors allow
603 changing this globally (for example, the qemu driver default can
604 be changed in /etc/libvirt/qemu.conf). Use 0.0.0.0 to allow
605 access from other machines. This is use by 'vnc' and 'spice'
606 keymap
608 Request that the virtual VNC console be configured to run with a
609 specific keyboard layout. If the special value 'local' is
610 specified, virt-install will attempt to configure to use the same
611 keymap as the local system. A value of 'none' specifically defers
612 to the hypervisor. Default behavior is hypervisor specific, but
613 typically is the same as 'local'. This is used by 'vnc'
614 password
616 Request a VNC password, required at connection time. Beware, this
617 info may end up in virt-install log files, so don't use an
618 important password. This is used by 'vnc' and 'spice'
619 passwordvalidto
621 Set an expiration date for password. After the date/time has
622 passed, all new graphical connections are denyed until a new
623 password is set. This is used by 'vnc' and 'spice'
624 The format for this value is YYYY-MM-DDTHH:MM:SS, for example
626 2011-04-01T14:30:15
627 --vnc
629 This option is deprecated in favor of "--graphics vnc,..."
630 --vncport=VNCPORT
632 This option is deprecated in favor of "--graphics vnc,port=PORT,..."
633 --vnclisten=VNCLISTEN
635 This option is deprecated in favor of "--graphics
636 vnc,listen=LISTEN,..."
637 -k KEYMAP, --keymap=KEYMAP
639 This option is deprecated in favor of "--graphics
640 vnc,keymap=KEYMAP,..."
641 --nographics
643 This option is deprecated in favor of "--graphics none"
644 --noautoconsole
646 Don't automatically try to connect to the guest console. The default
647 behaviour is to launch a VNC client to display the graphical console,
648 or to run the "virsh" "console" command to display the text console.
649 Use of this parameter will disable this behaviour.
650 Virtualization Type options
652 Options to override the default virtualization type choices.
653 -v, --hvm
655 Request the use of full virtualization, if both para & full
656 virtualization are available on the host. This parameter may not be
657 available if connecting to a Xen hypervisor on a machine without
658 hardware virtualization support. This parameter is implied if
659 connecting to a QEMU based hypervisor.
660 -p, --paravirt
662 This guest should be a paravirtualized guest. If the host supports
663 both para & full virtualization, and neither this parameter nor the
664 "--hvm" are specified, this will be assumed.
665 --container
667 This guest should be a container type guest. This option is only
668 required if the hypervisor supports other guest types as well (so for
669 example this option is the default behavior for LXC and OpenVZ, but
670 is provided for completeness).
671 --virt-type
673 The hypervisor to install on. Example choices are kvm, qemu, xen, or
674 kqemu. Availabile options are listed via 'virsh capabilities' in the
675 <domain> tags.
676 --accelerate
678 Prefer KVM or KQEMU (in that order) if installing a QEMU guest. This
679 behavior is now the default, and this option is deprecated. To
680 install a plain QEMU guest, use '--virt-type qemu'
681 --noapic
683 Force disable APIC for the guest.
684 --noacpi
686 Force disable ACPI for the guest.
687 Device Options
689 --host-device=HOSTDEV
690 Attach a physical host device to the guest. Some example values for
691 HOSTDEV:
692 --host-device pci_0000_00_1b_0
694 A node device name via libvirt, as shown by 'virsh nodedev-list'
695 --host-device 001.003
697 USB by bus, device (via lsusb).
698 --host-device 0x1234:0x5678
700 USB by vendor, product (via lsusb).
701 --host-device 1f.01.02
703 PCI device (via lspci).
704 --soundhw MODEL
706 Attach a virtual audio device to the guest. MODEL specifies the
707 emulated sound card model. Possible values are ich6, ac97, es1370,
708 sb16, pcspk, or default. 'default' will be AC97 if the hypervisor
709 supports it, otherwise it will be ES1370.
710 This deprecates the old boolean --sound model (which still works the
712 same as a single '--soundhw default')
713 --watchdog MODEL[,action=ACTION]
715 Attach a virtual hardware watchdog device to the guest. This requires
716 a daemon and device driver in the guest. The watchdog fires a signal
717 when the virtual machine appears to hung. ACTION specifies what
718 libvirt will do when the watchdog fires. Values are
719 reset
721 Forcefully reset the guest (the default)
722 poweroff
724 Forcefully power off the guest
725 pause
727 Pause the guest
728 none
730 Do nothing
731 shutdown
733 Gracefully shutdown the guest (not recommended, since a hung
734 guest probably won't respond to a graceful shutdown)
735 MODEL is the emulated device model: either i6300esb (the default) or
737 ib700. Some examples:
738 Use the recommended settings:
740 --watchdog default
742 Use the i6300esb with the 'poweroff' action
744 --watchdog i6300esb,action=poweroff
746 --parallel=CHAROPTS
748 --serial=CHAROPTS
749 Specifies a serial device to attach to the guest, with various
750 options. The general format of a serial string is
751 --serial type,opt1=val1,opt2=val2,...
753 --serial and --parallel devices share all the same options, unless
755 otherwise noted. Some of the types of character device redirection
756 are:
757 --serial pty
759 Pseudo TTY. The allocated pty will be listed in the running
760 guests XML description.
761 --serial dev,path=HOSTPATH
763 Host device. For serial devices, this could be /dev/ttyS0. For
764 parallel devices, this could be /dev/parport0.
765 --serial file,path=FILENAME
767 Write output to FILENAME.
768 --serial pipe,path=PIPEPATH
770 Named pipe (see pipe(7))
771 --serial tcp,host=HOST:PORT,mode=MODE,protocol=PROTOCOL
773 TCP net console. MODE is either 'bind' (wait for connections on
774 HOST:PORT) or 'connect' (send output to HOST:PORT), default is
775 'connect'. HOST defaults to '127.0.0.1', but PORT is required.
776 PROTOCOL can be either 'raw' or 'telnet' (default 'raw'). If
777 'telnet', the port acts like a telnet server or client. Some
778 examples:
779 Connect to localhost, port 1234:
781 --serial tcp,host=:1234
783 Wait for connections on any address, port 4567:
785 --serial tcp,host=0.0.0.0:4567,mode=bind
787 Wait for telnet connection on localhost, port 2222. The user
789 could then connect interactively to this console via 'telnet
790 localhost 2222':
791 --serial tcp,host=:2222,mode=bind,protocol=telnet
793 --serial udp,host=CONNECT_HOST:PORT,bind_host=BIND_HOST:BIND_PORT
795 UDP net console. HOST:PORT is the destination to send output to
796 (default HOST is '127.0.0.1', PORT is required).
797 BIND_HOST:BIND_PORT is the optional local address to bind to
798 (default BIND_HOST is 127.0.0.1, but is only set if BIND_PORT is
799 specified). Some examples:
800 Send output to default syslog port (may need to edit
802 /etc/rsyslog.conf accordingly):
803 --serial udp,host=:514
805 Send output to remote host 192.168.10.20, port 4444 (this output
807 can be read on the remote host using 'nc -u -l 4444'):
808 --serial udp,host=192.168.10.20:4444
810 --serial unix,path=UNIXPATH,mode=MODE
812 Unix socket, see unix(7). MODE has similar behavior and defaults
813 as --serial tcp,mode=MODE
814 --channel
816 Specifies a communication channel device to connect the guest and
817 host machine. This option uses the same options as --serial and
818 --parallel for specifying the host/source end of the channel. Extra
819 'target' options are used to specify how the guest machine sees the
820 channel.
821 Some of the types of character device redirection are:
823 --channel SOURCE,target_type=guestfwd,target_address=HOST:PORT
825 Communication channel using QEMU usermode networking stack. The
826 guest can connect to the channel using the specified HOST:PORT
827 combination.
828 --channel SOURCE,target_type=virtio[,name=NAME]
830 Communication channel using virtio serial (requires 2.6.34 or
831 later host and guest). Each instance of a virtio --channel line
832 is exposed in the guest as /dev/vport0p1, /dev/vport0p2, etc.
833 NAME is optional metadata, and can be any string, such as
834 org.linux-kvm.virtioport1. If specified, this will be exposed in
835 the guest at /sys/class/virtio-ports/vport0p1/NAME
836 --channel spicevmc,target_type=virtio[,name=NAME]
838 Communication channel for QEMU spice agent, using virtio serial
839 (requires 2.6.34 or later host and guest). NAME is optional
840 metadata, and can be any string, such as the default
841 com.redhat.spice.0 that specifies how the guest will see the
842 channel.
843 --console
845 Connect a text console between the guest and host. Certain guest and
846 hypervisor combinations can automatically set up a getty in the
847 guest, so an out of the box text login can be provided
848 (target_type=xen for xen paravirt guests, and possibly
849 target_type=virtio in the future).
850 Example:
852 --console pty,target_type=virtio
854 Connect a virtio console to the guest, redirected to a PTY on the
855 host. For supported guests, this exposes /dev/hvc0 in the guest.
856 See http://fedoraproject.org/wiki/Features/VirtioSerial for more
857 info. virtio console requires libvirt 0.8.3 or later.
858 --video=VIDEO
860 Specify what video device model will be attached to the guest. Valid
861 values for VIDEO are hypervisor specific, but some options for recent
862 kvm are cirrus, vga, qxl, or vmvga (vmware).
863 --smartcard=MODE[,OPTS]
865 Configure a virtual smartcard device.
866 Mode is one of host, host-certificates, or passthrough. Additional
868 options are:
869 type
871 Character device type to connect to on the host. This is only
872 applicable for passthrough mode.
873 An example invocation:
875 --smartcard passthrough,type=spicevmc
877 Use the smartcard channel of a SPICE graphics device to pass
878 smartcard info to the guest
879 See "http://libvirt.org/formatdomain.html#elementsSmartcard" for
881 complete details.
882 --redirdev=BUS[,OPTS]
884 Add a redirected device.
885 type
887 The redirection type, currently supported is tcp or spicevmc.
888 server
890 The TCP server connection details, of the form 'server:port'.
891 Examples of invocation:
893 --redirdev usb,type=tcp,server=localhost:4000
895 Add a USB redirected device provided by the TCP server on
896 'localhost' port 4000.
897 --redirdev usb,type=spicevmc
899 Add a USB device redirected via a dedicated Spice channel.
900 --panic OPTS
902 Attach a panic notifier device to the guest. For the recommended
903 settings, use:
904 --panic default
906 See "http://libvirt.org/formatdomain.html#elementsPanic" for complete
908 details.
909 Miscellaneous Options
911 --autostart
912 Set the autostart flag for a domain. This causes the domain to be
913 started on host boot up.
914 --print-xml
916 If the requested guest has no install phase (--import, --boot), print
917 the generated XML instead of defining the guest. By default this WILL
918 do storage creation (can be disabled with --dry-run).
919 If the guest has an install phase, you will need to use --print-step
921 to specify exactly what XML output you want. This option implies
922 --quiet.
923 --print-step
925 Acts similarly to --print-xml, except requires specifying which
926 install step to print XML for. Possible values are 1, 2, 3, or all.
927 Stage 1 is typically booting from the install media, and stage 2 is
928 typically the final guest config booting off hardisk. Stage 3 is only
929 relevant for windows installs, which by default have a second install
930 stage. This option implies --quiet.
931 --noreboot
933 Prevent the domain from automatically rebooting after the install has
934 completed.
935 --wait=WAIT
937 Amount of time to wait (in minutes) for a VM to complete its install.
938 Without this option, virt-install will wait for the console to close
939 (not neccessarily indicating the guest has shutdown), or in the case
940 of --noautoconsole, simply kick off the install and exit. Any
941 negative value will make virt-install wait indefinitely, a value of 0
942 triggers the same results as noautoconsole. If the time limit is
943 exceeded, virt-install simply exits, leaving the virtual machine in
944 its current state.
945 --force
947 Prevent interactive prompts. If the intended prompt was a yes/no
948 prompt, always say yes. For any other prompts, the application will
949 exit.
950 --dry-run
952 Proceed through the guest creation process, but do NOT create storage
953 devices, change host device configuration, or actually teach libvirt
954 about the guest. virt-install may still fetch install media, since
955 this is required to properly detect the OS to install.
956 --prompt
958 Specifically enable prompting for required information. Default
959 prompting is off (as of virtinst 0.400.0)
960 --check-cpu
962 Check that the number virtual cpus requested does not exceed physical
963 CPUs and warn if they do.
964 -q, --quiet
966 Only print fatal error messages.
967 -d, --debug
969 Print debugging information to the terminal when running the install
970 process. The debugging information is also stored in
971 "$HOME/.virtinst/virt-install.log" even if this parameter is omitted.
972
974 Install a Fedora 13 KVM guest with virtio accelerated disk/network,
975 creating a new 8GB storage file, installing from media in the hosts
976 CDROM drive, auto launching a graphical VNC viewer
977 # virt-install \
979 --connect qemu:///system \
980 --virt-type kvm \
981 --name demo \
982 --ram 500 \
983 --disk path=/var/lib/libvirt/images/demo.img,size=8 \
984 --graphics vnc \
985 --cdrom /dev/cdrom \
986 --os-variant fedora13
987 Install a Fedora 9 plain QEMU guest, using LVM partition, virtual
989 networking, booting from PXE, using VNC server/viewer
990 # virt-install \
992 --connect qemu:///system \
993 --name demo \
994 --ram 500 \
995 --disk path=/dev/HostVG/DemoVM \
996 --network network=default \
997 --virt-type qemu
998 --graphics vnc \
999 --os-variant fedora9
1000 Run a Live CD image under Xen fullyvirt, in diskless environment
1002 # virt-install \
1004 --hvm \
1005 --name demo \
1006 --ram 500 \
1007 --nodisks \
1008 --livecd \
1009 --graphics vnc \
1010 --cdrom /root/fedora7live.iso
1011 Run /usr/bin/httpd in a linux container guest (LXC). Resource usage is
1013 capped at 512 MB of ram and 2 host cpus:
1014 # virt-install \
1016 --connect lxc:/// \
1017 --name httpd_guest \
1018 --ram 512 \
1019 --vcpus 2 \
1020 --init /usr/bin/httpd
1021 Install a paravirtualized Xen guest, 500 MB of RAM, a 5 GB of disk, and
1023 Fedora Core 6 from a web server, in text-only mode, with old style
1024 --file options:
1025 # virt-install \
1027 --paravirt \
1028 --name demo \
1029 --ram 500 \
1030 --file /var/lib/xen/images/demo.img \
1031 --file-size 6 \
1032 --graphics none \
1033 --location http://download.fedora.redhat.com/pub/fedora/linux/core/6/x86_64/os/
1034 Create a guest from an existing disk image 'mydisk.img' using defaults
1036 for the rest of the options.
1037 # virt-install \
1039 --name demo
1040 --ram 512
1041 --disk /home/user/VMs/mydisk.img
1042 --import
1043 Test a custom kernel/initrd using an existing disk image, manually
1045 specifying a serial device hooked to a PTY on the host machine.
1046 # virt-install \
1048 --name mykernel
1049 --ram 512
1050 --disk /home/user/VMs/mydisk.img
1051 --boot kernel=/tmp/mykernel,initrd=/tmp/myinitrd,kernel_args="console=ttyS0"
1052 --serial pty
1053
1055 Written by Daniel P. Berrange, Hugh Brock, Jeremy Katz, Cole Robinson
1056 and a team of many other contributors. See the AUTHORS file in the
1057 source distribution for the complete list of credits.
1058
1060 Please see http://virt-manager.org/page/BugReporting
1061
1063 Copyright (C) 2006-2011 Red Hat, Inc, and various contributors. This
1064 is free software. You may redistribute copies of it under the terms of
1065 the GNU General Public License "http://www.gnu.org/licenses/gpl.html".
1066 There is NO WARRANTY, to the extent permitted by law.
1067
1069 virsh(1), "virt-clone(1)", "virt-manager(1)", the project website
1070 "http://virt-manager.org"
1071 2017-03-22 VIRT-INSTALL(1)