Virt-install
External
Internal
Overview
virt-install is a command-line utility for provisioning new virtual machines. It comes as part of the "virt-install" RPM package.
virt-install needs root privileges to work.
The execution results in creation of a virtual machine XML definition, which can then be displayed with virsh dumpxml and edited with virsh edit, and in the initialization of the virtual machine image as the result of the interactive O/S installation procedure. The corresponding storage volume will be created in the associated storage pool, if the storage volume did not exist already.
Documentation
virt-install --help
Procedure
Prerequisites
If not already declared, create an "iso-images" directory-based storage pool and place the DVD ISO image there. The procedure is described here:
The command assumes that /main-storage-pool was created and it is active.
Virtual Machine Creation
virt-install --name <virtual-machine-name> --memory 1024 --vcpus 2 --os-variant=<os-variant> --location /iso-images/rhel-server-7.3-x86_64-dvd.iso --extra-args="console=tty0 console=ttyS0,115200n8" --disk=/iso-images/rhel-server-7.3-x86_64-dvd.iso,device=cdrom --disk=/main-storage-pool/testvm-01.img,size=5 --network default --graphics none
Results
The virtual machine will appear in virsh list:
The XML definition of the virtual machine will be accessible with virsh dumpxml and can be edited with virsh edit:
The virtual machine image file is created as /main-storage-pool/<vm-name>.img
The virtual machine image storage volume is automatically added to the main storage pool:
Name Path ------------------------------------------------------------------------------ <vm-name>.img /main-storage-pool/<vm-name>.img ...
Mandatory Options
Guest Virtual Machine Name
The name of the guest virtual machine must be specified with --name or -n:
--name test-01
For more details about a virtual machine name see:
Memory Amount
virt-install needs the amount of memory allocated to the guest, in MiB, which must be specified with --memory:
--memory 1024
Equivalent: --ram and -r.
The amount can be changed after the virtual machine is creating by editing the definition with virsh edit.
Guest Storage Specification
One of the following must be specified:
--disk
Specifies guest storage, relative to the storage provided by the virtualization host. The most common option is to refer storage from a storage pool, but other options are also available.
It is recommended to follow the virtual machine image name convention when naming the media to use for storing the virtual machine image.
--disk size=10
Specified a new 10 GiB image on the default storage pool.
--disk /storage-pool-path/volume-path,size=8,sparse=false,cache=none
--disk device=cdrom,bus=scsi
If ISO images are shared with the guests as "cdrom"s as shown below, the ISO images should be deployed into an active directory-based storage pool. If the image is not available in a storage pool, libvirt will automatically build a storage pool for it, and sometimes build multiple storage pools for the same image, which is something we want to avoid. If the storage pool exists, but the ISO image is not declared as a storage volume, virt-install will create the corresponding storage volume (e.g. /iso-images/rhel-server-7.3-x86_64-dvd.iso).
--disk=/iso-images/rhel-dvd.iso,device=cdrom
--nodisks
Installation Method Option
--os-variant
This is an important option, used to optimize guest configuration. Valid "--os-variant" values can be obtained with osinfo-query os command
Example:
--os-variant=rhel7.3
--os-type
The quest operating system type.
Example:
--os-type=linux
Note that man girt-install does not refer --os-type, it can probably be inferred from --os-variant.
Distribution Tree Installation Source
The distribution tree installation source is specified with --location. virt-install can fetch a bootable kernel/initrd pair from the source declared with --location to launch the install.
Options:
ISO File
--location /path/to/iso-file.iso
--location is followed by a path to an ISO file containing an installable distribution image. Note that the file should be readable by the "qemu" user. Also note that the file will not be accessible by the guest after initial boot, so the OS installer will need another way to access the rest of the install media. For an example of how to do that, see Text-Based Anaconda Guest Installation Example. An equivalent format, though less flexible as it does not accept --extra-args, uses --cdrom option:
--cdrom /path/to/iso-file.iso | URL-with-the-same-format-as-the-ones-used-for--location-argument
For an end-to-end example of how to create a guest VM from a CDROM image, see:
Directory
--location /directory
--location is followed by a path to a local directory containing an installable distribution image. Note that the directory will not be accessible by the guest after initial boot, so the OS installer will need another way to access the rest of the install media. For an example of how to do that, see Text-Based Anaconda Guest Installation Example.
HTTP Server
--location http://host/path
FTP Server
--location ftp://host/path
NFS Server
--location nfs:host:/path --location nfs://host/path
Optional Installation Method Option
--boot
--boot BOOT_OPTS is used to configure guest boot settings:
--boot hd,cdrom,menu=on
--boot init=/sbin/init
--pxe
Boot from the network using the PXE protocol.
--import
Build guest around an existing disk image.
--extra-args=
--extra-args EXTRA_ARGS Additional arguments to pass to the install kernel booted from --location.
Optional Configuration
Graphics
Specifies the type of graphical tool to use for interactive installation or can be set to "none" for a fully automated installation.
--graphics none|spice|...
Network Specification
The network specification is optional. If "--network" is not used, or if "--network default" is used, the guest will connect to the default network:
--network default
Otherwise, it can be specified with '--network NETWORK-SPEC', as follows:
TODO:
--network bridge=mybr0
TODO: If using a bridge, the bridge must be previously created, as described here Bridged Networking Configuration.
TODO:
--network network=my_libvirt_virtual_net
TODO:
--network network=mynet,model=virtio,mac=00:11..
TODO:
--network none
--vcpus
Specifies the number of virtual CPUs for the guest:
--vcpus 2
The amount can be changed after the virtual machine is creating by editing the definition with virsh edit.
Virtualization Platform Options
-v, --hvm
This guest should be a fully virtualized guest.
-p, --paravirt
This guest should be a paravirtualized guest.
--container
This guest should be a container guest.
--virt-type
Represents the hypervisor name to use ("kvm", "qemu", "xen", etc.)
Access to a Host Directory
"--filesystem" can be used to specify a host directory to be available on the guest.
Example:
--filesystem /my/host/source/dir,/dir/in/guest