mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
Merge pull request #97530 from jherrman/dita_virtctl-modules_CNV-66695
This commit is contained in:
Pan Ousley
63
modules/virt-generating-a-vm-memory-dump.adoc
Normal file
63
modules/virt-generating-a-vm-memory-dump.adoc
Normal file
@@ -0,0 +1,63 @@
|
||||
:_newdoc-version: 2.18.5
|
||||
:_template-generated: 2025-08-14
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
|
||||
[id="virt-generating-a-vm-memory-dump_{context}"]
|
||||
= Generating a VM memory dump
|
||||
|
||||
When a virtual machine (VM) terminates unexpectedly, you can use the `virtctl memory-dump` to generate a memory dump command to output a VM memory dump and save it on a persistent volume claim (PVC). Afterwards, you can analyze the memory dump to diagnose and troubleshoot issues on the VM.
|
||||
|
||||
// You can specify an existing PVC or use the `--create-claim` flag to create a new PVC.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* The hot plug feature gate is enabled in the `HyperConverged` custom resource. To do so, run the following command:
|
||||
+
|
||||
[source,terminal,subs="attributes+"]
|
||||
----
|
||||
$ oc patch hyperconverged kubevirt-hyperconverged -n {CNVNamespace} \
|
||||
--type json -p '[{"op": "add", "path": "/spec/featureGates", \
|
||||
"value": "HotplugVolumes"}]'
|
||||
----
|
||||
|
||||
* Optional: You have an existing PVC on which you want to save the memory dump.
|
||||
** 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, and `FileSystemOverhead` is defined in the `HCO` object.
|
||||
|
||||
.Procedure
|
||||
|
||||
. Create a memory dump of the required VM:
|
||||
|
||||
** If you have an existing PVC selected on which you want to save the memory dump:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ virtctl memory-dump get <vm_name> --claim-name=<pvc_name>
|
||||
----
|
||||
|
||||
** If you want to create a new PVC for the memory dump:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ virtctl memory-dump get <vm_name> --claim-name=<new_pvc_name> --create-claim
|
||||
----
|
||||
|
||||
. Download the memory dump:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ virtctl memory-dump download <vm_name> --output=<output_file>
|
||||
----
|
||||
|
||||
. Attach the memory dump to a Red Hat Support case.
|
||||
+
|
||||
Alternatively, you can inspect the memory dump, for example by using link:https://github.com/volatilityfoundation/volatility3[the volatility3 tool].
|
||||
|
||||
. Optional: Remove the memory dump:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ virtctl memory-dump remove <vm_name>
|
||||
----
|
||||
31
modules/virt-hot-plug-and-hot-unplug-commands.adoc
Normal file
31
modules/virt-hot-plug-and-hot-unplug-commands.adoc
Normal file
@@ -0,0 +1,31 @@
|
||||
:_newdoc-version: 2.18.5
|
||||
:_template-generated: 2025-08-13
|
||||
:_mod-docs-content-type: REFERENCE
|
||||
|
||||
[id="hot-plug-and-hot-unplug-commands_{context}"]
|
||||
= Hot plug and hot unplug commands
|
||||
|
||||
|
||||
You can use the following `virtctl` commands to add or remove resources from running virtual machines (VMs) and VM 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.
|
||||
|===
|
||||
23
modules/virt-image-upload-commands.adoc
Normal file
23
modules/virt-image-upload-commands.adoc
Normal file
@@ -0,0 +1,23 @@
|
||||
:_newdoc-version: 2.18.5
|
||||
:_template-generated: 2025-08-13
|
||||
:_mod-docs-content-type: REFERENCE
|
||||
|
||||
[id="image-upload-commands_{context}"]
|
||||
= Image upload commands
|
||||
|
||||
You can use the following `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.
|
||||
|===
|
||||
|
||||
@@ -1,342 +0,0 @@
|
||||
// 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.
|
||||
|===
|
||||
|
||||
26
modules/virt-virtctl-information-commands.adoc
Normal file
26
modules/virt-virtctl-information-commands.adoc
Normal file
@@ -0,0 +1,26 @@
|
||||
:_newdoc-version: 2.18.5
|
||||
:_template-generated: 2025-08-13
|
||||
:_mod-docs-content-type: REFERENCE
|
||||
|
||||
[id="virtctl-information-commands_{context}"]
|
||||
= virtctl information commands
|
||||
|
||||
You can use the following `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.
|
||||
|===
|
||||
|
||||
45
modules/virt-vm-connection-commands.adoc
Normal file
45
modules/virt-vm-connection-commands.adoc
Normal file
@@ -0,0 +1,45 @@
|
||||
:_newdoc-version: 2.18.5
|
||||
:_template-generated: 2025-08-13
|
||||
:_mod-docs-content-type: REFERENCE
|
||||
|
||||
[id="vm-connection-commands_{context}"]
|
||||
= VM connection commands
|
||||
|
||||
You use can use the following `virtctl` commands to expose ports and connect to virtual machines (VMs) and VM 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/<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/<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/<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.
|
||||
|===
|
||||
|
||||
|
||||
57
modules/virt-vm-export-commands.adoc
Normal file
57
modules/virt-vm-export-commands.adoc
Normal file
@@ -0,0 +1,57 @@
|
||||
:_newdoc-version: 2.18.5
|
||||
:_template-generated: 2025-08-13
|
||||
:_mod-docs-content-type: REFERENCE
|
||||
|
||||
[id="vm-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.
|
||||
|===
|
||||
|
||||
24
modules/virt-vm-information-commands.adoc
Normal file
24
modules/virt-vm-information-commands.adoc
Normal file
@@ -0,0 +1,24 @@
|
||||
:_newdoc-version: 2.18.5
|
||||
:_template-generated: 2025-08-13
|
||||
:_mod-docs-content-type: REFERENCE
|
||||
|
||||
[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.
|
||||
|===
|
||||
|
||||
|
||||
41
modules/virt-vm-management-commands.adoc
Normal file
41
modules/virt-vm-management-commands.adoc
Normal file
@@ -0,0 +1,41 @@
|
||||
:_newdoc-version: 2.18.5
|
||||
:_template-generated: 2025-08-13
|
||||
:_mod-docs-content-type: REFERENCE
|
||||
|
||||
[id="vm-management-commands_{context}"]
|
||||
= VM management commands
|
||||
|
||||
You can use the following `virtctl` commands to manage and migrate virtual machines (VMs) and VM 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.
|
||||
|===
|
||||
51
modules/virt-vm-manifest-creation-commands.adoc
Normal file
51
modules/virt-vm-manifest-creation-commands.adoc
Normal file
@@ -0,0 +1,51 @@
|
||||
:_newdoc-version: 2.18.5
|
||||
:_template-generated: 2025-08-13
|
||||
:_mod-docs-content-type: REFERENCE
|
||||
|
||||
[id="vm-manifest-creation-commands_{context}"]
|
||||
= VM manifest creation commands
|
||||
|
||||
You can use the following `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.
|
||||
|===
|
||||
|
||||
@@ -23,7 +23,7 @@ The OLM deploys the Hostpath Provisioner (HPP) Operator, but it is not functiona
|
||||
|
||||
image::cnv_components_main.png[Deployments]
|
||||
|
||||
* xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#virt-virtctl-commands_virt-using-the-cli-tools[Virtctl client commands]
|
||||
* xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#virtctl-commands_virt-using-the-cli-tools[Virtctl client commands]
|
||||
|
||||
include::modules/virt-about-hco-operator.adoc[leveloffset=+1]
|
||||
|
||||
|
||||
@@ -68,7 +68,7 @@ ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
|
||||
* xref:../../networking/networking_operators/k8s-nmstate-about-the-k8s-nmstate-operator.adoc#installing-the-kubernetes-nmstate-operator-cli[Installing the Kubernetes NMState Operator].
|
||||
endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
|
||||
* xref:../../virt/managing_vms/advanced_vm_management/virt-specifying-nodes-for-vms.adoc#virt-specifying-nodes-for-vms[Specifying nodes for virtual machines].
|
||||
* xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#virt-virtctl-commands_virt-using-the-cli-tools[`Virtctl` commands].
|
||||
* xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#virtctl-commands_virt-using-the-cli-tools[`Virtctl` commands].
|
||||
|
||||
[id="creating-and-managing-vms_{context}"]
|
||||
== Creating and managing virtual machines
|
||||
@@ -118,7 +118,7 @@ Connect to a VM:
|
||||
Manage a VM:
|
||||
|
||||
* xref:../../virt/managing_vms/virt-controlling-vm-states.adoc#virt-controlling-vm-states[Manage a VM by using the web console].
|
||||
* xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#virt-virtctl-commands_virt-using-the-cli-tools[Manage a VM by using the `virtctl` CLI tool].
|
||||
* xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#virtctl-commands_virt-using-the-cli-tools[Manage a VM by using the `virtctl` CLI tool].
|
||||
* xref:../../virt/managing_vms/virt-exporting-vms.adoc#virt-accessing-exported-vm-manifests_virt-exporting-vms[Export a VM].
|
||||
|
||||
include::modules/migrating-to-virt.adoc[leveloffset=+1]
|
||||
|
||||
@@ -22,7 +22,31 @@ include::modules/virt-installing-virtctl-binary.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-installing-virtctl-rhel8-rpm.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-virtctl-commands.adoc[leveloffset=+1]
|
||||
[id="virtctl-commands_virt-using-the-cli-tools"]
|
||||
== 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.
|
||||
====
|
||||
|
||||
include::modules/virt-virtctl-information-commands.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-vm-information-commands.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-vm-manifest-creation-commands.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-vm-management-commands.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-vm-connection-commands.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-vm-export-commands.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-hot-plug-and-hot-unplug-commands.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-image-upload-commands.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/virt-deploying-libguestfs-with-virtctl.adoc[leveloffset=+1]
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ You can export a virtual machine (VM) and its associated disks in order to impor
|
||||
|
||||
You create a `VirtualMachineExport` custom resource (CR) by using the command-line interface.
|
||||
|
||||
Alternatively, you can use the xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#vm-volume-export-commands_virt-using-the-cli-tools[`virtctl vmexport` command] to create a `VirtualMachineExport` CR and to download exported volumes.
|
||||
Alternatively, you can use the xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#vm-export-commands_virt-using-the-cli-tools[`virtctl vmexport` command] to create a `VirtualMachineExport` CR and to download exported volumes.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
|
||||
@@ -78,7 +78,7 @@ ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
|
||||
. xref:../../virt/support/virt-collecting-virt-data.adoc#virt-must-gather-options_virt-collecting-virt-data[Collect must-gather data for the VMs] using the `/usr/bin/gather` script.
|
||||
endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
|
||||
. Collect screenshots of VMs that have crashed _before_ you restart them.
|
||||
. xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#vm-memory-dump-commands_virt-using-the-cli-tools[Collect memory dumps from VMs] _before_ remediation attempts.
|
||||
. xref:../../virt/support/virt-collecting-virt-data.adoc#virt-generating-a-vm-memory-dump_virt-collecting-virt-data[Collect memory dumps from VMs] _before_ remediation attempts.
|
||||
. Record factors that the malfunctioning VMs have in common. For example, the VMs have the same host or network.
|
||||
|
||||
// must-gather not supported for ROSA/OSD, per Dustin Row
|
||||
@@ -86,4 +86,13 @@ ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
|
||||
include::modules/virt-using-virt-must-gather.adoc[leveloffset=+1]
|
||||
|
||||
include::modules/virt-must-gather-options.adoc[leveloffset=+2]
|
||||
|
||||
endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
|
||||
|
||||
include::modules/virt-generating-a-vm-memory-dump.adoc[leveloffset=+1]
|
||||
|
||||
[role="_additional-resources"]
|
||||
[id="additional-resources_{context}"]
|
||||
== Additional resources
|
||||
* xref:../../virt/support/virt-support-overview.adoc#virt-support-overview[VM support overview]
|
||||
* link:https://access.redhat.com/solutions/2112[How to provide log files to Red Hat Support (Red Hat Knowledgebase)]
|
||||
Reference in New Issue
Block a user