neulab/tldr huggingface dataset:
Detach nodedev from the host, so that it can safely be used by guests via <hostdev> passthrough.  This is reversed with nodedev-reattach, and is done automatically for managed devices.
Different backend drivers expect the device to be bound to different dummy devices. For example, QEMU's "kvm" backend driver (the default) expects the device to be bound to pci-stub, but its "vfio" backend driver expects the device to be bound to vfio-pci. The --driver parameter can be used to specify the desired backend driver.
nodedev-dumpxml Syntax:
nodedev-dumpxml device
Dump a <device> XML representation for the given node device, including such information as the device name, which bus owns the device, the vendor and product id, and any capabilities of the device usable by libvirt (such as whether device reset is supported). device can be either device name or wwn pair in "wwnn,wwpn" format (only works for HBA).
nodedev-info Syntax:
nodedev-info device
Returns basic information about the device object.
nodedev-list Syntax:
nodedev-list [--cap capability] [--tree] [--inactive | --all]
List all of the devices available on the node that are known by libvirt. cap is used to filter the list by capability types, the types must be separated by comma, e.g. --cap pci,scsi. Valid capability types include 'system', 'pci', 'usb_device', 'usb', 'net', 'scsi_host', 'scsi_target', 'scsi', 'storage', 'fc_host', 'vports', 'scsi_generic', 'drm', 'mdev', 'mdev_types', 'ccw', 'css', 'ap_card', 'ap_queue', 'ap_matrix'. By default, only active devices are listed. --inactive is used to list only inactive devices, and -all is used to list both active and inactive devices.  If --tree is used, the output is formatted in a tree representing parents of each node.  --tree is mutually exclusive with all other options.
nodedev-reattach Syntax:
nodedev-reattach nodedev
Declare that nodedev is no longer in use by any guests, and that the host can resume normal use of the device.  This is done automatically for PCI devices in managed mode and USB devices, but must be done explicitly to match any explicit nodedev-detach.
nodedev-reset Syntax:
nodedev-reset nodedev
Trigger a device reset for nodedev, useful prior to transferring a node device between guest passthrough or the host.  Libvirt will often do this action implicitly when required, but this command allows an explicit reset when needed.
nodedev-event Syntax:
nodedev-event {[nodedev] event [--loop] [--timeout seconds] [--timestamp] | --list}
Wait for a class of node device events to occur, and print appropriate details of events as they happen.  The events can optionally be filtered by nodedev.  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.
nodedev-autostart Syntax:
nodedev-autostart [--disable] device
Configure a device to be automatically started when the host machine boots or the parent device becomes available. With --disable, the device will be set to manual mode and will no longer be automatically started by the host. This command is only supported for persistently-defined mediated devices.
The following commands manipulate networks. Libvirt has the capability to define virtual networks which can then be used by domains and linked to actual network devices. For more detailed information about this feature see the documentation at https://libvirt.org/formatnetwork.html . Many of the commands for virtual networks are similar to the ones used for domains, but the way to name a virtual network is either by its name or UUID.
net-autostart Syntax:
net-autostart network [--disable]
Configure a virtual network to be automatically started at boot.  The --disable option disable autostarting.
net-create Syntax:
net-create file [--validate]
Create a transient (temporary) virtual network from an XML file and instantiate (start) the network.  See the documentation at https://libvirt.org/formatnetwork.html to get a description of the XML network format used by libvirt.
Optionally, the format of the input XML file can be validated against an internal RNG schema with --validate.
net-define Syntax:
net-define file [--validate]
Define an inactive persistent virtual network or modify an existing persistent one from the XML file.  Optionally, the format of the input XML file can be validated against an internal RNG schema with --validate.
net-destroy Syntax:
net-destroy network
Destroy (stop) a given transient or persistent virtual network specified by its name or UUID. This takes effect immediately.
net-dumpxml Syntax:
net-dumpxml network [--inactive]
Output the virtual network information as an XML dump to stdout.  If --inactive is specified, then physical functions are not expanded into their associated virtual functions.
net-edit Syntax:
net-edit network
Edit the XML configuration file for a network.
virsh net-dumpxml --inactive network > network.xml vi network.xml (or make changes with your other text editor) virsh net-define network.xml
net-event Syntax:
net-event {[network] event [--loop] [--timeout seconds] [--timestamp] | --list}
Wait for a class of network events to occur, and print appropriate details of events as they happen.  The events can optionally be filtered by network.  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.
net-info Syntax:
net-info network
Returns basic information about the network object.
net-list Syntax:
net-list [--inactive | --all] { [--table] | --name | --uuid } [--persistent] [<--transient>] [--autostart] [<--no-autostart>]
Returns the list of active networks, if --all is specified this will also include defined but inactive networks, if --inactive is specified only the inactive ones will be listed. You may also want to filter the returned networks by --persistent to list the persistent ones, --transient to list the transient ones, --autostart to list the ones with autostart enabled, and --no-autostart to list the ones with autostart disabled.
If --name is specified, network names are printed instead of the table formatted one per line. If --uuid is specified network's UUID's are printed instead of names. Flag --table specifies that the legacy table-formatted output should be used. This is the default. All of these are mutually exclusive.
NOTE: When talking to older servers, this command is forced to use a series of API calls with an inherent race, where a pool might not be listed or might appear more than once if it changed state between calls while the list was being collected.  Newer servers do not have this problem.
net-name Syntax:
net-name network-UUID
Convert a network UUID to network name.
net-start Syntax:
net-start network
Start a (previously defined) inactive network.
net-undefine Syntax:
net-undefine network
Undefine the configuration for a persistent network. If the network is active, make it transient.
net-uuid Syntax:
net-uuid network-name
Convert a network name to network UUID.
net-update Syntax:
net-update network command section xml [--parent-index index] [[--live] [--config] | [--current]]
Update the given section of an existing network definition, with the changes optionally taking effect immediately, without needing to destroy and re-start the network.
command is one of "add-first", "add-last", "add" (a synonym for add-last), "delete", or "modify".
section is one of "bridge", "domain", "ip", "ip-dhcp-host", "ip-dhcp-range", "forward", "forward-interface", "forward-pf", "portgroup", "dns-host", "dns-txt", or "dns-srv", each section being named by a concatenation of the xml element hierarchy leading to the element being changed. For example, "ip-dhcp-host" will change a <host> element that is contained inside a <dhcp> element inside an <ip> element of the network.
xml is either the text of a complete xml element of the type being changed (e.g. "<host mac="00:11:22:33:44:55' ip='1.2.3.4'/>", or the name of a file that contains a complete xml element. Disambiguation is done by looking at the first character of the provided text - if the first character is "<", it is xml text, if the first character is not "<", it is the name of a file that contains the xml text to be used.
The --parent-index option is used to specify which of several parent elements the requested element is in (0-based). For example, a dhcp <host> element could be in any one of multiple <ip> elements in the network; if a parent-index isn't provided, the "most appropriate" <ip> element will be selected (usually the only one that already has a <dhcp> element), but if --parent-index is given, that particular instance of <ip> will get the modification.
If --live is specified, affect a running network.  If --config is specified, affect the next startup of a persistent network.  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. Not specifying any flag is the same as specifying --current.
net-dhcp-leases Syntax:
net-dhcp-leases network [mac]
Get a list of dhcp leases for all network interfaces connected to the given virtual network or limited output just for one interface if mac is specified.
The following commands manipulate network ports. Libvirt virtual networks have ports created when a virtual machine has a virtual network interface added. In general there should be no need to use any of the commands here, since the hypervisor drivers run these commands are the right point in a virtual machine's lifecycle. They can be useful for debugging problems and / or recovering from bugs / stale state.
net-port-list Syntax:
net-port-list { [--table] | --uuid } network
List all network ports recorded against the network.
If --uuid is specified network ports' UUID's are printed instead of a table. Flag --table specifies that the legacy table-formatted output should be used. This is the default.  All of these are mutually exclusive.
net-port-create Syntax:
net-port-create network file [--validate]
Allocate a new network port reserving resources based on the port description.  Optionally, the format of the input XML file can be validated against an internal RNG schema with --validate.
net-port-dumpxml Syntax:
net-port-dumpxml network port
Output the network port information as an XML dump to stdout.
net-port-delete Syntax:
net-port-delete network port
Delete record of the network port and release its resources
The following commands manipulate host interfaces.  Often, these host interfaces can then be used by name within domain <interface> elements (such as a system-created bridge interface), but there is no requirement that host interfaces be tied to any particular guest configuration XML at all.
Many of the commands for host interfaces are similar to the ones used for domains, and the way to name an interface is either by its name or its MAC address.  However, using a MAC address for an iface argument only works when that address is unique (if an interface and a bridge share the same MAC address, which is often the case, then using that MAC address results in an error due to ambiguity, and you must resort to a name instead).
iface-bridge Syntax:
iface-bridge interface bridge [--no-stp] [delay] [--no-start]
Create a bridge device named bridge, and attach the existing network device interface to the new bridge.  The new bridge defaults to starting immediately, with STP enabled and a delay of 0; these settings can be altered with --no-stp, --no-start, and an integer number of seconds for delay. All IP address configuration of interface will be moved to the new bridge device.
See also iface-unbridge for undoing this operation.
iface-define Syntax:
iface-define file [--validate]
Define an inactive persistent physical host interface or modify an existing persistent one from the XML file. Optionally, the format of the input XML file can be validated against an internal RNG schema with --validate.
iface-destroy Syntax:
iface-destroy interface
Destroy (stop) a given host interface, such as by running "if-down" to disable that interface from active use. This takes effect immediately.
iface-dumpxml Syntax:
iface-dumpxml interface [--inactive]
Output the host interface information as an XML dump to stdout.  If --inactive is specified, then the output reflects the persistent state of the interface that will be used the next time it is started.
iface-edit Syntax:
iface-edit interface
Edit the XML configuration file for a host interface.
virsh iface-dumpxml iface > iface.xml vi iface.xml (or make changes with your other text editor) virsh iface-define iface.xml
iface-list Syntax:
iface-list [--inactive | --all]
Returns the list of active host interfaces.  If --all is specified this will also include defined but inactive interfaces.  If --inactive is specified only the inactive ones will be listed.
iface-name Syntax:
iface-name interface
Convert a host interface MAC to interface name, if the MAC address is unique among the host's interfaces.
interface specifies the interface MAC address.
iface-mac Syntax:
iface-mac interface
Convert a host interface name to MAC address.
interface specifies the interface name.
iface-start Syntax:
iface-start interface
Start a (previously defined) host interface, such as by running "if-up".
iface-unbridge Syntax:
iface-unbridge bridge [--no-start]
Tear down a bridge device named bridge, releasing its underlying interface back to normal usage, and moving all IP address configuration from the bridge device to the underlying device.  The underlying interface is restarted unless --no-start is present; this flag is present for symmetry, but generally not recommended.
See also iface-bridge for creating a bridge.
iface-undefine Syntax:
iface-undefine interface
Undefine the configuration for an inactive host interface.
iface-begin Syntax:
iface-begin
Create a snapshot of current host interface settings, which can later be committed (iface-commit) or restored (iface-rollback).  If a snapshot already exists, then this command will fail until the previous snapshot has been committed or restored.  Undefined behavior results if any external changes are made to host interfaces outside of the libvirt API between the beginning of a snapshot and its eventual commit or rollback.
iface-commit Syntax:
iface-commit
Declare all changes since the last iface-begin as working, and delete the rollback point.  If no interface snapshot has already been started, then this command will fail.
iface-rollback Syntax:
iface-rollback
Revert all host interface settings back to the state recorded in the last iface-begin.  If no interface snapshot has already been started, then this command will fail.  Rebooting the host also serves as an implicit rollback point.
The following commands manipulate storage pools. Libvirt has the capability to manage various storage solutions, including files, raw partitions, and domain-specific formats, used to provide the storage volumes visible as devices within virtual machines. For more detailed information about this feature, see the documentation at https://libvirt.org/formatstorage.html . Many of the commands for pools are similar to the ones used for domains.
find-storage-pool-sources Syntax:
find-storage-pool-sources type [srcSpec]
Returns XML describing all possible available storage pool sources that could be used to create or define a storage pool of a given type. If srcSpec is provided, it is a file that contains XML to further restrict the query for pools.
Not all storage pools support discovery in this manner. Furthermore, for those that do support discovery, only specific XML elements are required in order to return valid data, while other elements and even attributes of some elements are ignored since they are not necessary to find the pool based on the search criteria. The following lists the supported type options and the expected minimal XML elements used to perform the search.
For a "netfs" or "gluster" pool, the minimal expected XML required is the <host> element with a "name" attribute describing the IP address or hostname to be used to find the pool. The "port" attribute will be ignored as will any other provided XML elements in srcSpec.
For a "logical" pool, the contents of the srcSpec file are ignored, although if provided the file must at least exist.
For an "iscsi" or "iscsi-direct" pool, the minimal expect XML required is the <host> element with a "name" attribute describing the IP address or hostname to be used to find the pool (the iSCSI server address). Optionally, the "port" attribute may be provided, although it will default to 3260. Optionally, an <initiator> XML element with a "name" attribute may be provided to further restrict the iSCSI target search to a specific initiator for multi-iqn iSCSI storage pools.
find-pool-sources-as Syntax:
find-storage-pool-sources-as type [host] [port] [initiator]
Rather than providing srcSpec XML file for find-storage-pool-sources use this command option in order to have virsh generate the query XML file using the optional arguments. The command will return the same output XML as find-storage-pool-sources.
Use host to describe a specific host to use for networked storage, such as netfs, gluster, and iscsi type pools.
Use port to further restrict which networked port to utilize for the connection if required by the specific storage backend, such as iscsi.
Use initiator to further restrict the iscsi type pool searches to specific target initiators.
pool-autostart Syntax:
pool-autostart pool-or-uuid [--disable]
Configure whether pool should automatically start at boot.
pool-build Syntax:
pool-build pool-or-uuid [--overwrite] [--no-overwrite]
Build a given pool.
Options --overwrite and --no-overwrite can only be used for pool-build a filesystem, disk, or logical pool.
For a file system pool if neither flag is specified, then pool-build just makes the target path directory and no attempt to run mkfs on the target volume device. If --no-overwrite is specified, it probes to determine if a filesystem already exists on the target device, returning an error if one exists or using mkfs to format the target device if not.  If --overwrite is specified, mkfs is always executed and any existing data on the target device is overwritten unconditionally.
For a disk pool, if neither of them is specified or --no-overwrite is specified, pool-build will check the target volume device for existing filesystems or partitions before attempting to write a new label on the target volume device. If the target volume device already has a label, the command will fail. If --overwrite is specified, then no check will be made on the target volume device prior to writing a new label. Writing of the label uses the pool source format type or "dos" if not specified.
For a logical pool, if neither of them is specified or --no-overwrite is specified, pool-build will check the target volume devices for existing filesystems or partitions before attempting to initialize and format each device for usage by the logical pool. If any target volume device already has a label, the command will fail. If --overwrite is specified, then no check will be made on the target volume devices prior to initializing and formatting each device. Once all the target volume devices are properly formatted via pvcreate, the volume group will be created using all the devices.
pool-create Syntax:
pool-create file [--build] [[--overwrite] | [--no-overwrite]]
Create and start a pool object from the XML file.
[--build] [[--overwrite] | [--no-overwrite]] perform a pool-build after creation in order to remove the need for a follow-up command to build the pool. The --overwrite and --no-overwrite flags follow the same rules as pool-build. If just --build is provided, then pool-build is called with no flags.
pool-create-as Syntax:
pool-create-as name type [--source-host hostname] [--source-path path] [--source-dev path] [--source-name name] [--target path] [--source-format format] [--source-initiator initiator-iqn] [--auth-type authtype --auth-username username [--secret-usage usage | --secret-uuid uuid]] [--source-protocol-ver ver] [[--adapter-name name] | [--adapter-wwnn wwnn --adapter-wwpn wwpn] [--adapter-parent parent | --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn | --adapter-parent-fabric-wwn parent_fabric_wwn]] [--build] [[--overwrite] | [--no-overwrite]] [--print-xml]
Create and start a pool object name from the raw parameters.  If --print-xml is specified, then print the XML of the pool object without creating the pool.  Otherwise, the pool has the specified type. When using pool-create-as for a pool of type "disk", the existing partitions found on the --source-dev path will be used to populate the disk pool. Therefore, it is suggested to use pool-define-as and pool-build with the --overwrite in order to properly initialize the disk pool.
[--source-host hostname] provides the source hostname for pools backed by storage from a remote server (pool types netfs, iscsi, rbd, sheepdog, gluster).
[--source-path path] provides the source directory path for pools backed by directories (pool type dir).
[--source-dev path] provides the source path for pools backed by physical devices (pool types fs, logical, disk, iscsi, zfs).
[--source-name name] provides the source name for pools backed by storage from a named element (pool types logical, rbd, sheepdog, gluster).
[--target path] is the path for the mapping of the storage pool into the host file system.
[--source-format format] provides information about the format of the pool (pool types fs, netfs, disk, logical).
[--source-initiator initiator-iqn] provides the initiator iqn for iscsi connection of the pool (pool type iscsi-direct).
[--auth-type authtype --auth-username username [--secret-usage usage | --secret-uuid uuid]] provides the elements required to generate authentication credentials for the storage pool. The authtype is either chap for iscsi type pools or ceph for rbd type pools. Either the secret usage or uuid value may be provided, but not both.
[--source-protocol-ver ver] provides the NFS protocol version number used to contact the server's NFS service via nfs mount option 'nfsvers=n'. It is expect the ver value is an unsigned integer.
[--adapter-name name] defines the scsi_hostN adapter name to be used for the scsi_host adapter type pool.
[--adapter-wwnn wwnn --adapter-wwpn wwpn [--adapter-parent parent | --adapter-parent-wwnn parent_wwnn adapter-parent-wwpn parent_wwpn | --adapter-parent-fabric-wwn parent_fabric_wwn]] defines the wwnn and wwpn to be used for the fc_host adapter type pool.  Optionally provide the parent scsi_hostN node device to be used for the vHBA either by parent name, parent_wwnn and parent_wwpn, or parent_fabric_wwn.  The parent name could change between reboots if the hardware environment changes, so providing the parent_wwnn and parent_wwpn ensure usage of the same physical HBA even if the scsi_hostN node device changes. Usage of the parent_fabric_wwn allows a bit more flexibility to choose an HBA on the same storage fabric in order to define the pool.
For a "logical" pool only [--name] needs to be provided. The [--source-name] if provided must match the Volume Group name.  If not provided, one will be generated using the [--name]. If provided the [--target] is ignored and a target source is generated using the [--source-name] (or as generated from the [--name]).
pool-define Syntax:
pool-define file [--validate]
Define an inactive persistent storage pool or modify an existing persistent one from the XML file.  Optionally, the format of the input XML file can be validated against an internal RNG schema with --validate.
pool-define-as Syntax:
pool-define-as name type [--source-host hostname] [--source-path path] [--source-dev path] [*--source-name name*] [*--target path*] [*--source-format format*] [--source-initiator initiator-iqn] [*--auth-type authtype* *--auth-username username* [*--secret-usage usage* | *--secret-uuid uuid*]] [*--source-protocol-ver ver*] [[*--adapter-name name*] | [*--adapter-wwnn* *--adapter-wwpn*] [*--adapter-parent parent*]] [*--print-xml*]
Create, but do not start, a pool object name from the raw parameters.  If --print-xml is specified, then print the XML of the pool object without defining the pool.  Otherwise, the pool has the specified type.
Use the same arguments as pool-create-as, except for the --build, --overwrite, and --no-overwrite options.
pool-destroy Syntax:
pool-destroy pool-or-uuid
Destroy (stop) a given pool object. Libvirt will no longer manage the storage described by the pool object, but the raw data contained in the pool is not changed, and can be later recovered with pool-create.
pool-delete Syntax:
pool-delete pool-or-uuid
Destroy the resources used by a given pool object. This operation is non-recoverable.  The pool object will still exist after this command, ready for the creation of new storage volumes.
pool-dumpxml Syntax:
pool-dumpxml [--inactive] pool-or-uuid
Returns the XML information about the pool object.  --inactive tells virsh to dump pool configuration that will be used on next start of the pool as opposed to the current pool configuration.
pool-edit Syntax:
pool-edit pool-or-uuid
Edit the XML configuration file for a storage pool.
virsh pool-dumpxml pool > pool.xml vi pool.xml (or make changes with your other text editor) virsh pool-define pool.xml
pool-info Syntax:
pool-info [--bytes] pool-or-uuid
Returns basic information about the pool object. If --bytes is specified the sizes of basic info are not converted to human friendly units.
pool-list Syntax:
pool-list [--inactive] [--all] [--persistent] [--transient] [--autostart] [--no-autostart] [[--details] [--uuid] [--name] [<type>]
List pool objects known to libvirt.  By default, only active pools are listed; --inactive lists just the inactive pools, and --all lists all pools.
In addition, there are several sets of filtering flags. --persistent is to list the persistent pools, --transient is to list the transient pools. --autostart lists the autostarting pools, --no-autostart lists the pools with autostarting disabled. If --uuid is specified only pool's UUIDs are printed.  If --name is specified only pool's names are printed. If both --name and --uuid are specified, pool's UUID and names are printed side by side without any header. Option --details is mutually exclusive with options --uuid and --name.
You may also want to list pools with specified types using type, the pool types must be separated by comma, e.g. --type dir,disk. The valid pool types include 'dir', 'fs', 'netfs', 'logical', 'disk', 'iscsi', 'scsi', 'mpath', 'rbd', 'sheepdog', 'gluster', 'zfs', 'vstorage' and 'iscsi-direct'.
The --details option instructs virsh to additionally display pool persistence and capacity related information where available.
pool-name Syntax:
pool-name uuid
Convert the uuid to a pool name.
pool-refresh Syntax:
pool-refresh pool-or-uuid
Refresh the list of volumes contained in pool.
pool-start Syntax:
pool-start pool-or-uuid [--build] [[--overwrite] | [--no-overwrite]]
Start the storage pool, which is previously defined but inactive.
[--build] [[--overwrite] | [--no-overwrite]] perform a pool-build prior to pool-start to ensure the pool environment is in an expected state rather than needing to run the build command prior to startup. The --overwrite and --no-overwrite flags follow the same rules as pool-build. If just --build is provided, then pool-build is called with no flags.
Note: A storage pool that relies on remote resources such as an "iscsi" or a (v)HBA backed "scsi" pool may need to be refreshed multiple times in order to have all the volumes detected (see pool-refresh).  This is because the corresponding volume devices may not be present in the host's filesystem during the initial pool startup or the current refresh attempt. The number of refresh retries is dependent upon the network connection and the time the host takes to export the corresponding devices.
pool-undefine Syntax:
pool-undefine pool-or-uuid
Undefine the configuration for an inactive pool.
pool-uuid Syntax:
pool-uuid pool
Returns the UUID of the named pool.
pool-event Syntax:
pool-event {[pool] event [--loop] [--timeout seconds] [--timestamp] | --list}
Wait for a class of storage pool events to occur, and print appropriate details of events as they happen.  The events can optionally be filtered by pool.  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.
vol-create Syntax:
vol-create pool-or-uuid FILE [--prealloc-metadata]
Create a volume from an XML <file>.
pool-or-uuid is the name or UUID of the storage pool to create the volume in.
FILE is the XML <file> with the volume definition. An easy way to create the XML <file> is to use the vol-dumpxml command to obtain the definition of a pre-existing volume.
[--prealloc-metadata] preallocate metadata (for qcow2 images which don't support full allocation). This option creates a sparse image file with metadata, resulting in higher performance compared to images with no preallocation and only slightly higher initial disk space usage.
virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml vi newvolume.xml (or make changes with your other text editor) virsh vol-create differentstoragepool newvolume.xml
vol-create-from Syntax:
vol-create-from pool-or-uuid FILE vol-name-or-key-or-path [--inputpool pool-or-uuid]  [--prealloc-metadata] [--reflink]
Create a volume, using another volume as input.
FILE is the XML <file> with the volume definition.
vol-name-or-key-or-path is the name or key or path of the source volume.
--inputpool pool-or-uuid is the name or uuid of the storage pool the source volume is in.
When --reflink is specified, perform a COW lightweight copy, where the data blocks are copied only when modified.  If this is not possible, the copy fails.
vol-create-as Syntax:
vol-create-as pool-or-uuid name capacity [--allocation size] [--format string] [--backing-vol vol-name-or-key-or-path] [--backing-vol-format string] [--prealloc-metadata] [--print-xml]
Create a volume from a set of arguments unless --print-xml is specified, in which case just the XML of the volume object is printed out without any actual object creation.
name is the name of the new volume. For a disk pool, this must match the partition name as determined from the pool's source device path and the next available partition. For example, a source device path of /dev/sdb and there are no partitions on the disk, then the name must be sdb1 with the next name being sdb2 and so on.
capacity is the size of the volume to be created, as a scaled integer (see NOTES above), defaulting to bytes if there is no suffix.
--allocation size is the initial size to be allocated in the volume, also as a scaled integer defaulting to bytes.
--format string is used in file based storage pools to specify the volume file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use extended for disk storage pools in order to create an extended partition (other values are validity checked but not preserved when libvirtd is restarted or the pool is refreshed).
--backing-vol vol-name-or-key-or-path is the source backing volume to be used if taking a snapshot of an existing volume.
--backing-vol-format string is the format of the snapshot backing volume; raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, however, meant for file based storage pools.
vol-clone Syntax:
vol-clone vol-name-or-key-or-path name [--pool pool-or-uuid] [--prealloc-metadata] [--reflink]
Clone an existing volume within the parent pool.  Less powerful, but easier to type, version of vol-create-from.
name is the name of the new volume.
--pool pool-or-uuid is the name or UUID of the storage pool that contains the source volume and will contain the new volume.  If the source volume name is provided instead of the key or path, then providing the pool is necessary to find the volume to be cloned; otherwise, the first volume found by the key or path will be used.
vol-delete Syntax:
vol-delete vol-name-or-key-or-path [--pool pool-or-uuid] [--delete-snapshots]
Delete a given volume.
vol-name-or-key-or-path is the volume name or key or path of the volume to delete.
[--pool pool-or-uuid] is the name or UUID of the storage pool the volume is in. If the volume name is provided instead of the key or path, then providing the pool is necessary to find the volume to be deleted; otherwise, the first volume found by the key or path will be used.
The --delete-snapshots flag specifies that any snapshots associated with the storage volume should be deleted as well. Not all storage drivers support this option, presently only rbd.
vol-upload Syntax:
vol-upload vol-name-or-key-or-path local-file [--pool pool-or-uuid] [--offset bytes] [--length bytes] [--sparse]
Upload the contents of local-file to a storage volume.
vol-name-or-key-or-path is the name or key or path of the volume where the local-file will be uploaded.
--pool pool-or-uuid is the name or UUID of the storage pool the volume is in. If the volume name is provided instead of the key or path, then providing the pool is necessary to find the volume to be uploaded into; otherwise, the first volume found by the key or path will be used.
--offset is the position in the storage volume at which to start writing the data. The value must be 0 or larger.
--length is an upper bound of the amount of data to be uploaded.  A negative value is interpreted as an unsigned long long value to essentially include everything from the offset to the end of the volume.
If --sparse is specified, this command will preserve volume sparseness.
An error will occur if the local-file is greater than the specified length.
See the description for the libvirt virStorageVolUpload API for details regarding possible target volume and pool changes as a result of the pool refresh when the upload is attempted.
vol-download Syntax:
vol-download vol-name-or-key-or-path local-file [--pool pool-or-uuid] [--offset bytes] [--length bytes] [--sparse]
Download the contents of a storage volume to local-file.
vol-name-or-key-or-path is the name or key or path of the volume to download into local-file.
--offset is the position in the storage volume at which to start reading the data. The value must be 0 or larger.
--length is an upper bound of the amount of data to be downloaded.  A negative value is interpreted as an unsigned long long value to essentially include everything from the offset to the end of the volume.
vol-wipe Syntax:
vol-wipe vol-name-or-key-or-path [--pool pool-or-uuid] [--algorithm algorithm]
Wipe a volume, ensure data previously on the volume is not accessible to future reads.
vol-name-or-key-or-path is the name or key or path of the volume to wipe. It is possible to choose different wiping algorithms instead of re-writing volume with zeroes.
--pool pool-or-uuid is the name or UUID of the storage pool the volume is in. If the volume name is provided instead of the key or path, then providing the pool is necessary to find the volume to be wiped; otherwise, the first volume found by the key or path will be used.
Use the --algorithm switch choosing from the list of the following algorithms in order to define which algorithm to use for the wipe.
Supported algorithms
• zero       - 1-pass all zeroes
• nnsa       - 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) for sanitizing removable and non-removable hard disks: random x2, 0x00, verify.
• dod        - 4-pass DoD 5220.22-M section 8-306 procedure for sanitizing removable and non-removable rigid disks: random, 0x00, 0xff, verify.
• bsi        - 9-pass method recommended by the German Center of Security in Information Technologies (https://www.bsi.bund.de): 0xff, 0xfe, 0xfd, 0xfb, 0xf7, 0xef, 0xdf, 0xbf, 0x7f.
• gutmann    - The canonical 35-pass sequence described in Gutmann's paper.
• schneier   - 7-pass method described by Bruce Schneier in "Applied Cryptography" (1996): 0x00, 0xff, random x5.
• pfitzner7  - Roy Pfitzner's 7-random-pass method: random x7.
• pfitzner33 - Roy Pfitzner's 33-random-pass method: random x33.
• random     - 1-pass pattern: random.
• trim       - 1-pass trimming the volume using TRIM or DISCARD
Note: The scrub binary will be used to handle the 'nnsa', 'dod', 'bsi', 'gutmann', 'schneier', 'pfitzner7' and 'pfitzner33' algorithms.  The availability of the algorithms may be limited by the version of the scrub binary installed on the host. The 'zero' algorithm will write zeroes to the entire volume. For some volumes, such as sparse or rbd volumes, this may result in completely filling the volume with zeroes making it appear to be completely full. As an alternative, the 'trim' algorithm does not overwrite all the data in a volume, rather it expects the storage driver to be able to discard all bytes in a volume. It is up to the storage driver to handle how the discarding occurs. Not all storage drivers or volume types can support 'trim'.
vol-dumpxml Syntax:
vol-dumpxml vol-name-or-key-or-path [--pool pool-or-uuid]
Output the volume information as an XML dump to stdout.
vol-name-or-key-or-path is the name or key or path of the volume to output the XML.
vol-info Syntax:
vol-info vol-name-or-key-or-path [--pool pool-or-uuid] [--bytes] [--physical]
Returns basic information about the given storage volume.
vol-name-or-key-or-path is the name or key or path of the volume to return information for.
If --bytes is specified the sizes are not converted to human friendly units.
If --physical is specified, then the host physical size is returned and displayed instead of the allocation value. The physical value for some file types, such as qcow2 may have a different (larger) physical value than is shown for allocation. Additionally sparse files will have different physical and allocation values.
vol-list Syntax:
vol-list [--pool pool-or-uuid] [--details]
Return the list of volumes in the given storage pool.
--pool pool-or-uuid is the name or UUID of the storage pool.
The --details option instructs virsh to additionally display volume type and capacity related information where available.
vol-pool Syntax:
vol-pool vol-key-or-path [--uuid]
Return the pool name or UUID for a given volume. By default, the pool name is returned.
vol-key-or-path is the key or path of the volume to return the pool information.
If the --uuid option is given, the pool UUID is returned instead.
vol-path Syntax:
vol-path vol-name-or-key [--pool pool-or-uuid]
Return the path for a given volume.
vol-name-or-key is the name or key of the volume to return the path.
--pool pool-or-uuid is the name or UUID of the storage pool the volume is in. If the volume name is provided instead of the key, then providing the pool is necessary to find the volume to be uploaded into; otherwise, the first volume found by the key will be used.
vol-name Syntax:
vol-name vol-key-or-path
Return the name for a given volume.
vol-key-or-path is the key or path of the volume to return the name.
vol-key Syntax:
vol-key vol-name-or-path [--pool pool-or-uuid]
Return the volume key for a given volume.
vol-name-or-path is the name or path of the volume to return the volume key.
--pool pool-or-uuid is the name or UUID of the storage pool the volume is in. If the volume name is provided instead of the path, then providing the pool is necessary to find the volume to be uploaded into; otherwise, the first volume found by the path will be used.
vol-resize Syntax:
vol-resize vol-name-or-path capacity [--pool pool-or-uuid] [--allocate] [--delta] [--shrink]
Resize the capacity of the given volume, in bytes.
vol-name-or-key-or-path is the name or key or path of the volume to resize.
capacity is a scaled integer (see NOTES above) for the volume, which defaults to bytes if there is no suffix.
The new capacity might be sparse unless --allocate is specified.
Normally, capacity is the new size, but if --delta is present, then it is added to the existing size.
Attempts to shrink the volume will fail unless --shrink is present.  The capacity cannot be negative unless --shrink is provided, but a negative sign is not necessary.
This command is only safe for storage volumes not in use by an active guest; see also blockresize for live resizing.
The following commands manipulate "secrets" (e.g. passwords, passphrases and encryption keys).  Libvirt can store secrets independently from their use, and other objects (e.g. volumes or domains) can refer to the secrets for encryption or possibly other uses.  Secrets are identified using a UUID.  See https://libvirt.org/formatsecret.html for documentation of the XML format used to represent properties of secrets.
secret-define Syntax:
secret-define file [--validate]
Create a secret with the properties specified in file, with no associated secret value.  If file does not specify a UUID, choose one automatically. If file specifies a UUID of an existing secret, replace its properties by properties defined in file, without affecting the secret value.
secret-dumpxml Syntax:
secret-dumpxml secret
Output properties of secret (specified by its UUID) as an XML dump to stdout.
secret-event Syntax:
secret-event {[secret] event [--loop] [--timeout seconds] [--timestamp] | --list}
Wait for a class of secret events to occur, and print appropriate details of events as they happen.  The events can optionally be filtered by secret.  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.
secret-set-value Syntax:
secret-set-value secret (--file filename [--plain] | --interactive | base64)
Set the value associated with secret (specified by its UUID) to the value Base64-encoded value base64 or Base-64-encoded contents of file named filename. Using the --plain flag is together with --file allows one to use the file contents directly as the secret value.
If --interactive flag is used the secret value is read as a password from the terminal.
Note that --file, --interactive and base64 options are mutually exclusive.
Passing secrets via the base64 option on command line is INSECURE and deprecated. Use the --file option instead.
secret-get-value Syntax:
secret-get-value [--plain] secret
Output the value associated with secret (specified by its UUID) to stdout, encoded using Base64.
If the --plain flag is used the value is not base64 encoded, but rather printed raw. Note that unless virsh is started in quiet mode (virsh -q) it prints a newline at the end of the command. This newline is not part of the secret.
secret-undefine Syntax:
secret-undefine secret
Delete a secret (specified by its UUID), including the associated value, if any.
secret-list Syntax:
secret-list [--ephemeral] [--no-ephemeral] [--private] [--no-private]
Returns the list of secrets. You may also want to filter the returned secrets by --ephemeral to list the ephemeral ones, --no-ephemeral to list the non-ephemeral ones, --private to list the private ones, and --no-private to list the non-private ones.
The following commands manipulate domain snapshots.  Snapshots take the disk, memory, and device state of a domain at a point-of-time, and save it for future use.  They have many uses, from saving a "clean" copy of an OS image to saving a domain's state before a potentially destructive operation.  Snapshots are identified with a unique name.  See https://libvirt.org/formatsnapshot.html for documentation of the XML format used to represent properties of snapshots.
snapshot-create Syntax:
snapshot-create domain [xmlfile] {[--redefine [--current]] | [--no-metadata] [--halt] [--disk-only] [--reuse-external] [--quiesce] [--atomic] [--live]} [--validate]
Create a snapshot for domain domain with the properties specified in xmlfile.   Optionally, the --validate option can be passed to validate the format of the input XML file against an internal RNG schema (identical to using the virt-xml-validate(1) tool). Normally, the only properties settable for a domain snapshot are the <name> and <description> elements, as well as <disks> if --disk-only is given; the rest of the fields are ignored, and automatically filled in by libvirt. If xmlfile is completely omitted, then libvirt will choose a value for all fields.  The new snapshot will become current, as listed by snapshot-current.
If --halt is specified, the domain will be left in an inactive state after the snapshot is created.
If --disk-only is specified, the snapshot will only include disk content rather than the usual full system snapshot with vm state.  Disk snapshots are captured faster than full system snapshots, but reverting to a disk snapshot may require fsck or journal replays, since it is like the disk state at the point when the power cord is abruptly pulled; and mixing --halt and --disk-only loses any data that was not flushed to disk at the time.
If --redefine is specified, then all XML elements produced by snapshot-dumpxml are valid; this can be used to migrate snapshot hierarchy from one machine to another, to recreate hierarchy for the case of a transient domain that goes away and is later recreated with the same name and UUID, or to make slight alterations in the snapshot metadata (such as host-specific aspects of the domain XML embedded in the snapshot).  When this flag is supplied, the xmlfile argument is mandatory, and the domain's current snapshot will not be altered unless the --current flag is also given.
If --no-metadata is specified, then the snapshot data is created, but any metadata is immediately discarded (that is, libvirt does not treat the snapshot as current, and cannot revert to the snapshot unless --redefine is later used to teach libvirt about the metadata again).
If --reuse-external is specified, and the snapshot XML requests an external snapshot with a destination of an existing file, then the destination must exist and be pre-created with correct format and metadata. The file is then reused; otherwise, a snapshot is refused to avoid losing contents of the existing files.
If --quiesce is specified, libvirt will try to use guest agent to freeze and unfreeze domain's mounted file systems. However, if domain has no guest agent, snapshot creation will fail.  Currently, this requires --disk-only to be passed as well.
If --atomic is specified, libvirt will guarantee that the snapshot either succeeds, or fails with no changes; not all hypervisors support this.  If this flag is not specified, then some hypervisors may fail after partially performing the action, and dumpxml must be used to see whether any partial changes occurred.
If --live is specified, libvirt takes the snapshot while the guest is running. Both disk snapshot and domain memory snapshot are taken. This increases the size of the memory image of the external snapshot. This is currently supported only for full system external snapshots.
Existence of snapshot metadata will prevent attempts to undefine a persistent guest.  However, for transient domains, snapshot metadata is silently lost when the domain quits running (whether by command such as destroy or by internal guest action).
For now, it is not possible to create snapshots in a domain that has checkpoints, although this restriction will be lifted in a future release.
snapshot-create-as Syntax:
snapshot-create-as domain {[--print-xml] [--no-metadata] [--halt] [--reuse-external]} [name] [description] [--disk-only [--quiesce]] [--atomic] [--validate] [[--live] [--memspec memspec]] [--diskspec] diskspec]...
Create a snapshot for domain domain with the given <name> and <description>; if either value is omitted, libvirt will choose a value. If --print-xml is specified, then XML appropriate for snapshot-create is output, rather than actually creating a snapshot.  Otherwise, if --halt is specified, the domain will be left in an inactive state after the snapshot is created, and if --disk-only is specified, the snapshot will not include vm state.
The --memspec option can be used to control whether a full system snapshot is internal or external.  The --memspec flag is mandatory, followed by a memspec of the form [file=]name[,snapshot=type], where type can be no, internal, or external.  To include a literal comma in file=name, escape it with a second comma. --memspec cannot be used together with --disk-only.