neulab/tldr huggingface dataset:
Normally only statistics for running and successful completed jobs are printed.  --anystats can be used to also display statistics for failed jobs.
In case --rawstats is used, all fields are printed as received from the server without any attempts to interpret the data. The "Job type:" field is special, since it's reported by the API and not part of stats.
Note that time information returned for completed migrations may be completely irrelevant unless both source and destination hosts have synchronized time (i.e., NTP daemon is running on both of them).
dommemstat Syntax:
dommemstat domain [--period seconds] [[--config] [--live] | [--current]]
Get memory stats for a running domain.
Explanation of fields:
• swap_in           - The amount of data read from swap space (in KiB)
• swap_out          - The amount of memory written out to swap space (in KiB)
• major_fault       - The number of page faults where disk IO was required
• minor_fault       - The number of other page faults
• unused            - The amount of memory left unused by the system (in KiB)
• available         - The amount of usable memory as seen by the domain (in KiB)
• actual            - Current balloon value (in KiB)
• rss               - Resident Set Size of the running domain's process (in KiB)
• usable            - The amount of memory which can be reclaimed by balloon without causing host swapping (in KiB)
• last-update       - Timestamp of the last update of statistics (in seconds)
• disk_caches       - The amount of memory that can be reclaimed without additional I/O, typically disk caches (in KiB)
• hugetlb_pgalloc   - The number of successful huge page allocations initiated from within the domain
• hugetlb_pgfail    - The number of failed huge page allocations initiated from within the domain
For QEMU/KVM with a memory balloon, setting the optional --period to a value larger than 0 in seconds will allow the balloon driver to return additional statistics which will be displayed by subsequent dommemstat commands. Setting the --period to 0 will stop the balloon driver collection, but does not clear the statistics in the balloon driver. Requires at least QEMU/KVM 1.5 to be running on the host.
The --live, --config, and --current flags are only valid when using the --period option in order to set the collection period for the balloon driver. If --live is specified, only the running guest collection period is affected. If --config is specified, affect the next start of a persistent guest. If --current is specified, it is equivalent to either --live or --config, depending on the current state of the guest.
Both --live and --config flags may be given, but --current is exclusive. If no flag is specified, behavior is different depending on the guest state.
domname Syntax:
domname domain-id-or-uuid
Convert a domain Id (or UUID) to domain name
dompmsuspend Syntax:
dompmsuspend domain target [--duration]
Suspend a running domain into one of these states (possible target values):
• mem - equivalent of S3 ACPI state
• disk - equivalent of S4 ACPI state
• hybrid - RAM is saved to disk but not powered off
The --duration argument specifies number of seconds before the domain is woken up after it was suspended (see also dompmwakeup). Default is 0 for unlimited suspend time. (This feature isn't currently supported by any hypervisor driver and 0 should be used.).
Beware that at least for QEMU, the domain's process will be terminated when target disk is used and a new process will be launched when libvirt is asked to wake up the domain. As a result of this, any runtime changes, such as device hotplug or memory settings, are lost unless such changes were made with --config flag.
dompmwakeup Syntax:
dompmwakeup domain
Wakeup a domain from pmsuspended state (either suspended by dompmsuspend or from the guest itself). Injects a wakeup into the guest that is in pmsuspended state, rather than waiting for the previously requested duration (if any) to elapse. This operation does not necessarily fail if the domain is running.
domrename Syntax:
domrename domain new-name
Rename a domain. This command changes current domain name to the new name specified in the second argument.
Note: Domain must be inactive.
domstate Syntax:
domstate domain [--reason]
Returns state about a domain.  --reason tells virsh to also print reason for the state.
domstats Syntax:
domstats [--raw] [--enforce] [--backing] [--nowait] [--state] [--cpu-total] [--balloon] [--vcpu] [--interface] [--block] [--perf] [--iothread] [--memory] [--dirtyrate] [[--list-active] [--list-inactive] [--list-persistent] [--list-transient] [--list-running]y [--list-paused] [--list-shutoff] [--list-other]] | [domain ...]
Get statistics for multiple or all domains. Without any argument this command prints all available statistics for all domains.
The list of domains to gather stats for can be either limited by listing the domains as a space separated list, or by specifying one of the filtering flags --list-NNN. (The approaches can't be combined.)
By default some of the returned fields may be converted to more human friendly values by a set of pretty-printers. To suppress this behavior use the --raw flag.
The individual statistics groups are selectable via specific flags. By default all supported statistics groups are returned. Supported statistics groups flags are: --state, --cpu-total, --balloon, --vcpu, --interface, --block, --perf, --iothread, --memory, --dirtyrate.
Note that - depending on the hypervisor type and version or the domain state - not all of the following statistics may be returned.
When selecting the --state group the following fields are returned:
• state.state - state of the VM, returned as number from virDomainState enum
• state.reason - reason for entering given state, returned as int from virDomain*Reason enum corresponding to given state
--cpu-total returns:
• cpu.time - total cpu time spent for this domain in nanoseconds
• cpu.user - user cpu time spent in nanoseconds
• cpu.system - system cpu time spent in nanoseconds
• cpu.haltpoll.success.time - cpu halt polling success time spent in nanoseconds
• cpu.haltpoll.fail.time - cpu halt polling fail time spent in nanoseconds
• cpu.cache.monitor.count - the number of cache monitors for this domain
• cpu.cache.monitor.<num>.name - the name of cache monitor <num>
• cpu.cache.monitor.<num>.vcpus - vcpu list of cache monitor <num>
• cpu.cache.monitor.<num>.bank.count - the number of cache banks in cache monitor <num>
• cpu.cache.monitor.<num>.bank.<index>.id - host allocated cache id for bank <index> in cache monitor <num>
• cpu.cache.monitor.<num>.bank.<index>.bytes - the number of bytes of last level cache that the domain is using on cache bank <index>
--balloon returns:
• balloon.current - the memory in KiB currently used
• balloon.maximum - the maximum memory in KiB allowed
• balloon.swap_in - the amount of data read from swap space (in KiB)
• balloon.swap_out - the amount of memory written out to swap space (in KiB)
• balloon.major_fault - the number of page faults when disk IO was required
• balloon.minor_fault - the number of other page faults
• balloon.unused - the amount of memory left unused by the system (in KiB)
• balloon.available - the amount of usable memory as seen by the domain (in KiB)
• balloon.rss - Resident Set Size of running domain's process (in KiB)
• balloon.usable - the amount of memory which can be reclaimed by balloon without causing host swapping (in KiB)
• balloon.last-update - timestamp of the last update of statistics (in seconds)
• balloon.disk_caches - the amount of memory that can be reclaimed without additional I/O, typically disk (in KiB)
• balloon.hugetlb_pgalloc - the number of successful huge page allocations from inside the domain via virtio balloon
• balloon.hugetlb_pgfail - the number of failed huge page allocations from inside the domain via virtio balloon
--vcpu returns:
• vcpu.current - current number of online virtual CPUs
• vcpu.maximum - maximum number of online virtual CPUs
• vcpu.<num>.state - state of the virtual CPU <num>, as number from virVcpuState enum
• vcpu.<num>.time - virtual cpu time spent by virtual CPU <num> (in microseconds)
• vcpu.<num>.wait - virtual cpu time spent by virtual CPU <num> waiting on I/O (in microseconds)
• vcpu.<num>.halted - virtual CPU <num> is halted: yes or no (may indicate the processor is idle or even disabled, depending on the architecture)
• vcpu.<num>.delay - time the vCPU <num> thread was enqueued by the host scheduler, but was waiting in the queue instead of running.  Exposed to the VM as a steal time.
--interface returns:
• net.count - number of network interfaces on this domain
• net.<num>.name - name of the interface <num>
• net.<num>.rx.bytes - number of bytes received
• net.<num>.rx.pkts - number of packets received
• net.<num>.rx.errs - number of receive errors
• net.<num>.rx.drop - number of receive packets dropped
• net.<num>.tx.bytes - number of bytes transmitted
• net.<num>.tx.pkts - number of packets transmitted
• net.<num>.tx.errs - number of transmission errors
• net.<num>.tx.drop - number of transmit packets dropped
--perf returns the statistics of all enabled perf events:
• perf.cmt - the cache usage in Byte currently used
• perf.mbmt - total system bandwidth from one level of cache
• perf.mbml - bandwidth of memory traffic for a memory controller
• perf.cpu_cycles - the count of cpu cycles (total/elapsed)
• perf.instructions - the count of instructions
• perf.cache_references - the count of cache hits
• perf.cache_misses - the count of caches misses
• perf.branch_instructions - the count of branch instructions
• perf.branch_misses - the count of branch misses
• perf.bus_cycles - the count of bus cycles
• perf.stalled_cycles_frontend - the count of stalled frontend cpu cycles
• perf.stalled_cycles_backend - the count of stalled backend cpu cycles
• perf.ref_cpu_cycles - the count of ref cpu cycles
• perf.cpu_clock - the count of cpu clock time
• perf.task_clock - the count of task clock time
• perf.page_faults - the count of page faults
• perf.context_switches - the count of context switches
• perf.cpu_migrations - the count of cpu migrations
• perf.page_faults_min - the count of minor page faults
• perf.page_faults_maj - the count of major page faults
• perf.alignment_faults - the count of alignment faults
• perf.emulation_faults - the count of emulation faults
See the perf command for more details about each event.
--block returns information about disks associated with each domain. Using the --backing flag extends this information to cover all resources in the backing chain, rather than the default of limiting information to the active layer for each guest disk.  Information listed includes:
• block.count - number of block devices being listed
• block.<num>.name - name of the target of the block device <num> (the same name for multiple entries if --backing is present)
• block.<num>.backingIndex - when --backing is present, matches up with the <backingStore> index listed in domain XML for backing files
• block.<num>.path - file source of block device <num>, if it is a local file or block device
• block.<num>.rd.reqs - number of read requests
• block.<num>.rd.bytes - number of read bytes
• block.<num>.rd.times - total time (ns) spent on reads
• block.<num>.wr.reqs - number of write requests
• block.<num>.wr.bytes - number of written bytes
• block.<num>.wr.times - total time (ns) spent on writes
• block.<num>.fl.reqs - total flush requests
• block.<num>.fl.times - total time (ns) spent on cache flushing
• block.<num>.errors - Xen only: the 'oo_req' value
• block.<num>.allocation - offset of highest written sector in bytes
• block.<num>.capacity - logical size of source file in bytes
• block.<num>.physical - physical size of source file in bytes
• block.<num>.threshold - threshold (in bytes) for delivering the VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD event. See domblkthreshold.
--iothread returns information about IOThreads on the running guest if supported by the hypervisor.
The "poll-max-ns" for each thread is the maximum nanoseconds to allow each polling interval to occur. A polling interval is a period of time allowed for a thread to process data before being the guest gives up its CPU quantum back to the host. A value set too small will not allow the IOThread to run long enough on a CPU to process data. A value set too high will consume too much CPU time per IOThread failing to allow other threads running on the CPU to get time. The polling interval is not available for statistical purposes.
iothread.count - maximum number of IOThreads in the subsequent list as unsigned int. Each IOThread in the list will will use it's iothread_id value as the <id>. There may be fewer <id> entries than the iothread.count value if the polling values are not supported.
• iothread.<id>.poll-max-ns - maximum polling time in nanoseconds used by the <id> IOThread. A value of 0 (zero) indicates polling is disabled.
• iothread.<id>.poll-grow - polling time grow value. A value of 0 (zero) growth is managed by the hypervisor.
• iothread.<id>.poll-shrink - polling time shrink value. A value of (zero) indicates shrink is managed by hypervisor.
--memory returns:
• memory.bandwidth.monitor.count - the number of memory bandwidth monitors for this domain
• memory.bandwidth.monitor.<num>.name  - the name of monitor <num>
• memory.bandwidth.monitor.<num>.vcpus - the vcpu list of monitor <num>
memory.bandwidth.monitor.<num>.node.count - the number of memory controller in monitor <num>
• memory.bandwidth.monitor.<num>.node.<index>.id - host allocated memory controller id for controller <index> of monitor <num>
• memory.bandwidth.monitor.<num>.node.<index>.bytes.local - the accumulative bytes consumed by @vcpus that passing through the memory controller in the same processor that the scheduled host CPU belongs to.
• memory.bandwidth.monitor.<num>.node.<index>.bytes.total - the total bytes consumed by @vcpus that passing through all memory controllers, either local or remote controller.
--dirtyrate returns:
• dirtyrate.calc_status - the status of last memory dirty rate calculation, returned as number from virDomainDirtyRateStatus enum.
• dirtyrate.calc_start_time - the start time of last memory dirty rate calculation.
• dirtyrate.calc_period - the period of last memory dirty rate calculation.
• dirtyrate.megabytes_per_second - the calculated memory dirty rate in MiB/s.
Selecting a specific statistics groups doesn't guarantee that the daemon supports the selected group of stats. Flag --enforce forces the command to fail if the daemon doesn't support the selected group.
When collecting stats libvirtd may wait for some time if there's already another job running on given domain for it to finish.  This may cause unnecessary delay in delivering stats. Using --nowait suppresses this behaviour. On the other hand some statistics might be missing for such domain.
domtime Syntax:
domtime domain { [--now] [--pretty] [--sync] [--time time] }
Gets or sets the domain's system time. When run without any arguments (but domain), the current domain's system time is printed out. The --pretty modifier can be used to print the time in more human readable form.
When --time time is specified, the domain's time is not gotten but set instead. The --now modifier acts like if it was an alias for --time $now, which means it sets the time that is currently on the host virsh is running at. In both cases (setting and getting), time is in seconds relative to Epoch of 1970-01-01 in UTC.  The --sync modifies the set behavior a bit: The time passed is ignored, but the time to set is read from domain's RTC instead. Please note, that some hypervisors may require a guest agent to be configured in order to get or set the guest time.
domuuid Syntax:
domuuid domain-name-or-id
Convert a domain name or id to domain UUID
domxml-from-native Syntax:
domxml-from-native format config
Convert the file config in the native guest configuration format named by format to a domain XML format. For QEMU/KVM hypervisor, the format argument must be qemu-argv. For Xen hypervisor, the format argument may be xen-xm, xen-xl, or xen-sxpr. For LXC hypervisor, the format argument must be lxc-tools. For VMware/ESX hypervisor, the format argument must be vmware-vmx.  For the Bhyve hypervisor, the format argument must be bhyve-argv.
domxml-to-native Syntax:
domxml-to-native format { [--xml] xml | --domain domain-name-or-id-or-uuid }
Convert the file xml into domain XML format or convert an existing --domain to the native guest configuration format named by format.  The xml and --domain arguments are mutually exclusive. For the types of format argument, refer to domxml-from-native.
dump Syntax:
dump domain corefilepath [--bypass-cache] { [--live] | [--crash] | [--reset] } [--verbose] [--memory-only] [--format string]
Dumps the core of a domain to a file for analysis.  If --live is specified, the domain continues to run until the core dump is complete, rather than pausing up front.  If --crash is specified, the domain is halted with a crashed status, rather than merely left in a paused state. If --reset is specified, the domain is reset after successful dump. Note, these three switches are mutually exclusive.  If --bypass-cache is specified, the save will avoid the file system cache, although this may slow down the operation.  If --memory-only is specified, the file is elf file, and will only include domain's memory and cpu common register value. It is very useful if the domain uses host devices directly. --format string is used to specify the format of 'memory-only' dump, and string can be one of: elf, kdump-zlib(kdump-compressed format with zlib-compressed), kdump-lzo(kdump-compressed format with lzo-compressed), kdump-snappy(kdump-compressed format with snappy-compressed), win-dmp(Windows full crashdump format).
The progress may be monitored using domjobinfo virsh command and canceled with domjobabort command (sent by another virsh instance). Another option is to send SIGINT (usually with Ctrl-C) to the virsh process running dump command. --verbose displays the progress of dump.
NOTE: Some hypervisors may require the user to manually ensure proper permissions on file and path specified by argument corefilepath.
NOTE: Crash dump in a old kvmdump format is being obsolete and cannot be loaded and processed by crash utility since its version 6.1.0. A --memory-only option is required in order to produce valid ELF file which can be later processed by the crash utility.
dumpxml Syntax:
dumpxml domain [--inactive] [--security-info] [--update-cpu] [--migratable]
Output the domain information as an XML dump to stdout, this format can be used by the create command. Additional options affecting the XML dump may be used. --inactive tells virsh to dump domain configuration that will be used on next start of the domain as opposed to the current domain configuration.  Using --security-info will also include security sensitive information in the XML dump. --update-cpu updates domain CPU requirements according to host CPU. With --migratable one can request an XML that is suitable for migrations, i.e., compatible with older libvirt releases and possibly amended with internal run-time options. This option may automatically enable other options (--update-cpu, --security-info, ...) as necessary.
edit Syntax:
Edit the XML configuration file for a domain, which will affect the next boot of the guest.
virsh dumpxml --inactive --security-info domain > domain.xml vi domain.xml (or make changes with your other text editor) virsh define domain.xml
except that it does some error checking.
The editor used can be supplied by the $VISUAL or $EDITOR environment variables, and defaults to vi.
emulatorpin Syntax:
emulatorpin domain [cpulist] [[--live] [--config]  | [--current]]
Query or change the pinning of domain's emulator threads to host physical CPUs.
See vcpupin for cpulist.
If --live is specified, affect a running guest.  If --config is specified, affect the next start of a persistent guest.  If --current is specified, it is equivalent to either --live or --config, depending on the current state of the guest.  Both --live and --config flags may be given if cpulist is present, but --current is exclusive.  If no flag is specified, behavior is different depending on hypervisor.
event Syntax:
event {[domain] { event | --all } [--loop] [--timeout seconds] [--timestamp] | --list}
Wait for a class of domain events to occur, and print appropriate details of events as they happen.  The events can optionally be filtered by domain.  Using --list as the only argument will provide a list of possible event values known by this client, although the connection might not allow registering for all these events.  It is also possible to use --all instead of event to register for all possible event types at once.
By default, this command is one-shot, and returns success once an event occurs; you can send SIGINT (usually via Ctrl-C) to quit immediately.  If --timeout is specified, the command gives up waiting for events after seconds have elapsed.   With --loop, the command prints all events until a timeout or interrupt key.
When --timestamp is used, a human-readable timestamp will be printed before the event.
get-user-sshkeys Syntax:
get-user-sshkeys domain user
Print SSH authorized keys for given user in the guest domain. Please note, that an entry in the file has internal structure as defined by sshd(8) and virsh/libvirt does handle keys as opaque strings, i.e. does not interpret them.
guest-agent-timeout Syntax:
guest-agent-timeout domain [--timeout value]
Set how long to wait for a response from guest agent commands. By default, agent commands block forever waiting for a response. value must be a positive value (wait for given amount of seconds) or one of the following values:
• -2 - block forever waiting for a result (used when --timeout is omitted),
• -1 - reset timeout to the default value (currently defined as 5 seconds in libvirt daemon),
• 0 - do not wait at all,
guestinfo Syntax:
guestinfo domain [--user] [--os] [--timezone] [--hostname] [--filesystem] [--disk]
Print information about the guest from the point of view of the guest agent.  Note that this command requires a guest agent to be configured and running in the domain's guest OS.
When run without any arguments, this command prints all information types that are supported by the guest agent. You can limit the types of information that are returned by specifying one or more flags.  If a requested information type is not supported, the processes will provide an exit code of 1.  Available information types flags are --user, --os, --timezone, --hostname, --filesystem and --disk.
Note that depending on the hypervisor type and the version of the guest agent running within the domain, not all of the following information may be returned.
When selecting the --user information type, the following fields may be returned:
• user.count - the number of active users on this domain
• user.<num>.name - username of user <num>
• user.<num>.domain - domain of the user <num> (may only be present on certain guets types)
• user.<num>.login-time - the login time of user <num> in milliseconds since the epoch
--os returns:
• os.id - a string identifying the operating system
• os.name - the name of the operating system
• os.pretty-name - a pretty name for the operating system
• os.version - the version of the operating system
• os.version-id - the version id of the operating system
• os.kernel-release - the release of the operating system kernel
• os.kernel-version - the version of the operating system kernel
• os.machine - the machine hardware name
• os.variant - a specific variant or edition of the operating system
• os.variant-id - the id for a specific variant or edition of the operating system
--timezone returns:
• timezone.name - the name of the timezone
• timezone.offset - the offset to UTC in seconds
--hostname returns:
• hostname - the hostname of the domain
--filesystem returns:
• fs.count - the number of filesystems defined on this domain
• fs.<num>.mountpoint - the path to the mount point for filesystem <num>
• fs.<num>.name - device name in the guest (e.g. sda1) for filesystem <num>
• fs.<num>.fstype - the type of filesystem <num>
• fs.<num>.total-bytes - the total size of filesystem <num>
• fs.<num>.used-bytes - the number of bytes used in filesystem <num>
• fs.<num>.disk.count - the number of disks targeted by filesystem <num>
• fs.<num>.disk.<num>.alias - the device alias of disk <num> (e.g. sda)
• fs.<num>.disk.<num>.serial - the serial number of disk <num>
• fs.<num>.disk.<num>.device - the device node of disk <num>
--disk returns:
• disk.count - the number of disks defined on this domain
• disk.<num>.name - device node (Linux) or device UNC (Windows)
• disk.<num>.partition - whether this is a partition or disk
• disk.<num>.dependency.count - the number of device dependencies
• disk.<num>.dependency.<num>.name - a dependency name
• disk.<num>.serial -  optional disk serial number
• disk.<num>.alias - the device alias of the disk (e.g. sda)
• disk.<num>.guest_alias - optional alias assigned to the disk
guestvcpus Syntax:
guestvcpus domain [[--enable] | [--disable]] [cpulist]
Query or change state of vCPUs from guest's point of view using the guest agent.  When invoked without cpulist the guest is queried for available guest vCPUs, their state and possibility to be offlined.
If cpulist is provided then one of --enable or --disable must be provided too. The desired operation is then executed on the domain.
See vcpupin for information on cpulist.
iothreadadd Syntax:
iothreadadd domain iothread_id [[--config] [--live] | [--current]]
Add a new IOThread to the domain using the specified iothread_id.  If the iothread_id already exists, the command will fail. The iothread_id must be greater than zero.
If --live is specified, affect a running guest. If the guest is not running an error is returned.  If --config is specified, affect the next start of a persistent guest.  If --current is specified, it is equivalent to either --live or --config, depending on the current state of the guest.
iothreaddel Syntax:
iothreaddel domain iothread_id [[--config] [--live] | [--current]]
Delete an IOThread from the domain using the specified iothread_id.  If an IOThread is currently assigned to a disk resource such as via the attach-disk command, then the attempt to remove the IOThread will fail. If the iothread_id does not exist an error will occur.
iothreadinfo Syntax:
iothreadinfo domain [[--live] [--config] | [--current]]
Display basic domain IOThreads information including the IOThread ID and the CPU Affinity for each IOThread.
If --live is specified, get the IOThreads data from the running guest. If the guest is not running, an error is returned.  If --config is specified, get the IOThreads data from the next start of a persistent guest.  If --current is specified or --live and --config are not specified, then get the IOThread data based on the current guest state, which can either be live or offline.
iothreadpin Syntax:
iothreadpin domain iothread cpulist [[--live] [--config] | [--current]]
Change the pinning of a domain IOThread to host physical CPUs. In order to retrieve a list of all IOThreads, use iothreadinfo. To pin an iothread specify the cpulist desired for the IOThread ID as listed in the iothreadinfo output.
cpulist is a list of physical CPU numbers. Its syntax is a comma separated list and a special markup using '-' and '^' (ex. '0-4', '0-3,^2') can also be allowed. The '-' denotes the range and the '^' denotes exclusive.  If you want to reset iothreadpin setting, that is, to pin an iothread to all physical cpus, simply specify 'r' as a cpulist.
If --live is specified, affect a running guest. If the guest is not running, an error is returned.  If --config is specified, affect the next start of a persistent guest.  If --current is specified, it is equivalent to either --live or --config, depending on the current state of the guest.  Both --live and --config flags may be given if cpulist is present, but --current is exclusive.  If no flag is specified, behavior is different depending on hypervisor.
Note: The expression is sequentially evaluated, so "0-15,^8" is identical to "9-14,0-7,15" but not identical to "^8,0-15".
iothreadset Syntax:
iothreadset domain iothread_id [[--poll-max-ns ns] [--poll-grow factor] [--poll-shrink divisor]] [[--config] [--live] | [--current]]
Modifies an existing iothread of the domain using the specified iothread_id. The --poll-max-ns provides the maximum polling interval to be allowed for an IOThread in ns. If a 0 (zero) is provided, then polling for the IOThread is disabled.  The --poll-grow is the factor by which the current polling time will be adjusted in order to reach the maximum polling time. If a 0 (zero) is provided, then the default factor will be used. The --poll-shrink is the quotient by which the current polling time will be reduced in order to get below the maximum polling interval. If a 0 (zero) is provided, then the default quotient will be used. The polling values are purely dynamic for a running guest. Saving, destroying, stopping, etc. the guest will result in the polling values returning to hypervisor defaults at the next start, restore, etc.
If --live is specified, affect a running guest. If the guest is not running an error is returned.  If --current is specified or --live is not specified, then handle as if --live was specified.  (Where "current" here means whatever the present guest state is: live or offline.)
managedsave Syntax:
managedsave domain [--bypass-cache] [{--running | --paused}] [--verbose]
Save and destroy (stop) a running domain, so it can be restarted from the same state at a later time.  When the virsh start command is next run for the domain, it will automatically be started from this saved state.  If --bypass-cache is specified, the save will avoid the file system cache, although this may slow down the operation.
The progress may be monitored using domjobinfo virsh command and canceled with domjobabort command (sent by another virsh instance). Another option is to send SIGINT (usually with Ctrl-C) to the virsh process running managedsave command. --verbose displays the progress of save.
Normally, starting a managed save will decide between running or paused based on the state the domain was in when the save was done; passing either the --running or --paused flag will allow overriding which state the start should use.
The dominfo command can be used to query whether a domain currently has any managed save image.
managedsave-define Syntax:
managedsave-define domain xml [{--running | --paused}]
Update the domain XML that will be used when domain is later started. The xml argument must be a file name containing the alternative XML, with changes only in the host-specific portions of the domain XML. For example, it can be used to change disk file paths.
The managed save image records whether the domain should be started to a running or paused state.  Normally, this command does not alter the recorded state; passing either the --running or --paused flag will allow overriding which state the start should use.
managedsave-dumpxml Syntax:
managedsave-dumpxml domain [--security-info]
Extract the domain XML that was in effect at the time the saved state file file was created with the managedsave command.  Using --security-info will also include security sensitive information.
managedsave-edit Syntax:
managedsave-edit domain [{--running | --paused}]
Edit the XML configuration associated with a saved state file of a domain was created by the managedsave command.
The managed save image records whether the domain should be started to a running or paused state.  Normally, this command does not alter the recorded state; passing either the --running or --paused flag will allow overriding which state the restore should use.
virsh managedsave-dumpxml domain-name > state-file.xml vi state-file.xml (or make changes with your other text editor) virsh managedsave-define domain-name state-file-xml
managedsave-remove Syntax:
managedsave-remove domain
Remove the managedsave state file for a domain, if it exists.  This ensures the domain will do a full boot the next time it is started.
maxvcpus Syntax:
maxvcpus [type]
Provide the maximum number of virtual CPUs supported for a guest VM on this connection.  If provided, the type parameter must be a valid type attribute for the <domain> element of XML.
memtune Syntax:
memtune domain [--hard-limit size] [--soft-limit size] [--swap-hard-limit size] [--min-guarantee size] [[--config] [--live] | [--current]]
Allows you to display or set the domain memory parameters. Without flags, the current settings are displayed; with a flag, the appropriate limit is adjusted if supported by the hypervisor.  LXC and QEMU/KVM support --hard-limit, --soft-limit, and --swap-hard-limit.  --min-guarantee is supported only by ESX hypervisor.  Each of these limits are scaled integers (see NOTES above), with a default of kibibytes (blocks of 1024 bytes) if no suffix is present. Libvirt rounds up to the nearest kibibyte.  Some hypervisors require a larger granularity than KiB, and requests that are not an even multiple will be rounded up.  For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes).
For QEMU/KVM, the parameters are applied to the QEMU process as a whole. Thus, when counting them, one needs to add up guest RAM, guest video RAM, and some memory overhead of QEMU itself.  The last piece is hard to determine so one needs guess and try.
For LXC, the displayed hard_limit value is the current memory setting from the XML or the results from a virsh setmem command.
• --hard-limit
The maximum memory the guest can use.
• --soft-limit
The memory limit to enforce during memory contention.
• --swap-hard-limit
The maximum memory plus swap the guest can use.  This has to be more than hard-limit value provided.
• --min-guarantee
The guaranteed minimum memory allocation for the guest.
Specifying -1 as a value for these limits is interpreted as unlimited.
metadata Syntax:
metadata domain [[--live] [--config] | [--current]] [--edit] [uri] [key] [set] [--remove]
Show or modify custom XML metadata of a domain. The metadata is a user defined XML that allows storing arbitrary XML data in the domain definition.  Multiple separate custom metadata pieces can be stored in the domain XML.  The pieces are identified by a private XML namespace provided via the uri argument. (See also desc that works with textual metadata of a domain.)
Flag --remove specifies that the metadata element specified by the uri argument should be removed rather than updated.
Flag --edit specifies that an editor with the metadata identified by the uri argument should be opened and the contents saved back afterwards. Otherwise the new contents can be provided via the set argument.
When setting metadata via --edit or set the key argument must be specified and is used to prefix the custom elements to bind them to the private namespace.
If neither of --edit and set are specified the XML metadata corresponding to the uri namespace is displayed instead of being modified.
migrate Syntax:
migrate [--live] [--offline] [--direct] [--p2p [--tunnelled]] [--persistent] [--undefinesource] [--suspend] [--copy-storage-all] [--copy-storage-inc] [--change-protection] [--unsafe] [--verbose] [--rdma-pin-all] [--abort-on-error] [--postcopy] [--postcopy-after-precopy] domain desturi [migrateuri] [graphicsuri] [listen-address] [dname] [--timeout seconds [--timeout-suspend | --timeout-postcopy]] [--xml file] [--migrate-disks disk-list] [--disks-port port] [--compressed] [--comp-methods method-list] [--comp-mt-level] [--comp-mt-threads] [--comp-mt-dthreads] [--comp-xbzrle-cache] [--auto-converge] [auto-converge-initial] [auto-converge-increment] [--persistent-xml file] [--tls] [--postcopy-bandwidth bandwidth] [--parallel [--parallel-connections connections]] [--bandwidth bandwidth] [--tls-destination hostname] [--disks-uri URI]
Migrate domain to another host.  Add --live for live migration; <--p2p> for peer-2-peer migration; --direct for direct migration; or --tunnelled for tunnelled migration.  --offline migrates domain definition without starting the domain on destination and without stopping it on source host.  Offline migration may be used with inactive domains and it must be used with --persistent option.  --persistent leaves the domain persistent on destination host, --undefinesource undefines the domain on the source host, and --suspend leaves the domain paused on the destination host. --copy-storage-all indicates migration with non-shared storage with full disk copy, --copy-storage-inc indicates migration with non-shared storage with incremental copy (same base image shared between source and destination).  In both cases the disk images have to exist on destination host, the --copy-storage-... options only tell libvirt to transfer data from the images on source host to the images found at the same place on the destination host. By default only non-shared non-readonly images are transferred. Use --migrate-disks to explicitly specify a list of disk targets to transfer via the comma separated disk-list argument. --change-protection enforces that no incompatible configuration changes will be made to the domain while the migration is underway; this flag is implicitly enabled when supported by the hypervisor, but can be explicitly used to reject the migration if the hypervisor lacks change protection support.  --verbose displays the progress of migration. --abort-on-error cancels the migration if a soft error (for example I/O error) happens during the migration. --postcopy enables post-copy logic in migration, but does not actually start post-copy, i.e., migration is started in pre-copy mode.  Once migration is running, the user may switch to post-copy using the migrate-postcopy command sent from another virsh instance or use --postcopy-after-precopy along with --postcopy to let libvirt automatically switch to post-copy after the first pass of pre-copy is finished.  The maximum bandwidth consumed during the post-copy phase may be limited using --postcopy-bandwidth. The maximum bandwidth consumed during the pre-copy phase may be limited using --bandwidth.
--auto-converge forces convergence during live migration. The initial guest CPU throttling rate can be set with auto-converge-initial. If the initial throttling rate is not enough to ensure convergence, the rate is periodically increased by auto-converge-increment.
--rdma-pin-all can be used with RDMA migration (i.e., when migrateuri starts with rdma://) to tell the hypervisor to pin all domain's memory at once before migration starts rather than letting it pin memory pages as needed. For QEMU/KVM this requires hard_limit memory tuning element (in the domain XML) to be used and set to the maximum memory configured for the domain plus any memory consumed by the QEMU process itself. Beware of setting the memory limit too high (and thus allowing the domain to lock most of the host's memory). Doing so may be dangerous to both the domain and the host itself since the host's kernel may run out of memory.
Note: Individual hypervisors usually do not support all possible types of migration. For example, QEMU does not support direct migration.
In some cases libvirt may refuse to migrate the domain because doing so may lead to potential problems such as data corruption, and thus the migration is considered unsafe. For QEMU domain, this may happen if the domain uses disks without explicitly setting cache mode to "none". Migrating such domains is unsafe unless the disk images are stored on coherent clustered filesystem, such as GFS2 or GPFS. If you are sure the migration is safe or you just do not care, use --unsafe to force the migration.
dname is used for renaming the domain to new name during migration, which also usually can be omitted.  Likewise, --xml file is usually omitted, but can be used to supply an alternative XML file for use on the destination to supply a larger set of changes to any host-specific portions of the domain XML, such as accounting for naming differences between source and destination in accessing underlying storage.  If --persistent is enabled, --persistent-xml file can be used to supply an alternative XML file which will be used as the persistent guest definition on the destination host.
--timeout seconds tells virsh to run a specified action when live migration exceeds that many seconds.  It can only be used with --live. If --timeout-suspend is specified, the domain will be suspended after the timeout and the migration will complete offline; this is the default if no --timeout-\`` option is specified on the command line.  When *--timeout-postcopy is used, virsh will switch migration from pre-copy to post-copy upon timeout; migration has to be started with --postcopy option for this to work.
--compressed activates compression, the compression method is chosen with --comp-methods. Supported methods are "mt" and "xbzrle" and can be used in any combination. When no methods are specified, a hypervisor default methods will be used. QEMU defaults to "xbzrle". Compression methods can be tuned further. --comp-mt-level sets compression level.  Values are in range from 0 to 9, where 1 is maximum speed and 9 is maximum compression. --comp-mt-threads and --comp-mt-dthreads set the number of compress threads on source and the number of decompress threads on target respectively. --comp-xbzrle-cache sets size of page cache in bytes.
Providing --tls causes the migration to use the host configured TLS setup (see migrate_tls_x509_cert_dir in /etc/libvirt/qemu.conf) in order to perform the migration of the domain. Usage requires proper TLS setup for both source and target. Normally the TLS certificate from the destination host must match the host's name for TLS verification to succeed. When the certificate does not match the destination hostname and the expected certificate's hostname is known, --tls-destination can be used to pass the expected hostname when starting the migration.
--parallel option will cause migration data to be sent over multiple parallel connections. The number of such connections can be set using --parallel-connections. Parallel connections may help with saturating the network link between the source and the target and thus speeding up the migration.
Running migration can be canceled by interrupting virsh (usually using Ctrl-C) or by domjobabort command sent from another virsh instance.
The desturi and migrateuri parameters can be used to control which destination the migration uses.  desturi is important for managed migration, but unused for direct migration; migrateuri is required for direct migration, but can usually be automatically determined for managed migration.
Note: The desturi parameter for normal migration and peer2peer migration has different semantics:
• normal migration: the desturi is an address of the target host as seen from the client machine.
• peer2peer migration: the desturi is an address of the target host as seen from the source machine.
In a special circumstance where you require a complete control of the connection and/or libvirt does not have network access to the remote side you can use a UNIX transport in the URI and specify a socket path in the query, for example with the qemu driver you could use this:
qemu+unix:///system?socket=/path/to/socket
When migrateuri is not specified, libvirt will automatically determine the hypervisor specific URI.  Some hypervisors, including QEMU, have an optional "migration_host" configuration parameter (useful when the host has multiple network interfaces).  If this is unspecified, libvirt determines a name by looking up the target host's configured hostname.
There are a few scenarios where specifying migrateuri may help:
• The configured hostname is incorrect, or DNS is broken.  If a host has a hostname which will not resolve to match one of its public IP addresses, then libvirt will generate an incorrect URI.  In this case migrateuri should be explicitly specified, using an IP address, or a correct hostname.
• The host has multiple network interfaces.  If a host has multiple network interfaces, it might be desirable for the migration data stream to be sent over a specific interface for either security or performance reasons.  In this case migrateuri should be explicitly specified, using an IP address associated with the network to be used.
• The firewall restricts what ports are available.  When libvirt generates a migration URI, it will pick a port number using hypervisor specific rules.  Some hypervisors only require a single port to be open in the firewalls, while others require a whole range of port numbers. In the latter case migrateuri might be specified to choose a specific port number outside the default range in order to comply with local firewall policies.
• The desturi uses UNIX transport method.  In this advanced case libvirt should not guess a migrateuri and it should be specified using UNIX socket path URI:
unix:///path/to/socket
See https://libvirt.org/migration.html#uris for more details on migration URIs.
Optional graphicsuri overrides connection parameters used for automatically reconnecting a graphical clients at the end of migration. If omitted, libvirt will compute the parameters based on target host IP address. In case the client does not have a direct access to the network virtualization hosts are connected to and needs to connect through a proxy, graphicsuri may be used to specify the address the client should connect to. The URI is formed as follows:
protocol://hostname[:port]/[?parameters]
where protocol is either "spice" or "vnc" and parameters is a list of protocol specific parameters separated by '&'. Currently recognized parameters are "tlsPort" and "tlsSubject". For example,
spice://target.host.com:1234/?tlsPort=4567
Optional listen-address sets the listen address that hypervisor on the destination side should bind to for incoming migration. Both IPv4 and IPv6 addresses are accepted as well as hostnames (the resolving is done on destination).  Some hypervisors do not support specifying the listen address and will return an error if this parameter is used. This parameter cannot be used if desturi uses UNIX transport method.
Optional disks-port sets the port that hypervisor on destination side should bind to for incoming disks traffic. Currently it is supported only by QEMU.
Optional disks-uri can also be specified (mutually exclusive with disks-port) to specify what the remote hypervisor should bind/connect to when migrating disks.  This can be tcp://address:port to specify a listen address (which overrides --migrate-uri and --listen-address for the disk migration) and a port or unix:///path/to/socket in case you need the disk migration to happen over a UNIX socket with that specified path.  In this case you need to make sure the same socket path is accessible to both source and destination hypervisors and connecting to the socket on the source (after hypervisor creates it on the destination) will actually connect to the destination. If you are using SELinux (at least on the source host) you need to make sure the socket on the source is accessible to libvirtd/QEMU for connection.  Libvirt cannot change the context of the existing socket because it is different from the file representation of the socket and the context is chosen by its creator (usually by using setsockcreatecon{,_raw}() functions).
migrate-compcache Syntax:
migrate-compcache domain [--size bytes]
Sets and/or gets size of the cache (in bytes) used for compressing repeatedly transferred memory pages during live migration. When called without size, the command just prints current size of the compression cache. When size is specified, the hypervisor is asked to change compression cache to size bytes and then the current size is printed (the result may differ from the requested size due to rounding done by the hypervisor). The size option is supposed to be used while the domain is being live-migrated as a reaction to migration progress and increasing number of compression cache misses obtained from domjobinfo.
migrate-getmaxdowntime Syntax:
migrate-getmaxdowntime domain
Get the maximum tolerable downtime for a domain which is being live-migrated to another host.  This is the number of milliseconds the guest is allowed to be down at the end of live migration.
migrate-getspeed Syntax:
migrate-getspeed domain [--postcopy]
Get the maximum migration bandwidth (in MiB/s) for a domain. If the --postcopy option is specified, the command will get the maximum bandwidth allowed during a post-copy migration phase.
migrate-postcopy Syntax:
migrate-postcopy domain