External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-11-08 22:39:56 +00:00
Code Issues Packages Projects Releases Wiki Activity
93a42f8507
libvirt/docs/formatstorage.html.in

1001 lines
46 KiB
HTML
Raw Normal View History

Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 14:25:37 +00:00
<?xml version="1.0" encoding="UTF-8"?>
docs: switch to using HTML5 doctype declaration The HTML5 doctype is simply <!DOCTYPE html> no DTD is present because HTML5 is no longer defined as an extension of SGML. XSL has no way to natively output a doctype without a public or system identifier, so we have to use an <xsl:text> hack instead. See also https://dev.w3.org/html5/html-author/#doctype-declaration Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 17:01:25 +00:00
<!DOCTYPE html>
Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 14:25:37 +00:00
<html xmlns="http://www.w3.org/1999/xhtml">
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
<body>
<h1>Storage pool and volume XML format</h1>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<ul id="toc"></ul>
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h2><a id="StoragePool">Storage pool XML</a></h2>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<p>
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.
</p>
<p>
Fix typo in storage pool documentation Remove 2 words that shouldn't be here.
2011-12-19 14:19:56 +00:00
The top level tag for a storage pool document is 'pool'. It has
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
a single attribute <code>type</code>, which is one of <code>dir</code>,
docs: add spaces to formatstorage.html Let the pool types breathe.
2013-06-04 13:20:51 +00:00
<code>fs</code>, <code>netfs</code>, <code>disk</code>,
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<code>iscsi</code>, <code>logical</code>, <code>scsi</code>
docs: Add more iscsi-direct references to storage pages Found that it was missing in formatstorage and had a few typos in the storage driver page. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Cole Robinson <crobinso@redhat.com>
2019-01-17 17:49:00 +00:00
(all <span class="since">since 0.4.1</span>),
<code>mpath</code> (<span class="since">since 0.7.1</span>),
<code>rbd</code> (<span class="since">since 0.9.13</span>),
<code>sheepdog</code> (<span class="since">since 0.10.0</span>),
<code>gluster</code> (<span class="since">since 1.2.0</span>),
<code>zfs</code> (<span class="since">since 1.2.8</span>),
<code>vstorage</code> (<span class="since">since 3.1.0</span>),
or <code>iscsi-direct</code> (<span class="since">since 4.7.0</span>).
This corresponds to the
docs: add spaces to formatstorage.html Let the pool types breathe.
2013-06-04 13:20:51 +00:00
storage backend drivers listed further along in this document.
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</p>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="StoragePoolFirst">General metadata</a></h3>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
&lt;pool type="iscsi"&gt;
&lt;name&gt;virtimages&lt;/name&gt;
&lt;uuid&gt;3e3fce45-4f53-4fa7-bb32-11f34168b82b&lt;/uuid&gt;
&lt;allocation&gt;10000000&lt;/allocation&gt;
&lt;capacity&gt;50000000&lt;/capacity&gt;
&lt;available&gt;40000000&lt;/available&gt;
...</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dl>
<dt><code>name</code></dt>
<dd>Providing a name for the pool which is unique to the host.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>uuid</code></dt>
<dd>Providing an identifier for the pool which is globally unique.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
This is optional when defining a pool, a UUID will be generated if
omitted. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>allocation</code></dt>
<dd>Providing the total storage allocation for the pool. This may
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>capacity</code></dt>
<dd>Providing the total storage capacity for the pool. Due to
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>available</code></dt>
<dd>Providing the free space available for allocating new volumes
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dl>
conf: add control over COW for storage pool directories The storage pool code now attempts to disable COW by default on btrfs, but management applications may wish to override this behaviour. Thus we introduce a concept of storage pool features: <features> <cow state='yes|no'/> </features> If the <cow> feature policy is set, it will be enforced. It will always return an hard error if COW cannot be explicitly set or unset. Reviewed-by: Neal Gompa <ngompa13@gmail.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Michal Privoznik <mprivozn@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-07-17 18:32:18 +00:00
<h3><a id="StoragePoolFeatures">Features</a></h3>
<p>
Some pools support optional features:
</p>
<pre>
...
&lt;features&gt;
&lt;cow state='no'&gt;
&lt;/features&gt;
...</pre>
<p>
Valid features are:
</p>
<ul>
<dd><code>cow</code></dd>
<dt>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 <code>btrfs</code> filesystem. If not set then libvirt
will attempt to disable COW on any btrfs filesystems.
<span class="since">Since 6.6.0</span>.</dt>
</ul>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="StoragePoolSource">Source elements</a></h3>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<p>
A single <code>source</code> element is contained within the top level
<code>pool</code> element. This tag is used to describe the source of
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
the storage pool. The set of child elements that it will contain
depend on the pool type, but come from the following child elements:
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</p>
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
...
&lt;source&gt;
&lt;host name="iscsi.example.com"/&gt;
&lt;device path="iqn.2013-06.com.example:iscsi-pool"/&gt;
&lt;auth type='chap' username='myname'&gt;
&lt;secret usage='mycluster_myname'/&gt;
&lt;/auth&gt;
&lt;vendor name="Acme"/&gt;
&lt;product name="model"/&gt;
&lt;/source&gt;
...</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
conf: Add storage pool device attribute part_separator Add a new storage pool source device attribute 'part_separator=[yes|no]' in order to allow a 'disk' storage pool using a device mapper multipath device to not add the "p" partition separator to the generated device name when libvirt_parthelper is run. This will allow libvirt to find device mapper multipath devices which were configured in /etc/multipath.conf to use 'user_friendly_names' or custom 'alias' names for the LUN.
2016-01-07 11:57:28 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
...
&lt;source&gt;
&lt;device path='/dev/mapper/mpatha' part_separator='no'/&gt;
&lt;format type='gpt'/&gt;
&lt;/source&gt;
...</pre>
conf: Add storage pool device attribute part_separator Add a new storage pool source device attribute 'part_separator=[yes|no]' in order to allow a 'disk' storage pool using a device mapper multipath device to not add the "p" partition separator to the generated device name when libvirt_parthelper is run. This will allow libvirt to find device mapper multipath devices which were configured in /etc/multipath.conf to use 'user_friendly_names' or custom 'alias' names for the LUN.
2016-01-07 11:57:28 +00:00
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
...
&lt;source&gt;
&lt;adapter type='scsi_host' name='scsi_host1'/&gt;
&lt;/source&gt;
...</pre>
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
...
&lt;source&gt;
&lt;adapter type='scsi_host'&gt;
&lt;parentaddr unique_id='1'&gt;
&lt;address domain='0x0000' bus='0x00' slot='0x1f' addr='0x2'/&gt;
&lt;/parentaddr&gt;
&lt;/adapter&gt;
&lt;/source&gt;
...</pre>
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
New XML attributes for storage pool source adapter This introduces 4 new attributes for storage pool source adapter. E.g. <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/> Attribute 'type' can be either 'scsi_host' or 'fc_host', and defaults to 'scsi_host' if attribute 'name' is specified. I.e. It's optional for 'scsi_host' adapter, for back-compat reason. However, mandatory for 'fc_host' adapter and any new future adapter types. Attribute 'parent' is to specify the parent for the fc_host adapter. * docs/formatstorage.html.in: - Add documents for the 4 new attrs * docs/schemas/storagepool.rng: - Add RNG schema * src/conf/storage_conf.c: - Parse and format the new XMLs * src/conf/storage_conf.h: - New struct virStoragePoolSourceAdapter, replace "char *adapter" with it; - New enum virStoragePoolSourceAdapterType * src/libvirt_private.syms: - Export TypeToString and TypeFromString * src/phyp/phyp_driver.c: - Replace "adapter" with "adapter.data.name", which is member of the union of the new struct virStoragePoolSourceAdapter now. Later patch will add the checking, as "adapter.data.name" is only valid for "scsi_host" adapter. * src/storage/storage_backend_scsi.c: - Like above * tests/storagepoolxml2xmlin/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlin/pool-scsi-type-fc-host.xml: - New test for 'fc_host' and "scsi_host" adapter * tests/storagepoolxml2xmlout/pool-scsi.xml: - Change the expected output, as the 'type' defaults to 'scsi_host' if 'name" specified now * tests/storagepoolxml2xmlout/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlout/pool-scsi-type-fc-host.xml: - New test * tests/storagepoolxml2xmltest.c: - Include the test
2013-03-25 16:43:36 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
...
&lt;source&gt;
&lt;adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/&gt;
&lt;/source&gt;
...</pre>
New XML attributes for storage pool source adapter This introduces 4 new attributes for storage pool source adapter. E.g. <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/> Attribute 'type' can be either 'scsi_host' or 'fc_host', and defaults to 'scsi_host' if attribute 'name' is specified. I.e. It's optional for 'scsi_host' adapter, for back-compat reason. However, mandatory for 'fc_host' adapter and any new future adapter types. Attribute 'parent' is to specify the parent for the fc_host adapter. * docs/formatstorage.html.in: - Add documents for the 4 new attrs * docs/schemas/storagepool.rng: - Add RNG schema * src/conf/storage_conf.c: - Parse and format the new XMLs * src/conf/storage_conf.h: - New struct virStoragePoolSourceAdapter, replace "char *adapter" with it; - New enum virStoragePoolSourceAdapterType * src/libvirt_private.syms: - Export TypeToString and TypeFromString * src/phyp/phyp_driver.c: - Replace "adapter" with "adapter.data.name", which is member of the union of the new struct virStoragePoolSourceAdapter now. Later patch will add the checking, as "adapter.data.name" is only valid for "scsi_host" adapter. * src/storage/storage_backend_scsi.c: - Like above * tests/storagepoolxml2xmlin/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlin/pool-scsi-type-fc-host.xml: - New test for 'fc_host' and "scsi_host" adapter * tests/storagepoolxml2xmlout/pool-scsi.xml: - Change the expected output, as the 'type' defaults to 'scsi_host' if 'name" specified now * tests/storagepoolxml2xmlout/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlout/pool-scsi-type-fc-host.xml: - New test * tests/storagepoolxml2xmltest.c: - Include the test
2013-03-25 16:43:36 +00:00
conf: Add optional NFS Source Pool <protocol ver='n'/> option Add an optional way to define which NFS Server version will be used to content the target NFS server. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-11 00:23:27 +00:00
<pre>
...
&lt;source&gt;
&lt;host name='localhost'/&gt;
&lt;dir path='/var/lib/libvirt/images'/&gt;
&lt;format type='nfs'/&gt;
&lt;protocol ver='3'/&gt;
&lt;/source&gt;
...</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dl>
<dt><code>device</code></dt>
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<dd>Provides the source for pools backed by physical devices
(pool types <code>fs</code>, <code>logical</code>, <code>disk</code>,
docs: Add more iscsi-direct references to storage pages Found that it was missing in formatstorage and had a few typos in the storage driver page. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Cole Robinson <crobinso@redhat.com>
2019-01-17 17:49:00 +00:00
<code>iscsi</code>, <code>iscsi-direct</code>, <code>zfs</code>,
<code>vstorage</code>).
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
May be repeated multiple times depending on backend driver. Contains
conf: Add storage pool device attribute part_separator Add a new storage pool source device attribute 'part_separator=[yes|no]' in order to allow a 'disk' storage pool using a device mapper multipath device to not add the "p" partition separator to the generated device name when libvirt_parthelper is run. This will allow libvirt to find device mapper multipath devices which were configured in /etc/multipath.conf to use 'user_friendly_names' or custom 'alias' names for the LUN.
2016-01-07 11:57:28 +00:00
a required attribute <code>path</code> which is either the fully
conf: Remove source host name check for iSCSI https://bugzilla.redhat.com/show_bug.cgi?id=1171984 https://bugzilla.redhat.com/show_bug.cgi?id=1188463 Remove the check for the source host name for iSCSI source XML processing declaring duplicate sources when the source device path and if present the initiator of a proposed storage pool matches an existing storage pool. The backend iSCSI storage driver uses 'iscsiadm --mode session' to query available iscsid target sessions. The output displayed is the IP address and the IQN (target path) of known targets. The displayed IP address is a resolved address based on the session --login. Additionally, iscsid keeps track of the various ways to define the host name (IPv4 Address, IPv6 Address, /etc/hosts, etc.) for that IQN (see output of an 'iscsiadm --mode node'). If an incoming IQN matches and the host name provided by libvirt is resolved to the existing IQN, then iscsid will "reuse" the session. Although libvirt could do the same name resolution, if there is a difference, iscsid could still declare two seemingly different sources to be the same and not create a new session which means libvirt now has two storage pools looking at the same source. Thus to avoid any strange host name resolution issues, just rely on iscsid for that and do not allow multiple pools on the same host to use the same device path (IQN).
2015-05-11 17:51:04 +00:00
qualified path to the block device node or for <code>iscsi</code>
docs: Add more iscsi-direct references to storage pages Found that it was missing in formatstorage and had a few typos in the storage driver page. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Cole Robinson <crobinso@redhat.com>
2019-01-17 17:49:00 +00:00
or <code>iscsi-direct</code> the iSCSI Qualified Name (IQN).
conf: Add storage pool device attribute part_separator Add a new storage pool source device attribute 'part_separator=[yes|no]' in order to allow a 'disk' storage pool using a device mapper multipath device to not add the "p" partition separator to the generated device name when libvirt_parthelper is run. This will allow libvirt to find device mapper multipath devices which were configured in /etc/multipath.conf to use 'user_friendly_names' or custom 'alias' names for the LUN.
2016-01-07 11:57:28 +00:00
<span class="since">Since 0.4.1</span>
<p>An optional attribute <code>part_separator</code> for each
<code>path</code> may be supplied. Valid values for the attribute
may be either "yes" or "no". This attribute is to be used for a
<code>disk</code> pool type using a <code>path</code> to a
storage: Fix algorithm generating path names for devmapper https://bugzilla.redhat.com/show_bug.cgi?id=1265694 Commit id '020135dc' didn't quite get the algorithm correct when a device mapper source ended with a non numeric value (e.g. ends with an alphabet value). This patch modifies the 'part_separator' logic to add the "p" separator to the attempted target path name only when specified as part_separator='yes'. For a source name that already ends with a number, the logic doesn't change as the part separator would need to be there. For a source name that ends with something other than a number, this allows the possibility that a "p" separator can be added. The default for one of these source devices is to not add the separator. The key for device mapper and the need for a partition separator "p" is the presence of a number in the last character of the device name link in /dev/mapper. A name such as "/dev/mapper/mpatha1" would generate a "/dev/mapper/mpatha1p1" partition, while "/dev/mapper/mpatha" would generate partition "/dev/mapper/mpatha1". Similarly for a device mapper entry not using friendly names or an alias, a device such as "/dev/mapper/3600a0b80005b10ca00005ad656fd8d93" would generate a paritition "/dev/mapper/3600a0b80005b10ca00005ad656fd8d93p1", while a device such as "/dev/mapper/3600a0b80005b10ca00005e115729093f" would generate a partition "/dev/mapper/3600a0b80005b10ca00005e115729093f1". The long number is the WWID of the device. It's also possible to assign an alias for a device mapper entry, that alias follows the same rules with respect to ending with a number or not when adding a "p" to create the target device path.
2016-05-09 18:57:17 +00:00
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
disk: Fixup error handling path for devmapper when part_separator='yes' https://bugzilla.redhat.com/show_bug.cgi?id=1346566 If libvirt_parthelper is erroneously told to append the partition separator 'p' onto the generated output for a disk pool using device mapper that has 'user_friendly_names' set to true, then the error recovery path will fail to find volume resulting in the pool being in an unusable state. So, augment the documentation to provide the better hint that the part_separator='yes' should be set when user_friendly_names are not being used. Additionally, once we're in the error path where the returned name doesn't match the expected partition name try to see if the reason is because the 'p' was erroneosly added. If so alter the about to be removed vol->target.path so that the DiskDeleteVol code can find the partition that was created and remove it.
2016-11-15 19:37:01 +00:00
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.
conf: Add storage pool device attribute part_separator Add a new storage pool source device attribute 'part_separator=[yes|no]' in order to allow a 'disk' storage pool using a device mapper multipath device to not add the "p" partition separator to the generated device name when libvirt_parthelper is run. This will allow libvirt to find device mapper multipath devices which were configured in /etc/multipath.conf to use 'user_friendly_names' or custom 'alias' names for the LUN.
2016-01-07 11:57:28 +00:00
<span class="since">Since 1.3.1</span></p></dd>
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<dt><code>dir</code></dt>
<dd>Provides the source for pools backed by directories (pool
storage: Generate correct parameters for CIFS https://bugzilla.redhat.com/show_bug.cgi?id=1186969 When generating the path to the dir for a CIFS/Samba driver, the code would generate a source path for the mount using "%s:%s" while the mount.cifs expects to see "//%s/%s". So check for the cifsfs and format the source path appropriately. Additionally, since there is no means to authenticate, the mount needs a "-o guest" on the command line in order to anonymously mount the Samba directory.
2015-06-03 14:20:56 +00:00
types <code>dir</code>, <code>netfs</code>, <code>gluster</code>),
or optionally to select a subdirectory
storage: document gluster pool Add support for a new <pool type='gluster'>, similar to RBD and Sheepdog. Terminology wise, a gluster volume forms a libvirt storage pool, within the gluster volume, individual files are treated as libvirt storage volumes. * docs/schemas/storagepool.rng (poolgluster): New pool type. * docs/formatstorage.html.in: Document gluster. * docs/storage.html.in: Likewise, and contrast it with netfs. * tests/storagepoolxml2xmlin/pool-gluster.xml: New test. * tests/storagepoolxml2xmlout/pool-gluster.xml: Likewise. * tests/storagepoolxml2xmltest.c (mymain): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 23:06:18 +00:00
within a pool that resembles a filesystem (pool
type <code>gluster</code>). May
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
only occur once. Contains a single attribute <code>path</code>
storage: Generate correct parameters for CIFS https://bugzilla.redhat.com/show_bug.cgi?id=1186969 When generating the path to the dir for a CIFS/Samba driver, the code would generate a source path for the mount using "%s:%s" while the mount.cifs expects to see "//%s/%s". So check for the cifsfs and format the source path appropriately. Additionally, since there is no means to authenticate, the mount needs a "-o guest" on the command line in order to anonymously mount the Samba directory.
2015-06-03 14:20:56 +00:00
which is the fully qualified path to the backing directory or
for a <code>netfs</code> pool type using <code>format</code>
type "cifs", the path to the Samba share without the leading slash.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.4.1</span></dd>
docs: storage: Document SCSI pools
2010-02-22 21:50:04 +00:00
<dt><code>adapter</code></dt>
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<dd>Provides the source for pools backed by SCSI adapters (pool
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
type <code>scsi</code>). May only occur once.
<dl>
<dt><code>name</code></dt>
<dd>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 <code>virsh nodedev-list
scsi_host</code> command followed by a combination of
<code>lspci</code> and <code>virsh nodedev-dumpxml
scsi_hostN</code> commands to find the <code>scsi_hostN</code>
to be used. <span class="since">Since 0.6.2</span>
<p>
It is further recommended to utilize the
<code>parentaddr</code> element since it's possible to have
the path to which the scsi_hostN uses change between system
reboots. <span class="since">Since 1.2.7</span>
</p>
</dd>
</dl>
<dl>
<dt><code>type</code></dt>
<dd>Specifies the adapter type. Valid values are "scsi_host" or
"fc_host". If omitted and the <code>name</code> attribute is
specified, then it defaults to "scsi_host". To keep backwards
compatibility, this attribute is optional <b>only</b> for the
"scsi_host" adapter, but is mandatory for the "fc_host" adapter.
<span class="since">Since 1.0.5</span>
storage: Add mixed fc_host/scsi_host duplicate adapter source checks https://bugzilla.redhat.com/show_bug.cgi?id=1159180 The virStoragePoolSourceFindDuplicate only checks the incoming definition against the same type of pool as the def; however, for "scsi_host" and "fc_host" adapter pools, it's possible that either some pool "scsi_host" adapter definition is already using the scsi_hostN that the "fc_host" adapter definition wants to use or some "fc_host" pool adapter definition is using a vHBA scsi_hostN or parent scsi_hostN that an incoming "scsi_host" definition is trying to use. This patch adds the mismatched type checks and adds extraneous comments to describe what each check is determining. This patch also modifies the documentation to be describe what scsi_hostN devices a "scsi_host" source adapter should use and which to avoid. It also updates the parent definition to specifically call out that for mixed environments it's better to define which parent to use so that the duplicate pool checks can be done properly.
2014-11-14 14:50:59 +00:00
A "fc_host" capable scsi_hostN can be determined by using
<code>virsh nodedev-list --cap fc_host</code>.
<span class="since">Since 1.2.8</span>
<p>
Note: Regardless of whether a "scsi_host" adapter type is defined
using a <code>name</code> or a <code>parentaddr</code>, it
should refer to a real scsi_host adapter as found through a
<code>virsh nodedev-list scsi_host</code> and <code>virsh
nodedev-dumpxml scsi_hostN</code> 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 <code>nodedev-dumpxml</code>
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
<code>nodedev-dumpxml</code> output parent field is generally
"computer". This is a libvirt created parent value indicating
no parent was defined for the node device.
</p>
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
</dd>
</dl>
<dl>
docs: Fix a couple of typos on the storage pool html Fix format of the secret XML in the example. The XML had an extraneous "type='iscsi'" (which is used by the <disk> definitions) The world wide node name had a typo in the acronym (wwwn).
2014-12-04 00:09:20 +00:00
<dt><code>wwnn</code> and <code>wwpn</code></dt>
storage: Disallow usage of the HBA for a fc_host backing Disallow providing the wwnn/wwpn of the HBA in the adapter XML: <adapter type='fc_host' [parent='scsi_hostN'] wwnn='HBA_wwnn' wwpn='HBA_wwpn'/> This should be considered a configuration error since a vHBA would not be created. In order to use the HBA as the backing the following XML should be used: <adapter type='scsi_host' name='scsi_hostN'/> So add a check prior to the checkParent call to validate that the provided wwnn/wwpn resolves to a vHBA and not an HBA. Signed-off-by: John Ferlan <jferlan@redhat.com>
2017-07-20 18:52:15 +00:00
<dd>The required "World Wide Node Name" (<code>wwnn</code>) and
"World Wide Port Name" (<code>wwpn</code>) 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" <code>type</code> pool instead. The
<code>wwnn</code> and <code>wwpn</code> 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".
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
<span class="since">Since 1.0.4</span>
</dd>
</dl>
<dl>
<dt><code>parent</code></dt>
<dd>Used by the "fc_host" adapter type to optionally specify the
parent scsi_host device defined in the
<a href="formatnode.html">Node Device</a> database as the
Prefer https: everywhere where possible Use https: links for websites that support them. The URIs which are used as namespace identifiers are left alone. Signed-off-by: Ján Tomko <jtomko@redhat.com> Reviewed-by: Erik Skultety <eskultet@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-08-25 22:44:00 +00:00
<a href="https://wiki.libvirt.org/page/NPIV_in_libvirt">NPIV</a>
storage: Ensure fc_host parent matches wwnn/wwpn https://bugzilla.redhat.com/show_bug.cgi?id=1160565 The existing code assumed that the configuration of a 'parent' attribute was correct for the createVport path. As it turns out, that may not be the case which leads errors during the deleteVport path because the wwnn/wwpn isn't associated with the parent. With this change the following is reported: error: Failed to start pool fc_pool_host3 error: XML error: Parent attribute 'scsi_host4' does not match parent 'scsi_host3' determined for the 'scsi_host16' wwnn/wwpn lookup. for XML as follows: <pool type='scsi'> <name>fc_pool</name> <source> <adapter type='fc_host' parent='scsi_host4' wwnn='5001a4aaf3ca174b' wwpn='5001a4a77192b864'/> </source> Where 'nodedev-dumpxml scsi_host16' provides: <device> <name>scsi_host16</name> <path>/sys/devices/pci0000:00/0000:00:04.0/0000:10:00.0/host3/vport-3:0-11/host16</path> <parent>scsi_host3</parent> <capability type='scsi_host'> <host>16</host> <unique_id>13</unique_id> <capability type='fc_host'> <wwnn>5001a4aaf3ca174b</wwnn> <wwpn>5001a4a77192b864</wwpn> ... The patch also adjusts the description of the storage pool to describe the restrictions. Signed-off-by: John Ferlan <jferlan@redhat.com>
2014-11-06 17:22:58 +00:00
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
storage: Add mixed fc_host/scsi_host duplicate adapter source checks https://bugzilla.redhat.com/show_bug.cgi?id=1159180 The virStoragePoolSourceFindDuplicate only checks the incoming definition against the same type of pool as the def; however, for "scsi_host" and "fc_host" adapter pools, it's possible that either some pool "scsi_host" adapter definition is already using the scsi_hostN that the "fc_host" adapter definition wants to use or some "fc_host" pool adapter definition is using a vHBA scsi_hostN or parent scsi_hostN that an incoming "scsi_host" definition is trying to use. This patch adds the mismatched type checks and adds extraneous comments to describe what each check is determining. This patch also modifies the documentation to be describe what scsi_hostN devices a "scsi_host" source adapter should use and which to avoid. It also updates the parent definition to specifically call out that for mixed environments it's better to define which parent to use so that the duplicate pool checks can be done properly.
2014-11-14 14:50:59 +00:00
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.
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
<span class="since">Since 1.0.4</span>
</dd>
docs: Document the new vHBA/NPIV params for storage Commit id 'bb74a7ffe' forgot to adjust the storage docs to describe the new fields.
2017-01-11 12:09:03 +00:00
<dt><code>parent_wwnn</code> and <code>parent_wwpn</code></dt>
<dd>Instead of the <code>parent</code> 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.
<span class="since">Since 3.0.0</span>
</dd>
<dt><code>parent_fabric_wwn</code></dt>
<dd>Instead of the <code>parent</code> 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.
<span class="since">Since 3.0.0</span>
</dd>
storage: Introduce 'managed' for the fchost parent https://bugzilla.redhat.com/show_bug.cgi?id=1160926 Introduce a 'managed' attribute to allow libvirt to decide whether to delete a vHBA vport created via external means such as nodedev-create. The code currently decides whether to delete the vHBA based solely on whether the parent was provided at creation time. However, that may not be the desired action, so rather than delete and force someone to create another vHBA via an additional nodedev-create allow the configuration of the storage pool to decide the desired action. During createVport when libvirt does the VPORT_CREATE, set the managed value to YES if not already set to indicate to the deleteVport code that it should delete the vHBA when the pool is destroyed. If libvirtd is restarted all the memory only state was lost, so for a persistent storage pool, use the virStoragePoolSaveConfig in order to write out the managed value. Because we're now saving the current configuration, we need to be sure to not save the parent in the output XML if it was undefined at start. Saving the name would cause future starts to always use the same parent which is not the expected result when not providing a parent. By not providing a parent, libvirt is expected to find the best available vHBA port for each subsequent (re)start. At deleteVport, use the new managed value to decide whether to execute the VPORT_DELETE. Since we no longer save the parent in memory or in XML when provided, if it was not provided, then we have to look it up.
2014-11-10 16:19:51 +00:00
<dt><code>managed</code></dt>
<dd>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.
<span class="since">Since 1.2.11</span>
</dd>
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
</dl>
<dl>
<dt><code>parentaddr</code></dt>
<dd>Used by the "scsi_host" adapter type instead of the
<code>name</code> attribute to more uniquely identify the
SCSI host. Using a combination of the <code>unique_id</code>
attribute and the <code>address</code> element to formulate
a PCI address, a search will be performed of the
<code>/sys/class/scsi_host/hostNN</code> links for a
matching PCI address with a matching <code>unique_id</code>
value in the <code>/sys/class/scsi_host/hostNN/unique_id</code>
file. The value in the "unique_id" file will be unique enough
for the specific PCI address. The <code>hostNN</code> will be
used by libvirt as the basis to define which SCSI host is to
be used for the currently booted system.
<span class="since">Since 1.2.7</span>
<dl>
<dt><code>address</code></dt>
<dd>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:
<code>domain</code> (a 2-byte hex integer, not currently used
by qemu), <code>bus</code> (a hex value between 0 and 0xff,
inclusive), <code>slot</code> (a hex value between 0x0 and
0x1f, inclusive), and <code>function</code> (a value between
0 and 7, inclusive). The PCI address can be determined by
listing the <code>/sys/bus/pci/devices</code> and the
<code>/sys/class/scsi_host</code> 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
<code>path</code> element as the basis to formulate the
correctly formatted PCI address.
</dd>
</dl>
<dl>
<dt><code>unique_id</code></dt>
<dd>Required <code>parentaddr</code> 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
<code>unique_id</code> file for the specific scsi_host adapter.
docs: fix misc spelling errors reported by codespell Reviewed-by: Peter Krempa <pkrempa@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-10-02 14:07:27 +00:00
For a PCI address of "0000:00:1f:2", the unique identifier files
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
can be found using the command
<code>find -H /sys/class/scsi_host/host*/unique_id |
scsi_host: Introduce virFindSCSIHostByPCI Introduce a new function to parse the provided scsi_host parent address and unique_id value in order to find the /sys/class/scsi_host directory which will allow a stable SCSI host address Add a test to scsihosttest to lookup the host# name by using the PCI address and unique_id value
2014-06-10 11:47:12 +00:00
xargs grep '[0-9]'</code>. Optionally, the
<code>virsh nodedev-dumpxml scsi_hostN</code>' of a
specific scsi_hostN list entry will list the
<code>unique_id</code> value.
storage: Introduce parentaddr into virStoragePoolSourceAdapter Between reboots and kernel reloads, the SCSI host number used for SCSI storage pools may change requiring modification to the storage pool XML in order to use a specific SCSI host adapter. This patch introduces the "parentaddr" element and "unique_id" attribute for the SCSI host adapter in order to uniquely identify the adapter between reboots and kernel reloads. For now the goal is to only parse and format the XML. Both will be required to be provided in order to uniquely identify the desired SCSI host. The new XML is expected to be as follows: <adapter type='scsi_host'> <parentaddr unique_id='3'> <address domain='0x0000' bus='0x00' slot='0x1f' func='0x2'/> </parentaddr> </adapter> where "parentaddr" is the parent device of the SCSI host using the PCI address on which the device resides and the value from the unique_id file for the device. Both the PCI address and unique_id values will be used to traverse the /sys/class/scsi_host/ directories looking at each link to match the PCI address reformatted to the directory link format where "domain:bus:slot:function" is found. Then for each matching directory the unique_id file for the scsi_host will be used to match the unique_id value in the xml. For a PCI address listed above, this will be formatted to "0000:00:1f.2" and the links in /sys/class/scsi_host will be used to find the host# to be used for the 'scsi_host' device. Each entry is a link to the /sys/bus/pci/devices directories, e.g.: % ls -al /sys/class/scsi_host/host2 lrwxrwxrwx. 1 root root 0 Jun 1 00:22 /sys/class/scsi_host/host2 -> ../../devices/pci0000:00/0000:00:1f.2/ata3/host2/scsi_host/host2 % cat /sys/class/scsi_host/host2/unique_id 3 The "parentaddr" and "name" attributes are mutually exclusive to identify the SCSI host number. Use of the "parentaddr" element will be the preferred mechanism. This patch only supports to parse and format the XMLs. Later patches will add code to find out the scsi host number.
2014-03-04 03:15:13 +00:00
</dd>
</dl>
</dd>
</dl>
</dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>host</code></dt>
<dd>Provides the source for pools backed by storage from a
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
remote server (pool types <code>netfs</code>, <code>iscsi</code>,
docs: Add more iscsi-direct references to storage pages Found that it was missing in formatstorage and had a few typos in the storage driver page. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Cole Robinson <crobinso@redhat.com>
2019-01-17 17:49:00 +00:00
<code>iscsi-direct</code>,
storage: document gluster pool Add support for a new <pool type='gluster'>, similar to RBD and Sheepdog. Terminology wise, a gluster volume forms a libvirt storage pool, within the gluster volume, individual files are treated as libvirt storage volumes. * docs/schemas/storagepool.rng (poolgluster): New pool type. * docs/formatstorage.html.in: Document gluster. * docs/storage.html.in: Likewise, and contrast it with netfs. * tests/storagepoolxml2xmlin/pool-gluster.xml: New test. * tests/storagepoolxml2xmlout/pool-gluster.xml: Likewise. * tests/storagepoolxml2xmltest.c (mymain): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 23:06:18 +00:00
<code>rbd</code>, <code>sheepdog</code>, <code>gluster</code>). Will be
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
used in combination with a <code>directory</code>
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
or <code>device</code> element. Contains an attribute <code>name</code>
which is the hostname or IP address of the server. May optionally
contain a <code>port</code> attribute for the protocol specific
conf: Remove source host name check for iSCSI https://bugzilla.redhat.com/show_bug.cgi?id=1171984 https://bugzilla.redhat.com/show_bug.cgi?id=1188463 Remove the check for the source host name for iSCSI source XML processing declaring duplicate sources when the source device path and if present the initiator of a proposed storage pool matches an existing storage pool. The backend iSCSI storage driver uses 'iscsiadm --mode session' to query available iscsid target sessions. The output displayed is the IP address and the IQN (target path) of known targets. The displayed IP address is a resolved address based on the session --login. Additionally, iscsid keeps track of the various ways to define the host name (IPv4 Address, IPv6 Address, /etc/hosts, etc.) for that IQN (see output of an 'iscsiadm --mode node'). If an incoming IQN matches and the host name provided by libvirt is resolved to the existing IQN, then iscsid will "reuse" the session. Although libvirt could do the same name resolution, if there is a difference, iscsid could still declare two seemingly different sources to be the same and not create a new session which means libvirt now has two storage pools looking at the same source. Thus to avoid any strange host name resolution issues, just rely on iscsid for that and do not allow multiple pools on the same host to use the same device path (IQN).
2015-05-11 17:51:04 +00:00
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 <code>directory</code> or <code>device</code>
element. Name resolution of the provided hostname or IP address
is left to the storage driver backend interactions with the remote
server. See the <a href="storage.html">storage driver page</a> for
any restrictions for specific storage backends.
<span class="since">Since 0.4.1</span></dd>
docs: Add more iscsi-direct references to storage pages Found that it was missing in formatstorage and had a few typos in the storage driver page. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Cole Robinson <crobinso@redhat.com>
2019-01-17 17:49:00 +00:00
<dt><code>initiator</code></dt>
<dd>Required by the <code>iscsi-direct</code> pool in order to provide
the iSCSI Qualified Name (IQN) to communicate with the pool's
<code>device</code> target IQN. There is one sub-element
<code>iqn</code> with the <code>name</code> attribute to describe
the IQN for the initiator.
<span class="since">Since 4.7.0</span></dd>
storage_pool: Rework chap XML to mimic ceph The existing 'chap' XML logic was never used - just defined. Rather than try to insert a square peg into a round hole, blow it up and rewrite the logic to follow the 'ceph' format. Remove the former "chap.login" and "chap.passwd" fields and replace with "chap.username" and "chap.secret" in _virStoragePoolAuthChap. Adjust the virStoragePoolDefParseAuthChap() to process. Change the rng file to describe the new layout Update the formatstorage.html to describe the usage of the secret element to mention that the secret type "iscsi" and "ceph" can be used to storage pool too. Update the formatsecret.html to include a reference to the storage pool Update tests to handle the changes from 'login' and 'passwd' to 'username' and '<secret>' format
2013-07-13 18:29:55 +00:00
<dt><code>auth</code></dt>
<dd>If present, the <code>auth</code> element provides the
authentication credentials needed to access the source by the
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
setting of the <code>type</code> attribute (pool
docs: Add more iscsi-direct references to storage pages Found that it was missing in formatstorage and had a few typos in the storage driver page. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Cole Robinson <crobinso@redhat.com>
2019-01-17 17:49:00 +00:00
types <code>iscsi</code>, <code>iscsi-direct</code>, <code>rbd</code>).
The <code>type</code>
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
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
storage_pool: Rework chap XML to mimic ceph The existing 'chap' XML logic was never used - just defined. Rather than try to insert a square peg into a round hole, blow it up and rewrite the logic to follow the 'ceph' format. Remove the former "chap.login" and "chap.passwd" fields and replace with "chap.username" and "chap.secret" in _virStoragePoolAuthChap. Adjust the virStoragePoolDefParseAuthChap() to process. Change the rng file to describe the new layout Update the formatstorage.html to describe the usage of the secret element to mention that the secret type "iscsi" and "ceph" can be used to storage pool too. Update the formatsecret.html to include a reference to the storage pool Update tests to handle the changes from 'login' and 'passwd' to 'username' and '<secret>' format
2013-07-13 18:29:55 +00:00
<code>username</code> identifies the username to use during
authentication as well as a sub-element <code>secret</code> with
a mandatory attribute <code>type</code>, to tie back to a
<a href="formatsecret.html">libvirt secret object</a> that
holds the actual password or other credentials. The domain XML
intentionally does not expose the password, only the reference
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
to the object that manages the password.
storage_pool: Rework chap XML to mimic ceph The existing 'chap' XML logic was never used - just defined. Rather than try to insert a square peg into a round hole, blow it up and rewrite the logic to follow the 'ceph' format. Remove the former "chap.login" and "chap.passwd" fields and replace with "chap.username" and "chap.secret" in _virStoragePoolAuthChap. Adjust the virStoragePoolDefParseAuthChap() to process. Change the rng file to describe the new layout Update the formatstorage.html to describe the usage of the secret element to mention that the secret type "iscsi" and "ceph" can be used to storage pool too. Update the formatsecret.html to include a reference to the storage pool Update tests to handle the changes from 'login' and 'passwd' to 'username' and '<secret>' format
2013-07-13 18:29:55 +00:00
The <code>secret</code> element requires either a <code>uuid</code>
attribute with the UUID of the secret object or a <code>usage</code>
attribute matching the key that was specified in the
secret object. <span class="since">Since 0.9.7 for "ceph" and
1.1.1 for "chap"</span>
</dd>
Adds storage source element for pools * src/storage_backend.h src/storage_backend_logical.c src/storage_conf.c src/storage_conf.h src/virsh.c: Applied patches from David Lively to add storage source elements needed for storage pool * docs/formatstorage.html docs/formatstorage.html.in: associated documentation Daniel
2008-09-02 14:15:42 +00:00
<dt><code>name</code></dt>
<dd>Provides the source for pools backed by storage from a
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
named element (pool types <code>logical</code>, <code>rbd</code>,
storage: document gluster pool Add support for a new <pool type='gluster'>, similar to RBD and Sheepdog. Terminology wise, a gluster volume forms a libvirt storage pool, within the gluster volume, individual files are treated as libvirt storage volumes. * docs/schemas/storagepool.rng (poolgluster): New pool type. * docs/formatstorage.html.in: Document gluster. * docs/storage.html.in: Likewise, and contrast it with netfs. * tests/storagepoolxml2xmlin/pool-gluster.xml: New test. * tests/storagepoolxml2xmlout/pool-gluster.xml: Likewise. * tests/storagepoolxml2xmltest.c (mymain): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 23:06:18 +00:00
<code>sheepdog</code>, <code>gluster</code>). Contains a
string identifier.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.4.5</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>format</code></dt>
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<dd>Provides information about the format of the pool (pool
types <code>fs</code>, <code>netfs</code>, <code>disk</code>,
<code>logical</code>). This
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
contains a single attribute <code>type</code> 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. <span class="since">Since 0.4.1</span></dd>
storage: add support for Vendor and Model in XML I wrote a patch to add support for listing the Vendor and Model of a storage pool in the storage pool XML. This would allow vendor extensions of specific devices. The patch includes a test for the new attributes as well. Patrick Dignan
2010-08-17 17:44:27 +00:00
conf: Add optional NFS Source Pool <protocol ver='n'/> option Add an optional way to define which NFS Server version will be used to content the target NFS server. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-11 00:23:27 +00:00
<dt><code>protocol</code></dt>
<dd>For a <code>netfs</code> Storage Pool provide a mechanism to
define which NFS protocol version number will be used to contact
the server's NFS service. The attribute <code>ver</code> accepts
an unsigned integer as the version number to use.
<span class="since">Since 5.1.0</span></dd>
storage: add support for Vendor and Model in XML I wrote a patch to add support for listing the Vendor and Model of a storage pool in the storage pool XML. This would allow vendor extensions of specific devices. The patch includes a test for the new attributes as well. Patrick Dignan
2010-08-17 17:44:27 +00:00
<dt><code>vendor</code></dt>
<dd>Provides optional information about the vendor of the
storage device. This contains a single
attribute <code>name</code> whose value is backend
specific. <span class="since">Since 0.8.4</span></dd>
<dt><code>product</code></dt>
<dd>Provides an optional product name of the storage device.
This contains a single attribute <code>name</code> whose value
is backend specific. <span class="since">Since 0.8.4</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dl>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="StoragePoolTarget">Target elements</a></h3>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<p>
A single <code>target</code> element is contained within the top level
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<code>pool</code> element for some types of pools (pool
types <code>dir</code>, <code>fs</code>, <code>netfs</code>,
<code>logical</code>, <code>disk</code>, <code>iscsi</code>,
docs: Update formatstorage to match code for pool path Seems commit id '0257d06b' forgot to include formatstorage when updating the docs to describe allowing zfs as a pool type and to furthermore note that the pool's target path element will be generated rather than read. Similarly commit id 'efab27afb' neglected to indicate that the target path for a logical pool will now be generated by libvirt. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-12-03 12:53:15 +00:00
<code>scsi</code>, <code>mpath</code>, <code>zfs</code>).
This tag is used to describe the mapping of
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
the storage pool into the host filesystem. It can contain the following
child elements:
</p>
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
...
&lt;target&gt;
&lt;path&gt;/dev/disk/by-path&lt;/path&gt;
&lt;permissions&gt;
&lt;owner&gt;107&lt;/owner&gt;
&lt;group&gt;107&lt;/group&gt;
&lt;mode&gt;0744&lt;/mode&gt;
&lt;label&gt;virt_image_t&lt;/label&gt;
&lt;/permissions&gt;
&lt;/target&gt;
&lt;/pool&gt;</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dl>
<dt><code>path</code></dt>
<dd>Provides the location at which the pool will be mapped into
doc: Add info (where necessary) that paths should be specified as absolute We documented this almost everywhere, but missed it on several places. https://bugzilla.redhat.com/show_bug.cgi?id=1208763
2015-04-07 10:46:13 +00:00
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
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
devices nodes exist. For the latter <code>/dev/</code> 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
docs: Fix typo in path for storage pool
2014-12-10 11:56:35 +00:00
of the <code>/dev/disk/by-{path|id|uuid|label}</code> locations.
docs: Update formatstorage to match code for pool path Seems commit id '0257d06b' forgot to include formatstorage when updating the docs to describe allowing zfs as a pool type and to furthermore note that the pool's target path element will be generated rather than read. Similarly commit id 'efab27afb' neglected to indicate that the target path for a logical pool will now be generated by libvirt. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-12-03 12:53:15 +00:00
For <code>logical</code> and <code>zfs</code> pool types, a
provided value is ignored and a default path generated.
mpath: Don't allow more than one mpath pool at a time https://bugzilla.redhat.com/show_bug.cgi?id=1232606 Since an mpath pool contains all the Multipath devices on a host, allowing more than one defined on a host at a time should be disallowed under the policy of disallowing duplicate source pools for the host. Adjust to docs to clarify the Multipath target path value usage for both the storage driver (only 1 pool per host) and formatstorage references (ignore the target element in favor of the default target mapping of /dev/mapper).
2015-06-24 12:45:24 +00:00
For a Multipath pool (type <code>mpath</code>), the provided
value is ignored and the default value of "/dev/mapper" is used.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.4.1</span>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dd>
<dt><code>permissions</code></dt>
doc: storage pool permission copy-paste fix The description for <permissions> was copied from the storage volume section to the storage pool section, but the semantics are different: 1. Currently only the "dir", "fs" and "netfs" storage pools use it. 2. They use it only to build the final directory. 3. A default for the storage volumes can't be set. Signed-off-by: Philipp Hahn <hahn@univention.de>
2013-08-13 12:38:33 +00:00
<dd>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
docs: formatstorage: Update <permissions> docs - Don't redocument the permissions fields for backingstore, just point to the volume docs. - Clarify that owner/group are inherited from the parent directory at volume create/pool build time. - Clarify that <permissions> fields report runtime values too
2015-05-21 19:29:39 +00:00
final directory when the pool is built. There are 4 child elements.
The <code>mode</code> element contains the octal permission set.
storage: use 0711 as the default perms for dirs There should be no need to make dir based pools world/group readable. So use 0711, not 0755, as the default perms for storage dirs. Updates in v2: - adapt commit wording to mention dropping group readable as well Signed-off-by: Christian Ehrhardt <christian.ehrhardt@canonical.com>
2017-05-15 11:05:31 +00:00
The <code>mode</code> defaults to 0711 when not provided.
docs: formatstorage: Update <permissions> docs - Don't redocument the permissions fields for backingstore, just point to the volume docs. - Clarify that owner/group are inherited from the parent directory at volume create/pool build time. - Clarify that <permissions> fields report runtime values too
2015-05-21 19:29:39 +00:00
The <code>owner</code> element contains the numeric user ID.
The <code>group</code> element contains the numeric group ID.
If <code>owner</code> or <code>group</code> aren't specified when
docs: storage: owner/group default to libvirtd UID/GID Commit fafcc818f changed the docs to say that when creating a pool directory or file volume with no owner/group specified, they will be inherited from the parent directory. This isn't correct now and doesn't seem to have ever been correct In reality default owner/group is whatever UID/GID libvirtd is running as Signed-off-by: Cole Robinson <crobinso@redhat.com>
2019-02-06 23:26:05 +00:00
creating a directory, the UID and GID of the libvirtd process are used.
The <code>label</code> element contains the MAC (eg SELinux)
docs: formatstorage: Update <permissions> docs - Don't redocument the permissions fields for backingstore, just point to the volume docs. - Clarify that owner/group are inherited from the parent directory at volume create/pool build time. - Clarify that <permissions> fields report runtime values too
2015-05-21 19:29:39 +00:00
label string.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.4.1</span>
docs: formatstorage: Update <permissions> docs - Don't redocument the permissions fields for backingstore, just point to the volume docs. - Clarify that owner/group are inherited from the parent directory at volume create/pool build time. - Clarify that <permissions> fields report runtime values too
2015-05-21 19:29:39 +00:00
For running directory or filesystem based pools, these fields
will be filled with the values used by the existing directory.
<span class="since">Since 1.2.16</span>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dd>
</dl>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="StoragePoolExtents">Device extents</a></h3>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<p>
If a storage pool exposes information about its underlying
placement / allocation scheme, the <code>device</code> element
within the <code>source</code> 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
</p>
<p>
For storage pools supporting extent information, within each
<code>device</code> element there will be zero or more <code>freeExtent</code>
elements. Each of these elements contains two attributes, <code>start</code>
and <code>end</code> which provide the boundaries of the extent on the
device, measured in bytes. <span class="since">Since 0.4.1</span>
</p>
storage: optional 'refresh' elemement on pool The new 'refresh' element can override the default refresh operations for a storage pool. The only currently supported override is to set the volume allocation size to the volume capacity. This can be specified by adding the following snippet: <pool> ... <refresh> <volume allocation='capacity'/> </refresh> ... </pool> This is useful for certain backends where computing the actual allocation of a volume might be an expensive operation. Signed-off-by: Jason Dillaman <dillaman@redhat.com> Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2019-03-19 13:42:17 +00:00
<h3><a id="StoragePoolRefresh">Refresh overrides</a></h3>
<p>
The optional <code>refresh</code> element can control how the pool and
associated volumes are refreshed (pool type <code>rbd</code>). The
<code>allocation</code> attribute of the <code>volume</code> child element
controls the method used for computing the allocation of a volume. The
valid attribute values are <code>default</code> to compute the actual
usage or <code>capacity</code> to use the logical capacity for cases where
computing the allocation is too expensive. The following XML snippet
shows the syntax:
<pre>
&lt;pool type="rbd"&gt;
&lt;name&gt;myrbdpool&lt;/name&gt;
...
&lt;source/&gt;
...
&lt;refresh&gt;
&lt;volume allocation='capacity'/&gt;
&lt;/refresh&gt;
...
&lt;/pool&gt;
</pre>
<span class="since">Since 5.2.0</span>
</p>
storage: Add infrastructure to manage XML namespace options Introduce the virStoragePoolFSMountOptionsDef to be used to manage the Storage Pool XML Namespace for mount options. Using a new virStorageBackendNamespaceInit function, set the virStoragePoolXMLNamespace into the _virStoragePoolOptions when the storage backend is loaded. Modify the storagepool.rng to allow for the usage of a different XML namespace to parse the fs_mount_opts to be included with the fs and netfs storage pool definitions. Modify the storagepoolxml2xmltest to utilize a properly modified XML file to parse and format the namespace for a netfs storage pool. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-07 22:14:57 +00:00
<h3><a id="StoragePoolNamespaces">Storage Pool Namespaces</a></h3>
<p>
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
rbd: Utilize storage pool namespace to manage config options Allow for adjustment of RBD configuration options via Storage Pool XML Namespace adjustments. When namespace arguments are used to start the pool, add a VIR_WARN to indicate that the startup was tainted by custom config_opts. Based off original patch/concept: https://www.redhat.com/archives/libvir-list/2014-May/msg00940.html Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-08 14:28:03 +00:00
mount options on the command line. For the "rbd" pool this provides
a mechanism to override default settings for RBD configuration options.
storage: Add infrastructure to manage XML namespace options Introduce the virStoragePoolFSMountOptionsDef to be used to manage the Storage Pool XML Namespace for mount options. Using a new virStorageBackendNamespaceInit function, set the virStoragePoolXMLNamespace into the _virStoragePoolOptions when the storage backend is loaded. Modify the storagepool.rng to allow for the usage of a different XML namespace to parse the fs_mount_opts to be included with the fs and netfs storage pool definitions. Modify the storagepoolxml2xmltest to utilize a properly modified XML file to parse and format the namespace for a netfs storage pool. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-07 22:14:57 +00:00
</p>
<p>
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.
</p>
<dl>
<dt><code>fs:mount_opts</code></dt>
<dd>Provides an XML namespace mechanism to optionally utilize
specifically named options for the mount command via the "-o"
option for the <code>fs</code> or <code>netfs</code> type storage
pools. In order to designate that the Storage Pool will be using
the mechanism, the <code>pool</code> element must be modified to
provide the XML namespace attribute syntax as follows:
<p>
storage: change custom namespace URIs to drop '/source' component The custom namespaces were originally registered against the storage pool source struct, but during review this was changed to the top level storage pool struct. The namespace URIs were not updated to match, so had a redundant '/source' component. Reviewed-by: John Ferlan <jferlan@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-31 11:14:09 +00:00
xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'
storage: Add infrastructure to manage XML namespace options Introduce the virStoragePoolFSMountOptionsDef to be used to manage the Storage Pool XML Namespace for mount options. Using a new virStorageBackendNamespaceInit function, set the virStoragePoolXMLNamespace into the _virStoragePoolOptions when the storage backend is loaded. Modify the storagepool.rng to allow for the usage of a different XML namespace to parse the fs_mount_opts to be included with the fs and netfs storage pool definitions. Modify the storagepoolxml2xmltest to utilize a properly modified XML file to parse and format the namespace for a netfs storage pool. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-07 22:14:57 +00:00
</p>
<p>
The <code>fs:mount_opts</code> defines the mount options by
specifying multiple <code>fs:option</code> subelements with
the attribute <code>name</code> 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.
</p>
The following XML snippet shows the syntax required in order to
utilize for a netfs pool:
<pre>
storage: change custom namespace URIs to drop '/source' component The custom namespaces were originally registered against the storage pool source struct, but during review this was changed to the top level storage pool struct. The namespace URIs were not updated to match, so had a redundant '/source' component. Reviewed-by: John Ferlan <jferlan@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-31 11:14:09 +00:00
&lt;pool type="netfs" xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'&gt;
storage: Add infrastructure to manage XML namespace options Introduce the virStoragePoolFSMountOptionsDef to be used to manage the Storage Pool XML Namespace for mount options. Using a new virStorageBackendNamespaceInit function, set the virStoragePoolXMLNamespace into the _virStoragePoolOptions when the storage backend is loaded. Modify the storagepool.rng to allow for the usage of a different XML namespace to parse the fs_mount_opts to be included with the fs and netfs storage pool definitions. Modify the storagepoolxml2xmltest to utilize a properly modified XML file to parse and format the namespace for a netfs storage pool. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-07 22:14:57 +00:00
&lt;name&gt;nfsimages&lt;/name&gt;
...
&lt;source&gt;
...
&lt;/source&gt;
...
&lt;target&gt;
...
&lt;/target&gt;
&lt;fs:mount_opts&gt;
&lt;fs:option name='sync'/&gt;
&lt;fs:option name='lazytime'/&gt;
&lt;/fs:mount_opts&gt;
&lt;/pool&gt;
...</pre>
<span class="since">Since 5.1.0.</span></dd>
rbd: Utilize storage pool namespace to manage config options Allow for adjustment of RBD configuration options via Storage Pool XML Namespace adjustments. When namespace arguments are used to start the pool, add a VIR_WARN to indicate that the startup was tainted by custom config_opts. Based off original patch/concept: https://www.redhat.com/archives/libvir-list/2014-May/msg00940.html Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-08 14:28:03 +00:00
<dt><code>rbd:config_opts</code></dt>
<dd>Provides an XML namespace mechanism to optionally utilize
specifically named options for the RBD configuration options
via the rados_conf_set API for the <code>rbd</code> type
storage pools. In order to designate that the Storage Pool
will be using the mechanism, the <code>pool</code> element
must be modified to provide the XML namespace attribute
syntax as follows:
<p>
storage: change custom namespace URIs to drop '/source' component The custom namespaces were originally registered against the storage pool source struct, but during review this was changed to the top level storage pool struct. The namespace URIs were not updated to match, so had a redundant '/source' component. Reviewed-by: John Ferlan <jferlan@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-31 11:14:09 +00:00
xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'
rbd: Utilize storage pool namespace to manage config options Allow for adjustment of RBD configuration options via Storage Pool XML Namespace adjustments. When namespace arguments are used to start the pool, add a VIR_WARN to indicate that the startup was tainted by custom config_opts. Based off original patch/concept: https://www.redhat.com/archives/libvir-list/2014-May/msg00940.html Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-08 14:28:03 +00:00
</p>
<p>
The <code>rbd:config_opts</code> defines the configuration options
by specifying multiple <code>rbd:option</code> subelements with
the attribute <code>name</code> specifying the configuration option
to be added and <code>value</code> 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.
</p>
The following XML snippet shows the syntax required in order to
utilize
<pre>
storage: change custom namespace URIs to drop '/source' component The custom namespaces were originally registered against the storage pool source struct, but during review this was changed to the top level storage pool struct. The namespace URIs were not updated to match, so had a redundant '/source' component. Reviewed-by: John Ferlan <jferlan@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-31 11:14:09 +00:00
&lt;pool type="rbd" xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'&gt;
rbd: Utilize storage pool namespace to manage config options Allow for adjustment of RBD configuration options via Storage Pool XML Namespace adjustments. When namespace arguments are used to start the pool, add a VIR_WARN to indicate that the startup was tainted by custom config_opts. Based off original patch/concept: https://www.redhat.com/archives/libvir-list/2014-May/msg00940.html Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-08 14:28:03 +00:00
&lt;name&gt;myrbdpool&lt;/name&gt;
...
&lt;source&gt;
...
&lt;/source&gt;
...
&lt;target&gt;
...
&lt;/target&gt;
...
&lt;rbd:config_opts&gt;
&lt;rbd:option name='client_mount_timeout' value='45'/&gt;
&lt;rbd:option name='rados_mon_op_timeout' value='20'/&gt;
&lt;rbd:option name='rados_osd_op_timeout' value='10'/&gt;
&lt;/rbd:config_opts&gt;
&lt;/pool&gt;
</pre>
<span class="since">Since 5.1.0.</span></dd>
storage: Add infrastructure to manage XML namespace options Introduce the virStoragePoolFSMountOptionsDef to be used to manage the Storage Pool XML Namespace for mount options. Using a new virStorageBackendNamespaceInit function, set the virStoragePoolXMLNamespace into the _virStoragePoolOptions when the storage backend is loaded. Modify the storagepool.rng to allow for the usage of a different XML namespace to parse the fs_mount_opts to be included with the fs and netfs storage pool definitions. Modify the storagepoolxml2xmltest to utilize a properly modified XML file to parse and format the namespace for a netfs storage pool. Signed-off-by: John Ferlan <jferlan@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-01-07 22:14:57 +00:00
</dl>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h2><a id="StorageVol">Storage volume XML</a></h2>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<p>
storage: expose volume meta-type in XML I got annoyed at having to use both 'virsh vol-list $pool --details' AND 'virsh vol-dumpxml $vol $pool' to learn if I had populated the volume correctly. Since two-thirds of the data present in virStorageVolGetInfo() already appears in virStorageVolGetXMLDesc(), this just adds the remaining piece of information, as: <volume type='...'> ... </volume> * docs/formatstorage.html.in: Document new <volume type=...>. * docs/schemas/storagevol.rng (vol): Add it to RelaxNG. * src/conf/storage_conf.h (virStorageVolTypeToString): Declare. * src/conf/storage_conf.c (virStorageVolTargetDefFormat): Output the metatype. (virStorageVolDefParseXML): Parse it, for unit tests. * tests/storagevolxml2xmlout/vol-*.xml: Update tests to match. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-11-19 20:14:54 +00:00
A storage volume will generally be either a file or a device
node; <span class="since">since 1.2.0</span>, an optional
output-only attribute <code>type</code> lists the actual type
storage: add ploop volume type Ploop image consists of directory with two files: ploop image itself, called root.hds and DiskDescriptor.xml that contains information about ploop device: https://openvz.org/Ploop/format. Such volume are difficult to manipulate in terms of existing volume types because they are neither a single files nor a directory. This patch introduces new volume type - ploop. This volume type is used by ploop volume's exclusively. Signed-off-by: Olga Krishtal <okrishtal@virtuozzo.com> Signed-off-by: Ján Tomko <jtomko@redhat.com>
2016-04-11 16:16:19 +00:00
(file, block, dir, network, netdir or ploop), which is also available
storage: expose volume meta-type in XML I got annoyed at having to use both 'virsh vol-list $pool --details' AND 'virsh vol-dumpxml $vol $pool' to learn if I had populated the volume correctly. Since two-thirds of the data present in virStorageVolGetInfo() already appears in virStorageVolGetXMLDesc(), this just adds the remaining piece of information, as: <volume type='...'> ... </volume> * docs/formatstorage.html.in: Document new <volume type=...>. * docs/schemas/storagevol.rng (vol): Add it to RelaxNG. * src/conf/storage_conf.h (virStorageVolTypeToString): Declare. * src/conf/storage_conf.c (virStorageVolTargetDefFormat): Output the metatype. (virStorageVolDefParseXML): Parse it, for unit tests. * tests/storagevolxml2xmlout/vol-*.xml: Update tests to match. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-11-19 20:14:54 +00:00
from <code>virStorageVolGetInfo()</code>. The storage volume
XML format is available <span class="since">since 0.4.1</span>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</p>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="StorageVolFirst">General metadata</a></h3>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
&lt;volume type='file'&gt;
&lt;name&gt;sparse.img&lt;/name&gt;
&lt;key&gt;/var/lib/xen/images/sparse.img&lt;/key&gt;
&lt;allocation&gt;0&lt;/allocation&gt;
&lt;capacity unit="T"&gt;1&lt;/capacity&gt;
...</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dl>
<dt><code>name</code></dt>
<dd>Providing a name for the volume which is unique to the pool.
storage: Check the partition name against provided name https://bugzilla.redhat.com/show_bug.cgi?id=1138516 If the provided volume name doesn't match what parted generated as the partition name, then return a failure. Update virsh.pod and formatstorage.html.in to describe the 'name' restriction for disk pools as well as the usage of the <target>'s <format type='value'>.
2015-01-16 00:12:42 +00:00
This is mandatory when defining a volume. For a disk pool, the
name must be combination of the <code>source</code> device path
device and next partition number to be created. For example, if
the <code>source</code> 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.
<span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>key</code></dt>
doc: storage: Explicitly state that it's possible to have non-unique key With most of our storage backends it's possible to have two separate volume keys to point to a single volume. (By creating sym/hard-links to local files or by mounting remote filesystems to two different locations and creating pools on top of them) Document this possibility.
2014-03-03 15:39:40 +00:00
<dd>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.
docs: storage: <volume><key> is always generated.
2010-02-22 20:54:06 +00:00
<span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>allocation</code></dt>
<dd>Providing the total storage allocation for the volume. This
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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 <strong>option</strong> of deciding
to sparsely allocate a volume. It does not have to honour requests
docs: Clarify semantics of sparse storage volumes Sparse LVM volumes do not behave in the way one would naively expect. The allocation does not automatically increase (which is different from how sparse files work).
2013-03-11 13:42:40 +00:00
for sparse allocation though. Different types of pools may treat
sparse volumes differently. For example, the <code>logical</code>
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.<br/>
docs: storage: Document capacity/alloc 'unit'
2010-02-22 20:52:14 +00:00
<br/>
docs: use correct terminology for 1024 bytes Yes, I like kilobytes better than kibibytes (when I say kilobytes, I generally mean 1024). But since the term is ambiguous, it can't hurt to say what we mean, by using both the correct name and calling out the numeric equivalent. * src/libvirt.c (virDomainGetMaxMemory, virDomainSetMaxMemory) (virDomainSetMemory, virDomainSetMemoryFlags) (virNodeGetFreeMemory): Tweak wording. * docs/formatdomain.html.in: Likewise. * docs/formatstorage.html.in: Likewise.
2012-03-02 15:23:07 +00:00
By default this is specified in bytes, but an optional attribute
docs: storage: Document capacity/alloc 'unit'
2010-02-22 20:52:14 +00:00
<code>unit</code> can be specified to adjust the passed value.
storage: support more scaling suffixes Disk manufacturers are fond of quoting sizes in powers of 10, rather than powers of 2 (after all, 2.1 GB sounds larger than 2.0 GiB, even though the exact opposite is true). So, we might as well follow coreutils' lead in supporting three types of suffix: single letter ${u} (which we already had) and ${u}iB for the power of 2, and ${u}B for power of 10. Additionally, it is impossible to create a file with more than 2**63 bytes, since off_t is signed (if you have enough storage to even create one 8EiB file, I'm jealous). This now reports failure up front rather than down the road when the kernel finally refuses an impossible size. * docs/schemas/basictypes.rng (unit): Add suffixes. * src/conf/storage_conf.c (virStorageSize): Use new function. * docs/formatstorage.html.in: Document it. * tests/storagevolxml2xmlin/vol-file-backing.xml: Test it. * tests/storagevolxml2xmlin/vol-file.xml: Likewise.
2012-03-05 21:06:33 +00:00
Values can be: 'B' or 'bytes' for bytes, 'KB' (kilobytes,
10<sup>3</sup> or 1000 bytes), 'K' or 'KiB' (kibibytes,
2<sup>10</sup> or 1024 bytes), 'MB' (megabytes, 10<sup>6</sup>
or 1,000,000 bytes), 'M' or 'MiB' (mebibytes, 2<sup>20</sup>
or 1,048,576 bytes), 'GB' (gigabytes, 10<sup>9</sup> or
1,000,000,000 bytes), 'G' or 'GiB' (gibibytes, 2<sup>30</sup>
or 1,073,741,824 bytes), 'TB' (terabytes, 10<sup>12</sup> or
1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes,
2<sup>40</sup> or 1,099,511,627,776 bytes), 'PB' (petabytes,
10<sup>15</sup> or 1,000,000,000,000,000 bytes), 'P' or 'PiB'
(pebibytes, 2<sup>50</sup> or 1,125,899,906,842,624 bytes),
'EB' (exabytes, 10<sup>18</sup> or 1,000,000,000,000,000,000
bytes), or 'E' or 'EiB' (exbibytes, 2<sup>60</sup> or
1,152,921,504,606,846,976 bytes). <span class="since">Since
0.4.1, multi-character <code>unit</code> since
0.9.11</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>capacity</code></dt>
<dd>Providing the logical capacity for the volume. This value is
docs: storage: Document capacity/alloc 'unit'
2010-02-22 20:52:14 +00:00
in bytes by default, but a <code>unit</code> attribute can be
specified with the same semantics as for <code>allocation</code>
This is compulsory when creating a volume.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.4.1</span></dd>
conf: Display <physical> in output of voldef Although the virStorageBackendUpdateVolTargetInfo will update the target.physical value, there is no way to provide that information via the virStorageGetVolInfo API since it only returns the capacity and allocation of a volume. So as described in commit id '0282ca45', it should be possible to generate an output only <physical> value for that purpose. This patch generates the <physical> value in the volume XML output for the sole purpose of being able to view/see the value to allow someone to parse the XML in order to obtain the value. Update the documentation to describe the output only nature. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-12-13 15:56:21 +00:00
<dt><code>physical</code></dt>
<dd>This output only element provides the host physical size of
the target storage volume. The default output <code>unit</code>
will be in bytes.
<span class="since">Since 3.0.0</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>source</code></dt>
<dd>Provides information about the underlying storage allocation
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
of the volume. This may not be available for some pool types.
<span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>target</code></dt>
<dd>Provides information about the representation of the volume
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
on the local host. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dl>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="StorageVolTarget">Target elements</a></h3>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<p>
A single <code>target</code> element is contained within the top level
<code>volume</code> element. This tag is used to describe the mapping of
the storage volume into the host filesystem. It can contain the following
child elements:
</p>
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
...
&lt;target&gt;
&lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
&lt;format type='qcow2'/&gt;
&lt;permissions&gt;
&lt;owner&gt;107&lt;/owner&gt;
&lt;group&gt;107&lt;/group&gt;
&lt;mode&gt;0744&lt;/mode&gt;
&lt;label&gt;virt_image_t&lt;/label&gt;
&lt;/permissions&gt;
docs: Adjust pool/vol target output Looks like the <timestamps> and <encryption> were put in the wrong place... They're not <pool> elements, rather they are <volume> elements
2016-12-07 15:12:50 +00:00
&lt;timestamps&gt;
&lt;atime&gt;1341933637.273190990&lt;/atime&gt;
&lt;mtime&gt;1341930622.047245868&lt;/mtime&gt;
&lt;ctime&gt;1341930622.047245868&lt;/ctime&gt;
&lt;/timestamps&gt;
&lt;encryption type='...'&gt;
...
&lt;/encryption&gt;
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
&lt;compat&gt;1.1&lt;/compat&gt;
&lt;nocow/&gt;
storage: add support for QCOW2 cluster_size option The default value hard-coded in QEMU (64KiB) is not always the ideal. Having a possibility to set the cluster_size by user may in specific use-cases improve performance for QCOW2 images. QEMU internally has some limits, the value has to be between 512B and 2048KiB and must by power of two, except when the image has Extended L2 Entries the minimal value has to be 16KiB. Since qemu-img ensures the value is correct and the limit is not always the same libvirt will not duplicate any of these checks as the error message from qemu-img is good enough: Cluster size must be a power of two between 512 and 2048k Resolves: https://gitlab.com/libvirt/libvirt/-/issues/154 Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2021-05-12 15:43:36 +00:00
&lt;clusterSize unit='KiB'&gt;64&lt;/clusterSize&gt;
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
&lt;features&gt;
&lt;lazy_refcounts/&gt;
&lt;/features&gt;
&lt;/target&gt;</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dl>
<dt><code>path</code></dt>
Fix documentation cut and paste errors, and a virsh typo.
2008-12-04 14:51:57 +00:00
<dd>Provides the location at which the volume can be accessed on
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
the local filesystem, as an absolute path. This is a readonly
attribute, so shouldn't be specified when creating a volume.
<span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>format</code></dt>
<dd>Provides information about the pool specific volume format.
storage: Check the partition name against provided name https://bugzilla.redhat.com/show_bug.cgi?id=1138516 If the provided volume name doesn't match what parted generated as the partition name, then return a failure. Update virsh.pod and formatstorage.html.in to describe the 'name' restriction for disk pools as well as the usage of the <target>'s <format type='value'>.
2015-01-16 00:12:42 +00:00
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
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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
docs: Point to list of valid pool target volume formats https://bugzilla.redhat.com/show_bug.cgi?id=1092886 Rather than point off to some nefarious "pool-specific docs" page when describing the "format" field for the target pool provide a link to the storage driver page which describes the various valid formats for each pool type. Also make it a bit more clear that if a valid format isn't specified, then the type field is ignored.
2014-07-23 12:36:50 +00:00
the <code>type</code> attribute. Consult the
<a href="storage.html">storage driver page</a> for the list of valid
volume format type values for each specific pool. The
<code>format</code> will be ignored on input for pools without a
volume format type value and the default pool format will be used.
<span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>permissions</code></dt>
docs: formatstorage: Update <permissions> docs - Don't redocument the permissions fields for backingstore, just point to the volume docs. - Clarify that owner/group are inherited from the parent directory at volume create/pool build time. - Clarify that <permissions> fields report runtime values too
2015-05-21 19:29:39 +00:00
<dd>Provides information about the permissions to use
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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
docs: formatstorage: Update <permissions> docs - Don't redocument the permissions fields for backingstore, just point to the volume docs. - Clarify that owner/group are inherited from the parent directory at volume create/pool build time. - Clarify that <permissions> fields report runtime values too
2015-05-21 19:29:39 +00:00
scripts determine permissions. There are 4 child elements.
The <code>mode</code> element contains the octal permission set.
storage: conf: Don't set any default <mode> in the XML The XML parser sets a default <mode> if none is explicitly passed in. This is then used at pool/vol creation time, and unconditionally reported in the XML. The problem with this approach is that it's impossible for other code to determine if the user explicitly requested a storage mode. There are some cases where we want to make this distinction, but we currently can't. Handle <mode> parsing like we handle <owner>/<group>: if no value is passed in, set it to -1, and adjust the internal consumers to handle it.
2015-04-27 20:48:05 +00:00
The <code>mode</code> defaults to 0600 when not provided.
docs: formatstorage: Update <permissions> docs - Don't redocument the permissions fields for backingstore, just point to the volume docs. - Clarify that owner/group are inherited from the parent directory at volume create/pool build time. - Clarify that <permissions> fields report runtime values too
2015-05-21 19:29:39 +00:00
The <code>owner</code> element contains the numeric user ID.
The <code>group</code> element contains the numeric group ID.
If <code>owner</code> or <code>group</code> aren't specified when
docs: storage: owner/group default to libvirtd UID/GID Commit fafcc818f changed the docs to say that when creating a pool directory or file volume with no owner/group specified, they will be inherited from the parent directory. This isn't correct now and doesn't seem to have ever been correct In reality default owner/group is whatever UID/GID libvirtd is running as Signed-off-by: Cole Robinson <crobinso@redhat.com>
2019-02-06 23:26:05 +00:00
creating a supported volume, the UID and GID of the libvirtd process
are used. The <code>label</code> element contains the MAC (eg SELinux)
docs: formatstorage: Update <permissions> docs - Don't redocument the permissions fields for backingstore, just point to the volume docs. - Clarify that owner/group are inherited from the parent directory at volume create/pool build time. - Clarify that <permissions> fields report runtime values too
2015-05-21 19:29:39 +00:00
label string.
For existing directory or filesystem based volumes, these fields
will be filled with the values used by the existing file.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.4.1</span>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dd>
docs: Move 'timestamps' and 'encryption' sub-element description The description should be in the target for a volume not a pool.
2017-03-12 15:47:07 +00:00
<dt><code>timestamps</code></dt>
<dd>Provides timing information about the volume. Up to four
sub-elements are present,
where <code>atime</code>, <code>btime</code>, <code>ctime</code>
and <code>mtime</code> hold the access, birth, change and
modification time of the volume, where known. The used time
format is &lt;seconds&gt;.&lt;nanoseconds&gt; 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.
<span class="since">Since 0.10.0</span>
</dd>
<dt><code>encryption</code></dt>
<dd>If present, specifies how the volume is encrypted. See
the <a href="formatstorageencryption.html">Storage Encryption</a> page
for more information.
</dd>
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
<dt><code>compat</code></dt>
<dd>Specify compatibility level. So far, this is only used for
<code>type='qcow2'</code> volumes. Valid values are <code>0.10</code>
and <code>1.1</code> so far, specifying QEMU version the images should
be compatible with. If the <code>feature</code> element is present,
Document behavior of compat when creating qcow2 volumes Commit bab2eda changed the behavior for missing compat attribute, but failed to update the documentation. Before, the option was omitted from qemu-img command line and the qemu-img default was used. Now we always specify the compat value and the default is 0.10. Reported by Christophe Fergeau https://bugzilla.gnome.org/show_bug.cgi?id=746660#c4
2015-03-24 16:13:24 +00:00
1.1 is used.
<span class="since">Since 1.1.0</span> If omitted, 0.10 is used.
<span class="since">Since 1.1.2</span>
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
</dd>
storagevol: add nocow to vol xml Add 'nocow' to storage volume xml so that user can have an option to set NOCOW flag to the newly created volume. It's useful on btrfs file system to enhance performance. Btrfs has low performance when hosting VM images, even more when the guest in those VM are also using btrfs as file system. One way to mitigate this bad performance is to turn off COW attributes on VM files. Generally, there are two ways to turn off COW on btrfs: a) by mounting fs with nodatacow, then all newly created files will be NOCOW. b) per file. Add the NOCOW file attribute. It could only be done to empty or new files. This patch tries the second way, according to 'nocow' option, it could set NOCOW flag per file: for raw file images, handle 'nocow' in libvirt code; for non-raw file images, pass 'nocow=on' option to qemu-img, and let qemu-img to handle that (requires qemu-img version >= 2.1). Signed-off-by: Chunyan Liu <cyliu@suse.com>
2014-07-15 08:49:46 +00:00
<dt><code>nocow</code></dt>
<dd>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. <span class="since">Since 1.2.7</span>
</dd>
storage: add support for QCOW2 cluster_size option The default value hard-coded in QEMU (64KiB) is not always the ideal. Having a possibility to set the cluster_size by user may in specific use-cases improve performance for QCOW2 images. QEMU internally has some limits, the value has to be between 512B and 2048KiB and must by power of two, except when the image has Extended L2 Entries the minimal value has to be 16KiB. Since qemu-img ensures the value is correct and the limit is not always the same libvirt will not duplicate any of these checks as the error message from qemu-img is good enough: Cluster size must be a power of two between 512 and 2048k Resolves: https://gitlab.com/libvirt/libvirt/-/issues/154 Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2021-05-12 15:43:36 +00:00
<dt><code>clusterSize</code></dt>
<dd>Changes the qcow2 cluster size which can affect image file size
and performance.
<span class="since">Since 7.4.0</span>
</dd>
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
<dt><code>features</code></dt>
<dd>Format-specific features. Only used for <code>qcow2</code> now.
Valid sub-elements are:
<ul>
<li><code>&lt;lazy_refcounts/&gt;</code> - allow delayed reference
Use 1.1.0 everywhere in the documentation Since we already have the v1.1.0-rc1 tag in git.
2013-06-25 13:25:29 +00:00
counter updates. <span class="since">Since 1.1.0</span></li>
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
</ul>
</dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dl>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="StorageVolBacking">Backing store elements</a></h3>
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
<p>
A single <code>backingStore</code> element is contained within the top level
<code>volume</code> 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:
</p>
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
...
&lt;backingStore&gt;
&lt;path&gt;/var/lib/virt/images/master.img&lt;/path&gt;
&lt;format type='raw'/&gt;
&lt;permissions&gt;
&lt;owner&gt;107&lt;/owner&gt;
&lt;group&gt;107&lt;/group&gt;
&lt;mode&gt;0744&lt;/mode&gt;
&lt;label&gt;virt_image_t&lt;/label&gt;
&lt;/permissions&gt;
&lt;/backingStore&gt;
&lt;/volume&gt;</pre>
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
<dl>
<dt><code>path</code></dt>
<dd>Provides the location at which the backing store can be accessed on
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
the local filesystem, as an absolute path. If omitted, there is no
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
backing store for this volume.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.6.0</span></dd>
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
<dt><code>format</code></dt>
<dd>Provides information about the pool specific backing store format.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
For disk pools it will provide the partition type. For filesystem
or directory pools it will provide the file format type, eg cow,
docs: storage: Fix backingStore <format> docs
2010-02-22 21:01:12 +00:00
qcow, vmdk, raw. The actual format is specified via the type attribute.
Consult the pool-specific docs for the list of valid
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
values. Most file formats require a backing store of the same format,
however, the qcow2 format allows a different backing store format.
<span class="since">Since 0.6.0</span></dd>
<dt><code>permissions</code></dt>
<dd>Provides information about the permissions of the backing file.
docs: formatstorage: Update <permissions> docs - Don't redocument the permissions fields for backingstore, just point to the volume docs. - Clarify that owner/group are inherited from the parent directory at volume create/pool build time. - Clarify that <permissions> fields report runtime values too
2015-05-21 19:29:39 +00:00
See volume <code>permissions</code> documentation for explanation
of individual fields.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.6.0</span>
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
</dd>
</dl>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h2><a id="examples">Example configuration</a></h2>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<p>
Here are a couple of examples, for a more complete set demonstrating
every type of storage pool, consult the <a href="storage.html">storage driver page</a>
</p>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="exampleFile">File based storage pool</a></h3>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
&lt;pool type="dir"&gt;
&lt;name&gt;virtimages&lt;/name&gt;
&lt;target&gt;
&lt;path&gt;/var/lib/virt/images&lt;/path&gt;
&lt;/target&gt;
&lt;/pool&gt;</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="exampleISCSI">iSCSI based storage pool</a></h3>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
&lt;pool type="iscsi"&gt;
&lt;name&gt;virtimages&lt;/name&gt;
&lt;source&gt;
&lt;host name="iscsi.example.com"/&gt;
&lt;device path="iqn.2013-06.com.example:iscsi-pool"/&gt;
&lt;auth type='chap' username='myuser'&gt;
&lt;secret usage='libvirtiscsi'/&gt;
&lt;/auth&gt;
&lt;/source&gt;
&lt;target&gt;
&lt;path&gt;/dev/disk/by-path&lt;/path&gt;
&lt;/target&gt;
&lt;/pool&gt;</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="exampleVol">Storage volume</a></h3>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
&lt;volume&gt;
&lt;name&gt;sparse.img&lt;/name&gt;
&lt;allocation&gt;0&lt;/allocation&gt;
&lt;capacity unit="T"&gt;1&lt;/capacity&gt;
&lt;target&gt;
&lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
&lt;permissions&gt;
&lt;owner&gt;107&lt;/owner&gt;
&lt;group&gt;107&lt;/group&gt;
&lt;mode&gt;0744&lt;/mode&gt;
&lt;label&gt;virt_image_t&lt;/label&gt;
&lt;/permissions&gt;
&lt;/target&gt;
&lt;/volume&gt;</pre>
docs: Update docs to reflect LUKS secret changes Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation to describe adding a 'passphrase' type secret usage model in order to reference the secret for a luks volume. After commit, it was deemed that a 'volume' usage model should be used, so adjust the various documents in order rephrase descriptions in order to follow the correct usage model. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-11 10:59:03 +00:00
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="exampleLuks">Storage volume using LUKS</a></h3>
docs: Update docs to reflect LUKS secret changes Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation to describe adding a 'passphrase' type secret usage model in order to reference the secret for a luks volume. After commit, it was deemed that a 'volume' usage model should be used, so adjust the various documents in order rephrase descriptions in order to follow the correct usage model. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-11 10:59:03 +00:00
<pre>
formatstorage.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
&lt;volume&gt;
&lt;name&gt;MyLuks.img&lt;/name&gt;
&lt;capacity unit="G"&gt;5&lt;/capacity&gt;
&lt;target&gt;
&lt;path&gt;/var/lib/virt/images/MyLuks.img&lt;/path&gt;
&lt;format type='raw'/&gt;
&lt;encryption format='luks'&gt;
&lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
&lt;/encryption&gt;
&lt;/target&gt;
&lt;/volume&gt;
docs: Update docs to reflect LUKS secret changes Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation to describe adding a 'passphrase' type secret usage model in order to reference the secret for a luks volume. After commit, it was deemed that a 'volume' usage model should be used, so adjust the various documents in order rephrase descriptions in order to follow the correct usage model. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-11 10:59:03 +00:00
</pre>
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
</body>
</html>
Reference in New Issue Copy Permalink