1VIRT-INSTALL(1)             Virtualization Support             VIRT-INSTALL(1)
2
3
4

NAME

6       virt-install - provision new virtual machines
7

SYNOPSIS

9       virt-install [OPTION]...
10

DESCRIPTION

12       virt-install is a command line tool for creating new KVM, 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
17       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  in‐
20       terfaces, audio devices, physical USB or PCI devices, among others.
21
22       The installation media can be local ISO or CDROM media, or a distro in‐
23       stall tree hosted remotely over HTTP, FTP, or in a local directory.  In
24       the  install tree case virt-install will fetch the minimal files neces‐
25       sary to kick off the installation process, allowing the guest to  fetch
26       the  rest  of the OS distribution as needed. PXE booting, and importing
27       an existing disk image (thus skipping the install phase) are also  sup‐
28       ported.
29
30       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
35       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
39       Most options are not required. If a suitable --osinfo value  is  speci‐
40       fied  or  detected,  all defaults will be filled in and reported in the
41       terminal output. Otherwise,  minimum  required  options  are  --memory,
42       guest storage (--disk or --filesystem), and an install method choice.
43

CONNECTING TO LIBVIRT

45   --connect
46       Syntax: --connect URI
47
48       Connect  to  a non-default hypervisor. If this isn't specified, libvirt
49       will try and choose the most suitable default.
50
51       Some valid options here are:
52
53       qemu:///system
54              For creating KVM and QEMU guests to be run by  the  system  lib‐
55              virtd  instance.   This  is  the  default mode that virt-manager
56              uses, and what most KVM users want.
57
58       qemu:///session
59              For creating KVM and QEMU guests for  libvirtd  running  as  the
60              regular user.
61
62       xen:///
63              For connecting to Xen.
64
65       lxc:///
66              For creating linux containers
67

GENERAL OPTIONS

69       General  configuration  parameters that apply to all types of guest in‐
70       stalls.
71
72   -n, --name
73       Syntax: -n, --name NAME
74
75       Name of the new guest virtual machine instance.  This  must  be  unique
76       amongst all guests known to the hypervisor on the connection, including
77       those not currently active. To re-define an  existing  guest,  use  the
78       virsh(1) tool to shut it down ('virsh shutdown') & delete ('virsh unde‐
79       fine') it prior to running virt-install.
80
81   --memory
82       Syntax: --memory OPTIONS
83
84       Memory to allocate for the guest, in MiB. This deprecates the  -r/--ram
85       option.   Sub  options  are  available, like 'memory', 'currentMemory',
86       'maxMemory' and 'maxMemory.slots', which all  map  to  the  identically
87       named XML values.
88
89       Back  compat  values  'memory' maps to the <currentMemory> element, and
90       maxmemory maps to the <memory> element.
91
92       To configure memory modules which can be hotunplugged see --memdev  de‐
93       scription.
94
95       Use  --memory=?  to  see a list of all available sub options.  Complete
96       details                                                              at
97       https://libvirt.org/formatdomain.html#elementsMemoryAllocation
98
99   --memorybacking
100       Syntax: --memorybacking OPTIONS
101
102       This  option will influence how virtual memory pages are backed by host
103       pages.
104
105       Use --memorybacking=? to see a list of all available sub options.  Com‐
106       plete                             details                            at
107       https://libvirt.org/formatdomain.html#elementsMemoryBacking
108
109   --arch
110       Syntax: --arch ARCH
111
112       Request a non-native CPU architecture for the  guest  virtual  machine.
113       If omitted, the host CPU architecture will be used in the guest.
114
115   --machine
116       Syntax: --machine MACHINE
117
118       The  machine type to emulate. This will typically not need to be speci‐
119       fied for Xen or KVM, but is useful for choosing machine types  of  more
120       exotic architectures.
121
122   --metadata
123       Syntax: --metadata OPT=VAL,[...]
124
125       Specify  metadata  values for the guest. Possible options include name,
126       uuid, title, and description.  This  option  deprecates  -u/--uuid  and
127       --description.
128
129       Use  --metadata=? to see a list of all available sub options.  Complete
130       details at https://libvirt.org/formatdomain.html#elementsMetadata
131
132   --events
133       Syntax: --events OPT=VAL,[...]
134
135       Specify  events  values  for  the  guest.  Possible   options   include
136       on_poweroff, on_reboot, and on_crash.
137
138       Use  --events=?  to  see a list of all available sub options.  Complete
139       details at https://libvirt.org/formatdomain.html#elementsEvents
140
141   --resource
142       Syntax: --resource OPT=VAL,[...]
143
144       Specify resource partitioning for the guest.
145
146       Use --resource=? to see a list of all available sub options.   Complete
147       details at https://libvirt.org/formatdomain.html#resPartition
148
149   --sysinfo
150       Syntax: --sysinfo OPT=VAL,[...]
151
152       Configure sysinfo/SMBIOS values exposed to the VM OS. Examples:
153
154       --sysinfo host
155              Special type that exposes the host's SMBIOS info into the VM.
156
157       --sysinfo emulate
158              Special type where hypervisor will generate SMBIOS info into the
159              VM.
160
161       --sysinfo bios.vendor=custom or --sysinfo smbios,bios.vendor=custom
162              The default type is smbios and allows users  to  specify  SMBIOS
163              info manually.
164
165       Use --sysinfo=? to see a list of all available sub options.
166
167       Complete                           details                           at
168       https://libvirt.org/formatdomain.html#elementsSysinfo               and
169       https://libvirt.org/formatdomain.html#elementsOSBIOS for smbios XML el‐
170       ement.
171
172   --xml
173       Syntax: --xml ARGS
174
175       Make direct edits to the generated XML using XPath syntax. Take an  ex‐
176       ample like
177
178          virt-install --xml ./@foo=bar --xml ./newelement/subelement=1
179
180       This will alter the generated XML to contain:
181
182          <domain foo='bar' ...>
183            ...
184            <newelement>
185              <subelement>1</subelement>
186            </newelement>
187          </domain>
188
189       The --xml option has 4 sub options:
190
191       --xml xpath.set=XPATH[=VALUE]
192              The  default behavior if no explicit suboption is set. Takes the
193              form XPATH=VALUE unless paired with xpath.value . See below  for
194              how value is interpreted.
195
196       --xml xpath.value=VALUE
197              xpath.set  will  be  interpreted  only  as the XPath string, and
198              xpath.value will be used as the value to set. May help  sidestep
199              problems  if  the  string  you need to set contains a '=' equals
200              sign.
201
202              If value is empty, it's treated  as  unsetting  that  particular
203              node.
204
205       --xml xpath.create=XPATH
206              Create the node as an empty element. Needed for boolean elements
207              like <readonly/>
208
209       --xml xpath.delete=XPATH
210              Delete the entire node specified by the xpath, and all its chil‐
211              dren
212
213   xpath subarguments
214       Similar  to the --xml option, most top level options have xpath.*  sub‐
215       options.   For   example,   --disk    xpath1.set=./@foo=bar,xpath2.cre‐
216       ate=./newelement would generate XML alterations like
217
218          <disk foo="bar">
219            <newelements/>
220          </disk>
221
222       This  is  useful  for setting XML options per device, when virt-install
223       does not support those options yet.
224
225   --qemu-commandline
226       Syntax: --qemu-commandline ARGS
227
228       Pass options directly to the qemu emulator. Only works for the  libvirt
229       qemu driver. The option can take a string of arguments, for example:
230
231          --qemu-commandline="-display gtk,gl=on"
232
233       Environment variables are specified with 'env', for example:
234
235          --qemu-commandline=env=DISPLAY=:0.1
236
237       Complete       details       about       the      libvirt      feature:
238       https://libvirt.org/drvqemu.html#qemucommand
239
240   --vcpus
241       Syntax: --vcpus OPTIONS
242
243       Number of virtual cpus to configure for the  guest.  If  'maxvcpus'  is
244       specified,  the guest will be able to hotplug up to MAX vcpus while the
245       guest is running, but will startup with VCPUS.
246
247       CPU topology can additionally be specified with sockets,  dies,  cores,
248       and  threads.   If values are omitted, the rest will be autofilled pre‐
249       ferring cores over sockets over threads. Cores  are  preferred  because
250       this  matches the characteristics of modern real world silicon and thus
251       a better fit for what guest OS will be expecting to deal with.
252
253       'cpuset' sets which physical cpus the guest can use. CPUSET is a  comma
254       separated  list  of  numbers,  which can also be specified in ranges or
255       cpus to exclude. Example:
256
257          0,2,3,5     : Use processors 0,2,3 and 5
258          1-5,^3,8    : Use processors 1,2,4,5 and 8
259
260       If the value 'auto' is passed, virt-install attempts  to  automatically
261       determine an optimal cpu pinning using NUMA data, if available.
262
263       Use --vcpus=? to see a list of all available sub options.  Complete de‐
264       tails at https://libvirt.org/formatdomain.html#elementsCPUAllocation
265
266   --numatune
267       Syntax: --numatune OPTIONS
268
269       Tune NUMA policy for the domain process. Example invocations
270
271          --numatune 1,2,3,4-7
272          --numatune 1-3,5,memory.mode=preferred
273
274       Specifies the numa nodes to allocate memory from.  This  has  the  same
275       syntax  as  --vcpus  cpuset=  option.  mode can be one of 'interleave',
276       'preferred', or 'strict' (the default). See 'man 8 numactl' for  infor‐
277       mation about each mode.
278
279       Use  --numatune=? to see a list of all available sub options.  Complete
280       details at https://libvirt.org/formatdomain.html#elementsNUMATuning
281
282   --memtune
283       Syntax: --memtune OPTIONS
284
285       Tune memory policy for the domain process. Example invocations
286
287          --memtune 1000
288          --memtune hard_limit=100,soft_limit=60,swap_hard_limit=150,min_guarantee=80
289
290       Use --memtune=? to see a list of all available sub  options.   Complete
291       details at https://libvirt.org/formatdomain.html#elementsMemoryTuning
292
293   --blkiotune
294       Syntax: --blkiotune OPTIONS
295
296       Tune blkio policy for the domain process. Example invocations
297
298          --blkiotune 100
299          --blkiotune weight=100,device.path=/dev/sdc,device.weight=200
300
301       Use --blkiotune=? to see a list of all available sub options.  Complete
302       details at https://libvirt.org/formatdomain.html#elementsBlockTuning
303
304   --cpu
305       Syntax:  --cpu   MODEL[,+feature][,-feature][,match=MATCH][,vendor=VEN‐
306       DOR],...
307
308       Configure the CPU model and CPU features exposed to the guest. The only
309       required value is MODEL, which is a valid CPU model as  known  to  lib‐
310       virt.
311
312       Libvirt's  feature  policy values force, require, optional, disable, or
313       forbid, or with the shorthand '+feature' and  '-feature',  which  equal
314       'force=feature' and 'disable=feature' respectively.
315
316       If  exact  CPU  model is specified virt-install will automatically copy
317       CPU features available on the host to mitigate recent  CPU  speculative
318       execution  side  channel and Microarchitectural Store Buffer Data secu‐
319       rity vulnerabilities.  This however will have some  impact  on  perfor‐
320       mance  and  will  break migration to hosts without security patches. In
321       order to control this behavior there is a  secure  parameter.  Possible
322       values are on and off, with on as the default. It is highly recommended
323       to leave this enabled and ensure all virtualization hosts have fully up
324       to date microcode, kernel & virtualization software installed.
325
326       Some examples:
327
328       --cpu core2duo,+x2apic,disable=vmx
329              Expose  the  core2duo CPU model, force enable x2apic, but do not
330              expose vmx
331
332       --cpu host
333              Expose the host CPUs configuration to the  guest.  This  enables
334              the  guest  to  take advantage of many of the host CPUs features
335              (better performance), but may  cause  issues  if  migrating  the
336              guest to a host without an identical CPU.
337
338       --cpu        numa.cell0.memory=1234,numa.cell0.cpus=0-3,numa.cell1.mem‐
339       ory=5678,numa.cell1.cpus=4-7
340              Example of specifying two NUMA cells.  This  will  generate  XML
341              like:
342
343                 <cpu>
344                   <numa>
345                     <cell cpus="0-3" memory="1234"/>
346                     <cell cpus="4-7" memory="5678"/>
347                   </numa>
348                 </cpu>
349
350       --cpu host-passthrough,cache.mode=passthrough
351              Example of passing through the host cpu's cache information.
352
353       Use  --cpu=?  to see a list of all available sub options.  Complete de‐
354       tails at https://libvirt.org/formatdomain.html#elementsCPU
355
356   --cputune
357       Syntax: --cputune OPTIONS
358
359       Tune CPU parameters for the guest.
360
361       Configure which of the host's physical CPUs the  domain  VCPU  will  be
362       pinned to.  Example invocation
363
364          --cputune vcpupin0.vcpu=0,vcpupin0.cpuset=0-3,vcpupin1.vcpu=1,vcpupin1.cpuset=4-7
365
366       Use  --cputune=?  to see a list of all available sub options.  Complete
367       details at https://libvirt.org/formatdomain.html#elementsCPUTuning
368
369   --security, --seclabel
370       Syntax:    --security,    --seclabel     type=TYPE[,label=LABEL][,rela‐
371       bel=yes|no],...
372
373       Configure  domain seclabel domain settings. Type can be either 'static'
374       or 'dynamic'. 'static' configuration requires a security LABEL.  Speci‐
375       fying LABEL without TYPE implies static configuration.
376
377       Use  --security=? to see a list of all available sub options.  Complete
378       details at https://libvirt.org/formatdomain.html#seclabel
379
380   --keywrap
381       Syntax: --keywrap OPTIONS
382
383       Specify domain <keywrap> XML, used for S390 cryptographic  key  manage‐
384       ment operations.
385
386       Use  --keywrap=?  to see a list of all available sub options.  Complete
387       details at https://libvirt.org/formatdomain.html#keywrap
388
389   --iothreads
390       Syntax: --iothreads OPTIONS
391
392       Specify domain <iothreads> and/or <iothreadids> XML.  For  example,  to
393       configure <iothreads>4</iothreads>, use --iothreads 4
394
395       Use --iothreads=? to see a list of all available sub options.  Complete
396       details                                                              at
397       https://libvirt.org/formatdomain.html#elementsIOThreadsAllocation
398
399   --features
400       Syntax: --features FEAT=on|off,...
401
402       Set  elements  in the guests <features> XML on or off. Examples include
403       acpi, apic, eoi, privnet, and hyperv features. Some examples:
404
405       --features apic.eoi=on
406              Enable APIC PV EOI
407
408       --features hyperv.vapic.state=on,hyperv.spinlocks.state=off
409              Enable hyperv VAPIC, but disable spinlocks
410
411       --features kvm.hidden.state=on
412              Allow the KVM hypervisor signature to be hidden from the guest
413
414       --features pvspinlock=on
415              Notify the guest that the host  supports  paravirtual  spinlocks
416              for example by exposing the pvticketlocks mechanism.
417
418       --features gic.version=2
419              This is relevant only for ARM architectures. Possible values are
420              "host" or version number.
421
422       --features smm.state=on
423              This enables System Management Mode  of  hypervisor.  Some  UEFI
424              firmwares may require this feature to be present. (QEMU supports
425              SMM only with q35 machine type.)
426
427       Use --features=? to see a list of all available sub options.   Complete
428       details at https://libvirt.org/formatdomain.html#elementsFeatures
429
430   --clock
431       Syntax: --clock offset=OFFSET,TIMER_OPT=VAL,...
432
433       Configure the guest's <clock> XML. Some supported options:
434
435       --clock offset=OFFSET
436              Set the clock offset, ex. 'utc' or 'localtime'
437
438       --clock TIMER_present=no
439              Disable  a  boolean  timer.  TIMER here might be hpet, kvmclock,
440              etc.
441
442       --clock TIMER_tickpolicy=VAL
443              Set a timer's tickpolicy value. TIMER here might  be  rtc,  pit,
444              etc. VAL might be catchup, delay, etc. Refer to the libvirt docs
445              for all values.
446
447       Use --clock=? to see a list of all available sub options.  Complete de‐
448       tails at https://libvirt.org/formatdomain.html#elementsTime
449
450   --pm
451       Syntax: --pm OPTIONS
452
453       Configure guest power management features. Example:
454
455          --pm suspend_to_memi.enabled=on,suspend_to_disk.enabled=off
456
457       Use  --pm=?  to  see a list of all available sub options.  Complete de‐
458       tails at https://libvirt.org/formatdomain.html#elementsPowerManagement
459
460   --launchSecurity
461       Syntax: --launchSecurity TYPE[,OPTS]
462
463       Enable launch security for the guest, e.g.  AMD  SEV.  Example  invoca‐
464       tions:
465
466          # This will use a default policy 0x03
467          # No dhCert provided, so no data can be exchanged with the SEV firmware
468          --launchSecurity sev
469
470          # Explicit policy 0x01 - disables debugging, allows guest key sharing
471          --launchSecurity sev,policy=0x01
472
473          # Provide the session blob obtained from the SEV firmware
474          # Provide dhCert to open a secure communication channel with SEV firmware
475          --launchSecurity sev,session=BASE64SESSIONSTRING,dhCert=BASE64DHCERTSTRING
476
477       SEV  has  further  implications on usage of virtio devices, so refer to
478       EXAMPLES  section  to  see  a  full  invocation  of  virt-install  with
479       --launchSecurity.
480
481       Use --launchSecurity=? to see a list of all available sub options. Com‐
482       plete details at https://libvirt.org/formatdomain.html#launchSecurity
483

INSTALLATION OPTIONS

485   -c, --cdrom
486       Syntax: --cdrom PATH
487
488       ISO file or CDROM device to use for VM install  media.  After  install,
489       the  virtual  CDROM device will remain attached to the VM, but with the
490       ISO or host path media ejected.
491
492   -l, --location
493       Syntax: -l, --location OPTIONS
494
495       Distribution tree installation source. virt-install can recognize  cer‐
496       tain  distribution  trees  and fetches a bootable kernel/initrd pair to
497       launch the install.
498
499       --location allows things like --extra-args for  kernel  arguments,  and
500       using  --initrd-inject. If you want to use those options with CDROM me‐
501       dia, you can pass the ISO to --location as well which works  for  some,
502       but not all, CDROM media.
503
504       The LOCATION can take one of the following forms:
505
506       https://host/path
507              An  HTTP  server location containing an installable distribution
508              image.
509
510       ftp://host/path
511              An FTP server location containing  an  installable  distribution
512              image.
513
514       ISO    Extract files directly from the ISO path
515
516       DIRECTORY
517              Path to a local directory containing an installable distribution
518              image.  Note that the directory will not be  accessible  by  the
519              guest  after initial boot, so the OS installer will need another
520              way to access the rest of the install media.
521
522       Some distro specific url samples:
523
524       Fedora/Red Hat Based
525              https://download.fedoraproject.org/pub/fedora/linux/releases/29/Server/x86_64/os
526
527       Debian https://debian.osuosl.org/debian/dists/stable/main/installer-amd64/
528
529       Ubuntu https://us.archive.ubuntu.com/ubuntu/dists/wily/main/installer-amd64/
530
531       Suse   https://download.opensuse.org/pub/opensuse/distribution/leap/42.3/repo/oss/
532
533       Additionally, --location can take 'kernel' and  'initrd'  sub  options.
534       These  paths  relative to the specified location URL/ISO that allow se‐
535       lecting specific files for kernel/initrd within the install tree.  This
536       can be useful if virt-install/ libosinfo doesn't know where to find the
537       kernel in the specified --location.
538
539       For example, if you have an  ISO  that  libosinfo  doesn't  know  about
540       called  my-unknown.iso,  with a kernel at 'kernel/fookernel' and initrd
541       at 'kernel/fooinitrd', you can make this work with:
542
543          --location my-unknown.iso,kernel=kernel/fookernel,initrd=kernel/fooinitrd
544
545   --pxe
546       Install from PXE. This just tells the VM to boot off  the  network  for
547       the first boot.
548
549   --import
550       Skip  the OS installation process, and build a guest around an existing
551       disk image. The device used for booting is the first  device  specified
552       via --disk or --filesystem.
553
554   -x, --extra-args
555       Syntax: -x, --extra-args KERNELARGS
556
557       Additional  kernel command line arguments to pass to the installer when
558       performing a guest install from --location. One common usage is  speci‐
559       fying  an anaconda kickstart file for automated installs, such as --ex‐
560       tra-args "ks=https://myserver/my.ks"
561
562   --initrd-inject
563       Syntax: --initrd-inject PATH
564
565       Add PATH to the root of the initrd fetched with --location. This can be
566       used  to  run  an  automated install without requiring a network hosted
567       kickstart     file:     --initrd-inject=/path/to/my.ks     --extra-args
568       "ks=file:/my.ks"
569
570   --install
571       This  is  a larger entry point for various types of install operations.
572       The command has multiple subarguments, similar to --disk  and  friends.
573       This  option is strictly for VM install operations, essentially config‐
574       uring the first boot.
575
576       The simplest usage to ex: install fedora29 is:
577
578          --install fedora29
579
580       And virt-install will fetch a --location URL from libosinfo, and  popu‐
581       late defaults from there.
582
583       Available suboptions:
584
585       os=    This  is  os install option described above. The explicit way to
586              specify that would be --install os=fedora29 . os= is the default
587              option if none is specified
588
589       kernel=, initrd=
590              Specify  a  kernel and initrd pair to use as install media. They
591              are copied into a temporary location before booting the  VM,  so
592              they  can be combined with --initrd-inject and your source media
593              will not be altered. Media will be uploaded to a remote  connec‐
594              tion if required.
595
596              Example  case  using  local  filesystem  paths:  --install  ker‐
597              nel=/path/to/kernel,initrd=/path/to/initrd
598
599              Example using network paths. Kernel/initrd  will  be  downloaded
600              locally  first, then passed to the VM as local filesystem paths:
601              --install              kernel=https://127.0.0.1/tree/kernel,ini‐
602              trd=https://127.0.0.1/tree/initrd
603
604              Note,  these  are  just for install time booting. If you want to
605              set the kernel used for permanent VM booting, use the --boot op‐
606              tion.
607
608       kernel_args=, kernel_args_overwrite=yes|no
609              Specify  install  time kernel arguments (libvirt <cmdline> XML).
610              These can be combine with ex: kernel/initrd options, or  --loca‐
611              tion  media.  By default, kernel_args is just like --extra-args,
612              and will _append_ to the arguments that virt-install will try to
613              set  by  default  for  most  --location installs. If you want to
614              override the virt-install  default,  additionally  specify  ker‐
615              nel_args_overwrite=yes
616
617       bootdev=
618              Specify the install bootdev (hd, cdrom, floppy, network) to boot
619              off of for the install phase. This  maps  to  libvirt  <os><boot
620              dev=X> XML.
621
622              If  you  want  to  install off a cdrom or network, it's probably
623              simpler and more backwards compatible to  just  use  --cdrom  or
624              --pxe , but this options gives fine grained control over the in‐
625              stall process if needed.
626
627       no_install=yes|no
628              Tell virt-install that there isn't actually any install  happen‐
629              ing,  and  you  just  want to create the VM. --import is just an
630              alias for this, as is specifying --boot without  any  other  in‐
631              stall  options.  The  deprecated  --live  option  is the same as
632              '--cdrom $ISO --install no_install=yes'
633
634   --reinstall DOMAIN
635       Reinstall an existing VM. DOMAIN can be a VM name, UUID, or ID  number.
636       virt-install  will  fetch the domain XML from libvirt, apply the speci‐
637       fied install config changes, boot the VM for the install  process,  and
638       then revert to roughly the same starting XML.
639
640       Only  install related options are processed, all other VM configuration
641       options like --name, --disk, etc. are completely ignored.
642
643       If --reinstall is used with --cdrom, an existing CDROM attached to  the
644       VM will be used if one is available, otherwise a permanent CDROM device
645       will be added.
646
647   --unattended
648       Syntax: --unattended [OPTIONS]
649
650       Perform an unattended install using libosinfo's install script support.
651       This is essentially a database of auto install scripts for various dis‐
652       tros: Red Hat kickstarts, Debian  installer  scripting,  Windows  unat‐
653       tended  installs, and potentially others. The simplest invocation is to
654       combine it with --install like:
655
656          --install fedora29 --unattended
657
658       A Windows install will look like
659
660          --cdrom /path/to/my/windows.iso --unattended
661
662       Sub options are:
663
664       profile=
665              Choose which libosinfo unattended profile to use.  Most  distros
666              have a 'desktop' and a 'jeos' profile. virt-install will default
667              to 'desktop' if this is unspecified.
668
669       admin-password-file=
670              A file used to set the VM OS admin/root password from. This  op‐
671              tion  can  be used either as "admin-password-file=/path/to/pass‐
672              word-file" or as "admin-password-file=/dev/fd/n",  being  n  the
673              file  descriptor of the password-file.  Note that only the first
674              line of the file will be considered,  including  any  whitespace
675              characters and excluding new-line.
676
677       user-login=
678              The  user  login name to be used in th VM. virt-install will de‐
679              fault to your current host  username  if  this  is  unspecified.
680              Note  that when running virt-install as "root", this option must
681              be specified.
682
683       user-password-file=
684              A file used to set the VM user password. This option can be used
685              either   as  "user-password-file=/path/to/password-file"  or  as
686              "user-password-file=/dev/fd/n", being n the file  descriptor  of
687              the  password-file. The username is either the user-login speci‐
688              fied or your current host username.  Note that  only  the  first
689              line  of  the  file will be considered, including any whitespace
690              characters and excluding new-line.
691
692       product-key=
693              Set a Windows product key
694
695   --cloud-init
696       Pass cloud-init metadata to the VM. A cloud-init NoCloud  ISO  file  is
697       generated, and attached to the VM as a CDROM device. The device is only
698       attached for the first boot. This option  is  particularly  useful  for
699       distro  cloud  images,  which  have  locked  login accounts by default;
700       --cloud-init provides the means to  initialize  those  login  accounts,
701       like setting a root password.
702
703       The  simplest invocation is just plain --cloud-init with no suboptions;
704       this maps  to  --cloud-init  root-password-generate=on,disable=on.  See
705       those suboptions for explanation of how they work.
706
707       Use --cloud-init=? to see a list of all available sub options.
708
709       Sub options are:
710
711       root-password-generate=on
712              Generate a new root password for the VM. When used, virt-install
713              will print the generated password to the console, and pause  for
714              10 seconds to give the user a chance to notice it and copy it.
715
716       disable=on
717              Disable cloud-init in the VM for subsequent boots. Without this,
718              cloud-init may reset auth on each boot.
719
720       root-password-file=
721              A file used to set the VM root password from. This option can be
722              used either as "root-password-file=/path/to/password-file" or as
723              "root-password-file=/dev/fd/n", being n the file  descriptor  of
724              the  password-file.   Note  that only the first line of the file
725              will be considered, including any whitespace characters and  ex‐
726              cluding new-line.
727
728       meta-data=
729              Specify  a cloud-init meta-data file to add directly to the iso.
730              All other meta-data configuration options  on  the  --cloud-init
731              command line are ignored.
732
733       user-data=
734              Specify  a cloud-init user-data file to add directly to the iso.
735              All other user-data configuration options  on  the  --cloud-init
736              command line are ignored.
737
738       root-ssh-key=
739              Specify a public key to inject into the guest, providing ssh ac‐
740              cess       to       the       root       account.       Example:
741              root-ssh-key=/home/user/.ssh/id_rsa.pub
742
743       clouduser-ssh-key
744              Specify a public key to inject into the guest, providing ssh ac‐
745              cess to the default cloud-init user account. The account name is
746              different  per  distro  cloud  image. Some common ones are docu‐
747              mented                                                     here:
748              https://docs.openstack.org/image-guide/obtain-images.html
749
750       network-config=
751              Specify  a cloud-init network-config file to add directly to the
752              iso.
753
754   --boot
755       Syntax: --boot BOOTOPTS
756
757       Optionally specify the post-install VM boot configuration. This  option
758       allows  specifying  a  boot  device order, permanently booting off ker‐
759       nel/initrd with option kernel arguments, and enabling a BIOS boot  menu
760       (requires libvirt 0.8.3 or later)
761
762       --boot  can  be specified in addition to other install options (such as
763       --location, --cdrom, etc.) or can be specified on its own. In the  lat‐
764       ter  case, behavior is similar to the --import install option: there is
765       no 'install' phase, the guest is just created and  launched  as  speci‐
766       fied.
767
768       Some examples:
769
770       --boot cdrom,fd,hd,network
771              Set the boot device priority as first cdrom, first floppy, first
772              harddisk, network PXE boot.
773
774       --boot kernel=KERNEL,initrd=INITRD,kernel_args="console=/dev/ttyS0"
775              Have guest permanently boot off a local kernel/initrd pair, with
776              the specified kernel options.
777
778       --boot kernel=KERNEL,initrd=INITRD,dtb=DTB
779              Have  guest permanently boot off a local kernel/initrd pair with
780              an external device tree binary. DTB can  be  required  for  some
781              non-x86 configurations like ARM or PPC
782
783       --boot loader=BIOSPATH
784              Use BIOSPATH as the virtual machine BIOS.
785
786       --boot bootmenu.enable=on,bios.useserial=on
787              Enable  the  bios boot menu, and enable sending bios text output
788              over serial console.
789
790       --boot init=INITPATH
791              Path to a binary that the container guest will init. If  a  root
792              --filesystem  has  been  specified, virt-install will default to
793              /sbin/init, otherwise will default to /bin/sh.
794
795       --boot uefi
796              Configure the VM to boot from UEFI. In order for virt-install to
797              know  the correct UEFI parameters, libvirt needs to be advertis‐
798              ing known UEFI binaries via domcapabilities XML,  so  this  will
799              likely only work if using properly configured distro packages.
800
801       --boot                            loader=/.../OVMF_CODE.fd,loader.read‐
802       only=yes,loader.type=pflash,nvram.template=/.../OVMF_VARS.fd,loader_se‐
803       cure=no
804              Specify  that  the virtual machine use the custom OVMF binary as
805              boot firmware, mapped as a virtual flash chip. In addition,  re‐
806              quest  that  libvirt  instantiate  the VM-specific UEFI varstore
807              from the custom "/.../OVMF_VARS.fd" varstore template.  This  is
808              the  recommended  UEFI  setup, and should be used if --boot uefi
809              doesn't know about your UEFI binaries.  If  your  UEFI  firmware
810              supports  Secure  boot  feature you can enable it via loader_se‐
811              cure.
812
813       Use --boot=? to see a list of all available sub options.  Complete  de‐
814       tails at https://libvirt.org/formatdomain.html#elementsOS
815
816   --idmap
817       Syntax: --idmap OPTIONS
818
819       If  the  guest  configuration declares a UID or GID mapping, the 'user'
820       namespace will be  enabled  to  apply  these.   A  suitably  configured
821       UID/GID  mapping  is  a pre-requisite to make containers secure, in the
822       absence of sVirt confinement.
823
824       --idmap can be specified to enable user namespace for  LXC  containers.
825       Example:
826
827          --idmap uid.start=0,uid.target=1000,uid.count=10,gid.start=0,gid.target=1000,gid.count=10
828
829       Use --idmap=? to see a list of all available sub options.  Complete de‐
830       tails at https://libvirt.org/formatdomain.html#elementsOSContainer
831

GUEST OS OPTIONS

833   --os-variant, --osinfo
834       Syntax: --osinfo [OSNAME|OPT1=VAL1,...]
835
836       Optimize the guest configuration for a specific operating system.   For
837       most  cases, an OS must be specified or detected from the install media
838       so performance critical features like virtio can be enabled.
839
840       The simplest usage is --os-variant OSNAME or --osinfo OSNAME, for exam‐
841       ple --osinfo fedora32. The supported suboptions are:
842
843       name=, short-id=
844              The OS name/short-id from libosinfo. Examples: fedora32, win10
845
846       id=    The  full URL style libosinfo ID. For example, name=win10 is the
847              same as id=http://microsoft.com/win/10
848
849       detect=on|off
850              Whether virt-install should attempt OS detection from the speci‐
851              fied  install  media.  Detection is presently only attempted for
852              URL and CDROM installs, and is not 100% reliable.
853
854       require=on|off
855              If on, virt-install errors if no OS value is set or detected.
856
857       Some interesting examples:
858
859       --osinfo detect=on,require=on
860              This tells virt-install to attempt detection from install media,
861              but  explicitly  fail if that does not succeed. This will ensure
862              your virt-install invocations don't fallback to  a  poorly  per‐
863              forming config
864
865       --osinfo detect=on,name=OSNAME
866              Attempt  OS detection from install media, but if that fails, use
867              OSNAME as a fallback.
868
869       If any manual --osinfo value is specified, the  default  is  all  other
870       settings off or unset.
871
872       By default, virt-install will always attempt --osinfo detect=on for ap‐
873       propriate install media. If no OS is detected, we  will  fail  in  most
874       common  cases.  This fatal error was added in 2022. You can work around
875       this by using the fallback example above, or disabling the require  op‐
876       tion.  If you just need to get back to the old non-fatal behavior ASAP,
877       set the environment variable VIRTINSTALL_OSINFO_DISABLE_REQUIRE=1.
878
879       Use the command virt-install --osinfo list to get the list of  the  ac‐
880       cepted OS variants. See osinfo-query os for even more output.
881
882       Note:  --os-variant and --osinfo are aliases for one another.  --osinfo
883       is the preferred new style naming.
884

STORAGE OPTIONS

886   --disk
887       Syntax: --disk OPTIONS
888
889       Specifies media to use as storage for the guest, with various  options.
890       The general format of a disk string is
891
892          --disk opt1=val1,opt2=val2,...
893
894       The  simplest  invocation to create a new 10G disk image and associated
895       disk device:
896
897          --disk size=10
898
899       virt-install will generate a path name, and place it in the default im‐
900       age  location for the hypervisor. To specify media, the command can ei‐
901       ther be:
902
903          --disk /some/storage/path[,opt1=val1]...
904
905       or explicitly specify one of the following arguments:
906
907       path   A path to some storage media to use, existing or  not.  Existing
908              media can be a file or block device.
909
910              Specifying  a non-existent path implies attempting to create the
911              new storage, and will require specifying a  'size'  value.  Even
912              for  remote  hosts, virt-install will try to use libvirt storage
913              APIs to automatically create the given path.
914
915              If the hypervisor supports it, path can also be a  network  URL,
916              like https://example.com/some-disk.img . For network paths, they
917              hypervisor will directly access the storage,  nothing  is  down‐
918              loaded locally.
919
920       pool   An  existing libvirt storage pool name to create new storage on.
921              Requires specifying a 'size' value.
922
923       vol    An existing libvirt storage volume to use. This is specified  as
924              'poolname/volname'.
925
926       Options that apply to storage creation:
927
928       size   size (in GiB) to use if creating new storage
929
930       sparse whether to skip fully allocating newly created storage. Value is
931              'yes' or 'no'. Default is 'yes' (do not fully  allocate)  unless
932              it isn't supported by the underlying storage type.
933
934              The  initial time taken to fully-allocate the guest virtual disk
935              (sparse=no) will be usually balanced by faster install times in‐
936              side the guest. Thus use of this option is recommended to ensure
937              consistently high performance and to avoid  I/O  errors  in  the
938              guest should the host filesystem fill up.
939
940       format Disk image format. For file volumes, this can be 'raw', 'qcow2',
941              'vmdk',       etc.        See       format       types        in
942              https://libvirt.org/storage.html  for  possible values.  This is
943              often mapped to the driver_type value as well.
944
945              If not specified when creating file images, this will default to
946              'qcow2'.
947
948              If  creating  storage, this will be the format of the new image.
949              If using an existing  image,  this  overrides  libvirt's  format
950              auto-detection.
951
952       backing_store
953              Path to a disk to use as the backing store for the newly created
954              image.
955
956       backing_format
957              Disk image format of backing_store
958
959       Some example device configuration suboptions:
960
961       device Disk device type. Example values are be 'cdrom',  'disk',  'lun'
962              or 'floppy'.  The default is 'disk'.
963
964       boot.order
965              Guest  installation with multiple disks will need this parameter
966              to boot correctly after being installed. A boot.order  parameter
967              will  take values 1,2,3,...  Devices with lower value has higher
968              priority.  This option applies to other bootable device types as
969              well.
970
971       target.bus** or *bus
972              Disk  bus  type.  Example  values  are be 'ide', 'sata', 'scsi',
973              'usb', 'virtio' or 'xen'.  The default is  hypervisor  dependent
974              since not all hypervisors support all bus types.
975
976       readonly
977              Set drive as readonly (takes 'on' or 'off')
978
979       shareable
980              Set drive as shareable (takes 'on' or 'off')
981
982       cache  The  cache  mode  to  be used. The host pagecache provides cache
983              memory.  The cache value can be 'none', 'writethrough', 'direct‐
984              sync',  'unsafe'  or  'writeback'.  'writethrough' provides read
985              caching. 'writeback' provides read and write  caching.  'direct‐
986              sync'  bypasses the host page cache. 'unsafe' may cache all con‐
987              tent and ignore flush requests from the guest.
988
989       driver.discard
990              Whether discard (also known as "trim" or "unmap")  requests  are
991              ignored  or  passed  to  the filesystem. The value can be either
992              "unmap" (allow the discard request to  be  passed)  or  "ignore"
993              (ignore the discard request). Since 1.0.6 (QEMU and KVM only)
994
995       driver.name
996              Driver  name the hypervisor should use when accessing the speci‐
997              fied storage. Typically does not need to be set by the user.
998
999       driver.type
1000              Driver format/type the hypervisor should use when accessing  the
1001              specified  storage.  Typically  does  not  need to be set by the
1002              user.
1003
1004       driver.io
1005              Disk IO backend. Can be either "threads",  "native"  or  "io_ur‐
1006              ing".
1007
1008       driver.error_policy
1009              How  guest  should react if a write error is encountered. Can be
1010              one of "stop", "ignore", or "enospace"
1011
1012       serial Serial number of the emulated disk device. This is used in linux
1013              guests to set /dev/disk/by-id symlinks. An example serial number
1014              might be: WD-WMAP9A966149
1015
1016       source.startupPolicy
1017              It defines what to do with the disk if the source  file  is  not
1018              accessible.
1019
1020       snapshot
1021              Defines default behavior of the disk during disk snapshots.
1022
1023       See  the  examples  section  for  some  uses.  This  option  deprecates
1024       -f/--file, -s/--file-size, --nonsparse, and --nodisks.
1025
1026       Use --disk=? to see a list of all available sub options.  Complete  de‐
1027       tails at https://libvirt.org/formatdomain.html#elementsDisks
1028
1029   --filesystem
1030       Specifies a directory on the host to export to the guest. The most sim‐
1031       ple invocation is:
1032
1033          --filesystem /source/on/host,/target/point/in/guest
1034
1035       Which will work for recent QEMU and linux guest OS or  LXC  containers.
1036       For  QEMU,  the  target point is just a mounting hint in sysfs, so will
1037       not be automatically mounted.
1038
1039       Some example suboptions:
1040
1041       type   The type or the source directory. Valid values are 'mount'  (the
1042              default) or 'template' for OpenVZ templates.
1043
1044       accessmode or mode
1045              The access mode for the source directory from the guest OS. Only
1046              used with QEMU and type=mount. Valid modes are 'mapped' (the de‐
1047              fault), 'passthrough', or 'squash'. See libvirt domain XML docu‐
1048              mentation for more info.
1049
1050       source The directory on the host to share.
1051
1052       target The mount location to use in the guest.
1053
1054       Use --filesystem=? to see a list of all available  sub  options.   Com‐
1055       plete                             details                            at
1056       https://libvirt.org/formatdomain.html#elementsFilesystems
1057

NETWORKING OPTIONS

1059   -w, --network
1060       Syntax: -w, --network OPTIONS
1061
1062       Connect the guest to the host network. Examples for specifying the net‐
1063       work type:
1064
1065       bridge=BRIDGE
1066              Connect  to  a bridge device in the host called BRIDGE. Use this
1067              option if the host has static networking config & the guest  re‐
1068              quires  full  outbound and inbound connectivity to/from the LAN.
1069              Also use this if live migration will be used with this guest.
1070
1071       network=NAME
1072              Connect to a virtual network in the host  called  NAME.  Virtual
1073              networks can be listed, created, deleted using the virsh command
1074              line tool. In an unmodified install of libvirt there is  usually
1075              a  virtual network with a name of default. Use a virtual network
1076              if the host has dynamic networking (e.g. NetworkManager), or us‐
1077              ing  wireless.  The  guest will be NATed to the LAN by whichever
1078              connection is active.
1079
1080       type=direct,source=IFACE[,source.mode=MODE]
1081              Direct connect to host interface IFACE using macvtap.
1082
1083       user   Connect to the LAN using SLIRP. Only use this if running a  QEMU
1084              guest as an unprivileged user. This provides a very limited form
1085              of NAT.
1086
1087       none   Tell virt-install not to add any default network interface.
1088
1089       If --network is omitted a single NIC will be created in the  guest.  If
1090       there  is  a  bridge  device  in the host with a physical interface at‐
1091       tached, that will be used for connectivity. Failing that,  the  virtual
1092       network  called default will be used. This option can be specified mul‐
1093       tiple times to setup more than one NIC.
1094
1095       Some example suboptions:
1096
1097       model.type or model
1098              Network device model as seen by the guest. Value can be any  nic
1099              model  supported  by  the  hypervisor, e.g.: 'e1000', 'rtl8139',
1100              'virtio', ...
1101
1102       mac.address or mac
1103              Fixed MAC address for the guest; If this parameter  is  omitted,
1104              or the value RANDOM is specified a suitable address will be ran‐
1105              domly generated. For Xen virtual machines it  is  required  that
1106              the first 3 pairs in the MAC address be the sequence '00:16:3e',
1107              while for QEMU or KVM virtual machines it must be '52:54:00'.
1108
1109       filterref.filter
1110              Controlling firewall and network filtering in libvirt. Value can
1111              be  any  nwfilter  defined  by the virsh 'nwfilter' subcommands.
1112              Available  filters  can  be  listed  by  running  'virsh  nwfil‐
1113              ter-list', e.g.: 'clean-traffic', 'no-mac-spoofing', ...
1114
1115       virtualport.* options
1116              Configure  the  device  virtual  port  profile. This is used for
1117              802.Qbg, 802.Qbh, midonet, and openvswitch config.
1118
1119              Use --network=? to see a list  of  all  available  sub  options.
1120              Complete                        details                       at
1121              https://libvirt.org/formatdomain.html#elementsNICS
1122
1123              This option deprecates -m/--mac, -b/--bridge, and --nonetworks
1124

GRAPHICS OPTIONS

1126       If no graphics option is specified, virt-install will try to select the
1127       appropriate graphics if the DISPLAY environment variable is set, other‐
1128       wise '--graphics none' is used.
1129
1130   --graphics
1131       Syntax: --graphics TYPE,opt1=arg1,opt2=arg2,...
1132
1133       Specifies the graphical display configuration. This does not  configure
1134       any virtual hardware, just how the guest's graphical display can be ac‐
1135       cessed.  Typically the user does  not  need  to  specify  this  option,
1136       virt-install  will  try and choose a useful default, and launch a suit‐
1137       able connection.
1138
1139       General format of a graphical string is
1140
1141          --graphics TYPE,opt1=arg1,opt2=arg2,...
1142
1143       For example:
1144
1145          --graphics vnc,password=foobar
1146
1147       Some supported TYPE values:
1148
1149       vnc    Setup a virtual console in the guest and  export  it  as  a  VNC
1150              server  in the host. Unless the port parameter is also provided,
1151              the VNC server will run on the first free port number at 5900 or
1152              above.  The  actual  VNC display allocated can be obtained using
1153              the vncdisplay command to virsh (or virt-viewer(1) can  be  used
1154              which handles this detail for the use).
1155
1156       spice  Export  the  guest's console using the Spice protocol. Spice al‐
1157              lows advanced features like audio and USB device  streaming,  as
1158              well as improved graphical performance.
1159
1160              Using  spice  graphic  type will work as if those arguments were
1161              given:
1162
1163                 --video qxl --channel spicevmc
1164
1165       none   No graphical console will be allocated  for  the  guest.  Guests
1166              will  likely need to have a text console configured on the first
1167              serial port in the guest (this can be done via the  --extra-args
1168              option). The command 'virsh console NAME' can be used to connect
1169              to the serial device.
1170
1171       Some supported suboptions:
1172
1173       port   Request a permanent, statically assigned  port  number  for  the
1174              guest console. This is used by 'vnc' and 'spice'
1175
1176       tlsPort
1177              Specify the spice tlsport.
1178
1179       websocket
1180              Request a VNC WebSocket port for the guest console.
1181
1182              If -1 is specified, the WebSocket port is auto-allocated.
1183
1184              This is used by 'vnc' and 'spice'
1185
1186       listen Address to listen on for VNC/Spice connections. Default is typi‐
1187              cally 127.0.0.1 (localhost only),  but  some  hypervisors  allow
1188              changing this globally (for example, the qemu driver default can
1189              be changed in /etc/libvirt/qemu.conf).  Use 0.0.0.0 to allow ac‐
1190              cess from other machines.
1191
1192              Use  'none' to specify that the display server should not listen
1193              on any port. The display server can  be  accessed  only  locally
1194              through  libvirt  unix socket (virt-viewer with --attach for in‐
1195              stance).
1196
1197              Use 'socket' to have the VM listen on a libvirt  generated  unix
1198              socket path on the host filesystem.
1199
1200              This is used by 'vnc' and 'spice'
1201
1202       password
1203              Request a console password, required at connection time. Beware,
1204              this info may end up in virt-install log files, so don't use  an
1205              important password. This is used by 'vnc' and 'spice'
1206
1207       gl.enable
1208              Whether  to  use OpenGL accelerated rendering. Value is 'yes' or
1209              'no'. This is used by 'spice'.
1210
1211       gl.rendernode
1212              DRM render node path to use. This is used when 'gl' is enabled.
1213
1214       Use --graphics=? to see a list of all available sub options.   Complete
1215       details at https://libvirt.org/formatdomain.html#elementsGraphics
1216
1217       This  deprecates  the following options: --vnc, --vncport, --vnclisten,
1218       -k/--keymap, --sdl, --nographics
1219
1220   --autoconsole
1221       Syntax: --autoconsole OPTIONS
1222
1223       Configure what interactive console virt-install will launch for the VM.
1224       This  option  is not required; the default behavior is adaptive and de‐
1225       pendent on how the VM is configured. But you can  use  this  option  to
1226       override the default choice.
1227
1228       --autoconsole graphical
1229              Use the graphical virt-viewer(1) as the interactive console
1230
1231       --autoconsole text
1232              Use the text mode virsh console as the interactive console.
1233
1234       --autoconsole none
1235              This is the same as --noautoconsole
1236
1237       --noautoconsole
1238              Don't automatically try to connect to the guest console. Same as
1239              --autoconsole none
1240
1241       Note, virt-install exits quickly when this option is specified. If your
1242       command  requested a multistep install, like --cdrom or --location, af‐
1243       ter the install phase is complete the VM will be shutoff, regardless of
1244       whether  a reboot was requested in the VM. If you want the VM to be re‐
1245       booted, virt-install must remain running. You can use '--wait' to  keep
1246       virt-install alive even if --noautoconsole is specified.
1247

VIRTUALIZATION OPTIONS

1249       Options to override the default virtualization type choices.
1250
1251   -v, --hvm
1252       Request the use of full virtualization, if both para & full virtualiza‐
1253       tion are available on the host. This parameter may not be available  if
1254       connecting  to  a Xen hypervisor on a machine without hardware virtual‐
1255       ization support. This parameter is implied  if  connecting  to  a  QEMU
1256       based hypervisor.
1257
1258   -p, --paravirt
1259       This guest should be a paravirtualized guest. If the host supports both
1260       para & full virtualization, and neither this parameter  nor  the  --hvm
1261       are specified, this will be assumed.
1262
1263   --container
1264       This  guest  should  be a container type guest. This option is only re‐
1265       quired if the hypervisor supports other guest types as well (so for ex‐
1266       ample  this  option  is the default behavior for LXC and OpenVZ, but is
1267       provided for completeness).
1268
1269   --virt-type
1270       The hypervisor to install on. Example choices are kvm,  qemu,  or  xen.
1271       Available  options  are listed via 'virsh capabilities' in the <domain>
1272       tags.
1273
1274       This deprecates the --accelerate option, which is now the  default  be‐
1275       havior.  To install a plain QEMU guest, use '--virt-type qemu'
1276

DEVICE OPTIONS

1278       All devices have a set of address.* options for configuring the partic‐
1279       ulars of the device's address on its parent  controller  or  bus.   See
1280       https://libvirt.org/formatdomain.html#elementsAddress for details.
1281
1282   --controller
1283       Syntax: --controller OPTIONS
1284
1285       Attach a controller device to the guest.
1286
1287       Some example invocations:
1288
1289       --controller usb2
1290              Add a full USB2 controller setup
1291
1292       --controller usb3
1293              Add a USB3 controller
1294
1295       --controller type=usb,model=none
1296              Disable USB entirely
1297
1298       --controller type=scsi,model=virtio-scsi
1299              Add a VirtIO SCSI controller
1300
1301       --controller num_pcie_root_ports=NUM
1302              Control  the number of default pcie-root-port controller devices
1303              we add to the new VM by default, if the VM will use PCIe by  de‐
1304              fault.
1305
1306       Use  --controller=?  to  see a list of all available sub options.  Com‐
1307       plete                            details                             at
1308       https://libvirt.org/formatdomain.html#elementsControllers
1309
1310   --input
1311       Syntax: --input OPTIONS
1312
1313       Attach  an  input  device  to the guest. Example input device types are
1314       mouse, tablet, or keyboard.
1315
1316       Use --input=? to see a list of all available sub options.  Complete de‐
1317       tails at https://libvirt.org/formatdomain.html#elementsInput
1318
1319   --hostdev, --host-device
1320       Syntax: --hostdev, --host-device OPTIONS
1321
1322       Attach  a  physical  host  device to the guest. Some example values for
1323       HOSTDEV:
1324
1325       --hostdev pci_0000_00_1b_0
1326              A node device name via libvirt, as shown by 'virsh nodedev-list'
1327
1328       --hostdev 001.003
1329              USB by bus, device (via lsusb).
1330
1331       --hostdev 0x1234:0x5678
1332              USB by vendor, product (via lsusb).
1333
1334       --hostdev 1f.01.02
1335              PCI device (via lspci).
1336
1337       --hostdev wlan0,type=net
1338              Network device (in LXC container).
1339
1340       --hostdev /dev/net/tun,type=misc
1341              Character device (in LXC container).
1342
1343       --hostdev /dev/sdf,type=storage
1344              Block device (in LXC container).
1345
1346       Use --hostdev=? to see a list of all available sub  options.   Complete
1347       details at https://libvirt.org/formatdomain.html#elementsHostDev
1348
1349   --sound
1350       Syntax: --sound MODEL
1351
1352       Attach  a  virtual  audio device to the guest. MODEL specifies the emu‐
1353       lated sound card model. Possible values are ich6, ich9,  ac97,  es1370,
1354       sb16, pcspk, or default. 'default' will try to pick the best model that
1355       the specified OS supports.
1356
1357       This deprecates the old --soundhw option.  Use --sound=? to see a  list
1358       of    all    available    sub    options.     Complete    details    at
1359       https://libvirt.org/formatdomain.html#elementsSound
1360
1361   --audio
1362       Configure host audio output for the guest's --sound hardware.
1363
1364       Use --audio=? to see a list of all available sub options.  Complete de‐
1365       tails at https://libvirt.org/formatdomain.html#audio-backends
1366
1367   --watchdog
1368       Syntax: --watchdog MODEL[,action=ACTION]
1369
1370       Attach a virtual hardware watchdog device to the guest. This requires a
1371       daemon and device driver in the guest. The watchdog fires a signal when
1372       the virtual machine appears to hung. ACTION specifies what libvirt will
1373       do when the watchdog fires. Values are
1374
1375       reset  Forcefully reset the guest (the default)
1376
1377       poweroff
1378              Forcefully power off the guest
1379
1380       pause  Pause the guest
1381
1382       none   Do nothing
1383
1384       shutdown
1385              Gracefully shutdown the guest (not  recommended,  since  a  hung
1386              guest probably won't respond to a graceful shutdown)
1387
1388       MODEL  is  the  emulated device model: either i6300esb (the default) or
1389       ib700.  Some examples:
1390
1391       --watchdog default
1392              Use the recommended settings
1393
1394       --watchdog i6300esb,action=poweroff
1395              Use the i6300esb with the 'poweroff' action
1396
1397       Use --watchdog=? to see a list of all available sub options.   Complete
1398       details at https://libvirt.org/formatdomain.html#elementsWatchdog
1399
1400   --serial
1401       Syntax: --serial OPTIONS
1402
1403       Specifies a serial device to attach to the guest, with various options.
1404       The general format of a serial string is
1405
1406          --serial type,opt1=val1,opt2=val2,...
1407
1408       --serial and --parallel devices share all the same options, unless oth‐
1409       erwise noted. Some of the types of character device redirection are:
1410
1411       --serial pty
1412              Pseudo  TTY.  The  allocated  pty  will be listed in the running
1413              guests XML description.
1414
1415       --serial dev,path=HOSTPATH
1416              Host device. For serial devices, this could be  /dev/ttyS0.  For
1417              parallel devices, this could be /dev/parport0.
1418
1419       --serial file,path=FILENAME
1420              Write output to FILENAME.
1421
1422       --serial tcp,host=HOST:PORT,source.mode=MODE,protocol.type=PROTOCOL
1423              TCP  net console. MODE is either 'bind' (wait for connections on
1424              HOST:PORT) or 'connect' (send output to HOST:PORT),  default  is
1425              'bind'. HOST defaults to '127.0.0.1', but PORT is required. PRO‐
1426              TOCOL can be either 'raw' or 'telnet' (default 'raw'). If  'tel‐
1427              net',  the port acts like a telnet server or client.  Some exam‐
1428              ples:
1429
1430              Wait for connections on any address, port 4567:
1431
1432              --serial tcp,host=0.0.0.0:4567
1433
1434              Connect to localhost, port 1234:
1435
1436              --serial tcp,host=:1234,source.mode=connect
1437
1438              Wait for telnet connection on localhost,  port  2222.  The  user
1439              could then connect interactively to this console via 'telnet lo‐
1440              calhost 2222':
1441
1442              --serial tcp,host=:2222,source.mode=bind,source.protocol=telnet
1443
1444       --serial udp,host=CONNECT_HOST:PORT,bind_host=BIND_HOST:BIND_PORT
1445              UDP net console. HOST:PORT is the destination to send output  to
1446              (default    HOST    is    '127.0.0.1',    PORT   is   required).
1447              BIND_HOST:BIND_PORT is the optional local  address  to  bind  to
1448              (default BIND_HOST is 127.0.0.1, but is only set if BIND_PORT is
1449              specified). Some examples:
1450
1451              Send output to default syslog port (may need to edit  /etc/rsys‐
1452              log.conf accordingly):
1453
1454              --serial udp,host=:514
1455
1456              Send output to remote host 192.168.10.20, port 4444 (this output
1457              can be read on the remote host using 'nc -u -l 4444'):
1458
1459              --serial udp,host=192.168.10.20:4444
1460
1461       --serial unix,path=UNIXPATH,mode=MODE
1462              Unix socket, see unix(7). MODE has similar behavior and defaults
1463              as --serial tcp,mode=MODE
1464
1465       Use  --serial=?  to  see a list of all available sub options.  Complete
1466       details at https://libvirt.org/formatdomain.html#elementsCharSerial
1467
1468   --parallel
1469       Syntax: --parallel OPTIONS
1470
1471       Specify a parallel device. The format and options are largely identical
1472       to serial
1473
1474       Use  --parallel=? to see a list of all available sub options.  Complete
1475       details at https://libvirt.org/formatdomain.html#elementsCharParallel
1476
1477   --channel
1478       Specifies a communication channel device to connect the guest and  host
1479       machine.  This  option uses the same options as --serial and --parallel
1480       for specifying the host/source end of the channel. Extra  'target'  op‐
1481       tions are used to specify how the guest machine sees the channel.
1482
1483       Some of the types of character device redirection are:
1484
1485       --channel SOURCE,target.type=guestfwd,target.address=HOST:PORT
1486              Communication  channel using QEMU usermode networking stack. The
1487              guest can connect to the channel using the  specified  HOST:PORT
1488              combination.
1489
1490       --channel SOURCE,target.type=virtio[,target.name=NAME]
1491              Communication  channel  using  virtio serial (requires 2.6.34 or
1492              later host and guest). Each instance of a virtio --channel  line
1493              is  exposed  in  the guest as /dev/vport0p1, /dev/vport0p2, etc.
1494              NAME is optional metadata,  and  can  be  any  string,  such  as
1495              org.linux-kvm.virtioport1.   If  specified, this will be exposed
1496              in the guest at /sys/class/virtio-ports/vport0p1/NAME
1497
1498       --channel spicevmc,target.type=virtio[,target.name=NAME]
1499              Communication channel for QEMU spice agent, using virtio  serial
1500              (requires  2.6.34  or  later  host  and guest). NAME is optional
1501              metadata, and can be any string, such as  the  default  com.red‐
1502              hat.spice.0 that specifies how the guest will see the channel.
1503
1504       --channel qemu-vdagent,target.type=virtio[,target.name=NAME]
1505              Communication  channel  for  QEMU  vd agent, using virtio serial
1506              (requires  2.6.34  or  later  host  and  guest).   This   allows
1507              copy/paste  functionality  with  VNC guests. Note that the guest
1508              clipboard integration is implemented  via  spice-vdagent,  which
1509              must be running even when the guest does not use spice graphics.
1510              NAME is optional metadata that specifies how the guest will  see
1511              the  channel,  and  should  be  left  as  the  default  com.red‐
1512              hat.spice.0 unless you know what you are doing.
1513
1514       Use --channel=? to see a list of all available sub  options.   Complete
1515       details at https://libvirt.org/formatdomain.html#elementsCharChannel
1516
1517   --console
1518       Connect  a  text  console between the guest and host. Certain guest and
1519       hypervisor combinations can automatically set up a getty in the  guest,
1520       so  an  out  of the box text login can be provided (target_type=xen for
1521       xen paravirt guests, and possibly target_type=virtio in the future).
1522
1523       Example:
1524
1525       --console pty,target.type=virtio
1526              Connect a virtio console to the guest, redirected to  a  PTY  on
1527              the  host.   For supported guests, this exposes /dev/hvc0 in the
1528              guest. See  https://fedoraproject.org/wiki/Features/VirtioSerial
1529              for more info. virtio console requires libvirt 0.8.3 or later.
1530
1531       Use  --console=?  to see a list of all available sub options.  Complete
1532       details at https://libvirt.org/formatdomain.html#elementsCharConsole
1533
1534   --video
1535       Syntax: --video OPTIONS
1536
1537       Specify what video device model will be attached to  the  guest.  Valid
1538       values  for  VIDEO are hypervisor specific, but some options for recent
1539       kvm are cirrus, vga, qxl, virtio, or vmvga (vmware).  Use --video=?  to
1540       see  a  list  of  all  available  sub  options.   Complete  details  at
1541       https://libvirt.org/formatdomain.html#elementsVideo
1542
1543   --smartcard
1544       Syntax: --smartcard MODE[,OPTIONS]
1545
1546       Configure a virtual smartcard device.
1547
1548       Example MODE values are host, host-certificates, or passthrough.  Exam‐
1549       ple suboptions include:
1550
1551       type   Character  device  type  to connect to on the host. This is only
1552              applicable for passthrough mode.
1553
1554       An example invocation:
1555
1556       --smartcard passthrough,type=spicevmc
1557              Use the smartcard channel of a SPICE  graphics  device  to  pass
1558              smartcard info to the guest
1559
1560       Use --smartcard=? to see a list of all available sub options.  Complete
1561       details at https://libvirt.org/formatdomain.html#elementsSmartcard
1562
1563   --redirdev
1564       Syntax: --redirdev BUS[,OPTIONS]
1565
1566       Add a redirected device. Example suboptions:
1567
1568       type   The redirection type, currently supported is tcp or spicevmc .
1569
1570       server The TCP server connection details, of the form 'server:port'.
1571
1572       Examples invocations:
1573
1574       --redirdev usb,type=tcp,server=localhost:4000
1575              Add a USB redirected device provided by the TCP server  on  'lo‐
1576              calhost' port 4000.
1577
1578       --redirdev usb,type=spicevmc
1579              Add a USB device redirected via a dedicated Spice channel.
1580
1581       Use  --redirdev=? to see a list of all available sub options.  Complete
1582       details at https://libvirt.org/formatdomain.html#elementsRedir
1583
1584   --memballoon
1585       Syntax: --memballoon MODEL[,OPTIONS]
1586
1587       Attach a virtual memory balloon device to the guest. If the  memballoon
1588       device needs to be explicitly disabled, MODEL='none' is used.
1589
1590       MODEL is the type of memballoon device provided. The value can be 'vir‐
1591       tio', 'xen' or 'none'. Some examples:
1592
1593       --memballoon virtio
1594              Explicitly create a 'virtio' memballoon device
1595
1596       --memballoon none
1597              Disable the memballoon device
1598
1599       Use --memballoon=? to see a list of all available  sub  options.   Com‐
1600       plete                             details                            at
1601       https://libvirt.org/formatdomain.html#elementsMemBalloon
1602
1603   --tpm
1604       Syntax: --tpm TYPE[,OPTIONS]
1605
1606       Configure a virtual TPM device. Examples:
1607
1608       --tpm /dev/tpm
1609              Convenience option for passing through the hosts TPM.
1610
1611       --tpm emulator
1612              Request an emulated TPM device.
1613
1614       --tpm default
1615              Request virt-install to fill in a modern recommended default
1616
1617       Use --tpm=? to see a list of all available sub options.   Complete  de‐
1618       tails at https://libvirt.org/formatdomain.html#elementsTpm
1619
1620   --rng
1621       Syntax: --rng TYPE[,OPTIONS]
1622
1623       Configure a virtual RNG device.
1624
1625       Example TYPE values include random, egd or builtin.
1626
1627       Example invocations:
1628
1629       --rng /dev/urandom
1630              Use  the  /dev/urandom device to get entropy data, this form im‐
1631              plicitly uses the "random" model.
1632
1633       --rng builtin
1634              Use the builtin rng device to get entropy data.
1635
1636       --rng             egd,backend.source.host=localhost,backend.source.ser‐
1637       vice=8000,backend.type=tcp
1638              Connect to localhost to the TCP port 8000 to get entropy data.
1639
1640       Use  --rng=?  to see a list of all available sub options.  Complete de‐
1641       tails at https://libvirt.org/formatdomain.html#elementsRng
1642
1643   --panic
1644       Syntax: --panic MODEL[,OPTS]
1645
1646       Attach a panic notifier device to the guest.  For the recommended  set‐
1647       tings, use: --panic default
1648
1649       Use --panic=? to see a list of all available sub options.  Complete de‐
1650       tails at https://libvirt.org/formatdomain.html#elementsPanic
1651
1652   --shmem
1653       Syntax: --shmem NAME[,OPTS]
1654
1655       Attach a shared memory device to the guest. The name must not contain /
1656       and must not be directory-specific to . or ..
1657
1658       Use --shmem=? to see a list of all available sub options.  Complete de‐
1659       tails at https://libvirt.org/formatdomain.html#shared-memory-device
1660
1661   --memdev
1662       Syntax: --memdev OPTS
1663
1664       Add a memory module to a guest which can  be  hotunplugged.  To  add  a
1665       memdev you need to configure hotplugmemory and NUMA for a guest.
1666
1667       Use  --memdev=?  to  see a list of all available sub options.  Complete
1668       details at https://libvirt.org/formatdomain.html#elementsMemory.
1669
1670   --vsock
1671       Syntax: --vsock OPTS
1672
1673       Configure a vsock host/guest interface. A typical  configuration  would
1674       be
1675
1676          --vsock cid.auto=yes
1677
1678       Use --vsock=? to see a list of all available sub options.  Complete de‐
1679       tails at https://libvirt.org/formatdomain.html#vsock.
1680
1681   --iommu
1682       Syntax: --iommu MODEL[,OPTS]
1683
1684       Add an IOMMU device to the guest.
1685
1686       Use --iommu=? to see a list of all available options.  Complete details
1687       at https://libvirt.org/formatdomain.html#elementsIommu.
1688

MISCELLANEOUS OPTIONS

1690   -h, --help
1691       Show the help message and exit
1692
1693   --version
1694       Show program's version number and exit
1695
1696   --autostart
1697       Set  the  autostart  flag  for  a  domain. This causes the domain to be
1698       started on host boot up.
1699
1700   --transient
1701       Use --import or --boot and --transient if you want a transient  libvirt
1702       VM.   These  VMs  exist  only until the domain is shut down or the host
1703       server is restarted.  Libvirt forgets the XML configuration of  the  VM
1704       after  either  of  these  events.  Note that the VM's disks will not be
1705       deleted.                                                           See:
1706       https://wiki.libvirt.org/page/VM_lifecycle#Transient_guest_domains_vs_Persistent_guest_domains
1707
1708   --destroy-on-exit
1709       When the VM console window is exited, destroy (force poweroff) the  VM.
1710       If  you combine this with --transient, this makes the virt-install com‐
1711       mand work similar to qemu, where the VM is shutdown  when  the  console
1712       window is closed by the user.
1713
1714   --print-xml
1715       Syntax: --print-xml [STEP]
1716
1717       Print  the  generated  XML of the guest, instead of defining it. By de‐
1718       fault this WILL do storage creation (can be disabled  with  --dry-run).
1719       This option implies --quiet.
1720
1721       If  the  VM install has multiple phases, by default this will print all
1722       generated XML. If you want to print a particular step, use  --print-xml
1723       2 (for the second phase XML).
1724
1725   --noreboot
1726       Prevent  the  domain from automatically rebooting after the install has
1727       completed.
1728
1729   --wait
1730       Syntax: --wait WAIT
1731
1732       Configure how virt-install will  wait  for  the  install  to  complete.
1733       Without  this  option,  virt-install will wait for the console to close
1734       (not necessarily indicating the guest has shutdown), or in the case  of
1735       --noautoconsole, simply kick off the install and exit.
1736
1737       Bare '--wait' or any negative value will make virt-install wait indefi‐
1738       nitely.  Any positive number is the number of minutes virt-install will
1739       wait. If the time limit is exceeded, virt-install simply exits, leaving
1740       the virtual machine in its current state.
1741
1742   --dry-run
1743       Proceed through the guest creation process, but do NOT  create  storage
1744       devices,  change  host  device configuration, or actually teach libvirt
1745       about the guest.  virt-install may still  fetch  install  media,  since
1746       this is required to properly detect the OS to install.
1747
1748   --check
1749       Enable  or  disable  some  validation checks. Some examples are warning
1750       about using a disk that's  already  assigned  to  another  VM  (--check
1751       path_in_use=on|off),  or warning about potentially running out of space
1752       during disk allocation (--check disk_size=on|off). Most checks are per‐
1753       formed by default.
1754
1755   -q, --quiet
1756       Only print fatal error messages.
1757
1758   -d, --debug
1759       Print  debugging  information  to the terminal when running the install
1760       process.    The   debugging   information    is    also    stored    in
1761       ~/.cache/virt-manager/virt-install.log  even if this parameter is omit‐
1762       ted.
1763

EXAMPLES

1765       The simplest invocation to interactively install a  Fedora  29  KVM  VM
1766       with  recommended  defaults. virt-viewer(1) will be launched to graphi‐
1767       cally interact with the VM install
1768
1769          # sudo virt-install --install fedora29
1770
1771       Similar, but use libosinfo's unattended  install  support,  which  will
1772       perform the fedora29 install automatically without user intervention:
1773
1774          # sudo virt-install --install fedora29 --unattended
1775
1776       Install  a  Windows  10 VM, using 40GiB storage in the default location
1777       and 4096MiB of ram, and ensure we are connecting to the system libvirtd
1778       instance:
1779
1780          # virt-install \
1781             --connect qemu:///system \
1782             --name my-win10-vm \
1783             --memory 4096 \
1784             --disk size=40 \
1785             --osinfo win10 \
1786             --cdrom /path/to/my/win10.iso
1787
1788       Install a CentOS 7 KVM from a URL, with recommended device defaults and
1789       default required storage, but specifically request VNC graphics instead
1790       of  the  default SPICE, and request 8 virtual CPUs and 8192 MiB of mem‐
1791       ory:
1792
1793          # virt-install \
1794              --connect qemu:///system \
1795              --memory 8192 \
1796              --vcpus 8 \
1797              --graphics vnc \
1798              --osinfo centos7.0 \
1799              --location http://mirror.centos.org/centos-7/7/os/x86_64/
1800
1801       Create a VM around an existing debian9 disk image:
1802
1803          # virt-install \
1804              --import \
1805              --memory 512 \
1806              --disk /home/user/VMs/my-debian9.img \
1807              --osinfo debian9
1808
1809       Start serial QEMU ARM VM, which requires specifying a manual kernel.
1810
1811          # virt-install \
1812              --name armtest \
1813              --memory 1024 \
1814              --arch armv7l --machine vexpress-a9 \
1815              --disk /home/user/VMs/myarmdisk.img \
1816              --boot kernel=/tmp/my-arm-kernel,initrd=/tmp/my-arm-initrd,dtb=/tmp/my-arm-dtb,kernel_args="console=ttyAMA0 rw root=/dev/mmcblk0p3" \
1817              --graphics none
1818
1819       Start an SEV launch security VM with 4GB RAM, 4GB+256MiB of hard_limit,
1820       with a couple of virtio devices:
1821
1822       Note: The IOMMU flag needs to be turned on with driver.iommu for virtio
1823       devices. Usage of --memtune is currently required because of SEV  limi‐
1824       tations, refer to libvirt docs for a detailed explanation.
1825
1826          # virt-install \
1827              --name foo \
1828              --memory 4096 \
1829              --boot uefi \
1830              --machine q35 \
1831              --memtune hard_limit=4563402 \
1832              --disk size=15,target.bus=scsi \
1833              --import \
1834              --controller type=scsi,model=virtio-scsi,driver.iommu=on \
1835              --controller type=virtio-serial,driver.iommu=on \
1836              --network network=default,model=virtio,driver.iommu=on \
1837              --rng /dev/random,driver.iommu=on \
1838              --memballoon driver.iommu=on \
1839              --launchSecurity sev
1840

BUGS

1842       Please see https://virt-manager.org/bugs
1843
1845       Copyright  (C)  Red  Hat,  Inc, and various contributors.  This is free
1846       software. You may redistribute copies of it under the terms of the  GNU
1847       General  Public License https://www.gnu.org/licenses/gpl.html. There is
1848       NO WARRANTY, to the extent permitted by law.
1849

SEE ALSO

1851       virsh(1),   virt-clone(1),   virt-manager(1),   the   project   website
1852       https://virt-manager.org
1853
1854
1855
1856
1857                                                               VIRT-INSTALL(1)
Impressum