Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 10. Using the virtctl and libguestfs CLI tools

You can manage OpenShift Virtualization resources by using the virtctl command line tool.

You can also deploy a libguestfs-tools container by using virtctl. Libguestfs is a set of tools for accessing and modifying virtual machine (VM) disk images.

10.1. Installing virtctl
Copy link

To install virtctl on Linux, Windows, and MacOS operating systems, you download and install the the virtctl binary file.

To install virtctl on Red Hat Enterprise Linux (RHEL), you enable the OpenShift Virtualization repository and then install the kubevirt-virtctl package.

You can download the virtctl binary for your operating system from the OpenShift Container Platform web console and then install it.

Procedure

  1. Navigate to the Virtualization Overview page in the web console.
  2. Click the Download virtctl link to download the virtctl binary for your operating system.

  3. Install virtctl:

    • For RHEL 9 and other Linux operating systems:

      1. Decompress the archive file: 

        $ tar -xvf <virtctl-version-distribution.arch>.tar.gz
        Copy to Clipboard Toggle word wrap

      2. Run the following command to make the virtctl binary executable: 

        $ chmod +x <path/virtctl-file-name>
        Copy to Clipboard Toggle word wrap

      3. Move the virtctl binary to a directory in your PATH environment variable.

        You can check your path by running the following command: 

        $ echo $PATH
        Copy to Clipboard Toggle word wrap

      4. Set the KUBECONFIG environment variable: 

        $ export KUBECONFIG=/home/<user>/clusters/current/auth/kubeconfig
        Copy to Clipboard Toggle word wrap

    • For Windows:

      1. Decompress the archive file.
      2. Navigate the extracted folder hierarchy and double-click the virtctl executable file to install the client.

      3. Move the virtctl binary to a directory in your PATH environment variable.

        You can check your path by running the following command: 

        C:\> path
        Copy to Clipboard Toggle word wrap

    • For macOS:

      1. Decompress the archive file.

      2. Move the virtctl binary to a directory in your PATH environment variable.

        You can check your path by running the following command: 

        echo $PATH
        Copy to Clipboard Toggle word wrap

10.1.2. Installing the virtctl RPM on RHEL 8
Copy link

You can install the virtctl RPM package on Red Hat Enterprise Linux (RHEL) 8 by enabling the OpenShift Virtualization repository and installing the kubevirt-virtctl package.

Prerequisites

  • Each host in your cluster must be registered with Red Hat Subscription Manager (RHSM) and have an active OpenShift Container Platform subscription.

Procedure

  1. Enable the OpenShift Virtualization repository for your operating system by using the subscription-manager CLI tool to run the following command: 

    # subscription-manager repos --enable cnv-4.13-for-rhel-8-x86_64-rpms
    Copy to Clipboard Toggle word wrap

  2. Install the kubevirt-virtctl package by running the following command: 

    # yum install kubevirt-virtctl
    Copy to Clipboard Toggle word wrap

10.2. Virtctl commands
Copy link

The virtctl client is a command-line utility for managing OpenShift Virtualization resources.

Note

The virtual machine (VM) commands also apply to virtual machine instances unless otherwise specified.

10.2.1. Virtctl information commands
Copy link

You use virtctl information commands to view information about the virtctl client.

Expand
Table 10.1. Information commands
CommandDescription

virtctl version

View the virtctl client and server versions.

virtctl help

View a list of virtctl commands.

virtctl <command> -h|--help

View a list of options for a specific command.

virtctl options

View a list of global command options for any virtctl command.

10.2.2. VM information commands
Copy link

You can use virtctl to view information about VMs and VMIs.

Expand
Table 10.2. VM information commands
CommandDescription

virtctl fslist <vm_name>

View the file systems available on a guest machine.

virtctl guestosinfo <vm_name>

View information about the operating systems on a guest machine.

virtctl userlist <vm_name>

View the logged-in users on a guest machine.

10.2.3. VM management commands
Copy link

You use virtctl virtual machine (VM) management commands to manage and migrate VMs and VMIs.

Expand
Table 10.3. VM management commands
CommandDescription

virtctl create -name <vm_name>

Create a VirtualMachine manifest.

virtctl start <vm_name>

Start a VM.

virtctl start --paused <vm_name>

Start a VM in a paused state. This option enables you to interrupt the boot process from the VNC console.

virtctl stop <vm_name>

Stop a VM.

virtctl stop <vm_name> --grace-period 0 --force

Force stop a VM. This option might cause data inconsistency or data loss.

virtctl pause vm <vm_name>

Pause a VM. The machine state is kept in memory.

virtctl unpause vm <vm_name>

Unpause a VM.

virtctl migrate <vm_name>

Migrate a VM.

virtctl restart <vm_name>

Restart a VM.

10.2.4. VM connection commands
Copy link

You use virtctl connection commands to expose ports and connect to VMs and VMIs.

Expand
Table 10.4. VM connection commands
CommandDescription

virtctl console <vm_name>

Connect to the serial console of a VM.

virtctl expose <vm_name>

Create a service that forwards a designated port of a VM and expose the service on the specified port of the node.

virtctl scp -i <ssh_key> <file_name> <user_name>@<vm_name>

Copy a file from your machine to a VM. This command uses the private key of an SSH key pair. The VM must be configured with the public key.

virtctl scp -i <ssh_key> <user_name@<vm_name>:<file_name> .

Copy a file from a VM to your machine. This command uses the private key of an SSH key pair. The VM must be configured with the public key.

virtctl ssh -i <ssh_key> <user_name>@<vm_name>

Open an SSH connection with a VM. This command uses the private key of an SSH key pair. The VM must be configured with the public key.

virtctl vnc --kubeconfig=$KUBECONFIG <vm_name>

Connect to the VNC console of a VM.

Accessing the graphical console of a VM through VNC requires a remote viewer on your local machine.

virtctl vnc --kubeconfig=$KUBECONFIG --proxy-only=true <vm_name>

Display the port number and connect manually to a VM by using any viewer through the VNC connection.

virtctl vnc --kubeconfig=$KUBECONFIG --port=<port-number> <vm_name>

Specify a port number to run the proxy on the specified port, if that port is available.

If a port number is not specified, the proxy runs on a random port.

10.2.5. VM export commands
Copy link

You use virtctl vmexport commands to create, download, or delete a volume exported from a VM, VM snapshot, or persistent volume claim (PVC).

Expand
Table 10.5. VM export commands
CommandDescription

virtctl vmexport create <vmexport_name> --vm|snapshot|pvc=<object_name>

Create a VirtualMachineExport custom resource (CR) to export a volume from a VM, VM snapshot, or PVC.

  • --vm: Exports the PVCs of a VM.
  • --snapshot: Exports the PVCs contained in a VirtualMachineSnapshot CR.
  • --pvc: Exports a PVC.
  • Optional: --ttl=1h specifies the time to live. The default duration is 2 hours.

virtctl vmexport delete <vmexport_name>

Delete a VirtualMachineExport CR manually.

virtctl vmexport download <vmexport_name> --output=<output_file> --volume=<volume_name>

Download the volume defined in a VirtualMachineExport CR.

  • --output specifies the file format. Example: disk.img.gz.
  • --volume specifies the volume to download. This flag is optional if only one volume is available.

Optional:

  • --keep-vme retains the VirtualMachineExport CR after download. The default behavior is to delete the VirtualMachineExport CR after download.
  • --insecure enables an insecure HTTP connection.

virtctl vmexport download <vmexport_name> --<vm|snapshot|pvc>=<object_name> --output=<output_file> --volume=<volume_name>

Create a VirtualMachineExport CR and then download the volume defined in the CR.

10.2.6. VM memory dump commands
Copy link

You can use the virtctl memory-dump command to output a VM memory dump on a PVC. You can specify an existing PVC or use the --create-claim flag to create a new PVC.

Prerequisites

  • The PVC volume mode must be FileSystem.

  • The PVC must be large enough to contain the memory dump.

    The formula for calculating the PVC size is (VMMemorySize + 100Mi) * FileSystemOverhead, where 100Mi is the memory dump overhead.

  • You must enable the hot plug feature gate in the HyperConverged custom resource by running the following command: 

    $ oc patch hco kubevirt-hyperconverged -n openshift-cnv \
  --type json -p '[{"op": "add", "path": "/spec/featureGates", \
  "value": "HotplugVolumes"}]'
    Copy to Clipboard Toggle word wrap

Downloading the memory dump

You must use the virtctl vmexport download command to download the memory dump: 

$ virtctl vmexport download <vmexport_name> --vm\|pvc=<object_name> \
  --volume=<volume_name> --output=<output_file>
Copy to Clipboard Toggle word wrap
Expand
Table 10.6. VM memory dump commands
CommandDescription

virtctl memory-dump get <vm_name> --claim-name=<pvc_name>

Save the memory dump of a VM on a PVC. The memory dump status is displayed in the status section of the VirtualMachine resource.

Optional:

  • --create-claim creates a new PVC with the appropriate size. This flag has the following options:

    • --storage-class=<storage_class>: Specify a storage class for the PVC.
    • --access-mode=<access_mode>: Specify ReadWriteOnce or ReadWriteMany.

virtctl memory-dump get <vm_name>

Rerun the virtctl memory-dump command with the same PVC.

This command overwrites the previous memory dump.

virtctl memory-dump remove <vm_name>

Remove a memory dump.

You must remove a memory dump manually if you want to change the target PVC.

This command removes the association between the VM and the PVC, so that the memory dump is not displayed in the status section of the VirtualMachine resource. The PVC is not affected.

10.2.7. Hot plug and hot unplug commands
Copy link

You use virtctl to add or remove resources from running VMs and VMIs.

Expand
Table 10.7. Hot plug and hot unplug commands
CommandDescription

virtctl addvolume <vm_name> --volume-name=<datavolume_or_PVC> [--persist] [--serial=<label>]

Hot plug a data volume or persistent volume claim (PVC).

Optional:

  • --persist mounts the virtual disk permanently on a VM. This flag does not apply to VMIs.
  • --serial=<label> adds a label to the VM. If you do not specify a label, the default label is the data volume or PVC name.

virtctl removevolume <vm_name> --volume-name=<virtual_disk>

Hot unplug a virtual disk.

10.2.8. Image upload commands
Copy link

You use the virtctl image-upload commands to upload a VM image to a data volume.

Expand
Table 10.8. Image upload commands
CommandDescription

virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create

Upload a VM image to a data volume that already exists.

virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image>

Upload a VM image to a new data volume of a specified requested size.

10.3. Using libguestfs
Copy link

You can use the virtctl guestfs command to deploy an interactive container with libguestfs-tools and a persistent volume claim (PVC) attached to it.

Procedure

  • To deploy a container with libguestfs-tools, mount the PVC, and attach a shell to it, run the following command: 

    $ virtctl guestfs -n <namespace> <pvc_name>
    1
    Copy to Clipboard Toggle word wrap
    1
    The PVC name is a required argument. If you do not include it, an error message appears.

10.3.2. Libguestfs and virtctl guestfs commands
Copy link

Libguestfs tools help you access and modify virtual machine (VM) disk images. You can use libguestfs tools to view and edit files in a guest, clone and build virtual machines, and format and resize disks.

You can also use the virtctl guestfs command and its sub-commands to modify, inspect, and debug VM disks on a PVC. To see a complete list of possible sub-commands, enter virt- on the command line and press the Tab key. For example:

Expand
CommandDescription

virt-edit -a /dev/vda /etc/motd

Edit a file interactively in your terminal.

virt-customize -a /dev/vda --ssh-inject root:string:<public key example>

Inject an ssh key into the guest and create a login.

virt-df -a /dev/vda -h

See how much disk space is used by a VM.

virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list'

See the full list of all RPMs installed on a guest by creating an output file containing the full list.

virt-cat -a /dev/vda /rpm-list

Display the output file list of all RPMs created using the virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list' command in your terminal.

virt-sysprep -a /dev/vda

Seal a virtual machine disk image to be used as a template.

By default, virtctl guestfs creates a session with everything needed to manage a VM disk. However, the command also supports several flag options if you want to customize the behavior:

Expand
Flag OptionDescription

--h or --help

Provides help for guestfs.

-n <namespace> option with a <pvc_name> argument

To use a PVC from a specific namespace.

If you do not use the -n <namespace> option, your current project is used. To change projects, use oc project <namespace>.

If you do not include a <pvc_name> argument, an error message appears.

--image string

Lists the libguestfs-tools container image.

You can configure the container to use a custom image by using the --image option.

--kvm

Indicates that kvm is used by the libguestfs-tools container.

By default, virtctl guestfs sets up kvm for the interactive container, which greatly speeds up the libguest-tools execution because it uses QEMU.

If a cluster does not have any kvm supporting nodes, you must disable kvm by setting the option --kvm=false.

If not set, the libguestfs-tools pod remains pending because it cannot be scheduled on any node.

--pull-policy string

Shows the pull policy for the libguestfs image.

You can also overwrite the image’s pull policy by setting the pull-policy option.

The command also checks if a PVC is in use by another pod, in which case an error message appears. However, once the libguestfs-tools process starts, the setup cannot avoid a new pod using the same PVC. You must verify that there are no active virtctl guestfs pods before starting the VM that accesses the same PVC.

Note

The virtctl guestfs command accepts only a single PVC attached to the interactive pod.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat