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> + <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 -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
