[EN] What Is Virsh? Tips for Managing Virtual Machines in KVM-Based Virtualization Environments – Veli Kadir KOZAN (IT Infrastructure Administrator)

If you use KVM/QEMU in Linux-based virtualization infrastructures, one of the most common tools you will encounter on the system administration side is the virsh command. Virsh is a powerful command-line tool used to manage virtual machines, virtual networks, storage pools, disk volumes, snapshots, checkpoints, host devices, and hypervisor connections through the libvirt infrastructure.

Virsh should not be considered only as a “virtual machine start and stop command.” This tool provides a very broad management scope, from the virtual machine lifecycle to CPU and memory configuration, disk management, network interface control, backup and migration operations, and QEMU Guest Agent commands.

In the official libvirt documentation, virsh is described as the main interface used to manage guest domains. In this context, the term domain usually means a virtual machine in practical usage. A domain can be managed by its name, ID, or UUID.

The general usage format is as follows:

virsh [OPTION]... <command> <domain> [ARG]...

For example:

virsh list --all
virsh dominfo web01
virsh shutdown web01

In these commands, web01 is the name of the virtual machine to be managed.

1. The Relationship Between Virsh and Libvirt

Behind virsh, there is libvirt. Libvirt is a management layer that allows communication with different virtualization technologies such as KVM/QEMU, Xen, LXC, OpenVZ, VirtualBox, and VMware ESX through a common API.

Thanks to this structure, a system administrator can manage different virtualization infrastructures with a single command-line tool: virsh. In KVM/QEMU environments, virsh mostly communicates with the hypervisor through libvirt daemon services.

The basic flow is as follows:

User -> virsh -> libvirt -> QEMU/KVM -> Virtual Machine

For this reason, libvirt services must be running on the system for virsh commands to work. In the official notes, it is also stated that most virsh operations require a connection to a running libvirtd service, and many commands may require root privileges because of the communication channels used with the hypervisor.

2. Ways to Use Virsh

Virsh can be used in two different ways.

The first method is to run a single command directly from the shell:

virsh list --all

This usage is ideal for scripts, automation, and quick checks.

The second method is to enter the interactive virsh shell:

virsh

Then commands can be executed inside the virsh prompt:

virsh # list --all
virsh # nodeinfo
virsh # quit

To exit interactive mode, use the quit or exit command.

3. Virsh Connection URIs

Virsh can connect to different hypervisor connections using a URI structure. In KVM/QEMU environments, the most commonly used connections are:

virsh -c qemu:///system

This connection is used to manage system-wide QEMU/KVM domains. It is generally preferred in server environments and usually requires root or an authorized user.

virsh -c qemu:///session

This connection is used for QEMU/KVM domains running under a regular user session.

To view the currently connected URI:

virsh uri

Common connection examples listed in the official manpage include xen:///system, qemu:///system, qemu:///session, and lxc:///system.

4. Virsh Global Options

Some global options can be used when running virsh:

Option	Description
`-c, --connect URI`	Connects to the specified libvirt URI.
`-d, --debug LEVEL`	Sets the debug level.
`-e, --escape string`	Changes the escape character for console connections.
`-h, --help`	Displays help output.
`-k, --keepalive-interval`	Sets the connection keepalive check interval.
`-K, --keepalive-count`	Sets how many unanswered keepalive messages are allowed before the connection is considered lost.
`-l, --log FILE`	Writes log output to a file.
`-q, --quiet`	Reduces unnecessary informational messages.
`-r, --readonly`	Opens a read-only connection.
`-t, --timing`	Shows the execution time of each command.
`--no-pkttyagent`	Does not enable the Polkit authentication agent.
`-v, --version`	Shows virsh/libvirt version information.
`-V, --version=long`	Shows version information along with build options and driver information.

Examples:

virsh -c qemu:///system list --all
virsh -r list --all
virsh -t dominfo web01
virsh --version
virsh -V

5. Generic Commands

These commands are not directly tied to a single virtual machine. They are generally used for connection management, host information, CPU compatibility, NUMA, hypervisor capabilities, and general virsh session operations. In the official manpage, this command group is listed as “Generic Commands.”

Command	Description
`help`	Shows all virsh commands or help for a specific command.
`quit`, `exit`	Exits the interactive virsh shell.
`version`	Shows virsh, libvirt, API, and hypervisor version information.
`cd`	Changes the current directory inside the virsh shell.
`pwd`	Shows the current working directory.
`connect`	Opens or changes the hypervisor connection.
`uri`	Shows the connected hypervisor URI.
`hostname`	Shows the hypervisor host name.
`sysinfo`	Shows hypervisor system information in XML format.
`nodeinfo`	Shows host CPU, memory, and basic hardware information.
`nodecpumap`	Shows the CPU map on the host.
`nodecpustats`	Shows host CPU statistics.
`nodememstats`	Shows host memory statistics.
`nodesevinfo`	Provides information about AMD SEV security features.
`nodesuspend`	Puts the host system into sleep mode.
`node-memory-tune`	Manages KSM/shared memory parameters on the host.
`capabilities`	Shows hypervisor and host capabilities in XML format.
`domcapabilities`	Shows domain creation capabilities in XML format.
`pool-capabilities`	Shows storage pool capabilities.
`inject-nmi`	Sends an NMI signal to a domain.
`list`	Lists domains.
`freecell`	Shows free memory information by NUMA cell.
`freepages`	Shows free page information by NUMA/page size.
`allocpages`	Used for hugepage/page allocation operations.
`cpu-baseline`	Produces a common CPU model from multiple CPU definitions.
`cpu-compare`	Compares a given CPU definition with the host CPU.
`cpu-models`	Lists known CPU models for a specific architecture.
`hypervisor-cpu-compare`	Compares CPU compatibility with hypervisor capabilities.
`hypervisor-cpu-baseline`	Produces a baseline CPU considering hypervisor capabilities.
`hypervisor-cpu-models`	Lists CPU models known by the hypervisor.

Examples:

virsh help
virsh version --daemon
virsh uri
virsh hostname
virsh nodeinfo
virsh capabilities
virsh list --all
virsh cpu-models x86_64

6. Domain Commands — Virtual Machine Management Commands

The most commonly used part of virsh is the Domain Commands group. In libvirt terminology, a domain usually means a virtual machine in practical usage. These commands are used to start and stop VMs, modify resources, retrieve disk and network information, manage snapshots, backups, migrations, guest agent operations, events, and debugging.

6.1 Lifecycle and Basic VM Management

Command	Description
`start`	Starts a defined but powered-off domain.
`shutdown`	Attempts a graceful shutdown by communicating with the guest OS.
`destroy`	Forces the VM to power off. It should be considered similar to a physical power-off.
`reboot`	Reboots the VM.
`reset`	Applies a hardware-like reset to the VM.
`suspend`	Pauses a running domain in memory.
`resume`	Resumes a suspended domain.
`save`	Saves the running VM state to a file.
`restore`	Restores a VM state previously created with `save`.
`managedsave`	Saves the VM state in a libvirt-managed way.
`managedsave-remove`	Deletes the managed save image.
`managedsave-define`	Changes the managed save state XML definition.
`managedsave-dumpxml`	Shows the managed save XML information.
`managedsave-edit`	Edits the managed save XML information.
`undefine`	Removes the domain definition from libvirt.
`autostart`	Configures the VM to start automatically when the host boots.
`domrename`	Renames an inactive domain.

Examples:

virsh start web01
virsh shutdown web01
virsh destroy web01
virsh reboot web01
virsh suspend web01
virsh resume web01
virsh autostart web01
virsh autostart web01 --disable

shutdown attempts a graceful shutdown, while destroy forces the VM to power off. Therefore, in production systems, shutdown should be tried first, and destroy should be used only as a last resort.

6.2 Domain Creation and XML Management

Command	Description
`create`	Starts a temporary or one-time domain from an XML file.
`define`	Registers the domain definition from an XML file in libvirt but does not start it.
`dumpxml`	Shows the domain XML configuration.
`edit`	Edits the domain XML configuration with an editor.
`desc`	Shows or changes the domain description or title.
`metadata`	Manages custom XML metadata on the domain.
`domxml-from-native`	Converts native hypervisor format to libvirt XML format.
`domxml-to-native`	Converts libvirt XML format to native hypervisor format.

Examples:

virsh dumpxml web01 > web01.xml
virsh define web01.xml
virsh create web01.xml
virsh edit web01
virsh desc web01

The define command creates a persistent definition, while create starts a domain from XML. When XML changes are made on a running domain, some settings may only take effect after the next reboot.

6.3 Domain Information and Status Commands

Command	Description
`dominfo`	Shows basic information about a domain.
`domstate`	Shows the state of a domain.
`domstats`	Shows CPU, memory, disk, and network statistics.
`domid`	Finds the ID from a domain name or UUID.
`domname`	Finds the domain name from a domain ID or UUID.
`domuuid`	Shows the domain UUID.
`domhostname`	Shows the domain hostname.
`domtime`	Gets or sets guest time information.
`domcontrol`	Shows the state of the domain control interface.
`domdisplay`	Shows graphical console connection information.
`domdisplay-reload`	Reloads graphical display configuration.
`ttyconsole`	Shows the domain TTY console device.
`vncdisplay`	Shows VNC display information.
`dommemstat`	Shows domain memory statistics.

Examples:

virsh dominfo web01
virsh domstate web01 --reason
virsh domstats web01
virsh domuuid web01
virsh dommemstat web01
virsh vncdisplay web01

6.4 CPU, Memory, NUMA, and Performance Commands

Command	Description
`cpu-stats`	Shows domain CPU statistics.
`vcpucount`	Shows the number of vCPUs on the domain.
`vcpuinfo`	Lists vCPU details.
`vcpupin`	Pins vCPUs to specific physical CPUs.
`setvcpus`	Changes the number of vCPUs for a domain.
`setvcpu`	Enables or disables specific vCPUs.
`maxvcpus`	Shows the maximum number of vCPUs supported by the hypervisor.
`emulatorpin`	Pins emulator threads to specific CPUs.
`iothreadadd`	Adds an IOThread to the domain.
`iothreaddel`	Removes an IOThread from the domain.
`iothreadinfo`	Shows IOThread information.
`iothreadpin`	Pins an IOThread to a CPU.
`iothreadset`	Changes IOThread parameters.
`memtune`	Shows or changes domain memory tuning parameters.
`setmem`	Changes the domain memory.
`setmaxmem`	Sets the maximum memory limit for the domain.
`numatune`	Configures the NUMA memory placement policy.
`perf`	Manages domain performance event counters.
`schedinfo`	Shows or changes scheduler parameters.

Examples:

virsh vcpuinfo web01
virsh vcpucount web01
virsh setvcpus web01 4 --config
virsh setmem web01 8G --config
virsh setmaxmem web01 16G --config
virsh vcpupin web01 0 0-3
virsh numatune web01
virsh perf web01

When changing CPU and memory settings, the effect of --live, --config, and --current parameters must be well understood. --live affects the running VM, while --config affects the persistent configuration.

6.5 Disk, Block Device, and I/O Commands

Command	Description
`domblklist`	Lists disks attached to the domain.
`domblkinfo`	Shows capacity and size information for a specific disk.
`domblkstat`	Shows disk I/O statistics.
`domblkerror`	Shows disk-related errors.
`domblkthreshold`	Configures threshold events for a block device.
`blkdeviotune`	Sets I/O limits for a specific block device.
`blkiotune`	Performs block I/O tuning at the domain level.
`blockresize`	Resizes the disk of a running domain.
`blockcopy`	Copies a running domain disk to another target.
`blockcommit`	Commits backing chain content to another layer.
`blockpull`	Pulls data from the backing chain into the active image.
`blockjob`	Monitors, cancels, or manages ongoing block jobs.
`domthrottlegroupset`	Configures a disk throttle group.
`domthrottlegroupdel`	Deletes a disk throttle group.
`domthrottlegroupinfo`	Shows throttle group information.
`domthrottlegrouplist`	Lists throttle groups.

Examples:

virsh domblklist web01
virsh domblklist web01 --details
virsh domblkinfo web01 vda
virsh domblkstat web01 vda
virsh domblkerror web01
virsh blockresize web01 vda 100G --extend
virsh blockjob web01 vda --info

When a disk is expanded with blockresize, partition and filesystem expansion must also be performed inside the guest OS. The --extend option is important to prevent accidental shrinking and possible data loss.

6.6 Network Interface Commands

Command	Description
`domiflist`	Lists network interfaces attached to the domain.
`domifaddr`	Shows domain interface IP/MAC addresses.
`domifstat`	Shows interface traffic statistics.
`domiftune`	Manages interface bandwidth/tuning settings.
`domif-getlink`	Shows interface link status.
`domif-setlink`	Sets interface link status up or down.
`domifannounce`	Announces interface information on the network.

Examples:

virsh domiflist web01
virsh domifaddr web01
virsh domifstat web01 vnet0
virsh domif-getlink web01 vnet0
virsh domif-setlink web01 vnet0 down
virsh domif-setlink web01 vnet0 up

The domifaddr command may retrieve IP information from DHCP leases, ARP, or QEMU Guest Agent. Therefore, in some environments, the guest agent must be installed for accurate results.

6.7 Guest Agent and Retrieving Information from the Guest

Command	Description
`guestinfo`	Shows OS, disk, filesystem, and interface information through the guest agent.
`guestvcpus`	Shows or changes vCPU status from the guest OS perspective.
`guest-agent-timeout`	Manages timeout values for guest agent commands.
`get-user-sshkeys`	Retrieves SSH key information for a user inside the guest.
`set-user-sshkeys`	Changes SSH key information for a user inside the guest.
`set-user-password`	Changes the password of a user inside the guest.

Examples:

virsh guestinfo web01
virsh guestvcpus web01
virsh guest-agent-timeout web01
virsh get-user-sshkeys web01 root
virsh set-user-password web01 root 'NewPassword'

Many of these commands produce meaningful results only when QEMU Guest Agent is installed and running inside the guest.

6.8 Filesystem Commands

Command	Description
`domfsfreeze`	Freezes guest filesystems. Used before backup operations.
`domfsthaw`	Thaws frozen filesystems.
`domfsinfo`	Shows the list of mounted filesystems inside the guest.
`domfstrim`	Runs TRIM/discard on the guest filesystem.

Examples:

virsh domfsfreeze web01
virsh domfsthaw web01
virsh domfsinfo web01
virsh domfstrim web01

For backup and snapshot operations, domfsfreeze and domfsthaw are important for filesystem consistency.

6.9 Domain Commands Related to Backup and Checkpoints

Command	Description
`backup-begin`	Starts a backup job for the domain.
`backup-dumpxml`	Shows XML information for an ongoing or created backup job.

Examples:

virsh backup-begin web01 backup.xml
virsh backup-dumpxml web01

These commands are generally used in incremental backup, checkpoint-based backup, and automation scenarios.

6.10 Migration Commands

Command	Description
`migrate`	Migrates a domain to another host.
`migrate-compcache`	Manages migration compression cache settings.
`migrate-getmaxdowntime`	Shows maximum downtime information for live migration.
`migrate-setmaxdowntime`	Sets maximum downtime for live migration.
`migrate-getspeed`	Shows migration bandwidth/speed limit.
`migrate-setspeed`	Sets migration bandwidth/speed limit.
`migrate-postcopy`	Switches an ongoing migration to post-copy mode.

Examples:

virsh migrate --live web01 qemu+ssh://kvm02/system
virsh migrate-getspeed web01
virsh migrate-setspeed web01 100
virsh migrate-getmaxdowntime web01
virsh migrate-setmaxdowntime web01 500
virsh migrate-postcopy web01

In migration operations, CPU compatibility, storage architecture, network bandwidth, libvirt/QEMU version compatibility, and shared storage status must be carefully evaluated.

6.11 Console, Event, Debug, and Advanced Domain Commands

Command	Description
`console`	Opens a serial console connection to the domain.
`screenshot`	Takes a screenshot of the domain.
`send-key`	Sends a keyboard key combination to the guest.
`send-process-signal`	Sends a signal to a process inside the guest.
`dump`	Takes a domain memory/core dump.
`event`	Monitors domain events.
`await`	Waits for a specific event or state on the domain.
`domjobinfo`	Shows information about a job running on the domain.
`domjobabort`	Cancels an ongoing domain job.
`domdirtyrate-calc`	Calculates dirty page rate for live migration.
`domlaunchsecinfo`	Shows launch security information.
`domsetlaunchsecstate`	Sets launch security state.
`set-lifecycle-action`	Changes domain lifecycle event behavior.
`dompmsuspend`	Puts the guest into power management suspend mode.
`dompmwakeup`	Wakes a guest from power management suspend state.

Examples:

virsh console web01
virsh screenshot web01 /tmp/web01.ppm
virsh send-key web01 KEY_LEFTCTRL KEY_LEFTALT KEY_DELETE
virsh event web01 --loop
virsh domjobinfo web01
virsh domjobabort web01
virsh domdirtyrate-calc web01

7. Device Commands — Virtual Machine Device Management

Device commands are used to add, remove, and update disks, network interfaces, CD-ROMs, PCI devices, or other devices defined by XML.

Command	Description
`attach-device`	Adds a device definition from an XML file to the domain.
`attach-disk`	Adds a disk to the domain.
`attach-interface`	Adds a network interface to the domain.
`detach-device`	Removes a device specified by XML from the domain.
`detach-device-alias`	Removes a device by alias.
`detach-disk`	Removes a disk from the domain.
`detach-interface`	Removes a network interface from the domain.
`update-device`	Updates an existing device configuration using XML.
`update-memory-device`	Updates memory device configuration.
`change-media`	Changes removable media such as CD-ROM or floppy.
`dom-fd-associate`	Associates a file descriptor with a domain.

Examples:

virsh attach-disk web01 /var/lib/libvirt/images/data.qcow2 vdb --persistent
virsh detach-disk web01 vdb --persistent
virsh attach-interface web01 network default --model virtio --persistent
virsh detach-interface web01 network --mac 52:54:00:aa:bb:cc --persistent
virsh change-media web01 hdc /iso/ubuntu.iso

8. Nodedev Commands — Host Hardware Devices

Nodedev commands are used to manage physical or virtual devices on the host. They are important in scenarios such as PCI passthrough, SR-IOV, and mediated devices.

Command	Description
`nodedev-create`	Creates a transient node device from XML.
`nodedev-update`	Updates node device information.
`nodedev-destroy`	Stops or destroys a node device.
`nodedev-define`	Creates a node device definition.
`nodedev-undefine`	Removes a node device definition.
`nodedev-start`	Starts a defined node device.
`nodedev-detach`	Detaches a device from the host driver and prepares it for VM passthrough.
`nodedev-dumpxml`	Shows node device XML output.
`nodedev-info`	Shows information about a node device.
`nodedev-list`	Lists node devices on the host.
`nodedev-reattach`	Reattaches a detached device to the host driver.
`nodedev-reset`	Resets a node device.
`nodedev-event`	Monitors node device events.
`nodedev-autostart`	Manages node device autostart settings.

Examples:

virsh nodedev-list
virsh nodedev-dumpxml pci_0000_03_00_0
virsh nodedev-info pci_0000_03_00_0
virsh nodedev-detach pci_0000_03_00_0
virsh nodedev-reattach pci_0000_03_00_0
virsh nodedev-reset pci_0000_03_00_0

Detaching the wrong device may affect host access or storage/network connectivity. These commands must be used carefully.

9. Virtual Network Commands

Libvirt can create NAT, routed, isolated, or bridge-based virtual network structures for virtual machines. These structures can be managed with virsh.

Command	Description
`net-autostart`	Configures the network to start automatically when the host boots.
`net-create`	Starts a temporary network from an XML file.
`net-define`	Defines a persistent network from an XML file.
`net-desc`	Manages the network description or title.
`net-destroy`	Stops an active network.
`net-dumpxml`	Shows network XML information.
`net-edit`	Edits network XML configuration.
`net-event`	Monitors network events.
`net-info`	Shows basic information about a network.
`net-list`	Lists networks.
`net-metadata`	Manages custom XML metadata for a network.
`net-name`	Finds the network name from a UUID.
`net-start`	Starts a defined network.
`net-undefine`	Deletes the network definition.
`net-uuid`	Shows the network UUID.
`net-update`	Updates network configuration at runtime or config level.
`net-dhcp-leases`	Shows DHCP lease records on the network.

Examples:

virsh net-list --all
virsh net-info default
virsh net-start default
virsh net-autostart default
virsh net-dumpxml default
virsh net-edit default
virsh net-dhcp-leases default

net-dhcp-leases is very useful for viewing IP addresses assigned to VMs in NAT network environments.

10. Network Port Commands

These commands are used to manage libvirt network port objects.

Command	Description
`net-port-list`	Lists ports on a specific network.
`net-port-create`	Creates a network port from XML.
`net-port-dumpxml`	Shows network port XML output.
`net-port-delete`	Deletes a network port.

Examples:

virsh net-port-list default
virsh net-port-dumpxml default <PORT_UUID>
virsh net-port-delete default <PORT_UUID>

11. Interface Commands — Host Network Interface Management

These commands are used to manage network interface configurations on the host. Incorrect bridge or interface operations may cut off host access.

Command	Description
`iface-bridge`	Places a physical interface into a bridge.
`iface-define`	Defines an interface from XML.
`iface-destroy`	Stops an interface.
`iface-dumpxml`	Shows interface XML information.
`iface-edit`	Edits interface XML configuration.
`iface-list`	Lists host interfaces.
`iface-name`	Finds the interface name from a MAC address.
`iface-mac`	Finds the MAC address from an interface name.
`iface-start`	Starts an interface.
`iface-unbridge`	Removes bridge configuration.
`iface-undefine`	Deletes the interface definition.
`iface-begin`	Starts a transaction for interface changes.
`iface-commit`	Applies interface transaction changes.
`iface-rollback`	Rolls back interface transaction changes.

Examples:

virsh iface-list --all
virsh iface-dumpxml eno1
virsh iface-bridge eno1 br0
virsh iface-unbridge br0
virsh iface-begin
virsh iface-commit
virsh iface-rollback

On production servers managed remotely, these commands should not be used outside a maintenance window.

12. Storage Pool Commands

A storage pool is the logical storage area where libvirt keeps disk images or volumes. Different pool types can be used, such as directory, filesystem, iSCSI, LVM, RBD, ZFS, or Gluster.

Command	Description
`find-storage-pool-sources`	Discovers sources for a specific pool type.
`find-pool-sources-as`	Searches for pool sources using parameters.
`pool-autostart`	Configures the pool to start automatically.
`pool-build`	Prepares the required infrastructure for the pool.
`pool-create`	Creates and starts a temporary pool from XML.
`pool-create-as`	Creates a temporary pool using parameters.
`pool-define`	Defines a persistent pool from XML.
`pool-define-as`	Defines a persistent pool using parameters.
`pool-destroy`	Stops the pool; it does not delete the data inside.
`pool-delete`	Deletes pool sources; this may be irreversible.
`pool-dumpxml`	Shows pool XML information.
`pool-edit`	Edits pool XML configuration.
`pool-info`	Shows basic information about a pool.
`pool-list`	Lists pools.
`pool-name`	Finds the pool name from a UUID.
`pool-refresh`	Refreshes the volume list inside the pool.
`pool-start`	Starts a defined but inactive pool.
`pool-undefine`	Deletes the inactive pool definition.
`pool-uuid`	Shows the pool UUID.
`pool-event`	Monitors pool events.

Examples:

virsh pool-list --all
virsh pool-info default
virsh pool-refresh default
virsh pool-start default
virsh pool-autostart default
virsh pool-dumpxml default
virsh pool-edit default

pool-destroy only stops the pool, while pool-delete may delete the pool resources. This distinction is critical to prevent data loss.

13. Volume Commands — Disk Image and Volume Management

A volume is a disk image or block device located inside a storage pool.

Command	Description
`vol-create`	Creates a volume from XML.
`vol-create-from`	Creates a new volume from an existing volume.
`vol-create-as`	Creates a volume using parameters.
`vol-clone`	Clones a volume.
`vol-delete`	Deletes a volume.
`vol-upload`	Uploads data from a file into a volume.
`vol-download`	Downloads volume content to a file.
`vol-wipe`	Securely wipes volume content.
`vol-dumpxml`	Shows volume XML information.
`vol-info`	Shows information about a volume.
`vol-list`	Lists volumes inside a pool.
`vol-pool`	Shows the pool to which the volume belongs.
`vol-path`	Shows the volume path.
`vol-name`	Shows the volume name.
`vol-key`	Shows the volume key.
`vol-resize`	Resizes a volume.

Examples:

virsh vol-list default
virsh vol-info web01.qcow2 --pool default
virsh vol-path web01.qcow2 --pool default
virsh vol-create-as default data01.qcow2 100G --format qcow2
virsh vol-clone web01.qcow2 web01-clone.qcow2 --pool default
virsh vol-delete data01.qcow2 --pool default

Since vol-delete may directly delete a disk image, the pool name, volume name, and path information must be verified before running it.

14. Secret Commands

The libvirt secret structure is used to store credentials in scenarios such as Ceph/RBD, iSCSI CHAP, disk encryption, and similar use cases.

Command	Description
`secret-define`	Defines a secret from XML.
`secret-dumpxml`	Shows secret XML information.
`secret-event`	Monitors secret events.
`secret-set-value`	Sets the secret value.
`secret-get-value`	Shows the secret value.
`secret-undefine`	Deletes the secret record.
`secret-list`	Lists secrets.

Examples:

virsh secret-list
virsh secret-dumpxml <SECRET_UUID>
virsh secret-set-value <SECRET_UUID> --file secret.txt
virsh secret-get-value <SECRET_UUID>

Providing sensitive values such as passwords or keys directly on the command line is not recommended for security reasons. Passing them through a file is a better approach.

15. Snapshot Commands

A snapshot is used to save the disk, memory, and device state of a domain at a specific point in time. It is useful for creating a rollback point before updates or for quick recovery in test environments.

Command	Description
`snapshot-create`	Creates a snapshot using an XML file.
`snapshot-create-as`	Creates a snapshot using parameters.
`snapshot-current`	Shows or changes the current snapshot information.
`snapshot-edit`	Edits snapshot XML information.
`snapshot-info`	Shows information about a snapshot.
`snapshot-list`	Lists domain snapshots.
`snapshot-dumpxml`	Shows snapshot XML output.
`snapshot-parent`	Shows the parent snapshot information.
`snapshot-revert`	Reverts the domain to a snapshot.
`snapshot-delete`	Deletes a snapshot.

Examples:

virsh snapshot-create-as web01 before-update "Snapshot before patching"
virsh snapshot-list web01
virsh snapshot-info web01 before-update
virsh snapshot-dumpxml web01 before-update
virsh snapshot-revert web01 before-update
virsh snapshot-delete web01 before-update

snapshot-revert may cause changes made after the snapshot to be lost. It must be used carefully in production systems.

16. Checkpoint Commands — Checkpoint Management for Incremental Backup

A checkpoint is mainly used in incremental backup scenarios to track which blocks have changed.

Command	Description
`checkpoint-create`	Creates a checkpoint from XML.
`checkpoint-create-as`	Creates a checkpoint using parameters.
`checkpoint-edit`	Edits checkpoint XML information.
`checkpoint-info`	Shows information about a checkpoint.
`checkpoint-list`	Lists checkpoints.
`checkpoint-dumpxml`	Shows checkpoint XML output.
`checkpoint-parent`	Shows parent checkpoint information.
`checkpoint-delete`	Deletes a checkpoint.

Examples:

virsh checkpoint-create-as web01 backup-checkpoint-01
virsh checkpoint-list web01
virsh checkpoint-info web01 backup-checkpoint-01
virsh checkpoint-dumpxml web01 backup-checkpoint-01
virsh checkpoint-delete web01 backup-checkpoint-01

While snapshots are used as rollback points, checkpoints are more important for incremental backup and changed block tracking.

17. NWFilter Commands — Network Filter Management

NWFilter is used to apply filtering rules on virtual machine network traffic. It can be used in security scenarios such as preventing MAC spoofing or IP spoofing.

Command	Description
`nwfilter-define`	Defines a network filter from XML.
`nwfilter-undefine`	Deletes a network filter.
`nwfilter-list`	Lists network filters.
`nwfilter-dumpxml`	Shows network filter XML output.
`nwfilter-edit`	Edits network filter XML information.

Examples:

virsh nwfilter-list
virsh nwfilter-dumpxml clean-traffic
virsh nwfilter-edit clean-traffic
virsh nwfilter-define filter.xml
virsh nwfilter-undefine filter-name

An incorrect NWFilter rule may cut off network access for a VM. XML output should be backed up before making changes.

18. NWFilter Binding Commands

These commands manage binding relationships between a network port and a network filter.

Command	Description
`nwfilter-binding-create`	Creates a binding between a network port and a network filter.
`nwfilter-binding-delete`	Removes the filter binding relationship from a port.
`nwfilter-binding-list`	Lists ports with applied filter bindings.
`nwfilter-binding-dumpxml`	Shows binding XML information.

Examples:

virsh nwfilter-binding-list
virsh nwfilter-binding-dumpxml <PORT_DEVICE>
virsh nwfilter-binding-create binding.xml
virsh nwfilter-binding-delete <PORT_DEVICE>

These commands are generally used in advanced network security and custom TAP/port filtering scenarios.

19. Hypervisor-Specific Commands

These commands directly interact with the hypervisor layer, such as QEMU or LXC. They are not intended for daily use; they are mostly used for advanced troubleshooting and special scenarios.

Command	Description
`qemu-attach`	Attaches an externally started QEMU process to libvirt management.
`qemu-monitor-command`	Runs a QEMU monitor command.
`qemu-agent-command`	Sends a direct command to QEMU Guest Agent.
`qemu-monitor-event`	Monitors QEMU monitor events.
`lxc-enter-namespace`	Enters the namespace of an LXC domain.

Examples:

virsh qemu-monitor-command web01 --hmp "info block"
virsh qemu-agent-command web01 '{"execute":"guest-info"}'
virsh qemu-monitor-event web01 --loop
virsh lxc-enter-namespace container01 -- /bin/bash

These commands may bypass libvirt’s normal management layer and lead to unexpected results. Therefore, they should only be used by experienced administrators and only when necessary.

20. Most Useful Virsh Commands for Daily Use

The following commands are among the most commonly used by a KVM/libvirt administrator in daily operations:

virsh list --all
virsh dominfo VM_NAME
virsh domstate VM_NAME --reason
virsh start VM_NAME
virsh shutdown VM_NAME
virsh reboot VM_NAME
virsh destroy VM_NAME
virsh dumpxml VM_NAME > VM_NAME.xml
virsh edit VM_NAME
virsh autostart VM_NAME
virsh domiflist VM_NAME
virsh domifaddr VM_NAME
virsh domblklist VM_NAME
virsh domblkinfo VM_NAME vda
virsh vcpuinfo VM_NAME
virsh setvcpus VM_NAME 4 --config
virsh setmem VM_NAME 8G --config
virsh console VM_NAME
virsh snapshot-list VM_NAME
virsh net-list --all
virsh pool-list --all
virsh vol-list default

These commands form the basic toolset for checking VM status, resource usage, disks, networking, snapshots, and storage.

21. Practical Virsh Flow for Troubleshooting

When a VM-related issue occurs, the following sequence can be used for initial checks:

virsh list --all

Checks whether the VM is running, powered off, or paused.

virsh dominfo VM_NAME

Retrieves basic VM information.

virsh domstate VM_NAME --reason

Checks the reason for the VM state.

virsh domblklist VM_NAME --details

Checks disks and attached block devices.

virsh domblkerror VM_NAME

Checks whether there are disk-related errors.

virsh domiflist VM_NAME

Examines network interface connections.

virsh domifaddr VM_NAME

Attempts to retrieve the VM IP address.

virsh pool-list --all

Checks storage pool status.

virsh vol-list default

Examines disk volumes.

virsh dumpxml VM_NAME > VM_NAME.xml

Backs up the VM XML configuration.

This flow is very useful for the initial analysis of most basic KVM/libvirt issues.

22. Critical Commands to Use Carefully

Virsh is a very powerful tool. Therefore, some commands may cause data loss, service interruption, or loss of management access.

Command	Risk
`destroy`	Forces the VM to power off and may cause data loss.
`undefine`	Removes the domain definition; with additional options, it may also affect disks.
`pool-delete`	May delete storage pool resources.
`vol-delete`	May delete disk images.
`snapshot-revert`	Reverts the VM to an older state; later changes may be lost.
`iface-bridge` / `iface-unbridge`	Incorrect usage may cut off host network access.
`nodedev-detach`	Detaching the wrong device may affect host hardware access.
`qemu-monitor-command`	May bypass the libvirt management layer and cause unexpected results.
`domjobabort`	May interrupt an ongoing critical job.

Before running these commands, XML backups should be taken if possible, storage paths should be verified, and maintenance windows should be preferred in production environments.

23. Conclusion

Virsh is one of the most comprehensive and flexible command-line management tools in libvirt-based virtualization environments. In KVM/QEMU infrastructures, it is used not only to start or stop virtual machines, but also to manage CPU, memory, disk, networking, storage pools, volumes, snapshots, checkpoints, backups, migrations, guest agents, and many hypervisor-level operations.

In small environments, a few basic commands may be enough. However, in large KVM infrastructures, virsh becomes an essential part of automation, troubleshooting, migration, backup integration, performance management, and daily operations.

When used correctly, it is fast and powerful. When used incorrectly, it may cause outages, data loss, or management access problems in running systems. Therefore, commands such as destroy, undefine, pool-delete, vol-delete, snapshot-revert, iface-*, nodedev-*, and hypervisor-specific commands must be used carefully.

In summary, virsh is a professional management tool that provides full command-line control in the KVM/libvirt world. Learning virsh commands provides a significant advantage for anyone who wants to better understand virtualization infrastructure, solve problems faster, and strengthen operations with automation.