Managing KVM guests with virsh: list, start, shutdown versus destroy, and autostart

Goal

Inspect, start, stop and configure autostart for KVM guests managed by libvirt, using virsh, without corrupting the persistent domain definition.

Prerequisites

Root or membership in the libvirt group on the hypervisor host; the libvirtd (or socket-activated virtqemud) service running. Run as root, virsh connects to qemu:///system; run as an ordinary user it defaults to that user's private qemu:///session (unless LIBVIRT_DEFAULT_URI or the client config says otherwise), which does not show the system guests. Pass -c qemu:///system explicitly and confirm with virsh uri.

Steps

1. List guests: virsh list --all shows all defined domains and their state (running, shut off, paused). virsh list alone shows only running ones.
2. Inspect one guest: virsh dominfo <name> prints state, CPU count, memory, autostart flag and persistence. virsh domstate <name> prints only the state.
3. Start a defined-but-stopped guest: virsh start <name>.
4. Graceful stop: virsh shutdown <name> asks the guest OS to shut down and returns immediately; success is not guaranteed and can take a variable time. With QEMU the hypervisor picks the method (normally an ACPI power-button event, which the guest OS must handle); --mode agent uses the QEMU guest agent instead, if one runs in the guest. Poll virsh domstate <name> until it reports shut off.
5. Hard stop: virsh destroy <name> immediately terminates the domain without giving the guest OS any chance to react, equivalent to pulling the power cord; unflushed guest writes can be lost. Use it only when shutdown does not complete within a reasonable wait. It deletes no disks, and a persistent domain can be started again; a transient domain disappears once stopped, together with its snapshot metadata.
6. Enable or disable boot-time start of a persistent domain: virsh autostart <name> (libvirt starts the guest when the host boots) and virsh autostart --disable <name> to remove it.
7. Console access: virsh console <name> attaches to a serial console defined in the guest XML (requires a <console type='pty'> device and a getty configured inside the guest); exit with Ctrl+].
8. Domain definitions live as XML under /etc/libvirt/qemu/<name>.xml; do not hand-edit these files, since libvirt does not pick up such edits. Use virsh edit <name>, which opens the persistent (inactive) definition in $VISUAL/$EDITOR, error-checks it and redefines the domain on save; for a running guest the change takes effect only at its next boot. Back up first with virsh dumpxml --inactive <name> > <name>.xml; virsh dumpxml <name> shows the running definition.

Expected result

virsh dominfo <name> reflects the new state or autostart setting immediately; virsh list --all shows shut off after a destroy or once a shutdown has completed (not necessarily when virsh shutdown returns).

Limits and test basis

Behaviour depends on the guest OS reacting to the shutdown request; a guest that does not handle the ACPI power-button event (for example a minimal image with nothing listening for it, or a Windows guest whose power-button policy is set to do nothing) will not respond and needs an in-guest shutdown, --mode agent, or destroy. This module does not cover libvirt installation or network/storage pool setup beyond what is cited.