openshift-docs/modules/virt-virtctl-commands.adoc

// Module included in the following assemblies:
//
// * virt/getting_started/virt-using-the-cli-tools.adoc

:_mod-docs-content-type: REFERENCE
[id="virt-virtctl-commands_{context}"]
= virtctl commands

The `virtctl` client is a command-line utility for managing {VirtProductName} resources.

[NOTE]
====
The virtual machine (VM) commands also apply to virtual machine instances (VMIs) unless otherwise specified.
====

// apinnick: I recommend not breaking these sections into separate modules because of maintenance issues.
// These sections will never be used independently.

[id='virtctl-information-commands_{context}']
== virtctl information commands

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

.Information commands
[width="100%",cols="1a,2a",options="header"]
|===
|Command |Description
|`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.
|===

[id='vm-information-commands_{context}']
== VM information commands

You can use `virtctl` to view information about virtual machines (VMs) and virtual machine instances (VMIs).

.VM information commands
[width="100%",cols="1a,2a",options="header"]
|===
|Command |Description
|`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.
|===

[id="vm-manifest-creation-commands_{context}"]
== VM manifest creation commands

You can use `virtctl create` commands to create manifests for virtual machines, instance types, and preferences.

.VM manifest creation commands
[width="100%",cols="2a,1a",options="header"]
|===
|Command |Description

|`virtctl create vm`::
|Create a `VirtualMachine` (VM) manifest.

|`virtctl create vm --name <vm_name>`
|Create a VM manifest, specifying a name for the VM.

|`virtctl create vm --user <user_name> --ssh-key\|password-file=<value>`
|Create a VM manifest with a cloud-init configuration to create the selected user and either add an SSH public key from the supplied string, or a password from a file.

|`virtctl create vm --access-cred type:password,src:<secret>`
|Create a VM manifest with a user and password combination injected from the selected secret.

|`virtctl create vm --access-cred type:ssh,src:<secret>,user:<user_name>`
|Create a VM manifest with an SSH public key injected from the selected secret.

|`virtctl create vm --volume-sysprep src:<config_map>`
|Create a VM manifest, specifying a config map to use as the sysprep volume. The config map must contain a valid answer file named `unattend.xml` or `autounattend.xml`.

|`virtctl create vm --instancetype <instancetype_name>`
|Create a VM manifest that uses an existing cluster-wide instance type.

|`virtctl create vm --instancetype=virtualmachineinstancetype/<instancetype_name>`
|Create a VM manifest that uses an existing namespaced instance type.

|`virtctl create instancetype --cpu <cpu_value> --memory <memory_value> --name <instancetype_name>`
|Create a manifest for a cluster-wide instance type.

|`virtctl create instancetype --cpu <cpu_value> --memory <memory_value> --name <instancetype_name> --namespace <namespace_value>`
|Create a manifest for a namespaced instance type.

|`virtctl create preference --name <preference_name>`
|Create a manifest for a cluster-wide VM preference, specifying a name for the preference.

|`virtctl create preference --namespace <namespace_value>`
|Create a manifest for a namespaced VM preference.
|===

[id='vm-management-commands_{context}']
== VM management commands

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

.VM management commands
[width="100%",cols="1a,2a",options="header"]
|===
|Command |Description

|`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 migrate-cancel <vm_name>`
|Cancel a VM migration.

|`virtctl restart <vm_name>`
|Restart a VM.
|===

[id='vm-connection-commands_{context}']
== VM connection commands

You use `virtctl` connection commands to expose ports and connect to virtual machines (VMs) and virtual machine instances (VMIs).

.VM connection commands
[width="100%",cols="1a,2a",options="header"]
|===
|Command |Description
|`virtctl console <vm_name>`
|Connect to the serial console of a VM.

|`virtctl expose vm <vm_name> --name <service_name> --type <ClusterIP\|NodePort\|LoadBalancer> --port <port>`
|Create a service that forwards a designated port of a VM and expose the service on the specified port of the node.

Example: `virtctl expose vm rhel9_vm --name rhel9-ssh --type NodePort --port 22`

|`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 <vm_name>`
|Connect to the VNC console of a VM.

You must have `virt-viewer` installed.

|`virtctl vnc --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 --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.
|===

[id='vm-volume-export-commands_{context}']
== VM export commands

Use `virtctl vmexport` commands to create, download, or delete a volume exported from a VM, VM snapshot, or persistent volume claim (PVC). Certain manifests also contain a header secret, which grants access to the endpoint to import a disk image in a format that {VirtProductName} can use.

.VM export commands
[width="100%",cols="1a,2a",options="header"]
|===
|Command |Description
|`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.

|`virtctl vmexport download export --manifest`
|Retrieve the manifest for an existing export. The manifest does not include the header secret.

|`virtctl vmexport download export --manifest --vm=example`
|Create a VM export for a VM example, and retrieve the manifest. The manifest does not include the header secret.

|`virtctl vmexport download export --manifest --snap=example`
|Create a VM export for a VM snapshot example, and retrieve the manifest. The manifest does not include the header secret.

|`virtctl vmexport download export --manifest --include-secret`
|Retrieve the manifest for an existing export. The manifest includes the header secret.

|`virtctl vmexport download export --manifest --manifest-output-format=json`
|Retrieve the manifest for an existing export in json format. The manifest does not include the header secret.

|`virtctl vmexport download export --manifest --include-secret --output=manifest.yaml`
|Retrieve the manifest for an existing export. The manifest includes the header secret and writes it to the file specified.
|===

[id='vm-memory-dump-commands_{context}']
== VM memory dump commands

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:
+
[source,terminal,subs="attributes+"]
----
$ oc patch hyperconverged kubevirt-hyperconverged -n {CNVNamespace} \
  --type json -p '[{"op": "add", "path": "/spec/featureGates", \
  "value": "HotplugVolumes"}]'
----

.Downloading the memory dump

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

[source,terminal]
----
$ virtctl vmexport download <vmexport_name> --vm|pvc=<object_name> \
  --volume=<volume_name> --output=<output_file>
----

.VM memory dump commands
[width="100%",cols="1a,2a",options="header"]
|===
|Command |Description
|`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.
|===

// hot-plug/unplug NICs will be added in 4.14
[id="hot-plug-and-hot-unplug-commands_{context}"]
== Hot plug and hot unplug commands

You use `virtctl` to add or remove resources from running virtual machines (VMs) and virtual machine instances (VMIs).

.Hot plug and hot unplug commands
[width="100%",cols="1a,2a",options="header"]
|===
|Command |Description
|`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.

|`virtctl addinterface <vm_name> --network-attachment-definition-name <net_attach_def_name> --name <interface_name>`
|Hot plug a Linux bridge network interface.

|`virtctl removeinterface <vm_name> --name <interface_name>`
|Hot unplug a Linux bridge network interface.
|===

[id='image-upload-commands_{context}']
== Image upload commands

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

.Image upload commands
[width="100%",cols="1a,2a",options="header"]
|===
|Command |Description
|`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.

|`virtctl image-upload dv <datavolume_name> --datasource --size=<datavolume_size> --image-path=</path/to/image>`
|Upload a VM image to a new data volume and create an associated `DataSource` object for it.
|===