Virt-install: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(29 intermediate revisions by the same user not shown)
Line 10: Line 10:
=Overview=
=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 on the virtualization host 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 [[Linux_Virtualization_Concepts#Virtual_Machine_Image|virtual machine image]] as the result of the interactive O/S installation procedure. The corresponding virtual machine root filesystem will be stored on an automatically created volume (/main-storage-pool/<guest-name>.qcow2). The volume will be created in the associated storage pool during the installation procedure, if the volume does not exist already. Additional block storage, in the form of different block devices available to the guest, can it be added later. The installation procedure may specify a minimal network configuration (DHCP and just host name), while the network can be further configured later.
<code>virt-install</code> 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 on the virtualization host to work.  
 
The execution results in creation of a virtual machine XML definition, which can then be displayed with <code>[[virsh dumpxml]]</code> and edited with <code>[[virsh edit]]</code>, and in the initialization of the [[Linux_Virtualization_Concepts#Virtual_Machine_Image|virtual machine image]] as the result of the interactive O/S installation procedure. Note that the underlying volume does not need to be created in advance. The corresponding virtual machine root filesystem will be stored on an automatically created volume (<code>/main-storage-pool/<guest-name>.qcow2</code>). The volume will be created in the associated storage pool during the installation procedure, if the volume does not exist already. Additional block storage, in the form of different block devices available to the guest, can it be added later. The installation procedure may specify a minimal network configuration (DHCP and just host name), while the network can be further configured later.


=Documentation=
=Documentation=
Line 24: Line 26:
Once the pool is created, the ISO image can be simply placed in there:
Once the pool is created, the ISO image can be simply placed in there:
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
cp .../CentOS-7-x86_64-DVD-7.9.2009.iso /iso-images
cp .../CentOS-7-x86_64-DVD-2009.iso /iso-images
chown qemu:qemu CentOS-7-x86_64-DVD-7.9.2009.iso
chown qemu:qemu CentOS-7-x86_64-DVD-2009.iso
</syntaxhighlight>
</syntaxhighlight>
While the file does is not exposed yet as a volume, 'virt-install' will expose it as a volume in the pool. Optionally, it can be exported as a pool volume in advance. The procedure to export the DVD ISO image as a pool volume is described here:{{Internal|KVM_Virtualization_Placing_an_ISO_Image_in_a_Directory-Based_Storage_Pool|Placing an ISO Image in a Directory-Based Storage Pool}}
While the file does is not exposed yet as a volume, <code>virt-install</code> will expose it as a volume in the pool. Optionally, it can be exported as a pool volume in advance. The procedure to export the DVD ISO image as a pool volume is described here:{{Internal|KVM_Virtualization_Placing_an_ISO_Image_in_a_Directory-Based_Storage_Pool|Placing an ISO Image in a Directory-Based Storage Pool}}


The command assumes that /main-storage-pool was created and it is active.
The command assumes that <code>main-storage-pool</code> was created and it is active.


{{Warn|Download "Red Hat Enterprise Linux 7.4 Binary DVD" and not the Boot ISO or KVM Guest image, otherwise the installation via virt-install will fail.}}
{{Warn|Download "Red Hat Enterprise Linux 7.4 Binary DVD" and not the Boot ISO or KVM Guest image, otherwise the installation via virt-install will fail.}}
Line 35: Line 37:
==Virtual Machine Creation==
==Virtual Machine Creation==


<font size=-2>
  virt-install  
  virt-install  
   [[#Guest_Virtual_Machine_Name|--name]] ''<virtual-machine-name>''
   [[#Guest_Virtual_Machine_Name|--name]] ''<virtual-machine-name>''
Line 46: Line 49:
   [[#Network_Specification|--network]] default
   [[#Network_Specification|--network]] default
   [[#Graphics|--graphics]] none
   [[#Graphics|--graphics]] none
</font>
===Notes===
* ⚠️ The size of the root partition determines how the RedHat/Centos installer will partition the space (create just a root partition "/" or a root "/" and a home "/home" partition. The cut-off is 50GB. For more details see [[Centos_7_Text_Installer#Root_Partition_Size|Centos 7 Text Installer &#124; Root_Partition_Size]].
* For <code>noper430</code> installations, these commands are usually saved as <code>/root/environments/single-hosts/<''host-name''>/<''host-name''>-virt-install.sh</code> and it is recommended to do so for any guest created on that virtualization host.
===Procedure===


Note: for noper430 installation, these commands are usually saved as /root/environments/single-hosts/<''host-name''>/<''host-name''>-virt-install.sh.
<font size=-2>
Starting install...
Retrieving file .treeinfo...
[...]
Welcome to CentOS Linux 7 (Core) dracut-033-572.el7 (Initramfs)!
[...]
</font>


===Interactive O/S Installation Procedure===
===Interactive O/S Installation Procedure===
Line 58: Line 74:


The virtual machine will appear in [[virsh list]]:
The virtual machine will appear in [[virsh list]]:
<syntaxhighlight lang='text'>
<font size=-2>
  Id    Name                          State
  Id    Name                          State
----------------------------------------------------
----------------------------------------------------
...
...
  9    nokb                          running
  9    gp                            running
</syntaxhighlight>
</font>


The XML definition of the virtual machine will be accessible with [[virsh dumpxml]] and can be edited with [[virsh edit]]:
The XML definition of the virtual machine will be accessible with <code>[[virsh dumpxml]]</code> and can be edited with <code>[[virsh edit]]</code>:


{{Internal|KVM Virtual Machine XML Defintion|KVM Virtual Machine XML Definition}}
{{Internal|KVM Virtual Machine XML Defintion|KVM Virtual Machine XML Definition}}


The virtual machine root filesystem is stored on an automatically created storage pool volume /main-storage-pool/<vm-name>.qcow2
The virtual machine root filesystem is stored on an automatically created storage pool volume <code>/main-storage-pool/<vm-name>.qcow2</code>.


The storage volume is automatically added to the main storage pool. Query with [[virsh vol-list]]:
The storage volume is automatically added to the main storage pool. Query with <code>[[virsh vol-list|virsh vol-list main-storage-pool --details]]</code>:


<syntaxhighlight lang='text'>
<font size=-2>
Name                Path
Name                Path
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
<vm-name>.qcow2      /main-storage-pool/<vm-name>.qcow2
<vm-name>.qcow2      /main-storage-pool/<vm-name>.qcow2
...
...
</syntaxhighlight>
</font>
 
There are two network interfaces: <code>lo</code> and <code>eth0</code>, configured by DHCP.


There are two network interfaces: lo and eth0, configured by DHCP.
There should be just a root partition (/) that occupies the entire block device.


Continue with [[#Post-Install|Post-Install]] below.
Continue with [[#Post-Install|Post-Install]] below.


=Post-Install=
==Post-Install==
 
===Remove the ISO Image from Guest Storage===
==Remove the ISO Image from Guest Storage==
 
If the ISO image remains mounted, it will not be usable by other guests, so it is a good idea to remove it. If left mounted, the attempt to create other guest will result in:
If the ISO image remains mounted, it will not be usable by other guests, so it is a good idea to remove it. If left mounted, the attempt to create other guest will result in:
<syntaxhighlight lang='bash'>
<syntaxhighlight lang='bash'>
Line 93: Line 109:
</syntaxhighlight>
</syntaxhighlight>
The procedure to remove it is available here: {{Internal|Linux_Virtualization_Remove_Storage_from_Guest|Remove Storage from Guest}}
The procedure to remove it is available here: {{Internal|Linux_Virtualization_Remove_Storage_from_Guest|Remove Storage from Guest}}
 
===Configure the Guest to Start at Boot===
==Configure the Guest to Start at Boot==
{{Internal|Virsh_autostart#Configure_to_Automatically_Start_at_Boot|Configure Guest to Automatically Start at Boot}}
{{Internal|Virsh_autostart#Configure_to_Automatically_Start_at_Boot|Configure Guest to Automatically Start at Boot}}
==Network Post-Configuration==
===Network Post-Configuration===
By default, guests are configured to attach in NAT mode to the "default" virtual network running on the virtualization host.  
By default, guests are configured to attach in NAT mode to the "default" virtual network running on the virtualization host.  


Additional network configurations:
Additional network configurations:
* [[Attaching_a_Guest_Directly_to_a_Virtualization_Host_Network_Interface_with_a_macvtap_Driver#Overview|Attaching a Guest Directly to a Virtualization Host Network Interface with a macvtap Driver]].
{{Internal|Attaching_a_Guest_Directly_to_a_Virtualization_Host_Network_Interface_with_a_macvtap_Driver#Overview|Attaching a Guest Directly to a Virtualization Host Network Interface with a macvtap Driver}}
 
===Storage Post-Configuration===
==Storage Post-Configuration==
{{Internal|Linux_Virtualization_Adding_Storage_to_Guests|Adding Storage to Guests}}
{{Internal|Linux_Virtualization_Adding_Storage_to_Guests|Adding Storage to Guests}}
===Generic RHEL/Centos Post-Install Tasks===
{{Internal|RHEL_7/Centos_7_Installation#Post-Install_Tasks|Post-Install}}
===Configure Access from Local Network===
On the main machine, add this to <code>.basrhc</code>:


==Generic RHEL/Centos Post-Install Tasks==
<syntaxhighlight lang='bash'>
{{Internal|RHEL_7/Centos_7_Installation#Post-Install_Tasks|Post-Install}}
alias gp='ssh -p 53531 root@192.168.1.15'
</syntaxhighlight>


=Mandatory Options=
=Mandatory Options=

Latest revision as of 02:38, 30 July 2023

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 on the virtualization host 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. Note that the underlying volume does not need to be created in advance. The corresponding virtual machine root filesystem will be stored on an automatically created volume (/main-storage-pool/<guest-name>.qcow2). The volume will be created in the associated storage pool during the installation procedure, if the volume does not exist already. Additional block storage, in the form of different block devices available to the guest, can it be added later. The installation procedure may specify a minimal network configuration (DHCP and just host name), while the network can be further configured later.

Documentation

virt-install --help

Procedure

Prerequisites

If not already declared, create an "iso-images" directory-based storage pool. The procedure to create the storage pool is described here:

Directory-Based Storage Pool Configuration

Once the pool is created, the ISO image can be simply placed in there:

cp .../CentOS-7-x86_64-DVD-2009.iso /iso-images
chown qemu:qemu CentOS-7-x86_64-DVD-2009.iso

While the file does is not exposed yet as a volume, virt-install will expose it as a volume in the pool. Optionally, it can be exported as a pool volume in advance. The procedure to export the DVD ISO image as a pool volume is described here:

Placing an ISO Image in a Directory-Based Storage Pool

The command assumes that main-storage-pool was created and it is active.


Download "Red Hat Enterprise Linux 7.4 Binary DVD" and not the Boot ISO or KVM Guest image, otherwise the installation via virt-install will fail.

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/<virtual-machine-name>.qcow2,size=<image-partition-size-in-GiB-without-alphanumeric-unit>
 --network default
 --graphics none

Notes

  • ⚠️ The size of the root partition determines how the RedHat/Centos installer will partition the space (create just a root partition "/" or a root "/" and a home "/home" partition. The cut-off is 50GB. For more details see Centos 7 Text Installer | Root_Partition_Size.
  • For noper430 installations, these commands are usually saved as /root/environments/single-hosts/<host-name>/<host-name>-virt-install.sh and it is recommended to do so for any guest created on that virtualization host.

Procedure

Starting install...
Retrieving file .treeinfo...
[...]
Welcome to CentOS Linux 7 (Core) dracut-033-572.el7 (Initramfs)!
[...]

Interactive O/S Installation Procedure

The command will enter in text interactive mode. Different installers will have their own installation procedure:

Results

The installation process should end up in console access to the newly installed host.

The virtual machine will appear in virsh list:

Id    Name                           State
----------------------------------------------------
...
9     gp                             running

The XML definition of the virtual machine will be accessible with virsh dumpxml and can be edited with virsh edit:

KVM Virtual Machine XML Definition

The virtual machine root filesystem is stored on an automatically created storage pool volume /main-storage-pool/<vm-name>.qcow2.

The storage volume is automatically added to the main storage pool. Query with virsh vol-list main-storage-pool --details:

Name                 Path
-----------------------------------------------------------------------------
<vm-name>.qcow2      /main-storage-pool/<vm-name>.qcow2
...

There are two network interfaces: lo and eth0, configured by DHCP.

There should be just a root partition (/) that occupies the entire block device.

Continue with Post-Install below.

Post-Install

Remove the ISO Image from Guest Storage

If the ISO image remains mounted, it will not be usable by other guests, so it is a good idea to remove it. If left mounted, the attempt to create other guest will result in:

ERROR    Disk /iso-images/CentOS-7-x86_64-DVD-7.9.2009.iso is already in use by other guests ['c3kb'].

The procedure to remove it is available here:

Remove Storage from Guest

Configure the Guest to Start at Boot

Configure Guest to Automatically Start at Boot

Network Post-Configuration

By default, guests are configured to attach in NAT mode to the "default" virtual network running on the virtualization host.

Additional network configurations:

Attaching a Guest Directly to a Virtualization Host Network Interface with a macvtap Driver

Storage Post-Configuration

Adding Storage to Guests

Generic RHEL/Centos Post-Install Tasks

Post-Install

Configure Access from Local Network

On the main machine, add this to .basrhc:

alias gp='ssh -p 53531 root@192.168.1.15'

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:

KVM Virtual Machine Definition 'name'

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

If a more recent os-variant is not available (the following error message is generated):

ERROR    Error validating install location: Distro 'rhel7.4' does not exist in our dictionary

the dictionary can be updated by performing an yum update on the virtualization host.

--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:

Text-Based Anaconda Guest Installation

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

Examples

virt-install Examples