1VIRT-INSTALL(1) Virtualization Support 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. See
14 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 local ISO or CDROM media, or a distro
23 install tree hosted remotely over HTTP, FTP, or in a local directory.
24 In the install tree case virt-install will fetch the minimal files nec‐
25 essary to kick off the installation process, allowing the guest to
26 fetch the rest of the OS distribution as needed. PXE booting, and
27 importing an existing disk image (thus skipping the install phase) are
28 also supported.
29 Given suitable command line arguments, virt-install is capable of run‐
31 ning completely unattended, with the guest 'kickstarting' itself too.
32 This allows for easy automation of guest installs. This can be done
33 manually, or more simply with the --unattended option.
34 Many arguments have sub options, specified like opt1=foo,opt2=bar, etc.
36 Try --option=? to see a complete list of sub options associated with
37 that argument, example: virt-install --disk=?
38 Most options are not required. If a suitable --os-variant value is
40 specified or detected, all defaults will be filled in and reported in
41 the terminal output. If an --os-variant is not specified. minimum
42 required options, --memory, guest storage (--disk or --filesystem), and
43 an install method choice.
44
46 --connect
47 Syntax: --connect URI
48 Connect to a non-default hypervisor. If this isn't specified, libvirt
50 will try and choose the most suitable default.
51 Some valid options here are:
53 qemu:///system
55 For creating KVM and QEMU guests to be run by the system lib‐
56 virtd instance. This is the default mode that virt-manager
57 uses, and what most KVM users want.
58 qemu:///session
60 For creating KVM and QEMU guests for libvirtd running as the
61 regular user.
62 xen:///
64 For connecting to Xen.
65 lxc:///
67 For creating linux containers
68
70 General configuration parameters that apply to all types of guest
71 installs.
72 -n, --name
74 Syntax: -n, --name NAME
75 Name of the new guest virtual machine instance. This must be unique
77 amongst all guests known to the hypervisor on the connection, including
78 those not currently active. To re-define an existing guest, use the
79 virsh(1) tool to shut it down ('virsh shutdown') & delete ('virsh unde‐
80 fine') it prior to running virt-install.
81 --memory
83 Syntax: --memory OPTIONS
84 Memory to allocate for the guest, in MiB. This deprecates the -r/--ram
86 option. Sub options are available, like 'memory', 'currentMemory',
87 'maxMemory' and 'maxMemory.slots', which all map to the identically
88 named XML values.
89 Back compat values 'memory' maps to the <currentMemory> element, and
91 maxmemory maps to the <memory> element.
92 To configure memory modules which can be hotunplugged see --memdev
94 description.
95 Use --memory=? to see a list of all available sub options. Complete
97 details at
98 https://libvirt.org/formatdomain.html#elementsMemoryAllocation
99 --memorybacking
101 Syntax: --memorybacking OPTIONS
102 This option will influence how virtual memory pages are backed by host
104 pages.
105 Use --memorybacking=? to see a list of all available sub options. Com‐
107 plete details at
108 https://libvirt.org/formatdomain.html#elementsMemoryBacking
109 --arch
111 Syntax: --arch ARCH
112 Request a non-native CPU architecture for the guest virtual machine.
114 If omitted, the host CPU architecture will be used in the guest.
115 --machine
117 Syntax: --machine MACHINE
118 The machine type to emulate. This will typically not need to be speci‐
120 fied for Xen or KVM, but is useful for choosing machine types of more
121 exotic architectures.
122 --metadata
124 Syntax: --metadata OPT=VAL,[...]
125 Specify metadata values for the guest. Possible options include name,
127 uuid, title, and description. This option deprecates -u/--uuid and
128 --description.
129 Use --metadata=? to see a list of all available sub options. Complete
131 details at https://libvirt.org/formatdomain.html#elementsMetadata
132 --events
134 Syntax: --events OPT=VAL,[...]
135 Specify events values for the guest. Possible options include
137 on_poweroff, on_reboot, and on_crash.
138 Use --events=? to see a list of all available sub options. Complete
140 details at https://libvirt.org/formatdomain.html#elementsEvents
141 --resource
143 Syntax: --resource OPT=VAL,[...]
144 Specify resource partitioning for the guest.
146 Use --resource=? to see a list of all available sub options. Complete
148 details at https://libvirt.org/formatdomain.html#resPartition
149 --sysinfo
151 Syntax: --sysinfo OPT=VAL,[...]
152 Configure sysinfo/SMBIOS values exposed to the VM OS. Examples:
154 --sysinfo host
156 Special type that exposes the host's SMBIOS info into the VM.
157 --sysinfo emulate
159 Special type where hypervisor will generate SMBIOS info into the
160 VM.
161 --sysinfo bios.vendor=custom or --sysinfo smbios,bios.vendor=custom
163 The default type is smbios and allows users to specify SMBIOS
164 info manually.
165 Use --sysinfo=? to see a list of all available sub options.
167 Complete details at
169 https://libvirt.org/formatdomain.html#elementsSysinfo and
170 https://libvirt.org/formatdomain.html#elementsOSBIOS for smbios XML
171 element.
172 --xml
174 Syntax: --xml ARGS
175 Make direct edits to the generated XML using XPath syntax. Take an
177 example like
178 virt-install --xml ./@foo=bar --xml ./newelement/subelement=1
180 This will alter the generated XML to contain:
182 <domain foo='bar' ...>
184 ...
185 <newelement>
186 <subelement>1</subelement>
187 </newelement>
188 </domain>
189 The --xml option has 4 sub options:
191 --xml xpath.set=XPATH[=VALUE]
193 The default behavior if no explicit suboption is set. Takes the
194 form XPATH=VALUE unless paired with xpath.value . See below for
195 how value is interpreted.
196 --xml xpath.value=VALUE
198 xpath.set will be interpreted only as the XPath string, and
199 xpath.value will be used as the value to set. May help sidestep
200 problems if the string you need to set contains a '=' equals
201 sign.
202 If value is empty, it's treated as unsetting that particular
204 node.
205 --xml xpath.create=XPATH
207 Create the node as an empty element. Needed for boolean elements
208 like <readonly/>
209 --xml xpath.delete=XPATH
211 Delete the entire node specified by the xpath, and all its chil‐
212 dren
213 --qemu-commandline
215 Syntax: --qemu-commandline ARGS
216 Pass options directly to the qemu emulator. Only works for the libvirt
218 qemu driver. The option can take a string of arguments, for example:
219 --qemu-commandline="-display gtk,gl=on"
221 Environment variables are specified with 'env', for example:
223 --qemu-commandline=env=DISPLAY=:0.1
225 Complete details about the libvirt feature:
227 https://libvirt.org/drvqemu.html#qemucommand
228 --vcpus
230 Syntax: --vcpus OPTIONS
231 Number of virtual cpus to configure for the guest. If 'maxvcpus' is
233 specified, the guest will be able to hotplug up to MAX vcpus while the
234 guest is running, but will startup with VCPUS.
235 CPU topology can additionally be specified with sockets, cores, and
237 threads. If values are omitted, the rest will be autofilled preferring
238 sockets over cores over threads.
239 'cpuset' sets which physical cpus the guest can use. CPUSET is a comma
241 separated list of numbers, which can also be specified in ranges or
242 cpus to exclude. Example:
243 0,2,3,5 : Use processors 0,2,3 and 5
245 1-5,^3,8 : Use processors 1,2,4,5 and 8
246 If the value 'auto' is passed, virt-install attempts to automatically
248 determine an optimal cpu pinning using NUMA data, if available.
249 Use --vcpus=? to see a list of all available sub options. Complete
251 details at https://libvirt.org/formatdomain.html#elementsCPUAllocation
252 --numatune
254 Syntax: --numatune OPTIONS
255 Tune NUMA policy for the domain process. Example invocations
257 --numatune 1,2,3,4-7
259 --numatune 1-3,5,memory.mode=preferred
260 Specifies the numa nodes to allocate memory from. This has the same
262 syntax as --vcpus cpuset= option. mode can be one of 'interleave',
263 'preferred', or 'strict' (the default). See 'man 8 numactl' for infor‐
264 mation about each mode.
265 Use --numatune=? to see a list of all available sub options. Complete
267 details at https://libvirt.org/formatdomain.html#elementsNUMATuning
268 --memtune
270 Syntax: --memtune OPTIONS
271 Tune memory policy for the domain process. Example invocations
273 --memtune 1000
275 --memtune hard_limit=100,soft_limit=60,swap_hard_limit=150,min_guarantee=80
276 Use --memtune=? to see a list of all available sub options. Complete
278 details at https://libvirt.org/formatdomain.html#elementsMemoryTuning
279 --blkiotune
281 Syntax: --blkiotune OPTIONS
282 Tune blkio policy for the domain process. Example invocations
284 --blkiotune 100
286 --blkiotune weight=100,device.path=/dev/sdc,device.weight=200
287 Use --blkiotune=? to see a list of all available sub options. Complete
289 details at https://libvirt.org/formatdomain.html#elementsBlockTuning
290 --cpu
292 Syntax: --cpu MODEL[,+feature][,-feature][,match=MATCH][,vendor=VEN‐
293 DOR],...
294 Configure the CPU model and CPU features exposed to the guest. The only
296 required value is MODEL, which is a valid CPU model as known to lib‐
297 virt.
298 Libvirt's feature policy values force, require, optional, disable, or
300 forbid, or with the shorthand '+feature' and '-feature', which equal
301 'force=feature' and 'disable=feature' respectively.
302 If exact CPU model is specified virt-install will automatically copy
304 CPU features available on the host to mitigate recent CPU speculative
305 execution side channel and Microarchitectural Store Buffer Data secu‐
306 rity vulnerabilities. This however will have some impact on perfor‐
307 mance and will break migration to hosts without security patches. In
308 order to control this behavior there is a secure parameter. Possible
309 values are on and off, with on as the default. It is highly recommended
310 to leave this enabled and ensure all virtualization hosts have fully up
311 to date microcode, kernel & virtualization software installed.
312 Some examples:
314 --cpu core2duo,+x2apic,disable=vmx
316 Expose the core2duo CPU model, force enable x2apic, but do not
317 expose vmx
318 --cpu host
320 Expose the host CPUs configuration to the guest. This enables
321 the guest to take advantage of many of the host CPUs features
322 (better performance), but may cause issues if migrating the
323 guest to a host without an identical CPU.
324 --cpu numa.cell0.memory=1234,numa.cell0.cpus=0-3,numa.cell1.mem‐
326 ory=5678,numa.cell1.cpus=4-7
327 Example of specifying two NUMA cells. This will generate XML
328 like:
329 <cpu>
331 <numa>
332 <cell cpus="0-3" memory="1234"/>
333 <cell cpus="4-7" memory="5678"/>
334 </numa>
335 </cpu>
336 --cpu host-passthrough,cache.mode=passthrough
338 Example of passing through the host cpu's cache information.
339 Use --cpu=? to see a list of all available sub options. Complete
341 details at https://libvirt.org/formatdomain.html#elementsCPU
342 --cputune
344 Syntax: --cputune OPTIONS
345 Tune CPU parameters for the guest.
347 Configure which of the host's physical CPUs the domain VCPU will be
349 pinned to. Example invocation
350 --cputune vcpupin0.vcpu=0,vcpupin0.cpuset=0-3,vcpupin1.vcpu=1,vcpupin1.cpuset=4-7
352 Use --cputune=? to see a list of all available sub options. Complete
354 details at https://libvirt.org/formatdomain.html#elementsCPUTuning
355 --security, --seclabel
357 Syntax: --security, --seclabel type=TYPE[,label=LABEL][,rela‐
358 bel=yes|no],...
359 Configure domain seclabel domain settings. Type can be either 'static'
361 or 'dynamic'. 'static' configuration requires a security LABEL. Speci‐
362 fying LABEL without TYPE implies static configuration.
363 Use --security=? to see a list of all available sub options. Complete
365 details at https://libvirt.org/formatdomain.html#seclabel
366 --keywrap
368 Syntax: --keywrap OPTIONS
369 Specify domain <keywrap> XML, used for S390 cryptographic key manage‐
371 ment operations.
372 Use --keywrap=? to see a list of all available sub options. Complete
374 details at https://libvirt.org/formatdomain.html#keywrap
375 --iothreads
377 Syntax: --iothreads OPTIONS
378 Specify domain <iothreads> and/or <iothreadids> XML. For example, to
380 configure <iothreads>4</iothreads>, use --iothreads 4
381 Use --iothreads=? to see a list of all available sub options. Complete
383 details at
384 https://libvirt.org/formatdomain.html#elementsIOThreadsAllocation
385 --features
387 Syntax: --features FEAT=on|off,...
388 Set elements in the guests <features> XML on or off. Examples include
390 acpi, apic, eoi, privnet, and hyperv features. Some examples:
391 --features apic.eoi=on
393 Enable APIC PV EOI
394 --features hyperv.vapic.state=on,hyperv.spinlocks.state=off
396 Enable hypver VAPIC, but disable spinlocks
397 --features kvm.hidden.state=on
399 Allow the KVM hypervisor signature to be hidden from the guest
400 --features pvspinlock=on
402 Notify the guest that the host supports paravirtual spinlocks
403 for example by exposing the pvticketlocks mechanism.
404 --features gic.version=2
406 This is relevant only for ARM architectures. Possible values are
407 "host" or version number.
408 --features smm.state=on
410 This enables System Management Mode of hypervisor. Some UEFI
411 firmwares may require this feature to be present. (QEMU supports
412 SMM only with q35 machine type.)
413 Use --features=? to see a list of all available sub options. Complete
415 details at https://libvirt.org/formatdomain.html#elementsFeatures
416 --clock
418 Syntax: --clock offset=OFFSET,TIMER_OPT=VAL,...
419 Configure the guest's <clock> XML. Some supported options:
421 --clock offset=OFFSET
423 Set the clock offset, ex. 'utc' or 'localtime'
424 --clock TIMER_present=no
426 Disable a boolean timer. TIMER here might be hpet, kvmclock,
427 etc.
428 --clock TIMER_tickpolicy=VAL
430 Set a timer's tickpolicy value. TIMER here might be rtc, pit,
431 etc. VAL might be catchup, delay, etc. Refer to the libvirt docs
432 for all values.
433 Use --clock=? to see a list of all available sub options. Complete
435 details at https://libvirt.org/formatdomain.html#elementsTime
436 --pm
438 Syntax: --pm OPTIONS
439 Configure guest power management features. Example:
441 --pm suspend_to_memi.enabled=on,suspend_to_disk.enabled=off
443 Use --pm=? to see a list of all available sub options. Complete
445 details at
446 https://libvirt.org/formatdomain.html#elementsPowerManagement
447 --launchSecurity
449 Syntax: --launchSecurity TYPE[,OPTS]
450 Enable launch security for the guest, e.g. AMD SEV. Example invoca‐
452 tions:
453 # This will use a default policy 0x03
455 # No dhCert provided, so no data can be exchanged with the SEV firmware
456 --launchSecurity sev
457 # Explicit policy 0x01 - disables debugging, allows guest key sharing
459 --launchSecurity sev,policy=0x01
460 # Provide the session blob obtained from the SEV firmware
462 # Provide dhCert to open a secure communication channel with SEV firmware
463 --launchSecurity sev,session=BASE64SESSIONSTRING,dhCert=BASE64DHCERTSTRING
464 SEV has further implications on usage of virtio devices, so refer to
466 EXAMPLES section to see a full invocation of virt-install with
467 --launchSecurity.
468 Use --launchSecurity=? to see a list of all available sub options. Com‐
470 plete details at https://libvirt.org/formatdomain.html#launchSecurity
471
473 -c, --cdrom
474 Syntax: --cdrom PATH
475 ISO file or CDROM device to use for VM install media. After install,
477 the the virtual CDROM device will remain attached to the VM, but with
478 the ISO or host path media ejected.
479 -l, --location
481 Syntax: -l, --location OPTIONS
482 Distribution tree installation source. virt-install can recognize cer‐
484 tain distribution trees and fetches a bootable kernel/initrd pair to
485 launch the install.
486 --location allows things like --extra-args for kernel arguments, and
488 using --initrd-inject. If you want to use those options with CDROM
489 media, you can pass the ISO to --location as well which works for some,
490 but not all, CDROM media.
491 The LOCATION can take one of the following forms:
493 https://host/path
495 An HTTP server location containing an installable distribution
496 image.
497 ftp://host/path
499 An FTP server location containing an installable distribution
500 image.
501 ISO Probe the ISO and extract files using 'isoinfo'
503 DIRECTORY
505 Path to a local directory containing an installable distribution
506 image. Note that the directory will not be accessible by the
507 guest after initial boot, so the OS installer will need another
508 way to access the rest of the install media.
509 Some distro specific url samples:
511 Fedora/Red Hat Based
513 https://download.fedoraproject.org/pub/fedora/linux/releases/29/Server/x86_64/os
514 Debian https://ftp.us.debian.org/debian/dists/stable/main/installer-amd64/
516 Ubuntu https://us.archive.ubuntu.com/ubuntu/dists/wily/main/installer-amd64/
518 Suse https://download.opensuse.org/pub/opensuse/distribution/leap/42.3/repo/oss/
520 Additionally, --location can take 'kernel' and 'initrd' sub options.
522 These paths relative to the specified location URL/ISO that allow
523 selecting specific files for kernel/initrd within the install tree.
524 This can be useful if virt-install/ libosinfo doesn't know where to
525 find the kernel in the specified --location.
526 For example, if you have an ISO that libosinfo doesn't know about
528 called my-unknown.iso, with a kernel at 'kernel/fookernel' and initrd
529 at 'kernel/fooinitrd', you can make this work with:
530 --location my-unknown.iso,kernel=kernel/fookernel,initrd=kernel/fooinitrd
532 --pxe
534 Install from PXE. This just tells the VM to boot off the network for
535 the first boot.
536 --import
538 Skip the OS installation process, and build a guest around an existing
539 disk image. The device used for booting is the first device specified
540 via --disk or --filesystem.
541 -x, --extra-args
543 Syntax: -x, --extra-args KERNELARGS
544 Additional kernel command line arguments to pass to the installer when
546 performing a guest install from --location. One common usage is speci‐
547 fying an anaconda kickstart file for automated installs, such as
548 --extra-args "ks=https://myserver/my.ks"
549 --initrd-inject
551 Syntax: --initrd-inject PATH
552 Add PATH to the root of the initrd fetched with --location. This can be
554 used to run an automated install without requiring a network hosted
555 kickstart file: --initrd-inject=/path/to/my.ks --extra-args
556 "ks=file:/my.ks"
557 --install
559 This is a larger entry point for various types of install operations.
560 The command has multiple subarguments, similar to --disk and friends.
561 This option is strictly for VM install operations, essentially config‐
562 uring the first boot.
563 The simplest usage to ex: install fedora29 is:
565 --install fedora29
567 And virt-install will fetch a --location URL from libosinfo, and popu‐
569 late defaults from there.
570 Available suboptions:
572 os= This is os install option described above. The explicit way to
574 specify that would be --install os=fedora29 . os= is the default
575 option if none is specified
576 kernel=, initrd=
578 Specify a kernel and initrd pair to use as install media. They
579 are copied into a temporary location before booting the VM, so
580 they can be combined with --initrd-inject and your source media
581 will not be altered. Media will be uploaded to a remote connec‐
582 tion if required.
583 Example case using local filesystem paths: --install ker‐
585 nel=/path/to/kernel,initrd=/path/to/initrd
586 Example using network paths. Kernel/initrd will be downloaded
588 locally first, then passed to the VM as local filesystem paths:
589 --install kernel=https://127.0.0.1/tree/kernel,ini‐
590 trd=https://127.0.0.1/tree/initrd
591 Note, these are just for install time booting. If you want to
593 set the kernel used for permanent VM booting, use the --boot
594 option.
595 kernel_args=, kernel_args_overwrite=yes|no
597 Specify install time kernel arguments (libvirt <cmdline> XML).
598 These can be combine with ex: kernel/initrd options, or --loca‐
599 tion media. By default, kernel_args is just like --extra-args,
600 and will _append_ to the arguments that virt-install will try to
601 set by default for most --location installs. If you want to
602 override the virt-install default, additionally specify ker‐
603 nel_args_overwrite=yes
604 bootdev=
606 Specify the install bootdev (hd, cdrom, floppy, network) to boot
607 off of for the install phase. This maps to libvirt <os><boot
608 dev=X> XML.
609 If you want to install off a cdrom or network, it's probably
611 simpler and more backwards compatible to just use --cdrom or
612 --pxe , but this options gives fine grained control over the
613 install process if needed.
614 no_install=yes|no
616 Tell virt-install that there isn't actually any install happen‐
617 ing, and you just want to create the VM. --import is just an
618 alias for this, as is specifying --boot without any other
619 install options. The deprecated --live option is the same as
620 '--cdrom $ISO --install no_install=yes'
621 --reinstall DOMAIN
623 Reinstall an existing VM. DOMAIN can be a VM name, UUID, or ID number.
624 virt-install will fetch the domain XML from libvirt, apply the speci‐
625 fied install config changes, boot the VM for the install process, and
626 then revert to roughly the same starting XML.
627 Only install related options are processed, all other VM configuration
629 options like --name, --disk, etc. are completely ignored.
630 If --reinstall is used with --cdrom, an existing CDROM attached to the
632 VM will be used if one is available, otherwise a permanent CDROM device
633 will be added.
634 --unattended
636 Syntax: --unattended [OPTIONS]
637 Perform an unattended install using libosinfo's install script support.
639 This is essentially a database of auto install scripts for various dis‐
640 tros: Red Hat kickstarts, Debian installer scripting, Windows unat‐
641 tended installs, and potentially others. The simplest invocation is to
642 combine it with --install like:
643 --install fedora29 --unattended
645 A Windows install will look like
647 --cdrom /path/to/my/windows.iso --unattended
649 Sub options are:
651 profile=
653 Choose which libosinfo unattended profile to use. Most distros
654 have a 'desktop' and a 'jeos' profile. virt-install will default
655 to 'desktop' if this is unspecified.
656 admin-password-file=
658 A file used to set the VM OS admin/root password from. This
659 option can be used either as "admin-password-file=/path/to/pass‐
660 word-file" or as "admin-password-file=/dev/fd/n", being n the
661 file descriptor of the password-file. Note that only the first
662 line of the file will be considered, including any whitespace
663 characters and excluding new-line.
664 user-login=
666 The user login name to be used in th VM. virt-install will
667 default to your current host username if this is unspecified.
668 Note that when running virt-install as "root", this option must
669 be specified.
670 user-password-file=
672 A file used to set the VM user password. This option can be used
673 either as "user-password-file=/path/to/password-file" or as
674 "user-password-file=/dev/fd/n", being n the file descriptor of
675 the password-file. The username is either the user-login speci‐
676 fied or your current host username. Note that only the first
677 line of the file will be considered, including any whitespace
678 characters and excluding new-line.
679 product-key=
681 Set a Windows product key
682 --cloud-init
684 Pass cloud-init metadata to the VM. A cloud-init NoCloud ISO file is
685 generated, and attached to the VM as a CDROM device. The device is only
686 attached for the first boot. This option is particularly useful for
687 distro cloud images, which have locked login accounts by default;
688 --cloud-init provides the means to initialize those login accounts,
689 like setting a root password.
690 The simplest invocation is just plain --cloud-init with no suboptions;
692 this maps to --cloud-init root-password-generate=on,disable=on. See
693 those suboptions for explanation of how they work.
694 Use --cloud-init=? to see a list of all available sub options.
696 Sub options are:
698 root-password-generate=on
700 Generate a new root password for the VM. When used, virt-install
701 will print the generated password to the console, and pause for
702 10 seconds to give the user a chance to notice it and copy it.
703 disable=on
705 Disable cloud-init in the VM for subsequent boots. Without this,
706 cloud-init may reset auth on each boot.
707 root-password-file=
709 A file used to set the VM root password from. This option can be
710 used either as "root-password-file=/path/to/password-file" or as
711 "root-password-file=/dev/fd/n", being n the file descriptor of
712 the password-file. Note that only the first line of the file
713 will be considered, including any whitespace characters and
714 excluding new-line.
715 meta-data=
717 Specify a cloud-init meta-data file to add directly to the iso.
718 All other meta-data configuration options on the --cloud-init
719 command line are ignored.
720 user-data=
722 Specify a cloud-init user-data file to add directly to the iso.
723 All other user-data configuration options on the --cloud-init
724 command line are ignored.
725 ssh-key=
727 Specify a public key to inject into the guest, providing ssh
728 access to the unprivileged account. Example:
729 ssh-key=/home/user/.ssh/id_rsa.pub
730 --boot
732 Syntax: --boot BOOTOPTS
733 Optionally specify the post-install VM boot configuration. This option
735 allows specifying a boot device order, permanently booting off ker‐
736 nel/initrd with option kernel arguments, and enabling a BIOS boot menu
737 (requires libvirt 0.8.3 or later)
738 --boot can be specified in addition to other install options (such as
740 --location, --cdrom, etc.) or can be specified on its own. In the lat‐
741 ter case, behavior is similar to the --import install option: there is
742 no 'install' phase, the guest is just created and launched as speci‐
743 fied.
744 Some examples:
746 --boot cdrom,fd,hd,network
748 Set the boot device priority as first cdrom, first floppy, first
749 harddisk, network PXE boot.
750 --boot kernel=KERNEL,initrd=INITRD,kernel_args="console=/dev/ttyS0"
752 Have guest permanently boot off a local kernel/initrd pair, with
753 the specified kernel options.
754 --boot kernel=KERNEL,initrd=INITRD,dtb=DTB
756 Have guest permanently boot off a local kernel/initrd pair with
757 an external device tree binary. DTB can be required for some
758 non-x86 configurations like ARM or PPC
759 --boot loader=BIOSPATH
761 Use BIOSPATH as the virtual machine BIOS.
762 --boot bootmenu.enable=on,bios.useserial=on
764 Enable the bios boot menu, and enable sending bios text output
765 over serial console.
766 --boot init=INITPATH
768 Path to a binary that the container guest will init. If a root
769 --filesystem has been specified, virt-install will default to
770 /sbin/init, otherwise will default to /bin/sh.
771 --boot uefi
773 Configure the VM to boot from UEFI. In order for virt-install to
774 know the correct UEFI parameters, libvirt needs to be advertis‐
775 ing known UEFI binaries via domcapabilities XML, so this will
776 likely only work if using properly configured distro packages.
777 --boot loader=/.../OVMF_CODE.fd,loader.read‐
779 only=yes,loader.type=pflash,nvram.tem‐
780 plate=/.../OVMF_VARS.fd,loader_secure=no
781 Specify that the virtual machine use the custom OVMF binary as
782 boot firmware, mapped as a virtual flash chip. In addition,
783 request that libvirt instantiate the VM-specific UEFI varstore
784 from the custom "/.../OVMF_VARS.fd" varstore template. This is
785 the recommended UEFI setup, and should be used if --boot uefi
786 doesn't know about your UEFI binaries. If your UEFI firmware
787 supports Secure boot feature you can enable it via
788 loader_secure.
789 Use --boot=? to see a list of all available sub options. Complete
791 details at https://libvirt.org/formatdomain.html#elementsOS
792 --idmap
794 Syntax: --idmap OPTIONS
795 If the guest configuration declares a UID or GID mapping, the 'user'
797 namespace will be enabled to apply these. A suitably configured
798 UID/GID mapping is a pre-requisite to make containers secure, in the
799 absence of sVirt confinement.
800 --idmap can be specified to enable user namespace for LXC containers.
802 Example:
803 --idmap uid.start=0,uid.target=1000,uid.count=10,gid.start=0,gid.target=1000,gid.count=10
805 Use --idmap=? to see a list of all available sub options. Complete
807 details at https://libvirt.org/formatdomain.html#elementsOSContainer
808
810 --os-variant, --osinfo
811 Syntax: --os-variant [OS_VARIANT|OPT1=VAL1,...]
812 Optimize the guest configuration for a specific operating system (ex.
814 'fedora29', 'rhel7', 'win10'). While not required, specifying this
815 options is HIGHLY RECOMMENDED, as it can greatly increase performance
816 by specifying virtio among other guest tweaks.
817 The simplest usage is --os-variant OS-NAME, for example --os-variant
819 fedora32. --os-variant supports explicit suboption syntax as well:
820 name=, short-id=
822 The OS name/short-id from libosinfo. Examples: fedora32, win10
823 id= The full URL style libosinfo ID. For example, name=win10 is the
825 same as id=http://microsoft.com/win/10
826 detect=on|off
828 Whether virt-install should attempt OS detection from the speci‐
829 fied install media. Detection is presently only attempted for
830 URL and CDROM installs, and is not 100% reliable.
831 require=on|off
833 If on, virt-install errors if no OS value is set or detected.
834 Some interesting examples:
836 --os-variant detect=on,require=on
838 This tells virt-install to attempt detection from install media,
839 but explicitly fail if that does not succeed. This will ensure
840 your virt-install invocations don't fallback to a poorly per‐
841 forming config
842 --os-variant detect=on,name=OSNAME
844 Attempt OS detection from install media, but if that fails, use
845 OSNAME as a fallback.
846 By default, virt-install will do --os-variant detect=on,name=generic,
848 using the detected OS if found, and falling back to the stub generic
849 value otherwise, and printing a warning.
850 If any manual --os-variant value is specified, the default is all set‐
852 tings off or unset.
853 Use the command "osinfo-query os" to get the list of the accepted OS
855 variant names.
856
858 --disk
859 Syntax: --disk OPTIONS
860 Specifies media to use as storage for the guest, with various options.
862 The general format of a disk string is
863 --disk opt1=val1,opt2=val2,...
865 The simplest invocation to create a new 10G disk image and associated
867 disk device:
868 --disk size=10
870 virt-install will generate a path name, and place it in the default
872 image location for the hypervisor. To specify media, the command can
873 either be:
874 --disk /some/storage/path[,opt1=val1]...
876 or explicitly specify one of the following arguments:
878 path A path to some storage media to use, existing or not. Existing
880 media can be a file or block device.
881 Specifying a non-existent path implies attempting to create the
883 new storage, and will require specifying a 'size' value. Even
884 for remote hosts, virt-install will try to use libvirt storage
885 APIs to automatically create the given path.
886 If the hypervisor supports it, path can also be a network URL,
888 like https://example.com/some-disk.img . For network paths, they
889 hypervisor will directly access the storage, nothing is down‐
890 loaded locally.
891 pool An existing libvirt storage pool name to create new storage on.
893 Requires specifying a 'size' value.
894 vol An existing libvirt storage volume to use. This is specified as
896 'poolname/volname'.
897 Options that apply to storage creation:
899 size size (in GiB) to use if creating new storage
901 sparse whether to skip fully allocating newly created storage. Value is
903 'yes' or 'no'. Default is 'yes' (do not fully allocate) unless
904 it isn't supported by the underlying storage type.
905 The initial time taken to fully-allocate the guest virtual disk
907 (sparse=no) will be usually balanced by faster install times
908 inside the guest. Thus use of this option is recommended to
909 ensure consistently high performance and to avoid I/O errors in
910 the guest should the host filesystem fill up.
911 format Disk image format. For file volumes, this can be 'raw', 'qcow2',
913 'vmdk', etc. See format types in
914 https://libvirt.org/storage.html for possible values. This is
915 often mapped to the driver_type value as well.
916 If not specified when creating file images, this will default to
918 'qcow2'.
919 If creating storage, this will be the format of the new image.
921 If using an existing image, this overrides libvirt's format
922 auto-detection.
923 backing_store
925 Path to a disk to use as the backing store for the newly created
926 image.
927 backing_format
929 Disk image format of backing_store
930 Some example device configuration suboptions:
932 device Disk device type. Example values are be 'cdrom', 'disk', 'lun'
934 or 'floppy'. The default is 'disk'.
935 boot.order
937 Guest installation with multiple disks will need this parameter
938 to boot correctly after being installed. A boot.order parameter
939 will take values 1,2,3,... Devices with lower value has higher
940 priority. This option applies to other bootable device types as
941 well.
942 target.bus** or *bus
944 Disk bus type. Example values are be 'ide', 'sata', 'scsi',
945 'usb', 'virtio' or 'xen'. The default is hypervisor dependent
946 since not all hypervisors support all bus types.
947 readonly
949 Set drive as readonly (takes 'on' or 'off')
950 shareable
952 Set drive as shareable (takes 'on' or 'off')
953 cache The cache mode to be used. The host pagecache provides cache
955 memory. The cache value can be 'none', 'writethrough', 'direct‐
956 sync', 'unsafe' or 'writeback'. 'writethrough' provides read
957 caching. 'writeback' provides read and write caching. 'direct‐
958 sync' bypasses the host page cache. 'unsafe' may cache all con‐
959 tent and ignore flush requests from the guest.
960 driver.discard
962 Whether discard (also known as "trim" or "unmap") requests are
963 ignored or passed to the filesystem. The value can be either
964 "unmap" (allow the discard request to be passed) or "ignore"
965 (ignore the discard request). Since 1.0.6 (QEMU and KVM only)
966 driver.name
968 Driver name the hypervisor should use when accessing the speci‐
969 fied storage. Typically does not need to be set by the user.
970 driver.type
972 Driver format/type the hypervisor should use when accessing the
973 specified storage. Typically does not need to be set by the
974 user.
975 driver.io
977 Disk IO backend. Can be either "threads", "native" or
978 "io_uring".
979 driver.error_policy
981 How guest should react if a write error is encountered. Can be
982 one of "stop", "ignore", or "enospace"
983 serial Serial number of the emulated disk device. This is used in linux
985 guests to set /dev/disk/by-id symlinks. An example serial number
986 might be: WD-WMAP9A966149
987 source.startupPolicy
989 It defines what to do with the disk if the source file is not
990 accessible.
991 snapshot
993 Defines default behavior of the disk during disk snapshots.
994 See the examples section for some uses. This option deprecates
996 -f/--file, -s/--file-size, --nonsparse, and --nodisks.
997 Use --disk=? to see a list of all available sub options. Complete
999 details at https://libvirt.org/formatdomain.html#elementsDisks
1000 --filesystem
1002 Specifies a directory on the host to export to the guest. The most sim‐
1003 ple invocation is:
1004 --filesystem /source/on/host,/target/point/in/guest
1006 Which will work for recent QEMU and linux guest OS or LXC containers.
1008 For QEMU, the target point is just a mounting hint in sysfs, so will
1009 not be automatically mounted.
1010 Some example suboptions:
1012 type The type or the source directory. Valid values are 'mount' (the
1014 default) or 'template' for OpenVZ templates.
1015 accessmode or mode
1017 The access mode for the source directory from the guest OS. Only
1018 used with QEMU and type=mount. Valid modes are 'passthrough'
1019 (the default), 'mapped', or 'squash'. See libvirt domain XML
1020 documentation for more info.
1021 source The directory on the host to share.
1023 target The mount location to use in the guest.
1025 Use --filesystem=? to see a list of all available sub options. Com‐
1027 plete details at
1028 https://libvirt.org/formatdomain.html#elementsFilesystems
1029
1031 -w, --network
1032 Syntax: -w, --network OPTIONS
1033 Connect the guest to the host network. Examples for specifying the net‐
1035 work type:
1036 bridge=BRIDGE
1038 Connect to a bridge device in the host called BRIDGE. Use this
1039 option if the host has static networking config & the guest
1040 requires full outbound and inbound connectivity to/from the
1041 LAN. Also use this if live migration will be used with this
1042 guest.
1043 network=NAME
1045 Connect to a virtual network in the host called NAME. Virtual
1046 networks can be listed, created, deleted using the virsh command
1047 line tool. In an unmodified install of libvirt there is usually
1048 a virtual network with a name of default. Use a virtual network
1049 if the host has dynamic networking (eg NetworkManager), or using
1050 wireless. The guest will be NATed to the LAN by whichever con‐
1051 nection is active.
1052 type=direct,source=IFACE[,source.mode=MODE]
1054 Direct connect to host interface IFACE using macvtap.
1055 user Connect to the LAN using SLIRP. Only use this if running a QEMU
1057 guest as an unprivileged user. This provides a very limited form
1058 of NAT.
1059 none Tell virt-install not to add any default network interface.
1061 If --network is omitted a single NIC will be created in the guest. If
1063 there is a bridge device in the host with a physical interface
1064 attached, that will be used for connectivity. Failing that, the virtual
1065 network called default will be used. This option can be specified mul‐
1066 tiple times to setup more than one NIC.
1067 Some example suboptions:
1069 model.type or model
1071 Network device model as seen by the guest. Value can be any nic
1072 model supported by the hypervisor, e.g.: 'e1000', 'rtl8139',
1073 'virtio', ...
1074 mac.address or mac
1076 Fixed MAC address for the guest; If this parameter is omitted,
1077 or the value RANDOM is specified a suitable address will be ran‐
1078 domly generated. For Xen virtual machines it is required that
1079 the first 3 pairs in the MAC address be the sequence '00:16:3e',
1080 while for QEMU or KVM virtual machines it must be '52:54:00'.
1081 filterref.filter
1083 Controlling firewall and network filtering in libvirt. Value can
1084 be any nwfilter defined by the virsh 'nwfilter' subcommands.
1085 Available filters can be listed by running 'virsh nwfil‐
1086 ter-list', e.g.: 'clean-traffic', 'no-mac-spoofing', ...
1087 virtualport.* options
1089 Configure the device virtual port profile. This is used for
1090 802.Qbg, 802.Qbh, midonet, and openvswitch config.
1091 Use --network=? to see a list of all available sub options.
1093 Complete details at
1094 https://libvirt.org/formatdomain.html#elementsNICS
1095 This option deprecates -m/--mac, -b/--bridge, and --nonetworks
1097
1099 If no graphics option is specified, virt-install will try to select the
1100 appropriate graphics if the DISPLAY environment variable is set, other‐
1101 wise '--graphics none' is used.
1102 --graphics
1104 Syntax: --graphics TYPE,opt1=arg1,opt2=arg2,...
1105 Specifies the graphical display configuration. This does not configure
1107 any virtual hardware, just how the guest's graphical display can be
1108 accessed. Typically the user does not need to specify this option,
1109 virt-install will try and choose a useful default, and launch a suit‐
1110 able connection.
1111 General format of a graphical string is
1113 --graphics TYPE,opt1=arg1,opt2=arg2,...
1115 For example:
1117 --graphics vnc,password=foobar
1119 Some supported TYPE values:
1121 vnc Setup a virtual console in the guest and export it as a VNC
1123 server in the host. Unless the port parameter is also provided,
1124 the VNC server will run on the first free port number at 5900 or
1125 above. The actual VNC display allocated can be obtained using
1126 the vncdisplay command to virsh (or virt-viewer(1) can be used
1127 which handles this detail for the use).
1128 spice Export the guest's console using the Spice protocol. Spice
1130 allows advanced features like audio and USB device streaming, as
1131 well as improved graphical performance.
1132 Using spice graphic type will work as if those arguments were
1134 given:
1135 --video qxl --channel spicevmc
1137 none No graphical console will be allocated for the guest. Guests
1139 will likely need to have a text console configured on the first
1140 serial port in the guest (this can be done via the --extra-args
1141 option). The command 'virsh console NAME' can be used to connect
1142 to the serial device.
1143 Some supported suboptions:
1145 port Request a permanent, statically assigned port number for the
1147 guest console. This is used by 'vnc' and 'spice'
1148 tlsPort
1150 Specify the spice tlsport.
1151 websocket
1153 Request a VNC WebSocket port for the guest console.
1154 If -1 is specified, the WebSocket port is auto-allocated.
1156 This is used by 'vnc' and 'spice'
1158 listen Address to listen on for VNC/Spice connections. Default is typi‐
1160 cally 127.0.0.1 (localhost only), but some hypervisors allow
1161 changing this globally (for example, the qemu driver default can
1162 be changed in /etc/libvirt/qemu.conf). Use 0.0.0.0 to allow
1163 access from other machines.
1164 Use 'none' to specify that the display server should not listen
1166 on any port. The display server can be accessed only locally
1167 through libvirt unix socket (virt-viewer with --attach for
1168 instance).
1169 Use 'socket' to have the VM listen on a libvirt generated unix
1171 socket path on the host filesystem.
1172 This is used by 'vnc' and 'spice'
1174 password
1176 Request a console password, required at connection time. Beware,
1177 this info may end up in virt-install log files, so don't use an
1178 important password. This is used by 'vnc' and 'spice'
1179 gl.enable
1181 Whether to use OpenGL accelerated rendering. Value is 'yes' or
1182 'no'. This is used by 'spice'.
1183 gl.rendernode
1185 DRM render node path to use. This is used when 'gl' is enabled.
1186 Use --graphics=? to see a list of all available sub options. Complete
1188 details at https://libvirt.org/formatdomain.html#elementsGraphics
1189 This deprecates the following options: --vnc, --vncport, --vnclisten,
1191 -k/--keymap, --sdl, --nographics
1192 --autoconsole
1194 Syntax: --autoconsole OPTIONS
1195 Configure what interactive console virt-install will launch for the VM.
1197 This option is not required; the default behavior is adaptive and
1198 dependent on how the VM is configured. But you can use this option to
1199 override the default choice.
1200 --autoconsole graphical
1202 Use the graphical virt-viewer(1) as the interactive console
1203 --autoconsole text
1205 Use the text mode virsh console as the interactive console.
1206 --autoconsole none
1208 This is the same as --noautoconsole
1209 --noautoconsole
1211 Don't automatically try to connect to the guest console. Same as
1212 --autoconsole none
1213 Note, virt-install exits quickly when this option is specified. If your
1215 command requested a multistep install, like --cdrom or --location,
1216 after the install phase is complete the VM will be shutoff, regardless
1217 of whether a reboot was requested in the VM. If you want the VM to be
1218 rebooted, virt-install must remain running. You can use '--wait' to
1219 keep virt-install alive even if --noautoconsole is specified.
1220
1222 Options to override the default virtualization type choices.
1223 -v, --hvm
1225 Request the use of full virtualization, if both para & full virtualiza‐
1226 tion are available on the host. This parameter may not be available if
1227 connecting to a Xen hypervisor on a machine without hardware virtual‐
1228 ization support. This parameter is implied if connecting to a QEMU
1229 based hypervisor.
1230 -p, --paravirt
1232 This guest should be a paravirtualized guest. If the host supports both
1233 para & full virtualization, and neither this parameter nor the --hvm
1234 are specified, this will be assumed.
1235 --container
1237 This guest should be a container type guest. This option is only
1238 required if the hypervisor supports other guest types as well (so for
1239 example this option is the default behavior for LXC and OpenVZ, but is
1240 provided for completeness).
1241 --virt-type
1243 The hypervisor to install on. Example choices are kvm, qemu, or xen.
1244 Available options are listed via 'virsh capabilities' in the <domain>
1245 tags.
1246 This deprecates the --accelerate option, which is now the default
1248 behavior. To install a plain QEMU guest, use '--virt-type qemu'
1249
1251 All devices have a set of address.* options for configuring the partic‐
1252 ulars of the device's address on its parent controller or bus. See
1253 https://libvirt.org/formatdomain.html#elementsAddress for details.
1254 --controller
1256 Syntax: --controller OPTIONS
1257 Attach a controller device to the guest. TYPE is one of: ide, fdc,
1259 scsi, sata, virtio-serial, or usb .
1260 Controller also supports the special values usb2 and usb3 to specify
1262 which version of the USB controller should be used (version 2 or 3).
1263 Some example suboptions:
1265 model Controller model. These may vary according to the hypervisor
1267 and its version. Most commonly used models are e.g. auto , vir‐
1268 tio-scsi for the scsi controller, ehci or none``for the ``usb
1269 controller.
1270 Use --controller=? to see a list of all available sub options. Com‐
1272 plete details at
1273 https://libvirt.org/formatdomain.html#elementsControllers
1274 --input
1276 Syntax: --input OPTIONS
1277 Attach an input device to the guest. Example input device types are
1279 mouse, tablet, or keyboard.
1280 Use --input=? to see a list of all available sub options. Complete
1282 details at https://libvirt.org/formatdomain.html#elementsInput
1283 --hostdev, --host-device
1285 Syntax: --hostdev, --host-device OPTIONS
1286 Attach a physical host device to the guest. Some example values for
1288 HOSTDEV:
1289 --hostdev pci_0000_00_1b_0
1291 A node device name via libvirt, as shown by 'virsh nodedev-list'
1292 --hostdev 001.003
1294 USB by bus, device (via lsusb).
1295 --hostdev 0x1234:0x5678
1297 USB by vendor, product (via lsusb).
1298 --hostdev 1f.01.02
1300 PCI device (via lspci).
1301 --hostdev wlan0,type=net
1303 Network device (in LXC container).
1304 --hostdev /dev/net/tun,type=misc
1306 Character device (in LXC container).
1307 --hostdev /dev/sdf,type=storage
1309 Block device (in LXC container).
1310 Use --hostdev=? to see a list of all available sub options. Complete
1312 details at https://libvirt.org/formatdomain.html#elementsHostDev
1313 --sound
1315 Syntax: --sound MODEL
1316 Attach a virtual audio device to the guest. MODEL specifies the emu‐
1318 lated sound card model. Possible values are ich6, ich9, ac97, es1370,
1319 sb16, pcspk, or default. 'default' will try to pick the best model that
1320 the specified OS supports.
1321 This deprecates the old --soundhw option. Use --sound=? to see a list
1323 of all available sub options. Complete details at
1324 https://libvirt.org/formatdomain.html#elementsSound
1325 --watchdog
1327 Syntax: --watchdog MODEL[,action=ACTION]
1328 Attach a virtual hardware watchdog device to the guest. This requires a
1330 daemon and device driver in the guest. The watchdog fires a signal when
1331 the virtual machine appears to hung. ACTION specifies what libvirt will
1332 do when the watchdog fires. Values are
1333 reset Forcefully reset the guest (the default)
1335 poweroff
1337 Forcefully power off the guest
1338 pause Pause the guest
1340 none Do nothing
1342 shutdown
1344 Gracefully shutdown the guest (not recommended, since a hung
1345 guest probably won't respond to a graceful shutdown)
1346 MODEL is the emulated device model: either i6300esb (the default) or
1348 ib700. Some examples:
1349 --watchdog default
1351 Use the recommended settings
1352 --watchdog i6300esb,action=poweroff
1354 Use the i6300esb with the 'poweroff' action
1355 Use --watchdog=? to see a list of all available sub options. Complete
1357 details at https://libvirt.org/formatdomain.html#elementsWatchdog
1358 --serial
1360 Syntax: --serial OPTIONS
1361 Specifies a serial device to attach to the guest, with various options.
1363 The general format of a serial string is
1364 --serial type,opt1=val1,opt2=val2,...
1366 --serial and --parallel devices share all the same options, unless oth‐
1368 erwise noted. Some of the types of character device redirection are:
1369 --serial pty
1371 Pseudo TTY. The allocated pty will be listed in the running
1372 guests XML description.
1373 --serial dev,path=HOSTPATH
1375 Host device. For serial devices, this could be /dev/ttyS0. For
1376 parallel devices, this could be /dev/parport0.
1377 --serial file,path=FILENAME
1379 Write output to FILENAME.
1380 --serial tcp,host=HOST:PORT,source.mode=MODE,protocol.type=PROTOCOL
1382 TCP net console. MODE is either 'bind' (wait for connections on
1383 HOST:PORT) or 'connect' (send output to HOST:PORT), default is
1384 'bind'. HOST defaults to '127.0.0.1', but PORT is required. PRO‐
1385 TOCOL can be either 'raw' or 'telnet' (default 'raw'). If 'tel‐
1386 net', the port acts like a telnet server or client. Some exam‐
1387 ples:
1388 Wait for connections on any address, port 4567:
1390 --serial tcp,host=0.0.0.0:4567
1392 Connect to localhost, port 1234:
1394 --serial tcp,host=:1234,source.mode=connect
1396 Wait for telnet connection on localhost, port 2222. The user
1398 could then connect interactively to this console via 'telnet
1399 localhost 2222':
1400 --serial tcp,host=:2222,source.mode=bind,source.protocol=telnet
1402 --serial udp,host=CONNECT_HOST:PORT,bind_host=BIND_HOST:BIND_PORT
1404 UDP net console. HOST:PORT is the destination to send output to
1405 (default HOST is '127.0.0.1', PORT is required).
1406 BIND_HOST:BIND_PORT is the optional local address to bind to
1407 (default BIND_HOST is 127.0.0.1, but is only set if BIND_PORT is
1408 specified). Some examples:
1409 Send output to default syslog port (may need to edit /etc/rsys‐
1411 log.conf accordingly):
1412 --serial udp,host=:514
1414 Send output to remote host 192.168.10.20, port 4444 (this output
1416 can be read on the remote host using 'nc -u -l 4444'):
1417 --serial udp,host=192.168.10.20:4444
1419 --serial unix,path=UNIXPATH,mode=MODE
1421 Unix socket, see unix(7). MODE has similar behavior and defaults
1422 as --serial tcp,mode=MODE
1423 Use --serial=? to see a list of all available sub options. Complete
1425 details at https://libvirt.org/formatdomain.html#elementsCharSerial
1426 --parallel
1428 Syntax: --parallel OPTIONS
1429 Specify a parallel device. The format and options are largely identical
1431 to serial
1432 Use --parallel=? to see a list of all available sub options. Complete
1434 details at https://libvirt.org/formatdomain.html#elementsCharParallel
1435 --channel
1437 Specifies a communication channel device to connect the guest and host
1438 machine. This option uses the same options as --serial and --parallel
1439 for specifying the host/source end of the channel. Extra 'target'
1440 options are used to specify how the guest machine sees the channel.
1441 Some of the types of character device redirection are:
1443 --channel SOURCE,target.type=guestfwd,target.address=HOST:PORT
1445 Communication channel using QEMU usermode networking stack. The
1446 guest can connect to the channel using the specified HOST:PORT
1447 combination.
1448 --channel SOURCE,target.type=virtio[,target.name=NAME]
1450 Communication channel using virtio serial (requires 2.6.34 or
1451 later host and guest). Each instance of a virtio --channel line
1452 is exposed in the guest as /dev/vport0p1, /dev/vport0p2, etc.
1453 NAME is optional metadata, and can be any string, such as
1454 org.linux-kvm.virtioport1. If specified, this will be exposed
1455 in the guest at /sys/class/virtio-ports/vport0p1/NAME
1456 --channel spicevmc,target.type=virtio[,target.name=NAME]
1458 Communication channel for QEMU spice agent, using virtio serial
1459 (requires 2.6.34 or later host and guest). NAME is optional
1460 metadata, and can be any string, such as the default com.red‐
1461 hat.spice.0 that specifies how the guest will see the channel.
1462 Use --channel=? to see a list of all available sub options. Complete
1464 details at https://libvirt.org/formatdomain.html#elementsCharChannel
1465 --console
1467 Connect a text console between the guest and host. Certain guest and
1468 hypervisor combinations can automatically set up a getty in the guest,
1469 so an out of the box text login can be provided (target_type=xen for
1470 xen paravirt guests, and possibly target_type=virtio in the future).
1471 Example:
1473 --console pty,target.type=virtio
1475 Connect a virtio console to the guest, redirected to a PTY on
1476 the host. For supported guests, this exposes /dev/hvc0 in the
1477 guest. See https://fedoraproject.org/wiki/Features/VirtioSerial
1478 for more info. virtio console requires libvirt 0.8.3 or later.
1479 Use --console=? to see a list of all available sub options. Complete
1481 details at https://libvirt.org/formatdomain.html#elementsCharConsole
1482 --video
1484 Syntax: --video OPTIONS
1485 Specify what video device model will be attached to the guest. Valid
1487 values for VIDEO are hypervisor specific, but some options for recent
1488 kvm are cirrus, vga, qxl, virtio, or vmvga (vmware). Use --video=? to
1489 see a list of all available sub options. Complete details at
1490 https://libvirt.org/formatdomain.html#elementsVideo
1491 --smartcard
1493 Syntax: --smartcard MODE[,OPTIONS]
1494 Configure a virtual smartcard device.
1496 Example MODE values are host, host-certificates, or passthrough. Exam‐
1498 ple suboptions include:
1499 type Character device type to connect to on the host. This is only
1501 applicable for passthrough mode.
1502 An example invocation:
1504 --smartcard passthrough,type=spicevmc
1506 Use the smartcard channel of a SPICE graphics device to pass
1507 smartcard info to the guest
1508 Use --smartcard=? to see a list of all available sub options. Complete
1510 details at https://libvirt.org/formatdomain.html#elementsSmartcard
1511 --redirdev
1513 Syntax: --redirdev BUS[,OPTIONS]
1514 Add a redirected device. Example suboptions:
1516 type The redirection type, currently supported is tcp or spicevmc .
1518 server The TCP server connection details, of the form 'server:port'.
1520 Examples invocations:
1522 --redirdev usb,type=tcp,server=localhost:4000
1524 Add a USB redirected device provided by the TCP server on
1525 'localhost' port 4000.
1526 --redirdev usb,type=spicevmc
1528 Add a USB device redirected via a dedicated Spice channel.
1529 Use --redirdev=? to see a list of all available sub options. Complete
1531 details at https://libvirt.org/formatdomain.html#elementsRedir
1532 --memballoon
1534 Syntax: --memballoon MODEL[,OPTIONS]
1535 Attach a virtual memory balloon device to the guest. If the memballoon
1537 device needs to be explicitly disabled, MODEL='none' is used.
1538 MODEL is the type of memballoon device provided. The value can be 'vir‐
1540 tio', 'xen' or 'none'. Some examples:
1541 --memballoon virtio
1543 Explicitly create a 'virtio' memballoon device
1544 --memballoon none
1546 Disable the memballoon device
1547 Use --memballoon=? to see a list of all available sub options. Com‐
1549 plete details at
1550 https://libvirt.org/formatdomain.html#elementsMemBalloon
1551 --tpm
1553 Syntax: --tpm TYPE[,OPTIONS]
1554 Configure a virtual TPM device. Examples:
1556 --tpm /dev/tpm
1558 Convenience option for passing through the hosts TPM.
1559 --tpm emulator
1561 Request an emulated TPM device.
1562 Use --tpm=? to see a list of all available sub options. Complete
1564 details at https://libvirt.org/formatdomain.html#elementsTpm
1565 --rng
1567 Syntax: --rng TYPE[,OPTIONS]
1568 Configure a virtual RNG device.
1570 Example TYPE values include random, egd or builtin.
1572 Example invocations:
1574 --rng /dev/urandom
1576 Use the /dev/urandom device to get entropy data, this form
1577 implicitly uses the "random" model.
1578 --rng builtin
1580 Use the builtin rng device to get entropy data.
1581 --rng egd,backend.source.host=localhost,backend.source.ser‐
1583 vice=8000,backend.type=tcp
1584 Connect to localhost to the TCP port 8000 to get entropy data.
1585 Use --rng=? to see a list of all available sub options. Complete
1587 details at https://libvirt.org/formatdomain.html#elementsRng
1588 --panic
1590 Syntax: --panic MODEL[,OPTS]
1591 Attach a panic notifier device to the guest. For the recommended set‐
1593 tings, use: --panic default
1594 Use --panic=? to see a list of all available sub options. Complete
1596 details at https://libvirt.org/formatdomain.html#elementsPanic
1597 --memdev
1599 Syntax: --memdev OPTS
1600 Add a memory module to a guest which can be hotunplugged. To add a
1602 memdev you need to configure hotplugmemory and NUMA for a guest.
1603 Use --memdev=? to see a list of all available sub options. Complete
1605 details at https://libvirt.org/formatdomain.html#elementsMemory.
1606 --vsock
1608 Syntax: --vsock OPTS
1609 Configure a vsock host/guest interface. A typical configuration would
1611 be
1612 --vsock cid.auto=yes
1614 Use --vsock=? to see a list of all available sub options. Complete
1616 details at https://libvirt.org/formatdomain.html#vsock.
1617 --iommu
1619 Syntax: --iommu MODEL[,OPTS]
1620 Add an IOMMU device to the guest.
1622 Use --iommu=? to see a list of all available options. Complete details
1624 at https://libvirt.org/formatdomain.html#elementsIommu.
1625
1627 -h, --help
1628 Show the help message and exit
1629 --version
1631 Show program's version number and exit
1632 --autostart
1634 Set the autostart flag for a domain. This causes the domain to be
1635 started on host boot up.
1636 --transient
1638 Use --import or --boot and --transient if you want a transient libvirt
1639 VM. These VMs exist only until the domain is shut down or the host
1640 server is restarted. Libvirt forgets the XML configuration of the VM
1641 after either of these events. Note that the VM's disks will not be
1642 deleted. See:
1643 https://wiki.libvirt.org/page/VM_lifecycle#Transient_guest_domains_vs_Persistent_guest_domains
1644 --destroy-on-exit
1646 When the VM console window is exited, destroy (force poweroff) the VM.
1647 If you combine this with --transient, this makes the virt-install com‐
1648 mand work similar to qemu, where the VM is shutdown when the console
1649 window is closed by the user.
1650 --print-xml
1652 Syntax: --print-xml [STEP]
1653 Print the generated XML of the guest, instead of defining it. By
1655 default this WILL do storage creation (can be disabled with --dry-run).
1656 This option implies --quiet.
1657 If the VM install has multiple phases, by default this will print all
1659 generated XML. If you want to print a particular step, use --print-xml
1660 2 (for the second phase XML).
1661 --noreboot
1663 Prevent the domain from automatically rebooting after the install has
1664 completed.
1665 --wait
1667 Syntax: --wait WAIT
1668 Configure how virt-install will wait for the install to complete.
1670 Without this option, virt-install will wait for the console to close
1671 (not necessarily indicating the guest has shutdown), or in the case of
1672 --noautoconsole, simply kick off the install and exit.
1673 Bare '--wait' or any negative value will make virt-install wait indefi‐
1675 nitely. Any positive number is the number of minutes virt-install will
1676 wait. If the time limit is exceeded, virt-install simply exits, leaving
1677 the virtual machine in its current state.
1678 --dry-run
1680 Proceed through the guest creation process, but do NOT create storage
1681 devices, change host device configuration, or actually teach libvirt
1682 about the guest. virt-install may still fetch install media, since
1683 this is required to properly detect the OS to install.
1684 --check
1686 Enable or disable some validation checks. Some examples are warning
1687 about using a disk that's already assigned to another VM (--check
1688 path_in_use=on|off), or warning about potentially running out of space
1689 during disk allocation (--check disk_size=on|off). Most checks are per‐
1690 formed by default.
1691 -q, --quiet
1693 Only print fatal error messages.
1694 -d, --debug
1696 Print debugging information to the terminal when running the install
1697 process. The debugging information is also stored in
1698 ~/.cache/virt-manager/virt-install.log even if this parameter is omit‐
1699 ted.
1700
1702 The simplest invocation to interactively install a Fedora 29 KVM VM
1703 with recommended defaults. virt-viewer(1) will be launched to graphi‐
1704 cally interact with the VM install
1705 # sudo virt-install --install fedora29
1707 Similar, but use libosinfo's unattended install support, which will
1709 perform the fedora29 install automatically without user intervention:
1710 # sudo virt-install --install fedora29 --unattended
1712 Install a Windows 10 VM, using 40GiB storage in the default location
1714 and 4096MiB of ram, and ensure we are connecting to the system libvirtd
1715 instance:
1716 # virt-install \
1718 --connect qemu:///system \
1719 --name my-win10-vm \
1720 --memory 4096 \
1721 --disk size=40 \
1722 --os-variant win10 \
1723 --cdrom /path/to/my/win10.iso
1724 Install a CentOS 7 KVM from a URL, with recommended device defaults and
1726 default required storage, but specifically request VNC graphics instead
1727 of the default SPICE, and request 8 virtual CPUs and 8192 MiB of mem‐
1728 ory:
1729 # virt-install \
1731 --connect qemu:///system \
1732 --memory 8192 \
1733 --vcpus 8 \
1734 --graphics vnc \
1735 --os-variant centos7.0 \
1736 --location http://mirror.centos.org/centos-7/7/os/x86_64/
1737 Create a VM around an existing debian9 disk image:
1739 # virt-install \
1741 --import \
1742 --memory 512 \
1743 --disk /home/user/VMs/my-debian9.img \
1744 --os-variant debian9
1745 Start serial QEMU ARM VM, which requires specifying a manual kernel.
1747 # virt-install \
1749 --name armtest \
1750 --memory 1024 \
1751 --arch armv7l --machine vexpress-a9 \
1752 --disk /home/user/VMs/myarmdisk.img \
1753 --boot kernel=/tmp/my-arm-kernel,initrd=/tmp/my-arm-initrd,dtb=/tmp/my-arm-dtb,kernel_args="console=ttyAMA0 rw root=/dev/mmcblk0p3" \
1754 --graphics none
1755 Start an SEV launch security VM with 4GB RAM, 4GB+256MiB of hard_limit,
1757 with a couple of virtio devices:
1758 Note: The IOMMU flag needs to be turned on with driver.iommu for virtio
1760 devices. Usage of --memtune is currently required because of SEV limi‐
1761 tations, refer to libvirt docs for a detailed explanation.
1762 # virt-install \
1764 --name foo \
1765 --memory 4096 \
1766 --boot uefi \
1767 --machine q35 \
1768 --memtune hard_limit=4563402 \
1769 --disk size=15,target.bus=scsi \
1770 --import \
1771 --controller type=scsi,model=virtio-scsi,driver.iommu=on \
1772 --controller type=virtio-serial,driver.iommu=on \
1773 --network network=default,model=virtio,driver.iommu=on \
1774 --rng /dev/random,driver.iommu=on \
1775 --memballoon driver.iommu=on \
1776 --launchSecurity sev
1777
1779 Please see https://virt-manager.org/bugs
1780
1782 Copyright (C) Red Hat, Inc, and various contributors. This is free
1783 software. You may redistribute copies of it under the terms of the GNU
1784 General Public License https://www.gnu.org/licenses/gpl.html. There is
1785 NO WARRANTY, to the extent permitted by law.
1786
1788 virsh(1), virt-clone(1), virt-manager(1), the project website
1789 https://virt-manager.org
1790 VIRT-INSTALL(1)