Essential KVM CLI Tools for Administrators – virt-top, virt-cat, virt-ls

While tools like Virt-Manager make KVM virtualization easy to access, administrators often go to command line tools due to speed in troubleshooting, and helpful automation. Tools like virt-top, virt-cat, and virt-ls allow you to access and control a virtual machine without booting into the guest or using a GUI. By monitoring performance and resource usage of the VM or retrieving logs or listing files inside the virtual disk image, the utilities grant the administrators powerful capabilities to effectively manage KVM environments. These three CLI tools can ease the day-to-day tasks related to KVM virtualization.

In this guide, we’ll explore virt-top, virt-cat for monitoring VM performance, virt-cat for inspecting virtual machine files, and virt-ls to list files within a VM’s disk image.

Here’s a list of all the essential KVM CLI tools, but we’ll only look at the first three in this guide:

• virt-top – Monitor CPU, memory, and disk activity of KVM guests in real-time.
• virt-cat & virt-ls – Access and list files within a VM’s disk image.
• virt-edit – Modify configuration files inside a VM without booting it.
• virt-df – Analyze disk usage across multiple VMs.
• virt-clone – Create identical VM copies quickly.
• qemu-img & qemu-nbd – Manage, convert, and connect disk images dynamically.
• virt-sysprep – Reset and sanitize VM images before cloning.
• virt-resize – Expand or shrink virtual disk sizes.
• virt-copy-in – Copy files into a virtual machine without booting.
• guestfish – Perform advanced file system modifications inside VM images.

Mastering these tools will boost your ability to manage KVM environments effectively, whether you need to optimize VM performance, automating tasks, or troubleshooting virtual machines.

1. Virt-top – top command for VMs

The virt-top is a command-line performance monitoring tool for virtual machines, similar to the top utility for processes. It uses the libvirt API to query for the information about virtual machines (VMs) running on a KVM host and provides details about CPU, memory, disk, and network usage.

virt-top displays real-time performance metrics and supports user interaction. The data available can be exported for further analysis.

Installing virt-top

On RHEL-Based Distributions:

sudo dnf install epel-release -y
sudo dnf install virt-top -y

On Debian-Based Distributions:

sudo apt update
sudo apt install virt-top -y

Verify installation by checking the software version:

virt-top --version

Launching virt-top requires sufficient privileges to access libvirt.

sudo virt-top

By default it connects to the default hypervisor (qemu:///system) unless specified.

To monitor VMs on a remote host, specify by connection URI:

sudo virt-top -c qemu+ssh://user@remote-host/system

Here is an output from virt-top command:

virt-top 22:43:42 - x86_64 12/12CPU 3000MHz 64015MB
4 domains, 4 active, 4 running, 0 sleeping, 0 paused, 0 inactive D:0 O:0 X:0
CPU: 12.4%  Mem: 65536 MB (65536 MB by guests)

   ID S RDRQ WRRQ RXBY TXBY %CPU %MEM    TIME   NAME
   20 R 1901  134 503K   1M 10.5 51.0 877:32:13 dbmaster01
   19 R    0    3 887K   1M  1.6 25.0 414:30:50 app-server01
    3 R    0    7  36K  46K  0.2 12.0 286:56:27 vpn-server01
    4 R    0    0  36K  43K  0.2 12.0 232:24:59 radius01

Key information from the output are;

• Header: Shows general system metrics, including host CPU, memory, and the number of VMs.
• Columns:

Column	Description
ID	The ID assigned to the VM by the hypervisor.
S	The state of the VM (R = Running, S = Sleeping, P = Paused).
RDRQ	The number of read requests issued by the VM.
WRRQ	The number of write requests issued by the VM.
RXBY	Network bytes received (e.g., 503K = 503 KB).
TXBY	Network bytes transmitted (e.g., 1M = 1 MB).
%CPU	Percentage of host CPU used by the VM.
%MEM	Percentage of host memory used by the VM.
TIME	Total CPU time used by the VM (HH:MM:SS format).
NAME	Name of the VM.

Filter to display specific VMs by name or ID:

sudo virt-top --domain

Run virt-top for one minute and save output in csv file.

sudo virt-top --csv report.csv --end-time  +60

For more usage example run:

virt-top --help

2. virt-cat – Display files in a virtual machine

The virt-cat CLI utility allows you to display the contents of a file easily within a virtual machine’s disk image. It is particularly useful for examining configuration files, logs, or other text files without booting up the virtual machine. It also works on a live guest instance.

Commonly used options:

• -a or --add – Specifies a file which should be a disk image from a virtual machine. For machines with multiple block devices, you must supply all of them with separate -a options.
• -d or --domain – Add all the disks from the named libvirt guest. Domain UUID can also be used instead of the name.
• -a or --add – Add a remote disk device
• -m or --mount – Used to mount the named partition or logical volume on the given mountpoint.

Get usage help page:

virt-cat --help

Example 1: Cat contents of /etc/fstab in a VM

Example to show the contents of the file /etc/fstab inside a VM:

VM_NAME="<vm-name>"
sudo virt-cat -d $VM_NAME /etc/fstab

Example 2: Pipe the output to another command

The output can be piped into other commands for filtering.

sudo virt-cat -d $VM_NAME /etc/passwd | tail
sudo virt-cat -d $VM_NAME /etc/group | tail -n 10

Example 3: Output the contents into file

The output from the command can be saved into a file using standard unix redirection operator.

sudo virt-cat -a debian12.qcow2 /etc/passwd > passwd.txt

3. virt-ls – List files in a virtual machine

Use virt-ls command to list files and directories from a VM’s disk image when offline. This is useful for managing and inspecting guest filesystem contents in an offline state.

Usage synopsis:

# With domain / vm name
virt-ls -d <vm-name> <dir>

# With image path
virt-ls -a <image> <dir>

Useful command options:

• -d or --domain – Specify guest name to edit
• -a or --add – Specify file or remote disk URI
• -R or --recursive – Recursive listing of files and directories
• -h or --human-readable – Human-readable sizes in output
• -l or --long – Long listing of contents

All available options can be checked using:

virt-ls --help

See usage examples below:

VM_NAME="ubuntu14"
sudo virt-ls -d $VM_NAME /
sudo virt-ls -a  $VM_NAME /
sudo virt-ls -l -d $VM_NAME  /
sudo virt-ls -R -d $VM_NAME /tmp

If using VM image, specify with -a

sudo virt-ls -h -a /var/lib/libvirt/images/deb12.qcow2 /

• Installing VMs using virt-install and kickstart
• How to Install VMs using PXE Boot and virt-install
• How to Install Windows 11|10 on KVM using virt-install