[libvirt] [PATCH RFC v3 15/15] FSPool: Tests and documentation
Olga Krishtal
okrishtal at virtuozzo.com
Fri Dec 2 15:38:20 UTC 2016
Patch adds general documentation for fspool and
tests for directory backend.
Signed-off-by: Olga Krishtal <okrishtal at virtuozzo.com>
---
docs/formatfs.html.in | 206 +++++++++++++++++++++
docs/fspool.html.in | 41 ++++
docs/sitemap.html.in | 4 +
tests/Makefile.am | 12 ++
tests/fsitemxml2xmlin/item.xml | 13 ++
tests/fsitemxml2xmlout/item.xml | 13 ++
tests/fsitemxml2xmltest.c | 105 +++++++++++
.../dir-missing-target-path-invalid.xml | 12 ++
tests/fspoolxml2xmlin/fspool-dir.xml | 16 ++
tests/fspoolxml2xmlout/fspool-dir.xml | 16 ++
tests/fspoolxml2xmltest.c | 81 ++++++++
11 files changed, 519 insertions(+)
create mode 100644 docs/formatfs.html.in
create mode 100644 docs/fspool.html.in
create mode 100644 tests/fsitemxml2xmlin/item.xml
create mode 100644 tests/fsitemxml2xmlout/item.xml
create mode 100644 tests/fsitemxml2xmltest.c
create mode 100644 tests/fspoolschemadata/dir-missing-target-path-invalid.xml
create mode 100644 tests/fspoolxml2xmlin/fspool-dir.xml
create mode 100644 tests/fspoolxml2xmlout/fspool-dir.xml
create mode 100644 tests/fspoolxml2xmltest.c
diff --git a/docs/formatfs.html.in b/docs/formatfs.html.in
new file mode 100644
index 0000000..b50034c
--- /dev/null
+++ b/docs/formatfs.html.in
@@ -0,0 +1,206 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <body>
+ <h1>Filesystem pool and item XML format</h1>
+
+ <ul id="toc"></ul>
+
+ <h2><a name="FSPool">Filesystem pool XML</a></h2>
+
+ <p>
+ Filesystem pools is a facility to manage filesystems. They has a lot in common with
+ storage pools (nearly the same api and way of managment). However the managment units
+ are completely different. To avoid the misunderstanding in fspool usage use this XML
+ description. See <a href="fspool.html">fspool driver page</a>
+ </p>
+
+ <p>
+ The root element is named <code>fspool</code>. It has attribute <code>type</code>,
+ at the moment fspool has only one type <code>dir</code>. It represents fspool that
+ holds filesystems in subdirectories on a host filesystem.
+ </p>
+
+ <h3><a name="FSPoolFirst">General metadata</a></h3>
+
+ <pre>
+ <fspool type="dir">
+ <name>virfs</name>
+ <uuid>4584ee21-db40-4e98-980e-44802c47b62f</uuid>
+ <allocation>10000000</allocation>
+ <capacity>50000000</capacity>
+ <available>40000000</available>
+ ...</pre>
+
+ <dl>
+ <dt><code>name</code></dt>
+ <dd>Providing a name for the fspool which is unique to the host.
+ This is mandatory when defining a filesystem pool.</dd>
+ <dt><code>uuid</code></dt>
+ <dd>Providing an identifier for the fspool which is globally unique.
+ This is optional when defining a fspool, a UUID will be generated if
+ omitted.</dd>
+ <dt><code>allocation</code></dt>
+ <dd>Providing the total storage allocation for the pool. This value is in bytes.
+ This is not applicable when creating a fspool.</dd>
+ <dt><code>capacity</code></dt>
+ <dd>Providing the total capacity for the fspool. This value is in bytes. This
+ is not applicable when creating a fspool.</dd>
+ <dt><code>available</code></dt>
+ <dd>Providing the free space available for allocating new items
+ in the fspool. This value is in bytes. This is not applicable when creating a
+ fspool.</dd>
+ </dl>
+
+ <h3><a name="FSPoolSource">Source elements</a></h3>
+
+ <p>
+ A single <code>source</code> element is contained within the top level
+ <code>fspool</code> element. This tag is used to describe the source of
+ the fspool. At the moment it is left empty.
+ </p>
+
+ <h3><a name="FSPoolTarget">Target elements</a></h3>
+
+ <p>
+ A single <code>target</code> element is contained within the top level
+ <code>fspool</code> element for all types of fspools (fspool types <code>dir</code>).
+ This tag is used to describe the mapping of fspool into the host filesystem.
+ It can contain the following child elements:
+ </p>
+
+ <pre>
+ ...
+ <target>
+ <path>/path/in/host/fs</path>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ </permissions>
+ </target>
+ </fspool></pre>
+
+ <dl>
+ <dt><code>path</code></dt>
+ <dd>Provides the location at which the fspool will be mapped into
+ the local filesystem namespace, as an absolute path. For a fspool with directory
+ backend it will be a fully qualified name of the directory in which items
+ will be created.
+ </dd>
+ <dt><code>permissions</code></dt>
+ <dd> It provides information about the permissions to use for the
+ final directory when the fspool is built. There are 4 child elements.
+ The <code>mode</code> element contains the octal permission set.
+ The <code>mode</code> defaults to 0755 when not provided.
+ 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
+ creating a directory, the values are inherited from the parent
+ directory.
+ </dd>
+ </dl>
+
+ <h2><a name="FSItem">Item XML</a></h2>
+ <p>
+ An item is a directory that holds single filesystem. The filesystem item
+ XML format is available.
+ </p>
+
+ <h3><a name="FSItemFirst">General metadata</a></h3>
+
+ <pre>
+ <item>
+ <name>item1</name>
+ <key>/path/to/fspool/</key>
+ <allocation>0</allocation>
+ <capacity unit="T">1</capacity>
+ ...</pre>
+
+ <dl>
+ <dt><code>name</code></dt>
+ <dd>Providing a name for the item which is unique to the fspool.
+ This is mandatory when defining an item.</dd>
+ <dt><code>key</code></dt>
+ <dd>Providing an identifier for the item which identifies a
+ single item. It is impossible to have two distinct keys
+ identifying a single item. This field cannot be set when creating
+ an item: it is always generated.</dd>
+ <dt><code>allocation</code></dt>
+ <dd>Providing the total storage allocation for the item.</dd>
+ <dt><code>capacity</code></dt>
+ <dd>Providing the logical capacity for the item.</dd>
+ </dl>
+
+ <h3><a name="FsItemTarget">Target elements</a></h3>
+
+ <p>
+ A single <code>target</code> element is contained within the top level
+ <code>item</code> element. This tag is used to describe the mapping of
+ the fspool item into the host filesystem. It can contain the following
+ child elements:
+ </p>
+
+ <pre>
+ ...
+ <target>
+ <path>/var/lib/virt/images/sparse.img</path>
+ <format type='qcow2'/>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ </permissions>
+ </target></pre>
+
+ <dl>
+ <dt><code>permissions</code></dt>
+ <dd>Provides information about the permissions to use
+ when creating items. There are 4 child elements.
+ The <code>mode</code> element contains the octal permission set.
+ The <code>mode</code> defaults to 0600 when not provided.
+ 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
+ creating fspool item, the values are inherited from the parent
+ directory.
+ </dd>
+ </dl>
+
+
+ <h2><a name="examples">Example configuration</a></h2>
+
+ <p>
+ Here is an example of fspool and item.
+ </p>
+
+ <h3><a name="exampleDir">Directory based fspool</a></h3>
+
+ <pre>
+ <fspool type="dir">
+ <name>my_fspool</name>
+ <source>
+ </source>
+ <target>
+ <path>/my_fspool_dir</path>
+ </target>
+ </fspool></pre>
+
+ <h3><a name="exampleItem">Fspool Item</a></h3>
+
+ <pre>
+ <item>
+ <name>item1</name>
+ <allocation>0</allocation>
+ <capacity unit="T">1</capacity>
+ <target>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ </permissions>
+ </target>
+ </item></pre>
+
+ </body>
+</html>
diff --git a/docs/fspool.html.in b/docs/fspool.html.in
new file mode 100644
index 0000000..a501ad3
--- /dev/null
+++ b/docs/fspool.html.in
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <body>
+ <h1 >Filesystem Pool Management</h1>
+ <p>
+ Libvirt provides filesystems managment on the physical host through
+ fspools and items.
+ </p>
+ <p>
+ Fspool is the entity that holds filesystems. It has a lot in
+ common with storage pools and volumes. However, fspool deals with
+ filesystems and has the only one unit managment type - filesystem.
+ Single filesystem in fspool is called an item.
+ </p>
+ <p>
+ Libvirt supports the following fspool types:
+ </p>
+ <ul>
+ <li>
+ <a href="#FSPoolBackendDir">Directory backend</a>
+ </li>
+ </ul>
+
+ <h2><a name="FSPoolBackendDir">Fspool with directory backend</a></h2>
+ <p>
+ A fspool with a type of <code>dir</code> provides the means to manage
+ filesystems within a directory on a single host.
+ </p>
+
+ <h3>Example pool input definition</h3>
+ <pre>
+ <fspool type="dir">
+ <name>virtfs</name>
+ <target>
+ <path>/var/lib/virt/fs</path>
+ </target>
+ </fspool></pre>
+
+ </body>
+</html>
diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in
index 757d5aa..31606d1 100644
--- a/docs/sitemap.html.in
+++ b/docs/sitemap.html.in
@@ -177,6 +177,10 @@
<span>Network filter XML format</span>
</li>
<li>
+ <a href="formatfs.html">Filesystem pool</a>
+ <span>The filesystem pool and filesystem item XML format</span>
+ </li>
+ <li>
<a href="formatstorage.html">Storage</a>
<span>The storage pool and volume XML format</span>
</li>
diff --git a/tests/Makefile.am b/tests/Makefile.am
index 924029a..cf4eb1c 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -351,6 +351,8 @@ test_programs += secretxml2xmltest
test_programs += genericxml2xmltest
+test_programs += fsitemxml2xmltest fspoolxml2xmltest
+
if WITH_LINUX
test_programs += virusbtest \
virnetdevbandwidthtest \
@@ -873,6 +875,16 @@ interfacexml2xmltest_SOURCES = \
testutils.c testutils.h
interfacexml2xmltest_LDADD = $(LDADDS)
+fsitemxml2xmltest_SOURCES = \
+ fsitemxml2xmltest.c \
+ testutils.c testutils.h
+fsitemxml2xmltest_LDADD = $(LDADDS)
+
+fspoolxml2xmltest_SOURCES = \
+ fspoolxml2xmltest.c \
+ testutils.c testutils.h
+fspoolxml2xmltest_LDADD = $(LDADDS)
+
cputest_SOURCES = \
cputest.c \
testutils.c testutils.h
diff --git a/tests/fsitemxml2xmlin/item.xml b/tests/fsitemxml2xmlin/item.xml
new file mode 100644
index 0000000..ae1be59
--- /dev/null
+++ b/tests/fsitemxml2xmlin/item.xml
@@ -0,0 +1,13 @@
+<item>
+ <name>item1</name>
+ <key>/var/lib/libvirt/images/fs/item1</key>
+ <capacity unit='bytes'>0</capacity>
+ <allocation unit='bytes'>4096</allocation>
+ <target>
+ <permissions>
+ <mode>0600</mode>
+ <owner>0</owner>
+ <group>0</group>
+ </permissions>
+ </target>
+</item>
diff --git a/tests/fsitemxml2xmlout/item.xml b/tests/fsitemxml2xmlout/item.xml
new file mode 100644
index 0000000..ae1be59
--- /dev/null
+++ b/tests/fsitemxml2xmlout/item.xml
@@ -0,0 +1,13 @@
+<item>
+ <name>item1</name>
+ <key>/var/lib/libvirt/images/fs/item1</key>
+ <capacity unit='bytes'>0</capacity>
+ <allocation unit='bytes'>4096</allocation>
+ <target>
+ <permissions>
+ <mode>0600</mode>
+ <owner>0</owner>
+ <group>0</group>
+ </permissions>
+ </target>
+</item>
diff --git a/tests/fsitemxml2xmltest.c b/tests/fsitemxml2xmltest.c
new file mode 100644
index 0000000..a6fec33
--- /dev/null
+++ b/tests/fsitemxml2xmltest.c
@@ -0,0 +1,105 @@
+#include <config.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+
+#include <sys/types.h>
+#include <fcntl.h>
+
+#include "internal.h"
+#include "testutils.h"
+#include "fs_conf.h"
+#include "testutilsqemu.h"
+#include "virstring.h"
+
+#define VIR_FROM_THIS VIR_FROM_NONE
+
+static int
+testCompareXMLToXMLFiles(const char *fspoolxml, const char *inxml,
+ const char *outxml, unsigned int flags)
+{
+ char *actual = NULL;
+ int ret = -1;
+ virFSPoolDefPtr fspool = NULL;
+ virFSItemDefPtr dev = NULL;
+
+ if (!(fspool = virFSPoolDefParseFile(fspoolxml)))
+ goto fail;
+
+ if (!(dev = virFSItemDefParseFile(fspool, inxml, flags)))
+ goto fail;
+
+ if (!(actual = virFSItemDefFormat(fspool, dev)))
+ goto fail;
+
+ if (virTestCompareToFile(actual, outxml) < 0)
+ goto fail;
+
+ ret = 0;
+
+ fail:
+ VIR_FREE(actual);
+ virStoragePoolDefFree(fspool);
+ virFSItemDefFree(dev);
+ return ret;
+}
+
+struct testInfo {
+ const char *fspool;
+ const char *name;
+ unsigned int flags;
+};
+
+static int
+testCompareXMLToXMLHelper(const void *data)
+{
+ int result = -1;
+ const struct testInfo *info = data;
+ char *fspoolxml = NULL;
+ char *inxml = NULL;
+ char *outxml = NULL;
+
+ if (virAsprintf(&fspoolxml, "%s/fspoolxml2xmlin/%s.xml",
+ abs_srcdir, info->fspool) < 0 ||
+ virAsprintf(&inxml, "%s/fsitemxml2xmlin/%s.xml",
+ abs_srcdir, info->name) < 0 ||
+ virAsprintf(&outxml, "%s/fsitemxml2xmlout/%s.xml",
+ abs_srcdir, info->name) < 0) {
+ goto cleanup;
+ }
+
+ result = testCompareXMLToXMLFiles(fspoolxml, inxml, outxml, info->flags);
+
+ cleanup:
+ VIR_FREE(fspoolxml);
+ VIR_FREE(inxml);
+ VIR_FREE(outxml);
+
+ return result;
+}
+
+
+static int
+mymain(void)
+{
+ int ret = 0;
+
+#define DO_TEST_FULL(fspool, name, flags) \
+ do { \
+ struct testInfo info = { fspool, name, flags }; \
+ if (virTestRun("FS Item XML-2-XML " name, \
+ testCompareXMLToXMLHelper, &info) < 0) \
+ ret = -1; \
+ } \
+ while (0);
+
+#define DO_TEST(fspool, name) DO_TEST_FULL(fspool, name, 0)
+
+ DO_TEST("fspool-dir", "item");
+
+ return ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE;
+}
+
+VIRT_TEST_MAIN(mymain)
diff --git a/tests/fspoolschemadata/dir-missing-target-path-invalid.xml b/tests/fspoolschemadata/dir-missing-target-path-invalid.xml
new file mode 100644
index 0000000..a52bf49
--- /dev/null
+++ b/tests/fspoolschemadata/dir-missing-target-path-invalid.xml
@@ -0,0 +1,12 @@
+<fspool type='dir'>
+ <name>test</name>
+ <source>
+ </source>
+ <target>
+ <permissions>
+ <mode>0700</mode>
+ <owner>-1</owner>
+ <group>-1</group>
+ </permissions>
+ </target>
+</fspool>
diff --git a/tests/fspoolxml2xmlin/fspool-dir.xml b/tests/fspoolxml2xmlin/fspool-dir.xml
new file mode 100644
index 0000000..d1a3f28
--- /dev/null
+++ b/tests/fspoolxml2xmlin/fspool-dir.xml
@@ -0,0 +1,16 @@
+<fspool type='dir'>
+ <name>virtfs</name>
+ <uuid>5584ee21-db40-4e98-980e-44802c47b62f</uuid>
+ <capacity unit='bytes'>0</capacity>
+ <allocation unit='bytes'>0</allocation>
+ <available unit='bytes'>0</available>
+ <source>
+ </source>
+ <target>
+ <path>///var/////lib/libvirt/fs//</path>
+ <permissions>
+ <mode>0700</mode>
+ <label>some_lable_t</label>
+ </permissions>
+ </target>
+</fspool>
diff --git a/tests/fspoolxml2xmlout/fspool-dir.xml b/tests/fspoolxml2xmlout/fspool-dir.xml
new file mode 100644
index 0000000..dbca470
--- /dev/null
+++ b/tests/fspoolxml2xmlout/fspool-dir.xml
@@ -0,0 +1,16 @@
+<fspool type='dir'>
+ <name>virtfs</name>
+ <uuid>5584ee21-db40-4e98-980e-44802c47b62f</uuid>
+ <capacity unit='bytes'>0</capacity>
+ <allocation unit='bytes'>0</allocation>
+ <available unit='bytes'>0</available>
+ <source>
+ </source>
+ <target>
+ <path>/var/lib/libvirt/fs</path>
+ <permissions>
+ <mode>0700</mode>
+ <label>some_lable_t</label>
+ </permissions>
+ </target>
+</fspool>
diff --git a/tests/fspoolxml2xmltest.c b/tests/fspoolxml2xmltest.c
new file mode 100644
index 0000000..7883d65
--- /dev/null
+++ b/tests/fspoolxml2xmltest.c
@@ -0,0 +1,81 @@
+#include <config.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+
+#include <sys/types.h>
+#include <fcntl.h>
+
+#include "internal.h"
+#include "testutils.h"
+#include "fs_conf.h"
+#include "testutilsqemu.h"
+#include "virstring.h"
+
+#define VIR_FROM_THIS VIR_FROM_NONE
+
+static int
+testCompareXMLToXMLFiles(const char *inxml, const char *outxml)
+{
+ char *actual = NULL;
+ int ret = -1;
+ virFSPoolDefPtr dev = NULL;
+
+ if (!(dev = virFSPoolDefParseFile(inxml)))
+ goto fail;
+
+ if (!(actual = virFSPoolDefFormat(dev)))
+ goto fail;
+
+ if (virTestCompareToFile(actual, outxml) < 0)
+ goto fail;
+
+ ret = 0;
+
+ fail:
+ VIR_FREE(actual);
+ virStoragePoolDefFree(dev);
+ return ret;
+}
+
+static int
+testCompareXMLToXMLHelper(const void *data)
+{
+ int result = -1;
+ char *inxml = NULL;
+ char *outxml = NULL;
+
+ if (virAsprintf(&inxml, "%s/fspoolxml2xmlin/%s.xml",
+ abs_srcdir, (const char*)data) < 0 ||
+ virAsprintf(&outxml, "%s/fspoolxml2xmlout/%s.xml",
+ abs_srcdir, (const char*)data) < 0) {
+ goto cleanup;
+ }
+
+ result = testCompareXMLToXMLFiles(inxml, outxml);
+
+ cleanup:
+ VIR_FREE(inxml);
+ VIR_FREE(outxml);
+
+ return result;
+}
+
+static int
+mymain(void)
+{
+ int ret = 0;
+
+#define DO_TEST(name) \
+ if (virTestRun("FS Pool XML-2-XML " name, \
+ testCompareXMLToXMLHelper, (name)) < 0) \
+ ret = -1
+
+ DO_TEST("fspool-dir");
+
+ return ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE;
+}
+
+VIRT_TEST_MAIN(mymain)
--
1.8.3.1
More information about the libvir-list
mailing list