144
136
\&\fBvirt-install\fR [\s-1OPTION\s0]...
145
137
.SH "DESCRIPTION"
146
138
.IX Header "DESCRIPTION"
147
\&\fBvirt-install\fR is a command line tool for provisioning new virtual machines
148
using the \f(CW\*(C`libvirt\*(C'\fR hypervisor management library. The tool supports both
149
text based & graphical installations, using serial console, \s-1SDL\s0 graphics
150
or a \s-1VNC\s0 client/server pair. The guest can be configured to use one or more
151
virtual disks, network interfaces, audio devices, and physical host devices
152
(\s-1USB\s0, \s-1PCI\s0).
139
\&\fBvirt-install\fR is a command line tool for creating new \s-1KVM\s0 or Xen virtual
140
machines using the \f(CW\*(C`libvirt\*(C'\fR hypervisor management library. See the \s-1EXAMPLES\s0
141
section at the end of this document to quickly get started.
143
\&\fBvirt-install\fR tool supports both text based & graphical installations,
144
using \s-1VNC\s0 or \s-1SDL\s0 graphics, or a text serial console. The guest can be
145
configured to use one or more virtual disks, network interfaces,
146
audio devices, physical \s-1USB\s0 or \s-1PCI\s0 devices, among others.
154
148
The installation media can be held locally or remotely on \s-1NFS\s0, \s-1HTTP\s0, \s-1FTP\s0
155
149
servers. In the latter case \f(CW\*(C`virt\-install\*(C'\fR will fetch the minimal files
208
202
.IX Item "--arch=ARCH"
209
203
Request a non-native \s-1CPU\s0 architecture for the guest virtual machine.
210
204
If omitted, the host \s-1CPU\s0 architecture will be used in the guest.
205
.IP "\-\-machine=MACHINE" 2
206
.IX Item "--machine=MACHINE"
207
The machine type to emulate. This will typically not need to be specified
208
for Xen or \s-1KVM\s0, but is useful for choosing machine times of more exotic
211
210
.IP "\-u \s-1UUID\s0, \-\-uuid=UUID" 2
212
211
.IX Item "-u UUID, --uuid=UUID"
213
212
\&\s-1UUID\s0 for the guest; if none is given a random \s-1UUID\s0 will be generated. If you
214
213
specify \s-1UUID\s0, you should use a 32\-digit hexadecimal number. \s-1UUID\s0 are intended
215
214
to be unique across the entire data center, and indeed world. Bear this in
216
215
mind if manually specifying a \s-1UUID\s0
217
.IP "\-\-vcpus=VCPUS" 2
218
.IX Item "--vcpus=VCPUS"
219
Number of virtual cpus to configure for the guest. Not all hypervisors support
220
\&\s-1SMP\s0 guests, in which case this argument will be silently ignored
216
.IP "\-\-vcpus=VCPUS[,maxvcpus=MAX][,sockets=#][,cores=#][,threads=#]" 2
217
.IX Item "--vcpus=VCPUS[,maxvcpus=MAX][,sockets=#][,cores=#][,threads=#]"
218
Number of virtual cpus to configure for the guest. If 'maxvcpus' is specified,
219
the guest will be able to hotplug up to \s-1MAX\s0 vcpus while the guest is running,
220
but will startup with \s-1VCPUS\s0.
222
\&\s-1CPU\s0 topology can additionally be specified with sockets, cores, and threads.
223
If values are omitted, the rest will be autofilled prefering sockets over
221
225
.IP "\-\-cpuset=CPUSET" 2
222
226
.IX Item "--cpuset=CPUSET"
223
227
Set which physical cpus the guest can use. \f(CW\*(C`CPUSET\*(C'\fR is a comma separated list of numbers, which can also be specified in ranges. Example:
230
234
If the value 'auto' is passed, virt-install attempts to automatically determine
231
235
an optimal cpu pinning using \s-1NUMA\s0 data, if available.
236
.IP "\-\-cpu MODEL[,+feature][,\-feature][,match=MATCH][,vendor=VENDOR]" 2
237
.IX Item "--cpu MODEL[,+feature][,-feature][,match=MATCH][,vendor=VENDOR]"
238
Configure the \s-1CPU\s0 model and \s-1CPU\s0 features exposed to the guest. The only
239
required value is \s-1MODEL\s0, which is a valid \s-1CPU\s0 model as listed in libvirt's
242
Specific \s-1CPU\s0 features can be specified in a number of ways: using one of
243
libvirt's feature policy values force, require, optional, disable, or forbid,
244
or with the shorthand '+feature' and '\-feature', which equal 'force=feature'
245
and 'disable=feature' respectively
249
.IP "\fB\-\-cpu core2duo,+x2apic,disable=vmx\fR" 2
250
.IX Item "--cpu core2duo,+x2apic,disable=vmx"
251
Expose the core2duo \s-1CPU\s0 model, force enable x2apic, but do not expose vmx
252
.IP "\fB\-\-cpu host\fR" 2
253
.IX Item "--cpu host"
254
Expose the host CPUs configuration to the guest. This enables the guest to
255
take advantage of many of the host CPUs features (better performance), but
256
may cause issues if migrating the guest to a host without an identical \s-1CPU\s0.
232
260
.IP "\-\-description" 2
233
261
.IX Item "--description"
234
262
Human readable text description of the virtual machine. This will be stored
327
364
Valid values are:
376
Microsoft Windows Vista
379
Microsoft Windows \s-1XP\s0 (x86_64)
382
Microsoft Windows \s-1XP\s0
385
Microsoft Windows 2000
388
Microsoft Windows Server 2008
391
Microsoft Windows Server 2003
427
.IX Item "opensolaris"
459
.IP "debiansqueeze" 4
460
.IX Item "debiansqueeze"
464
.IX Item "debianlenny"
333
466
.IP "debianetch" 4
334
467
.IX Item "debianetch"
338
.IX Item "debianlenny"
340
.IP "debiansqueeze" 4
341
.IX Item "debiansqueeze"
344
497
.IX Item "fedora5"
378
Generic 2.6.25 or later kernel with virtio
501
Mandriva Enterprise Server 5.1 and later
504
Mandriva Enterprise Server 5.0
506
.IX Item "mandriva2010"
507
Mandriva Linux 2010 and later
379
508
.IP "mandriva2009" 4
380
509
.IX Item "mandriva2009"
381
510
Mandriva Linux 2009 and earlier
383
.IX Item "mandriva2010"
384
Mandriva Linux 2010 and later
387
Mandriva Enterprise Server 5.0
390
Mandriva Enterprise Server 5.1 and later
513
Red Hat Enterprise Linux 6
516
Red Hat Enterprise Linux 5.4 or later
519
Red Hat Enterprise Linux 5
522
Red Hat Enterprise Linux 4
525
Red Hat Enterprise Linux 3
392
527
.IX Item "rhel2.1"
393
528
Red Hat Enterprise Linux 2.1
396
Red Hat Enterprise Linux 3
399
Red Hat Enterprise Linux 4
402
Red Hat Enterprise Linux 5
405
Red Hat Enterprise Linux 5.4 or later
408
Red Hat Enterprise Linux 6
531
Suse Linux Enterprise Server 11
410
533
.IX Item "sles10"
411
534
Suse Linux Enterprise Server
414
Suse Linux Enterprise Server 11
535
.IP "ubuntumaverick" 4
536
.IX Item "ubuntumaverick"
537
Ubuntu 10.10 (Maverick Meerkat)
539
.IX Item "ubuntulucid"
540
Ubuntu 10.4 (Lucid Lynx)
542
.IX Item "ubuntukarmic"
543
Ubuntu 9.10 (Karmic Koala)
545
.IX Item "ubuntujaunty"
546
Ubuntu 9.04 (Jaunty Jackalope)
547
.IP "ubuntuintrepid" 4
548
.IX Item "ubuntuintrepid"
549
Ubuntu 8.10 (Intrepid Ibex)
415
550
.IP "ubuntuhardy" 4
416
551
.IX Item "ubuntuhardy"
417
552
Ubuntu 8.04 \s-1LTS\s0 (Hardy Heron)
418
.IP "ubuntuintrepid" 4
419
.IX Item "ubuntuintrepid"
420
Ubuntu 8.10 (Intrepid Ibex)
422
.IX Item "ubuntujaunty"
423
Ubuntu 9.04 (Jaunty Jackalope)
425
.IX Item "ubuntukarmic"
426
Ubuntu 9.10 (Karmic Koala)
458
.IX Item "opensolaris"
494
Microsoft Windows Vista
497
Microsoft Windows 2000
500
Microsoft Windows 2003
503
Microsoft Windows 2008
509
Microsoft Windows \s-1XP\s0 (x86)
512
Microsoft Windows \s-1XP\s0 (x86_64)
555
Generic 2.6.25 or later kernel with virtio
522
.Sh "Storage Configuration"
571
.IP "\-\-boot=BOOTOPTS" 2
572
.IX Item "--boot=BOOTOPTS"
573
Optionally specify the post-install \s-1VM\s0 boot configuration. This option allows
574
specifying a boot device order, permanently booting off kernel/initrd with
575
option kernel arguments, and enabling a \s-1BIOS\s0 boot menu (requires libvirt
578
\&\-\-boot can be specified in addition to other install options
579
(such as \-\-location, \-\-cdrom, etc.) or can be specified on it's own. In
580
the latter case, behavior is similar to the \-\-import install option: there
581
is no 'install' phase, the guest is just created and launched as specified.
585
.IP "\fB\-\-boot cdrom,fd,hd,network,menu=on\fR" 2
586
.IX Item "--boot cdrom,fd,hd,network,menu=on"
587
Set the boot device priority as first cdrom, first floppy, first harddisk,
588
network \s-1PXE\s0 boot. Additionally enable \s-1BIOS\s0 boot menu prompt.
589
.ie n .IP "\fB\-\-boot kernel=KERNEL,initrd=INITRD,kernel_args=""console=/dev/ttyS0""\fR" 2
590
.el .IP "\fB\-\-boot kernel=KERNEL,initrd=INITRD,kernel_args=``console=/dev/ttyS0''\fR" 2
591
.IX Item "--boot kernel=KERNEL,initrd=INITRD,kernel_args=console=/dev/ttyS0"
592
Have guest permanently boot off a local kernel/initrd pair, with the
593
specified kernel options.
597
.SS "Storage Configuration"
523
598
.IX Subsection "Storage Configuration"
524
599
.IP "\-\-disk=DISKOPTS" 2
525
600
.IX Item "--disk=DISKOPTS"
676
766
.IP "\-m \s-1MAC\s0, \-\-mac=MAC" 2
677
767
.IX Item "-m MAC, --mac=MAC"
678
768
This parameter is deprecated in favour of \f(CW\*(C`\-\-network NETWORK,mac=12:34...\*(C'\fR
679
.Sh "Graphics Configuration"
769
.SS "Graphics Configuration"
680
770
.IX Subsection "Graphics Configuration"
681
771
If no graphics option is specified, \f(CW\*(C`virt\-install\*(C'\fR will default to \-\-vnc
682
772
if the \s-1DISPLAY\s0 environment variable is set, otherwise \-\-nographics is used.
773
.IP "\-\-graphics \s-1TYPE\s0,opt1=arg1,opt2=arg2,..." 2
774
.IX Item "--graphics TYPE,opt1=arg1,opt2=arg2,..."
775
Specifies the graphical display configuration. This does not configure any
776
virtual hardware, just how the guest's graphical display can be accessed.
777
Typically the user does not need to specify this option, virt-install will
778
try and choose a useful default, and launch a suitable connection.
780
General format of a graphical string is
783
\& \-\-graphics TYPE,opt1=arg1,opt2=arg2,...
789
\& \-\-graphics vnc,password=foobar
792
The supported options are:
796
The display type. This is one of:
685
800
Setup a virtual console in the guest and export it as a \s-1VNC\s0 server in
686
the host. Unless the \f(CW\*(C`\-\-vncport\*(C'\fR parameter is also provided, the \s-1VNC\s0
801
the host. Unless the \f(CW\*(C`port\*(C'\fR parameter is also provided, the \s-1VNC\s0
687
802
server will run on the first free port number at 5900 or above. The
688
803
actual \s-1VNC\s0 display allocated can be obtained using the \f(CW\*(C`vncdisplay\*(C'\fR
689
804
command to \f(CW\*(C`virsh\*(C'\fR (or \fIvirt\-viewer\fR\|(1) can be used which handles this
690
805
detail for the use).
809
Setup a virtual console in the guest and display an \s-1SDL\s0 window in the
810
host to render the output. If the \s-1SDL\s0 window is closed the guest may
811
be unconditionally terminated.
815
Export the guest's console using the Spice protocol. Spice allows advanced
816
features like audio and \s-1USB\s0 device streaming, as well as improved graphical
821
No graphical console will be allocated for the guest. Fully virtualized guests
822
(Xen \s-1FV\s0 or QEmu/KVM) will need to have a text console configured on the first
823
serial port in the guest (this can be done via the \-\-extra\-args option). Xen
824
\&\s-1PV\s0 will set this up automatically. The command 'virsh console \s-1NAME\s0' can be
825
used to connect to the serial device.
828
Request a permanent, statically assigned port number for the guest
829
console. This is used by 'vnc' and 'spice'
830
.IP "\fBtlsport\fR" 4
832
Specify the spice tlsport.
835
Address to listen on for VNC/Spice connections. Default is typically 127.0.0.1
836
(localhost only), but some hypervisors allow changing this globally (for
837
example, the qemu driver default can be changed in /etc/libvirt/qemu.conf).
838
Use 0.0.0.0 to allow access from other machines. This is use by 'vnc' and
842
Request that the virtual \s-1VNC\s0 console be configured to run with a specific
843
keyboard layout. If the special value 'local' is specified, virt-install
844
will attempt to configure to use the same keymap as the local system. A value
845
of 'none' specifically defers to the hypervisor. Default behavior is
846
hypervisor specific, but typically is the same as 'local'. This is used
848
.IP "\fBpassword\fR" 4
850
Request a \s-1VNC\s0 password, required at connection time. Beware, this info may
851
end up in virt-install log files, so don't use an important password. This
852
is used by 'vnc' and 'spice'
853
.IP "\fBpasswordvalidto\fR" 4
854
.IX Item "passwordvalidto"
855
Set an expiration date for password. After the date/time has passed,
856
all new graphical connections are denyed until a new password is set.
857
This is used by 'vnc' and 'spice'
859
The format for this value is \s-1YYYY\-MM\-DDTHH:MM:SS\s0, for example
860
2011\-04\-01T14:30:15
866
This option is deprecated in favor of \f(CW\*(C`\-\-graphics vnc,...\*(C'\fR
691
867
.IP "\-\-vncport=VNCPORT" 2
692
868
.IX Item "--vncport=VNCPORT"
693
Request a permanent, statically assigned port number for the guest \s-1VNC\s0
694
console. Use of this option is discouraged as other guests may automatically
695
choose to run on this port causing a clash.
869
This option is deprecated in favor of \f(CW\*(C`\-\-graphics vnc,port=PORT,...\*(C'\fR
696
870
.IP "\-\-vnclisten=VNCLISTEN" 2
697
871
.IX Item "--vnclisten=VNCLISTEN"
698
Address to listen on for \s-1VNC\s0 connections. Default is typically 127.0.0.1
699
(localhost only), but some hypervisors allow changing this globally (for
700
example, the qemu driver default can be changed in /etc/libvirt/qemu.conf).
701
Use 0.0.0.0 to allow access from other machines.
872
This option is deprecated in favor of \f(CW\*(C`\-\-graphics vnc,listen=LISTEN,...\*(C'\fR
702
873
.IP "\-k \s-1KEYMAP\s0, \-\-keymap=KEYMAP" 2
703
874
.IX Item "-k KEYMAP, --keymap=KEYMAP"
704
Request that the virtual \s-1VNC\s0 console be configured to run with a specific
705
keyboard layout. If the special value 'local' is specified, virt-install
706
will attempt to configure to use the same keymap as the local system. A value
707
of 'none' specifically defers to the hypervisor. Default behavior is
708
hypervisor specific, but typically is the same as 'local'.
875
This option is deprecated in favor of \f(CW\*(C`\-\-graphics vnc,keymap=KEYMAP,...\*(C'\fR
711
Setup a virtual console in the guest and display an \s-1SDL\s0 window in the
712
host to render the output. If the \s-1SDL\s0 window is closed the guest may
713
be unconditionally terminated.
878
This option is deprecated in favor of \f(CW\*(C`\-\-graphics sdl,...\*(C'\fR
714
879
.IP "\-\-nographics" 2
715
880
.IX Item "--nographics"
716
No graphical console will be allocated for the guest. Fully virtualized guests
717
(Xen \s-1FV\s0 or QEmu/KVM) will need to have a text console configured on the first
718
serial port in the guest (this can be done via the \-\-extra\-args option). Xen
719
\&\s-1PV\s0 will set this up automatically. The command 'virsh console \s-1NAME\s0' can be
720
used to connect to the serial device.
881
This option is deprecated in favor of \f(CW\*(C`\-\-graphics none\*(C'\fR
721
882
.IP "\-\-noautoconsole" 2
722
883
.IX Item "--noautoconsole"
723
884
Don't automatically try to connect to the guest console. The default behaviour
724
885
is to launch a \s-1VNC\s0 client to display the graphical console, or to run the
725
886
\&\f(CW\*(C`virsh\*(C'\fR \f(CW\*(C`console\*(C'\fR command to display the text console. Use of this parameter
726
887
will disable this behaviour.
727
.Sh "Virtualization Type options"
888
.SS "Virtualization Type options"
728
889
.IX Subsection "Virtualization Type options"
729
890
Options to override the default virtualization type choices.
730
891
.IP "\-v, \-\-hvm" 2
1059
.IX Item "--channel"
1060
Specifies a communication channel device to connect the guest and host
1061
machine. This option uses the same options as \-\-serial and \-\-parallel
1062
for specifying the host/source end of the channel. Extra 'target' options
1063
are used to specify how the guest machine sees the channel.
1065
Some of the types of character device redirection are:
1067
.IP "\fB\-\-channel \s-1SOURCE\s0,target_type=guestfwd,target_address=HOST:PORT\fR" 4
1068
.IX Item "--channel SOURCE,target_type=guestfwd,target_address=HOST:PORT"
1069
Communication channel using \s-1QEMU\s0 usermode networking stack. The guest can
1070
connect to the channel using the specified \s-1HOST:PORT\s0 combination.
1071
.IP "\fB\-\-channel \s-1SOURCE\s0,target_type=virtio[,name=NAME]\fR" 4
1072
.IX Item "--channel SOURCE,target_type=virtio[,name=NAME]"
1073
Communication channel using virtio serial (requires 2.6.34 or later host and
1074
guest). Each instance of a virtio \-\-channel line is exposed in the
1075
guest as /dev/vport0p1, /dev/vport0p2, etc. \s-1NAME\s0 is optional metadata, and
1076
can be any string, such as org.linux\-kvm.virtioport1.
1077
If specified, this will be exposed in the guest at
1078
/sys/class/virtio\-ports/vport0p1/NAME
1083
.IX Item "--console"
1084
Connect a text console between the guest and host. Certain guest and
1085
hypervisor combinations can automatically set up a getty in the guest, so
1086
an out of the box text login can be provided (target_type=xen for xen
1087
paravirt guests, and possibly target_type=virtio in the future).
1091
.IP "\fB\-\-console pty,target_type=virtio\fR" 4
1092
.IX Item "--console pty,target_type=virtio"
1093
Connect a virtio console to the guest, redirected to a \s-1PTY\s0 on the host.
1094
For supported guests, this exposes /dev/hvc0 in the guest. See
1095
http://fedoraproject.org/wiki/Features/VirtioSerial for more info. virtio
1096
console requires libvirt 0.8.3 or later.
897
1100
.IP "\-\-video=VIDEO" 2
898
1101
.IX Item "--video=VIDEO"
899
1102
Specify what video device model will be attached to the guest. Valid values
900
1103
for \s-1VIDEO\s0 are hypervisor specific, but some options for recent kvm are
901
1104
cirrus, vga, or vmvga (vmware).
902
.Sh "Miscellaneous Options"
1105
.SS "Miscellaneous Options"
903
1106
.IX Subsection "Miscellaneous Options"
904
1107
.IP "\-\-autostart" 2
905
1108
.IX Item "--autostart"
906
1109
Set the autostart flag for a domain. This causes the domain to be started
907
1110
on host boot up.
1111
.IP "\-\-print\-xml" 2
1112
.IX Item "--print-xml"
1113
If the requested guest has no install phase (\-\-import, \-\-boot), print the
1114
generated \s-1XML\s0 instead of defining the guest. By default this \s-1WILL\s0 do storage
1115
creation (can be disabled with \-\-dry\-run).
1117
If the guest has an install phase, you will need to use \-\-print\-step to
1118
specify exactly what \s-1XML\s0 output you want. This option implies \-\-quiet.
1119
.IP "\-\-print\-step" 2
1120
.IX Item "--print-step"
1121
Acts similarly to \-\-print\-xml, except requires specifying which install step
1122
to print \s-1XML\s0 for. Possible values are 1, 2, 3, or all. Stage 1 is typically
1123
booting from the install media, and stage 2 is typically the final guest
1124
config booting off hardisk. Stage 3 is only relevant for windows installs,
1125
which by default have a second install stage. This option implies \-\-quiet.
908
1126
.IP "\-\-noreboot" 2
909
1127
.IX Item "--noreboot"
910
1128
Prevent the domain from automatically rebooting after the install has
added
removed
man/en/virt-install.1
