[PATCH RFC v3 15/15] FSPool: Tests and documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Patch adds general documentation for fspool and
tests for directory backend.

Signed-off-by: Olga Krishtal <okrishtal@xxxxxxxxxxxxx>
---
 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>
+      &lt;fspool type="dir"&gt;
+        &lt;name&gt;virfs&lt;/name&gt;
+        &lt;uuid&gt;4584ee21-db40-4e98-980e-44802c47b62f&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>
+
+    <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>
+        ...
+        &lt;target&gt;
+          &lt;path&gt;/path/in/host/fs&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;/permissions&gt;
+        &lt;/target&gt;
+      &lt;/fspool&gt;</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>
+      &lt;item&gt;
+        &lt;name&gt;item1&lt;/name&gt;
+        &lt;key&gt;/path/to/fspool/&lt;/key&gt;
+        &lt;allocation&gt;0&lt;/allocation&gt;
+        &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
+        ...</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>
+        ...
+        &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;/permissions&gt;
+        &lt;/target&gt;</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>
+      &lt;fspool type="dir"&gt;
+        &lt;name&gt;my_fspool&lt;/name&gt;
+        &lt;source&gt;
+        &lt;/source&gt;
+        &lt;target&gt;
+          &lt;path&gt;/my_fspool_dir&lt;/path&gt;
+        &lt;/target&gt;
+      &lt;/fspool&gt;</pre>
+
+    <h3><a name="exampleItem">Fspool Item</a></h3>
+
+    <pre>
+      &lt;item&gt;
+        &lt;name&gt;item1&lt;/name&gt;
+        &lt;allocation&gt;0&lt;/allocation&gt;
+        &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
+        &lt;target&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;/permissions&gt;
+        &lt;/target&gt;
+      &lt;/item&gt;</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>
+      &lt;fspool type="dir"&gt;
+        &lt;name&gt;virtfs&lt;/name&gt;
+        &lt;target&gt;
+          &lt;path&gt;/var/lib/virt/fs&lt;/path&gt;
+        &lt;/target&gt;
+      &lt;/fspool&gt;</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

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list



[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]
  Powered by Linux