Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

Chapter 4. Getting Started with Virtualization Command-line Interface

The standard method of operating virtualization on Red Hat Enterprise Linux 7 is using the command-line user interface (CLI). Entering CLI commands activates system utilities that create or interact with virtual machines on the host system. This method offers more detailed control than using graphical applications such as virt-manager and provides opportunities for scripting and automation.

4.1. Primary Command-line Utilities for Virtualization

The following subsections list the main command-line utilities you can use to set up and manage virtualization on Red Hat Enterprise Linux 7. These commands, as well as numerous other virtualization utilities, are included in packages provided by the Red Hat Enterprise Linux repositories and can be installed using the Yum package manager.
For more information about installing virtualization packages, see the Virtualization Deployment and Administration Guide.

4.1.1. virsh

virsh is a CLI utility for managing hypervisors and guest virtual machines. It is the primary means of controlling virtualization on Red Hat Enterprise Linux 7. Its capabilities include:
  • Creating, configuring, pausing, listing, and shutting down virtual machines
  • Managing virtual networks
  • Loading virtual machine disk images
The virsh utility is ideal for creating virtualization administration scripts. Users without root privileges can use virsh as well, but in read-only mode.

Using virsh

The virsh utility can be used in a standard command-line input, but also as an interactive shell. In shell mode, the virsh command prefix is not needed, and the user is always registered as root. The following example uses the virsh hostname command to display the hypervisor's host name - first in standard mode, then in interactive mode. 
 $ virsh hostname
 localhost.localdomain

 $ virsh
 Welcome to virsh, the virtualization interactive terminal.

 Type:  'help' for help with commands
        'quit' to quit

 virsh # hostname
 localhost.localdomain

Important

When using virsh as a non-root user, you enter an unprivileged libvirt session, which means you cannot see or interact with guests or any other virtualized elements created by the root.
To gain read-only access to the elements, use virsh with the -c qemu:///system option.

Getting help with virsh

Like with all Linux bash commands, you can obtain help with virsh by using the man virsh command or the --help option. In addition, the virsh help command can be used to view the help text of a specific virsh command, or, by using a keyword, to list all virsh commands that belong to a certain group.
The virsh command groups and their respective keywords are as follows:
  • Guest management - keyword domain
  • Guest monitoring - keyword monitor
  • Host and hypervisor monitoring and management- keyword host
  • Host system network interface management - keyword interface
  • Virtual network management - keyword network
  • Network filter management - keyword filter
  • Node device management - keyword nodedev
  • Management of secrets, such as passphrases or encryption keys - keyword secret
  • Snapshot management - keyword snapshot
  • Storage pool management - keyword pool
  • Storage volume management - keyword volume
  • General virsh usage - keyword virsh
In the following example, you need to learn how to rename a guest virtual machine. By using virsh help, you first find the proper command to use and then learn its syntax. Finally, you use the command to rename a guest called Fontaine to Atlas.

Example 4.1. How to list help for all commands with a keyword

# virsh help domain
 Domain Management (help keyword 'domain'):
    attach-device                  attach device from an XML file
    attach-disk                    attach disk device
    [...]
    domname                        convert a domain id or UUID to domain name
    domrename                      rename a domain
    [...]
# virsh help domrename
 NAME
   domrename - rename a domain

 SYNOPSIS
   domrename <domain> <new-name>

 DESCRIPTION
   Rename an inactive domain.

 OPTIONS
   [--domain] <string>  domain name, id or uuid
   [--new-name] <string>  new domain name

# virsh domrename --domain Fontaine --new-name Atlas
Domain successfully renamed

Note

For more information about managing virtual machines using virsh, see the Red Hat Enterprise Linux 7 Virtualization Deployment and Administration Guide.

4.1.2. virt-install

virt-install is a CLI utility for creating new virtual machines. It supports both text-based and graphical installations, using serial console, SPICE, or VNC client-server pair graphics. Installation media can be local, or exist remotely on an NFS, HTTP, or FTP server. The tool can also be configured to run unattended and use the kickstart method to prepare the guest, allowing for easy automation of installation. This tool is included in the virt-install package.

Important

When using virt-install as a non-root user, you enter an unprivileged libvirt session. This means that the created guest will only be visible to you, and it will not have access to certain capabilities that guests created by the root have.

Note

For more information about using virt-install, see the Red Hat Enterprise Linux 7 Virtualization Deployment and Administration Guide.

4.1.3. virt-xml

virt-xml is a command-line utility for editing domain XML files. For the XML configuration to be modified successfully, the name of the guest, the XML action, and the change to make must be included with the command.
For example, the following lists the suboptions that relate to guest boot configuration, and then turns on the boot menu on the example_domain guest: 
# virt-xml boot=?
 --boot options:
   arch
   cdrom
   [...]
   menu
   network
   nvram
   nvram_template
   os_type
   smbios_mode
   uefi
   useserial
# virt-xml example_domain --edit --boot menu=on
Domain 'example_domain' defined successfully.
Note that each invocation of the command can perform one action on one domain XML file.

Note

This tool is included in the virt-install package. For more information about using virt-xml, see the virt-xml man pages.

4.1.4. guestfish

guestfish is a command-line utility for examining and modifying virtual machine disk images. It uses the libguestfs library and exposes all functionalities provided by the libguestfs API.

Using guestfish

The guestfish utility can be used in a standard command-line input mode, but also as an interactive shell. In shell mode, the guestfish command prefix is not needed, and the user is always registered as root. The following example uses the guestfish to display the file systems on the testguest virtual machine - first in standard mode, then in interactive mode. 
# guestfish domain testguest : run : list-filesystems
/dev/sda1: xfs
/dev/rhel/root: xfs
/dev/rhel/swap: swap
# guestfish

Welcome to guestfish, the guest filesystem shell for
editing virtual machine filesystems and disk images.

Type: 'help' for help on commands
	  'man' to read the manual
	  'quit' to quit the shell

><fs> domain testguest
><fs> run
><fs> list-filesystems
/dev/sda1: xfs
/dev/rhel/root: xfs
/dev/rhel/swap: swap
In addition, guestfish can be used in bash scripts for automation purposes.

Important

When using guestfish as a non-root user, you enter an unprivileged libvirt session. This means you cannot see or interact with disk images on guests created by the root.
To gain read-only access to these disk images, use guestfish with the -ro -c qemu:///system options. In addition, you must have read privileges for the disk image files.

Getting help with guestfish

Like with all Linux bash commands, you can obtain help with guestfish by using the man guestfish command or the --help option. In addition, the guestfish help command can be used to view detailed information about a specific guestfish command. The following example displays information about the guestfish add command: 
$ guestfish help add
NAME
    add-drive - add an image to examine or modify

SYNOPSIS
     add-drive filename [readonly:true|false] [format:..] [iface:..] [name:..] [label:..] [protocol:..] [server:..] [username:..] [secret:..] [cachemode:..] [discard:..] [copyonread:true|false]

DESCRIPTION
    This function adds a disk image called filename to the handle. filename
    may be a regular host file or a host device.
    [...]

Note

For more information about guestfish, see the Red Hat Enterprise Linux 7 Virtualization Deployment and Administration Guide.