mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-09 23:10:08 +00:00
96777db719
Make sure that they're entirely contained within a single line and that punctuation is used in a way that doesn't make the resulting HTML look weird. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
837 lines
36 KiB
ReStructuredText
837 lines
36 KiB
ReStructuredText
.. role:: since
|
|
.. role:: removed
|
|
|
|
==================================
|
|
Storage pool and volume XML format
|
|
==================================
|
|
|
|
.. contents::
|
|
|
|
Storage pool XML
|
|
----------------
|
|
|
|
Although all storage pool backends share the same public APIs and XML format,
|
|
they have varying levels of capabilities. Some may allow creation of volumes,
|
|
others may only allow use of pre-existing volumes. Some may have constraints on
|
|
volume size, or placement.
|
|
|
|
The top level tag for a storage pool document is 'pool'. It has a single
|
|
attribute ``type``, which is one of ``dir``, ``fs``, ``netfs``, ``disk``,
|
|
``iscsi``, ``logical``, ``scsi`` (all :since:`since 0.4.1` ), ``mpath`` (
|
|
:since:`since 0.7.1` ), ``rbd`` ( :since:`since 0.9.13` ),
|
|
``sheepdog`` (:since:`since 0.10.0`, :removed:`removed in 8.8.0` ),
|
|
``gluster`` ( :since:`since 1.2.0` ), ``zfs`` (
|
|
:since:`since 1.2.8` ), ``vstorage`` ( :since:`since 3.1.0` ), or
|
|
``iscsi-direct`` ( :since:`since 4.7.0` ). This corresponds to the storage
|
|
backend drivers listed further along in this document.
|
|
|
|
Storage pool general metadata
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
<pool type="iscsi">
|
|
<name>virtimages</name>
|
|
<uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
|
|
<allocation>10000000</allocation>
|
|
<capacity>50000000</capacity>
|
|
<available>40000000</available>
|
|
...
|
|
|
|
``name``
|
|
Providing a name for the pool which is unique to the host. This is mandatory
|
|
when defining a pool. :since:`Since 0.4.1`
|
|
``uuid``
|
|
Providing an identifier for the pool which is globally unique. This is
|
|
optional when defining a pool, a UUID will be generated if omitted.
|
|
:since:`Since 0.4.1`
|
|
``allocation``
|
|
Providing the total storage allocation for the pool. This may be larger than
|
|
the sum of the allocation of all volumes due to metadata overhead. This value
|
|
is in bytes. This is not applicable when creating a pool.
|
|
:since:`Since 0.4.1`
|
|
``capacity``
|
|
Providing the total storage capacity for the pool. Due to underlying device
|
|
constraints it may not be possible to use the full capacity for storage
|
|
volumes. This value is in bytes. This is not applicable when creating a pool.
|
|
:since:`Since 0.4.1`
|
|
``available``
|
|
Providing the free space available for allocating new volumes in the pool.
|
|
Due to underlying device constraints it may not be possible to allocate the
|
|
entire free space to a single volume. This value is in bytes. This is not
|
|
applicable when creating a pool. :since:`Since 0.4.1`
|
|
|
|
Features
|
|
~~~~~~~~
|
|
|
|
Some pools support optional features:
|
|
|
|
::
|
|
|
|
...
|
|
<features>
|
|
<cow state='no'>
|
|
</features>
|
|
...
|
|
|
|
Valid features are:
|
|
|
|
``cow``
|
|
Controls whether the filesystem performs copy-on-write (COW) for images in
|
|
the pool. This may only be set for directory / filesystem pools on the
|
|
``btrfs`` filesystem. If not set then libvirt will attempt to disable COW
|
|
on any btrfs filesystems. :since:`Since 6.6.0`.
|
|
|
|
Source elements
|
|
~~~~~~~~~~~~~~~
|
|
|
|
A single ``source`` element is contained within the top level ``pool`` element.
|
|
This tag is used to describe the source of the storage pool. The set of child
|
|
elements that it will contain depend on the pool type, but come from the
|
|
following child elements:
|
|
|
|
::
|
|
|
|
...
|
|
<source>
|
|
<host name="iscsi.example.com"/>
|
|
<device path="iqn.2013-06.com.example:iscsi-pool"/>
|
|
<auth type='chap' username='myname'>
|
|
<secret usage='mycluster_myname'/>
|
|
</auth>
|
|
<vendor name="Acme"/>
|
|
<product name="model"/>
|
|
</source>
|
|
...
|
|
|
|
::
|
|
|
|
...
|
|
<source>
|
|
<device path='/dev/mapper/mpatha' part_separator='no'/>
|
|
<format type='gpt'/>
|
|
</source>
|
|
...
|
|
|
|
::
|
|
|
|
...
|
|
<source>
|
|
<adapter type='scsi_host' name='scsi_host1'/>
|
|
</source>
|
|
...
|
|
|
|
::
|
|
|
|
...
|
|
<source>
|
|
<adapter type='scsi_host'>
|
|
<parentaddr unique_id='1'>
|
|
<address domain='0x0000' bus='0x00' slot='0x1f' addr='0x2'/>
|
|
</parentaddr>
|
|
</adapter>
|
|
</source>
|
|
...
|
|
|
|
::
|
|
|
|
...
|
|
<source>
|
|
<adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/>
|
|
</source>
|
|
...
|
|
|
|
::
|
|
|
|
...
|
|
<source>
|
|
<host name='localhost'/>
|
|
<dir path='/var/lib/libvirt/images'/>
|
|
<format type='nfs'/>
|
|
<protocol ver='3'/>
|
|
</source>
|
|
...
|
|
|
|
``device``
|
|
Provides the source for pools backed by physical devices (pool types ``fs``,
|
|
``logical``, ``disk``, ``iscsi``, ``iscsi-direct``, ``zfs``, ``vstorage``).
|
|
May be repeated multiple times depending on backend driver. Contains a
|
|
required attribute ``path`` which is either the fully qualified path to the
|
|
block device node or for ``iscsi`` or ``iscsi-direct`` the iSCSI Qualified
|
|
Name (IQN). :since:`Since 0.4.1`
|
|
|
|
An optional attribute ``part_separator`` for each ``path`` may be supplied.
|
|
Valid values for the attribute may be either "yes" or "no". This attribute is
|
|
to be used for a ``disk`` pool type using a ``path`` to a device mapper
|
|
multipath device. Setting the attribute to "yes" causes libvirt to attempt to
|
|
generate and find target volume path's using a "p" separator. The default
|
|
algorithm used by device mapper is to add the "p" separator only when the
|
|
source device path ends with a number; however, it's possible to configure
|
|
the devmapper device to not use 'user_friendly_names' thus creating
|
|
partitions with the "p" separator even when the device source path does not
|
|
end with a number. :since:`Since 1.3.1`
|
|
|
|
``dir``
|
|
Provides the source for pools backed by directories (pool types ``dir``,
|
|
``netfs``, ``gluster``), or optionally to select a subdirectory within a pool
|
|
that resembles a filesystem (pool type ``gluster``). May only occur once.
|
|
Contains a single attribute ``path`` which is the fully qualified path to the
|
|
backing directory or for a ``netfs`` pool type using ``format`` type "cifs",
|
|
the path to the Samba share without the leading slash. :since:`Since 0.4.1`
|
|
``adapter``
|
|
Provides the source for pools backed by SCSI adapters (pool type ``scsi``).
|
|
May only occur once.
|
|
|
|
``name``
|
|
The SCSI adapter name (e.g. "scsi_host1", although a name such as "host1"
|
|
is still supported for backwards compatibility, it is not recommended).
|
|
The scsi_host name to be used can be determined from the output of a
|
|
``virsh nodedev-list scsi_host`` command followed by a
|
|
combination of ``lspci`` and
|
|
``virsh nodedev-dumpxml scsi_hostN`` commands to find the
|
|
``scsi_hostN`` to be used. :since:`Since 0.6.2`
|
|
|
|
It is further recommended to utilize the ``parentaddr`` element since it's
|
|
possible to have the path to which the scsi_hostN uses change between
|
|
system reboots. :since:`Since 1.2.7`
|
|
|
|
``type``
|
|
Specifies the adapter type. Valid values are "scsi_host" or "fc_host". If
|
|
omitted and the ``name`` attribute is specified, then it defaults to
|
|
"scsi_host". To keep backwards compatibility, this attribute is optional
|
|
**only** for the "scsi_host" adapter, but is mandatory for the "fc_host"
|
|
adapter. :since:`Since 1.0.5` A "fc_host" capable scsi_hostN can be
|
|
determined by using ``virsh nodedev-list --cap fc_host``.
|
|
:since:`Since 1.2.8`
|
|
|
|
Note: Regardless of whether a "scsi_host" adapter type is defined using a
|
|
``name`` or a ``parentaddr``, it should refer to a real scsi_host adapter
|
|
as found through a ``virsh nodedev-list scsi_host`` and
|
|
``virsh nodedev-dumpxml scsi_hostN`` on one of the scsi_host's
|
|
displayed. It should not refer to a "fc_host" capable scsi_hostN nor
|
|
should it refer to the vHBA created for some "fc_host" adapter. For a vHBA
|
|
the ``nodedev-dumpxml`` output parent setting will be the "fc_host"
|
|
capable scsi_hostN value. Additionally, do not refer to an iSCSI
|
|
scsi_hostN for the "scsi_host" source. An iSCSI scsi_hostN's
|
|
``nodedev-dumpxml`` output parent field is generally "computer". This is a
|
|
libvirt created parent value indicating no parent was defined for the node
|
|
device.
|
|
|
|
``wwnn`` and ``wwpn``
|
|
The required "World Wide Node Name" (``wwnn``) and "World Wide Port Name"
|
|
(``wwpn``) are used by the "fc_host" adapter to uniquely identify the vHBA
|
|
device in the Fibre Channel storage fabric. If the vHBA device already
|
|
exists as a Node Device, then libvirt will use it; otherwise, the vHBA
|
|
will be created using the provided values. It is considered a
|
|
configuration error use the values from the HBA as those would be for a
|
|
"scsi_host" ``type`` pool instead. The ``wwnn`` and ``wwpn`` have very
|
|
specific format requirements based on the hypervisor being used, thus care
|
|
should be taken if you decide to generate your own to follow the
|
|
standards; otherwise, the pool will fail to start with an opaque error
|
|
message indicating failure to write to the vport_create file during vport
|
|
create/delete due to "No such file or directory". :since:`Since 1.0.4`
|
|
|
|
``parent``
|
|
Used by the "fc_host" adapter type to optionally specify the parent
|
|
scsi_host device defined in the `Node Device <formatnode.html>`__ database
|
|
as the `NPIV <https://wiki.libvirt.org/page/NPIV_in_libvirt>`__ virtual
|
|
Host Bus Adapter (vHBA). The value provided must be a vport capable
|
|
scsi_host. The value is not the scsi_host of the vHBA created by 'virsh
|
|
nodedev-create', rather it is the parent of that vHBA. If the value is not
|
|
provided, libvirt will determine the parent based either finding the
|
|
wwnn,wwpn defined for an existing scsi_host or by creating a vHBA.
|
|
Providing the parent attribute is also useful for the duplicate pool
|
|
definition checks. This is more important in environments where both the
|
|
"fc_host" and "scsi_host" source adapter pools are being used in order to
|
|
ensure a new definition doesn't duplicate using the scsi_hostN of some
|
|
existing storage pool. :since:`Since 1.0.4`
|
|
``parent_wwnn`` and ``parent_wwpn``
|
|
Instead of the ``parent`` to specify which scsi_host to use by name, it's
|
|
possible to provide the wwnn and wwpn of the parent to be used for the
|
|
vHBA in order to ensure that between reboots or after a hardware
|
|
configuration change that the scsi_host parent name doesn't change. Both
|
|
the parent_wwnn and parent_wwpn must be provided. :since:`Since 3.0.0`
|
|
``parent_fabric_wwn``
|
|
Instead of the ``parent`` to specify which scsi_host to use by name, it's
|
|
possible to provide the fabric_wwn on which the scsi_host exists. This
|
|
provides flexibility for choosing a scsi_host that may be available on the
|
|
fabric rather than requiring a specific parent by wwnn or wwpn to be
|
|
available. :since:`Since 3.0.0`
|
|
``managed``
|
|
An optional attribute to instruct the SCSI storage backend to manage
|
|
destroying the vHBA when the pool is destroyed. For configurations that do
|
|
not provide an already created vHBA from a 'virsh nodedev-create', libvirt
|
|
will set this property to "yes". For configurations that have already
|
|
created a vHBA via 'virsh nodedev-create' and are using the wwnn/wwpn from
|
|
that vHBA and optionally the scsi_host parent, setting this attribute to
|
|
"yes" will allow libvirt to destroy the node device when the pool is
|
|
destroyed. If this attribute is set to "no" or not defined in the XML,
|
|
then libvirt will not destroy the vHBA. :since:`Since 1.2.11`
|
|
|
|
``parentaddr``
|
|
Used by the "scsi_host" adapter type instead of the ``name`` attribute to
|
|
more uniquely identify the SCSI host. Using a combination of the
|
|
``unique_id`` attribute and the ``address`` element to formulate a PCI
|
|
address, a search will be performed of the ``/sys/class/scsi_host/hostNN``
|
|
links for a matching PCI address with a matching ``unique_id`` value in
|
|
the ``/sys/class/scsi_host/hostNN/unique_id`` file. The value in the
|
|
"unique_id" file will be unique enough for the specific PCI address. The
|
|
``hostNN`` will be used by libvirt as the basis to define which SCSI host
|
|
is to be used for the currently booted system. :since:`Since 1.2.7`
|
|
|
|
``address``
|
|
The PCI address of the scsi_host device to be used. Using a PCI address
|
|
provides consistent naming across system reboots and kernel reloads.
|
|
The address will have four attributes: ``domain`` (a 2-byte hex
|
|
integer, not currently used by qemu), ``bus`` (a hex value between 0
|
|
and 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f,
|
|
inclusive), and ``function`` (a value between 0 and 7, inclusive). The
|
|
PCI address can be determined by listing the ``/sys/bus/pci/devices``
|
|
and the ``/sys/class/scsi_host`` directories in order to find the
|
|
expected scsi_host device. The address will be provided in a format
|
|
such as "0000:00:1f:2" which can be used to generate the expected PCI
|
|
address "domain='0x0000' bus='0x00' slot='0x1f' function='0x0'".
|
|
Optionally, using the combination of the commands 'virsh nodedev-list
|
|
scsi_host' and 'virsh nodedev-dumpxml' for a specific list entry and
|
|
converting the resulting ``path`` element as the basis to formulate the
|
|
correctly formatted PCI address.
|
|
|
|
``unique_id``
|
|
Required ``parentaddr`` attribute used to determine which of the
|
|
scsi_host adapters for the provided PCI address should be used. The
|
|
value is determine by contents of the ``unique_id`` file for the
|
|
specific scsi_host adapter. For a PCI address of "0000:00:1f:2", the
|
|
unique identifier files can be found using the command
|
|
``find -H /sys/class/scsi_host/host*/unique_id | xargs grep '[0-9]'``.
|
|
Optionally, the ``virsh nodedev-dumpxml scsi_hostN``' of a specific
|
|
scsi_hostN list entry will list the ``unique_id`` value.
|
|
``host``
|
|
Provides the source for pools backed by storage from a remote server (pool
|
|
types ``netfs``, ``iscsi``, ``iscsi-direct``, ``rbd``, ``sheepdog``,
|
|
``gluster``). Will be used in combination with a ``directory`` or ``device``
|
|
element. Contains an attribute ``name`` which is the hostname or IP address
|
|
of the server. May optionally contain a ``port`` attribute for the protocol
|
|
specific port number. Duplicate storage pool definition checks may perform a
|
|
cursory check that the same host name by string comparison in the new pool
|
|
does not match an existing pool's source host name when combined with the
|
|
``directory`` or ``device`` element. Name resolution of the provided hostname
|
|
or IP address is left to the storage driver backend interactions with the
|
|
remote server. See the `storage driver page <storage.html>`__ for any
|
|
restrictions for specific storage backends. :since:`Since 0.4.1`
|
|
``initiator``
|
|
Required by the ``iscsi-direct`` pool in order to provide the iSCSI Qualified
|
|
Name (IQN) to communicate with the pool's ``device`` target IQN. There is one
|
|
sub-element ``iqn`` with the ``name`` attribute to describe the IQN for the
|
|
initiator. :since:`Since 4.7.0`
|
|
``auth``
|
|
If present, the ``auth`` element provides the authentication credentials
|
|
needed to access the source by the setting of the ``type`` attribute (pool
|
|
types ``iscsi``, ``iscsi-direct``, ``rbd``). The ``type`` must be either
|
|
"chap" or "ceph". Use "ceph" for Ceph RBD (Rados Block Device) network
|
|
sources and use "iscsi" for CHAP (Challenge-Handshake Authentication
|
|
Protocol) iSCSI targets. Additionally a mandatory attribute ``username``
|
|
identifies the username to use during authentication as well as a sub-element
|
|
``secret`` with a mandatory attribute ``type``, to tie back to a `libvirt
|
|
secret object <formatsecret.html>`__ that holds the actual password or other
|
|
credentials. The domain XML intentionally does not expose the password, only
|
|
the reference to the object that manages the password. The ``secret`` element
|
|
requires either a ``uuid`` attribute with the UUID of the secret object or a
|
|
``usage`` attribute matching the key that was specified in the secret object.
|
|
:since:`Since 0.9.7 for "ceph" and 1.1.1 for "chap"`
|
|
``name``
|
|
Provides the source for pools backed by storage from a named element (pool
|
|
types ``logical``, ``rbd``, ``sheepdog``, ``gluster``). Contains a string
|
|
identifier. :since:`Since 0.4.5`
|
|
``format``
|
|
Provides information about the format of the pool (pool types ``fs``,
|
|
``netfs``, ``disk``, ``logical``). This contains a single attribute ``type``
|
|
whose value is backend specific. This is typically used to indicate
|
|
filesystem type, or network filesystem type, or partition table type, or LVM
|
|
metadata type. All drivers are required to have a default value for this, so
|
|
it is optional. :since:`Since 0.4.1`
|
|
``protocol``
|
|
For a ``netfs`` Storage Pool provide a mechanism to define which NFS protocol
|
|
version number will be used to contact the server's NFS service. The
|
|
attribute ``ver`` accepts the version number to use.
|
|
:since:`Since 5.1.0`
|
|
``vendor``
|
|
Provides optional information about the vendor of the storage device. This
|
|
contains a single attribute ``name`` whose value is backend specific.
|
|
:since:`Since 0.8.4`
|
|
``product``
|
|
Provides an optional product name of the storage device. This contains a
|
|
single attribute ``name`` whose value is backend specific.
|
|
:since:`Since 0.8.4`
|
|
|
|
Storage pool target elements
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A single ``target`` element is contained within the top level ``pool`` element
|
|
for some types of pools (pool types ``dir``, ``fs``, ``netfs``, ``logical``,
|
|
``disk``, ``iscsi``, ``scsi``, ``mpath``, ``zfs``). This tag is used to describe
|
|
the mapping of the storage pool into the host filesystem. It can contain the
|
|
following child elements:
|
|
|
|
::
|
|
|
|
...
|
|
<target>
|
|
<path>/dev/disk/by-path</path>
|
|
<permissions>
|
|
<owner>107</owner>
|
|
<group>107</group>
|
|
<mode>0744</mode>
|
|
<label>virt_image_t</label>
|
|
</permissions>
|
|
</target>
|
|
</pool>
|
|
|
|
``path``
|
|
Provides the location at which the pool will be mapped into the local
|
|
filesystem namespace, as an absolute path. For a filesystem/directory based
|
|
pool it will be a fully qualified name of the directory in which volumes will
|
|
be created. For device based pools it will be a fully qualified name of the
|
|
directory in which devices nodes exist. For the latter ``/dev/`` may seem
|
|
like the logical choice, however, devices nodes there are not guaranteed
|
|
stable across reboots, since they are allocated on demand. It is preferable
|
|
to use a stable location such as one of the
|
|
``/dev/disk/by-{path|id|uuid|label}`` locations. For ``logical`` and ``zfs``
|
|
pool types, a provided value is ignored and a default path generated. For a
|
|
Multipath pool (type ``mpath``), the provided value is ignored and the
|
|
default value of "/dev/mapper" is used. :since:`Since 0.4.1`
|
|
``permissions``
|
|
This is currently only useful for directory or filesystem based pools, which
|
|
are mapped as a directory into the local filesystem namespace. It provides
|
|
information about the permissions to use for the final directory when the
|
|
pool is built. There are 4 child elements. The ``mode`` element contains the
|
|
octal permission set. The ``mode`` defaults to 0711 when not provided. The
|
|
``owner`` element contains the numeric user ID. The ``group`` element
|
|
contains the numeric group ID. If ``owner`` or ``group`` aren't specified
|
|
when creating a directory, the UID and GID of the libvirtd process are used.
|
|
The ``label`` element contains the MAC (eg SELinux) label string.
|
|
:since:`Since 0.4.1` For running directory or filesystem based pools, these
|
|
fields will be filled with the values used by the existing directory.
|
|
:since:`Since 1.2.16`
|
|
|
|
Device extents
|
|
~~~~~~~~~~~~~~
|
|
|
|
If a storage pool exposes information about its underlying placement /
|
|
allocation scheme, the ``device`` element within the ``source`` element may
|
|
contain information about its available extents. Some pools have a constraint
|
|
that a volume must be allocated entirely within a single constraint (eg disk
|
|
partition pools). Thus the extent information allows an application to determine
|
|
the maximum possible size for a new volume
|
|
|
|
For storage pools supporting extent information, within each ``device`` element
|
|
there will be zero or more ``freeExtent`` elements. Each of these elements
|
|
contains two attributes, ``start`` and ``end`` which provide the boundaries of
|
|
the extent on the device, measured in bytes. :since:`Since 0.4.1`
|
|
|
|
Refresh overrides
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
The optional ``refresh`` element can control how the pool and associated volumes
|
|
are refreshed (pool type ``rbd``). The ``allocation`` attribute of the
|
|
``volume`` child element controls the method used for computing the allocation
|
|
of a volume. The valid attribute values are ``default`` to compute the actual
|
|
usage or ``capacity`` to use the logical capacity for cases where computing the
|
|
allocation is too expensive. The following XML snippet shows the syntax:
|
|
|
|
::
|
|
|
|
<pool type="rbd">
|
|
<name>myrbdpool</name>
|
|
...
|
|
<source/>
|
|
...
|
|
<refresh>
|
|
<volume allocation='capacity'/>
|
|
</refresh>
|
|
...
|
|
</pool>
|
|
|
|
:since:`Since 5.2.0`
|
|
|
|
Storage Pool Namespaces
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Usage of Storage Pool Namespaces provides a mechanism to provide pool type
|
|
specific data in a free form or arbitrary manner via XML syntax targeted solely
|
|
for the needs of the specific pool type which is not otherwise supported in
|
|
standard XML. For the "fs" and "netfs" pool types this provides a mechanism to
|
|
provide additional mount options on the command line. For the "rbd" pool this
|
|
provides a mechanism to override default settings for RBD configuration options.
|
|
|
|
Usage of namespaces comes with no support guarantees. It is intended for
|
|
developers testing out a concept prior to requesting an explicitly supported XML
|
|
option in libvirt, and thus should never be used in production.
|
|
|
|
``fs:mount_opts``
|
|
Provides an XML namespace mechanism to optionally utilize specifically named
|
|
options for the mount command via the "-o" option for the ``fs`` or ``netfs``
|
|
type storage pools. In order to designate that the Storage Pool will be using
|
|
the mechanism, the ``pool`` element must be modified to provide the XML
|
|
namespace attribute syntax as follows::
|
|
|
|
xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'
|
|
|
|
The ``fs:mount_opts`` defines the mount options by specifying multiple
|
|
``fs:option`` subelements with the attribute ``name`` specifying the mount
|
|
option to be added. The value of the named option is not checked since it's
|
|
possible options don't exist on all distributions. It is expected that proper
|
|
and valid options will be supplied for the target host.
|
|
|
|
The following XML snippet shows the syntax required in order to utilize for a
|
|
netfs pool:
|
|
|
|
::
|
|
|
|
<pool type="netfs" xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'>
|
|
<name>nfsimages</name>
|
|
...
|
|
<source>
|
|
...
|
|
</source>
|
|
...
|
|
<target>
|
|
...
|
|
</target>
|
|
<fs:mount_opts>
|
|
<fs:option name='sync'/>
|
|
<fs:option name='lazytime'/>
|
|
</fs:mount_opts>
|
|
</pool>
|
|
...
|
|
|
|
:since:`Since 5.1.0`.
|
|
|
|
``rbd:config_opts``
|
|
Provides an XML namespace mechanism to optionally utilize specifically named
|
|
options for the RBD configuration options via the rados_conf_set API for the
|
|
``rbd`` type storage pools. In order to designate that the Storage Pool will
|
|
be using the mechanism, the ``pool`` element must be modified to provide the
|
|
XML namespace attribute syntax as follows:
|
|
|
|
xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'
|
|
|
|
The ``rbd:config_opts`` defines the configuration options by specifying
|
|
multiple ``rbd:option`` subelements with the attribute ``name`` specifying
|
|
the configuration option to be added and ``value`` specifying the
|
|
configuration option value. The name and value for each option is only
|
|
checked to be not empty. The name and value provided are not checked since
|
|
it's possible options don't exist on all distributions. It is expected that
|
|
proper and valid options will be supplied for the target host.
|
|
|
|
The following XML snippet shows the syntax required in order to utilize
|
|
|
|
::
|
|
|
|
<pool type="rbd" xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'>
|
|
<name>myrbdpool</name>
|
|
...
|
|
<source>
|
|
...
|
|
</source>
|
|
...
|
|
<target>
|
|
...
|
|
</target>
|
|
...
|
|
<rbd:config_opts>
|
|
<rbd:option name='client_mount_timeout' value='45'/>
|
|
<rbd:option name='rados_mon_op_timeout' value='20'/>
|
|
<rbd:option name='rados_osd_op_timeout' value='10'/>
|
|
</rbd:config_opts>
|
|
</pool>
|
|
|
|
:since:`Since 5.1.0`.
|
|
|
|
Storage volume XML
|
|
------------------
|
|
|
|
A storage volume will generally be either a file or a device node;
|
|
:since:`since 1.2.0`, an optional output-only attribute ``type`` lists
|
|
the actual type (file,
|
|
block, dir, network, netdir or ploop), which is also available from
|
|
``virStorageVolGetInfo()``. The storage volume XML format is available
|
|
:since:`since 0.4.1`
|
|
|
|
Storage volume general metadata
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
<volume type='file'>
|
|
<name>sparse.img</name>
|
|
<key>/var/lib/xen/images/sparse.img</key>
|
|
<allocation>0</allocation>
|
|
<capacity unit="T">1</capacity>
|
|
...
|
|
|
|
``name``
|
|
Providing a name for the volume which is unique to the pool. This is
|
|
mandatory when defining a volume. For a disk pool, the name must be
|
|
combination of the ``source`` device path device and next partition number to
|
|
be created. For example, if the ``source`` device path is /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. :since:`Since 0.4.1`
|
|
``key``
|
|
Providing an identifier for the volume which identifies a single volume. In
|
|
some cases it's possible to have two distinct keys identifying a single
|
|
volume. This field cannot be set when creating a volume: it is always
|
|
generated. :since:`Since 0.4.1`
|
|
``allocation``
|
|
Providing the total storage allocation for the volume. This may be smaller
|
|
than the logical capacity if the volume is sparsely allocated. It may also be
|
|
larger than the logical capacity if the volume has substantial metadata
|
|
overhead. This value is in bytes. If omitted when creating a volume, the
|
|
volume will be fully allocated at time of creation. If set to a value smaller
|
|
than the capacity, the pool has the **option** of deciding to sparsely
|
|
allocate a volume. It does not have to honour requests for sparse allocation
|
|
though. Different types of pools may treat sparse volumes differently. For
|
|
example, the ``logical`` pool will not automatically expand volume's
|
|
allocation when it gets full; the user is responsible for doing that or
|
|
configuring dmeventd to do so automatically.
|
|
By default this is specified in bytes, but an optional attribute ``unit`` can
|
|
be specified to adjust the passed value. Values can be: 'B' or 'bytes' for
|
|
bytes, 'KB' (kilobytes, 10\ :sup:`3` or 1000 bytes), 'K' or 'KiB' (kibibytes,
|
|
2\ :sup:`10` or 1024 bytes), 'MB' (megabytes, 10\ :sup:`6` or 1,000,000
|
|
bytes), 'M' or 'MiB' (mebibytes, 2\ :sup:`20` or 1,048,576 bytes), 'GB'
|
|
(gigabytes, 10\ :sup:`9` or 1,000,000,000 bytes), 'G' or 'GiB' (gibibytes,
|
|
2\ :sup:`30` or 1,073,741,824 bytes), 'TB' (terabytes, 10\ :sup:`12` or
|
|
1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes, 2\ :sup:`40` or
|
|
1,099,511,627,776 bytes), 'PB' (petabytes, 10\ :sup:`15` or
|
|
1,000,000,000,000,000 bytes), 'P' or 'PiB' (pebibytes, 2\ :sup:`50` or
|
|
1,125,899,906,842,624 bytes), 'EB' (exabytes, 10\ :sup:`18` or
|
|
1,000,000,000,000,000,000 bytes), or 'E' or 'EiB' (exbibytes, 2\ :sup:`60` or
|
|
1,152,921,504,606,846,976 bytes). :since:`Since 0.4.1`, multi-character
|
|
``unit`` :since:`since 0.9.11`.
|
|
``capacity``
|
|
Providing the logical capacity for the volume. This value is in bytes by
|
|
default, but a ``unit`` attribute can be specified with the same semantics as
|
|
for ``allocation`` This is compulsory when creating a volume.
|
|
:since:`Since 0.4.1`
|
|
``physical``
|
|
This output only element provides the host physical size of the target
|
|
storage volume. The default output ``unit`` will be in bytes.
|
|
:since:`Since 3.0.0`
|
|
``source``
|
|
Provides information about the underlying storage allocation of the volume.
|
|
This may not be available for some pool types. :since:`Since 0.4.1`
|
|
``target``
|
|
Provides information about the representation of the volume on the local
|
|
host. :since:`Since 0.4.1`
|
|
|
|
Storage volume target elements
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A single ``target`` element is contained within the top level ``volume``
|
|
element. This tag is used to describe the mapping of the storage volume into the
|
|
host filesystem. It can contain the following child elements:
|
|
|
|
::
|
|
|
|
...
|
|
<target>
|
|
<path>/var/lib/virt/images/sparse.img</path>
|
|
<format type='qcow2'/>
|
|
<permissions>
|
|
<owner>107</owner>
|
|
<group>107</group>
|
|
<mode>0744</mode>
|
|
<label>virt_image_t</label>
|
|
</permissions>
|
|
<timestamps>
|
|
<atime>1341933637.273190990</atime>
|
|
<mtime>1341930622.047245868</mtime>
|
|
<ctime>1341930622.047245868</ctime>
|
|
</timestamps>
|
|
<encryption type='...'>
|
|
...
|
|
</encryption>
|
|
<compat>1.1</compat>
|
|
<nocow/>
|
|
<clusterSize unit='KiB'>64</clusterSize>
|
|
<features>
|
|
<lazy_refcounts/>
|
|
<extended_l2/>
|
|
</features>
|
|
</target>
|
|
|
|
``path``
|
|
Provides the location at which the volume can be accessed on the local
|
|
filesystem, as an absolute path. This is a readonly attribute, so shouldn't
|
|
be specified when creating a volume. :since:`Since 0.4.1`
|
|
``format``
|
|
Provides information about the pool specific volume format. For disk pools it
|
|
will provide the partition table format type, but is not preserved after a
|
|
pool refresh or libvirtd restart. Use extended in order to create an extended
|
|
disk extent partition. For filesystem or directory pools it will provide the
|
|
file format type, eg cow, qcow, vmdk, raw. If omitted when creating a volume,
|
|
the pool's default format will be used. The actual format is specified via
|
|
the ``type`` attribute. Consult the `storage driver page <storage.html>`__
|
|
for the list of valid volume format type values for each specific pool. The
|
|
``format`` will be ignored on input for pools without a volume format type
|
|
value and the default pool format will be used. :since:`Since 0.4.1`
|
|
``permissions``
|
|
Provides information about the permissions to use when creating volumes. This
|
|
is currently only useful for directory or filesystem based pools, where the
|
|
volumes allocated are simple files. For pools where the volumes are device
|
|
nodes, the hotplug scripts determine permissions. There are 4 child elements.
|
|
The ``mode`` element contains the octal permission set. The ``mode`` defaults
|
|
to 0600 when not provided. The ``owner`` element contains the numeric user
|
|
ID. The ``group`` element contains the numeric group ID. If ``owner`` or
|
|
``group`` aren't specified when creating a supported volume, the UID and GID
|
|
of the libvirtd process are used. The ``label`` element contains the MAC (eg
|
|
SELinux) label string. For existing directory or filesystem based volumes,
|
|
these fields will be filled with the values used by the existing file.
|
|
:since:`Since 0.4.1`
|
|
``timestamps``
|
|
Provides timing information about the volume. Up to four sub-elements are
|
|
present, where ``atime``, ``btime``, ``ctime`` and ``mtime`` hold the access,
|
|
birth, change and modification time of the volume, where known. The used time
|
|
format is <seconds>.<nanoseconds> since the beginning of the epoch (1 Jan
|
|
1970). If nanosecond resolution is 0 or otherwise unsupported by the host OS
|
|
or filesystem, then the nanoseconds part is omitted. This is a readonly
|
|
attribute and is ignored when creating a volume. :since:`Since 0.10.0`
|
|
``encryption``
|
|
If present, specifies how the volume is encrypted. See the `Storage
|
|
Encryption <formatstorageencryption.html>`__ page for more information.
|
|
``compat``
|
|
Specify compatibility level. So far, this is only used for ``type='qcow2'``
|
|
volumes. Valid values are ``0.10`` and ``1.1`` so far, specifying QEMU
|
|
version the images should be compatible with. If the ``feature`` element is
|
|
present, 1.1 is used. :since:`Since 1.1.0` If omitted, 0.10 is used.
|
|
:since:`Since 1.1.2`
|
|
``nocow``
|
|
Turn off COW of the newly created volume. So far, this is only valid for a
|
|
file image in btrfs file system. It will improve performance when the file
|
|
image is used in VM. To create non-raw file images, it requires QEMU version
|
|
since 2.1. :since:`Since 1.2.7`
|
|
``clusterSize``
|
|
Changes the qcow2 cluster size which can affect image file size and
|
|
performance. :since:`Since 7.4.0`
|
|
``features``
|
|
Format-specific features. Only used for ``qcow2`` now. Valid sub-elements
|
|
are:
|
|
|
|
- ``<lazy_refcounts/>`` - allow delayed reference counter updates.
|
|
:since:`Since 1.1.0`
|
|
- ``<extended_l2/>`` - enables subcluster allocation for qcow2 images. QCOW2
|
|
clusters are split into 32 subclusters decreasing the size of L2 cache
|
|
needed. It's recommended to increase ``clusterSize``.
|
|
|
|
Backing store elements
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A single ``backingStore`` element is contained within the top level ``volume``
|
|
element. This tag is used to describe the optional copy on write, backing store
|
|
for the storage volume. It can contain the following child elements:
|
|
|
|
::
|
|
|
|
...
|
|
<backingStore>
|
|
<path>/var/lib/virt/images/master.img</path>
|
|
<format type='raw'/>
|
|
<permissions>
|
|
<owner>107</owner>
|
|
<group>107</group>
|
|
<mode>0744</mode>
|
|
<label>virt_image_t</label>
|
|
</permissions>
|
|
</backingStore>
|
|
</volume>
|
|
|
|
``path``
|
|
Provides the location at which the backing store can be accessed on the local
|
|
filesystem, as an absolute path. If omitted, there is no backing store for
|
|
this volume. :since:`Since 0.6.0`
|
|
``format``
|
|
Provides information about the pool specific backing store format. For disk
|
|
pools it will provide the partition type. For filesystem or directory pools
|
|
it will provide the file format type, eg cow, qcow, vmdk, raw. The actual
|
|
format is specified via the type attribute. Consult the pool-specific docs
|
|
for the list of valid values. Most file formats require a backing store of
|
|
the same format, however, the qcow2 format allows a different backing store
|
|
format. :since:`Since 0.6.0`
|
|
``permissions``
|
|
Provides information about the permissions of the backing file. See volume
|
|
``permissions`` documentation for explanation of individual fields.
|
|
:since:`Since 0.6.0`
|
|
|
|
Example configuration
|
|
---------------------
|
|
|
|
Here are a couple of examples, for a more complete set demonstrating every type
|
|
of storage pool, consult the `storage driver page <storage.html>`__
|
|
|
|
File based storage pool
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
<pool type="dir">
|
|
<name>virtimages</name>
|
|
<target>
|
|
<path>/var/lib/virt/images</path>
|
|
</target>
|
|
</pool>
|
|
|
|
iSCSI based storage pool
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
<pool type="iscsi">
|
|
<name>virtimages</name>
|
|
<source>
|
|
<host name="iscsi.example.com"/>
|
|
<device path="iqn.2013-06.com.example:iscsi-pool"/>
|
|
<auth type='chap' username='myuser'>
|
|
<secret usage='libvirtiscsi'/>
|
|
</auth>
|
|
</source>
|
|
<target>
|
|
<path>/dev/disk/by-path</path>
|
|
</target>
|
|
</pool>
|
|
|
|
Storage volume
|
|
~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
<volume>
|
|
<name>sparse.img</name>
|
|
<allocation>0</allocation>
|
|
<capacity unit="T">1</capacity>
|
|
<target>
|
|
<path>/var/lib/virt/images/sparse.img</path>
|
|
<permissions>
|
|
<owner>107</owner>
|
|
<group>107</group>
|
|
<mode>0744</mode>
|
|
<label>virt_image_t</label>
|
|
</permissions>
|
|
</target>
|
|
</volume>
|
|
|
|
Storage volume using LUKS
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
<volume>
|
|
<name>MyLuks.img</name>
|
|
<capacity unit="G">5</capacity>
|
|
<target>
|
|
<path>/var/lib/virt/images/MyLuks.img</path>
|
|
<format type='raw'/>
|
|
<encryption format='luks'>
|
|
<secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
|
|
</encryption>
|
|
</target>
|
|
</volume>
|