Using the CLI tools

Using the CLI tools

The two primary CLI tools used for managing resources in the cluster are:

The OKD Virtualization virtctl client
The OKD oc client

Prerequisites

You must enable the virtctl client.

OKD client commands

The OKD oc client is a command-line utility for managing OKD resources, including the VirtualMachine (vm) and VirtualMachineInstance (vmi) object types.

You can use the -n <namespace> flag to specify a different project.

Table 1. `oc` commands
Command	Description
`oc login -u <user_name>`	Log in to the OKD cluster as `<user_name>`.
`oc get <object_type>`	Display a list of objects for the specified object type in the current project.
`oc describe <object_type> <resource_name>`	Display details of the specific resource in the current project.
`oc create -f <object_config>`	Create a resource in the current project from a file name or from stdin.
`oc edit <object_type> <resource_name>`	Edit a resource in the current project.
`oc delete <object_type> <resource_name>`	Delete a resource in the current project.

For more comprehensive information on oc client commands, see the OKD CLI tools documentation.

Virtctl client commands

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

To view a list of virtctl commands, run the following command:

$ virtctl help

To view a list of options that you can use with a specific command, run it with the -h or --help flag. For example:

$ virtctl image-upload -h

To view a list of global command options that you can use with any virtctl command, run the following command:

$ virtctl options

The following table contains the virtctl commands used throughout the OKD Virtualization documentation.

Table 2. `virtctl` client commands
Command	Description
`virtctl start <vm_name>`	Start a virtual machine.
`virtctl stop <vm_name>`	Stop a virtual machine.
`virtctl pause vm\|vmi <object_name>`	Pause a virtual machine or virtual machine instance. The machine state is kept in memory.
`virtctl unpause vm\|vmi <object_name>`	Unpause a virtual machine or virtual machine instance.
`virtctl migrate <vm_name>`	Migrate a virtual machine.
`virtctl restart <vm_name>`	Restart a virtual machine.
`virtctl expose <vm_name>`	Create a service that forwards a designated port of a virtual machine or virtual machine instance and expose the service on the specified port of the node.
`virtctl console <vmi_name>`	Connect to a serial console of a virtual machine instance.
`virtctl vnc —kubeconfig=$KUBECONFIG <vmi_name>`	Open a VNC (Virtual Network Client) connection to a virtual machine instance. Access the graphical console of a virtual machine instance through a VNC which requires a remote viewer on your local machine.
`virtctl vnc —kubeconfig=$KUBECONFIG —proxy-only=true <vmi-name>`	Display the port number and connect manually to the virtual machine instance by using any viewer through the VNC connection.
`virtctl vnc —kubeconfig=$KUBECONFIG —port=<port-number> <vmi-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.
`virtctl image-upload dv <datavolume_name> —image-path=</path/to/image> —no-create`	Upload a virtual machine image to a data volume that already exists.
`virtctl image-upload dv <datavolume_name> —size=<datavolume_size> —image-path=</path/to/image>`	Upload a virtual machine image to a new data volume.
`virtctl version`	Display the client and server version information.
`virtctl help`	Display a descriptive list of `virtctl` commands.
`virtctl fslist <vmi_name>`	Return a full list of file systems available on the guest machine.
`virtctl guestosinfo <vmi_name>`	Return guest agent information about the operating system.
`virtctl userlist <vmi_name>`	Return a full list of logged-in users on the guest machine.

Creating a container using virtctl guestfs

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)
```
1 The PVC name is a required argument. If you do not include it, an error message appears.

Libguestfs tools and virtctl guestfs

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:

Command	Description
`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:

Flag Option	Description
`—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.

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

Additional resources

Libguestfs: tools for accessing and modifying virtual machine disk images.