13
B<virt-install> is a command line tool for provisioning new virtual machines
14
using the C<libvirt> hypervisor management library. The tool supports both
15
text based & graphical installations, using serial console, SDL graphics
16
or a VNC client/server pair. The guest can be configured to use one or more
17
virtual disks, network interfaces, audio devices, and physical host devices
13
B<virt-install> is a command line tool for creating new KVM or Xen virtual
14
machines using the C<libvirt> hypervisor management library. See the EXAMPLES
15
section at the end of this document to quickly get started.
17
B<virt-install> tool supports both text based & graphical installations,
18
using VNC or SDL graphics, or a text serial console. The guest can be
19
configured to use one or more virtual disks, network interfaces,
20
audio devices, physical USB or PCI devices, among others.
20
22
The installation media can be held locally or remotely on NFS, HTTP, FTP
21
23
servers. In the latter case C<virt-install> will fetch the minimal files
98
106
to be unique across the entire data center, and indeed world. Bear this in
99
107
mind if manually specifying a UUID
103
Number of virtual cpus to configure for the guest. Not all hypervisors support
104
SMP guests, in which case this argument will be silently ignored
109
=item --vcpus=VCPUS[,maxvcpus=MAX][,sockets=#][,cores=#][,threads=#]
111
Number of virtual cpus to configure for the guest. If 'maxvcpus' is specified,
112
the guest will be able to hotplug up to MAX vcpus while the guest is running,
113
but will startup with VCPUS.
115
CPU topology can additionally be specified with sockets, cores, and threads.
116
If values are omitted, the rest will be autofilled prefering sockets over
106
119
=item --cpuset=CPUSET
113
126
If the value 'auto' is passed, virt-install attempts to automatically determine
114
127
an optimal cpu pinning using NUMA data, if available.
129
=item --cpu MODEL[,+feature][,-feature][,match=MATCH][,vendor=VENDOR]
131
Configure the CPU model and CPU features exposed to the guest. The only
132
required value is MODEL, which is a valid CPU model as listed in libvirt's
135
Specific CPU features can be specified in a number of ways: using one of
136
libvirt's feature policy values force, require, optional, disable, or forbid,
137
or with the shorthand '+feature' and '-feature', which equal 'force=feature'
138
and 'disable=feature' respectively
144
=item B<--cpu core2duo,+x2apic,disable=vmx>
146
Expose the core2duo CPU model, force enable x2apic, but do not expose vmx
150
Expose the host CPUs configuration to the guest. This enables the guest to
151
take advantage of many of the host CPUs features (better performance), but
152
may cause issues if migrating the guest to a host without an identical CPU.
116
156
=item --description
118
158
Human readable text description of the virtual machine. This will be stored
240
290
::VARIANT VALUES::
292
=item --boot=BOOTOPTS
294
Optionally specify the post-install VM boot configuration. This option allows
295
specifying a boot device order, permanently booting off kernel/initrd with
296
option kernel arguments, and enabling a BIOS boot menu (requires libvirt
299
--boot can be specified in addition to other install options
300
(such as --location, --cdrom, etc.) or can be specified on it's own. In
301
the latter case, behavior is similar to the --import install option: there
302
is no 'install' phase, the guest is just created and launched as specified.
308
=item B<--boot cdrom,fd,hd,network,menu=on>
310
Set the boot device priority as first cdrom, first floppy, first harddisk,
311
network PXE boot. Additionally enable BIOS boot menu prompt.
313
=item B<--boot kernel=KERNEL,initrd=INITRD,kernel_args="console=/dev/ttyS0">
315
Have guest permanently boot off a local kernel/initrd pair, with the
316
specified kernel options.
547
=item --graphics TYPE,opt1=arg1,opt2=arg2,...
549
Specifies the graphical display configuration. This does not configure any
550
virtual hardware, just how the guest's graphical display can be accessed.
551
Typically the user does not need to specify this option, virt-install will
552
try and choose a useful default, and launch a suitable connection.
554
General format of a graphical string is
556
--graphics TYPE,opt1=arg1,opt2=arg2,...
560
--graphics vnc,password=foobar
562
The supported options are:
568
The display type. This is one of:
461
572
Setup a virtual console in the guest and export it as a VNC server in
462
the host. Unless the C<--vncport> parameter is also provided, the VNC
573
the host. Unless the C<port> parameter is also provided, the VNC
463
574
server will run on the first free port number at 5900 or above. The
464
575
actual VNC display allocated can be obtained using the C<vncdisplay>
465
576
command to C<virsh> (or L<virt-viewer(1)> can be used which handles this
466
577
detail for the use).
468
=item --vncport=VNCPORT
470
Request a permanent, statically assigned port number for the guest VNC
471
console. Use of this option is discouraged as other guests may automatically
472
choose to run on this port causing a clash.
474
=item --vnclisten=VNCLISTEN
476
Address to listen on for VNC connections. Default is typically 127.0.0.1
581
Setup a virtual console in the guest and display an SDL window in the
582
host to render the output. If the SDL window is closed the guest may
583
be unconditionally terminated.
587
Export the guest's console using the Spice protocol. Spice allows advanced
588
features like audio and USB device streaming, as well as improved graphical
593
No graphical console will be allocated for the guest. Fully virtualized guests
594
(Xen FV or QEmu/KVM) will need to have a text console configured on the first
595
serial port in the guest (this can be done via the --extra-args option). Xen
596
PV will set this up automatically. The command 'virsh console NAME' can be
597
used to connect to the serial device.
601
Request a permanent, statically assigned port number for the guest
602
console. This is used by 'vnc' and 'spice'
606
Specify the spice tlsport.
610
Address to listen on for VNC/Spice connections. Default is typically 127.0.0.1
477
611
(localhost only), but some hypervisors allow changing this globally (for
478
612
example, the qemu driver default can be changed in /etc/libvirt/qemu.conf).
479
Use 0.0.0.0 to allow access from other machines.
613
Use 0.0.0.0 to allow access from other machines. This is use by 'vnc' and
481
=item -k KEYMAP, --keymap=KEYMAP
483
618
Request that the virtual VNC console be configured to run with a specific
484
619
keyboard layout. If the special value 'local' is specified, virt-install
485
620
will attempt to configure to use the same keymap as the local system. A value
486
621
of 'none' specifically defers to the hypervisor. Default behavior is
487
hypervisor specific, but typically is the same as 'local'.
622
hypervisor specific, but typically is the same as 'local'. This is used
627
Request a VNC password, required at connection time. Beware, this info may
628
end up in virt-install log files, so don't use an important password. This
629
is used by 'vnc' and 'spice'
631
=item B<passwordvalidto>
633
Set an expiration date for password. After the date/time has passed,
634
all new graphical connections are denyed until a new password is set.
635
This is used by 'vnc' and 'spice'
637
The format for this value is YYYY-MM-DDTHH:MM:SS, for example
644
This option is deprecated in favor of C<--graphics vnc,...>
646
=item --vncport=VNCPORT
648
This option is deprecated in favor of C<--graphics vnc,port=PORT,...>
650
=item --vnclisten=VNCLISTEN
652
This option is deprecated in favor of C<--graphics vnc,listen=LISTEN,...>
654
=item -k KEYMAP, --keymap=KEYMAP
656
This option is deprecated in favor of C<--graphics vnc,keymap=KEYMAP,...>
491
Setup a virtual console in the guest and display an SDL window in the
492
host to render the output. If the SDL window is closed the guest may
493
be unconditionally terminated.
660
This option is deprecated in favor of C<--graphics sdl,...>
495
662
=item --nographics
497
No graphical console will be allocated for the guest. Fully virtualized guests
498
(Xen FV or QEmu/KVM) will need to have a text console configured on the first
499
serial port in the guest (this can be done via the --extra-args option). Xen
500
PV will set this up automatically. The command 'virsh console NAME' can be
501
used to connect to the serial device.
664
This option is deprecated in favor of C<--graphics none>
503
666
=item --noautoconsole
883
Specifies a communication channel device to connect the guest and host
884
machine. This option uses the same options as --serial and --parallel
885
for specifying the host/source end of the channel. Extra 'target' options
886
are used to specify how the guest machine sees the channel.
888
Some of the types of character device redirection are:
892
=item B<--channel SOURCE,target_type=guestfwd,target_address=HOST:PORT>
894
Communication channel using QEMU usermode networking stack. The guest can
895
connect to the channel using the specified HOST:PORT combination.
897
=item B<--channel SOURCE,target_type=virtio[,name=NAME]>
899
Communication channel using virtio serial (requires 2.6.34 or later host and
900
guest). Each instance of a virtio --channel line is exposed in the
901
guest as /dev/vport0p1, /dev/vport0p2, etc. NAME is optional metadata, and
902
can be any string, such as org.linux-kvm.virtioport1.
903
If specified, this will be exposed in the guest at
904
/sys/class/virtio-ports/vport0p1/NAME
910
Connect a text console between the guest and host. Certain guest and
911
hypervisor combinations can automatically set up a getty in the guest, so
912
an out of the box text login can be provided (target_type=xen for xen
913
paravirt guests, and possibly target_type=virtio in the future).
919
=item B<--console pty,target_type=virtio>
921
Connect a virtio console to the guest, redirected to a PTY on the host.
922
For supported guests, this exposes /dev/hvc0 in the guest. See
923
http://fedoraproject.org/wiki/Features/VirtioSerial for more info. virtio
924
console requires libvirt 0.8.3 or later.
718
928
=item --video=VIDEO
720
930
Specify what video device model will be attached to the guest. Valid values
736
946
Set the autostart flag for a domain. This causes the domain to be started
951
If the requested guest has no install phase (--import, --boot), print the
952
generated XML instead of defining the guest. By default this WILL do storage
953
creation (can be disabled with --dry-run).
955
If the guest has an install phase, you will need to use --print-step to
956
specify exactly what XML output you want. This option implies --quiet.
960
Acts similarly to --print-xml, except requires specifying which install step
961
to print XML for. Possible values are 1, 2, 3, or all. Stage 1 is typically
962
booting from the install media, and stage 2 is typically the final guest
963
config booting off hardisk. Stage 3 is only relevant for windows installs,
964
which by default have a second install stage. This option implies --quiet.
741
968
Prevent the domain from automatically rebooting after the install has
779
Install a KVM guest (assuming proper host support), creating a new
780
storage file, virtual networking, booting from the host CDROM, using
1017
Install a Fedora 13 KVM guest with virtio accelerated disk/network,
1018
creating a new 8GB storage file, installing from media in the hosts
1019
CDROM drive, auto launching a graphical VNC viewer
783
1021
# virt-install \
784
1022
--connect qemu:///system \
787
--disk path=/var/lib/libvirt/images/demo.img,size=5 \
788
--network network=default,model=virtio \
1026
--disk path=/var/lib/libvirt/images/demo.img,size=8 \
1028
--cdrom /dev/cdrom \
1029
--os-variant fedora13
792
1031
Install a Fedora 9 plain QEMU guest, using LVM partition, virtual networking,
793
1032
booting from PXE, using VNC server/viewer
added
removed
man/en/virt-install.pod.in
