<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//UR1//DTD docbookAllegeEsup//FR"
"http://www.esup-portail.org/consortium/espace/docbook/xxe/dtd/docbook_allege_esup.dtd">
<article lang="FR">
  <title>Backup/restore procedures</title>

  <articleinfo>
    <abstract>
      <para>This section deals with the backup/restore problems and
      solutions</para>
    </abstract>

    <author>
      <firstname>Thomas Bellembois</firstname>

      <surname></surname>

      <affiliation>
        <orgname><ulink url="http://www.univ-rennes1.fr">University of Rennes
        1</ulink></orgname>
      </affiliation>
    </author>

    <revhistory>
      <revision>
        <revnumber>1.0</revnumber>

        <date>2006.08.29 : Thomas Bellembois (University of Rennes1) : first
        release</date>

        <revdescription>
          <para></para>
        </revdescription>
      </revision>
    </revhistory>
  </articleinfo>

  <section>
    <title>Introduction</title>

    <para>The ESUP-WebDAV server is based on the Jakarta Slide WebDAV server.
    In this document the terms "Slide" and "ESUP WebDAV server" refer to the
    same entity : The ESUP WebDAV server.</para>

    <para>Slide does not provide a user-friendly backup/restore interface. But
    given that Slide content and metadata are well structured it is possible
    to backup and restore them easily.</para>

    <para>The ESUP Portail consortium does not provide a friendly tool to
    handle backup/restore procedures, but we have tested two procedures that
    work properly.</para>

    <para>Feel free to contact me for further details.</para>

    <para>Notational conventions :</para>

    <itemizedlist>
      <listitem>
        <para>resource = a file or directory</para>
      </listitem>

      <listitem>
        <para>content/metadata = when a file is put on the WebDAV server, the
        server attach it informations. This is totally transparent for users
        but not for the administrator. That is why we call the file "content"
        and its attached information "metadata".</para>
      </listitem>

      <listitem>
        <para>backend = place (storage media) where the WebDAV server stores
        the content and metadata.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>What you have to know</title>

    <para>To understand how to bakup and particularly restore Slide content
    and metadata, you must be aware of how Slide handle these datas.</para>

    <para>In the <filename>build.properties</filename> file of the ESUP Webdav
    server you have defined 5 parameters :</para>

    <para><programlisting>slide.rootPath = /home/tbellemb/esup-serveur-WebDav-3.5/SlideData
slide.contentRootStore = ${slide.rootPath}/content/store
slide.contentWorkStore = ${slide.rootPath}/content/work
slide.metadataRootStore = ${slide.rootPath}/metadata/store
slide.metadataWorkStore = ${slide.rootPath}/metadata/work</programlisting></para>

    <para>Note that once the server is deployed, you can get these parameters
    in the <filename>webapps/Slide/Domain.xml</filename> file in the
    deployment directory :</para>

    <para><programlisting>...
&lt;nodestore classname="org.apache.slide.store.txfile.TxXMLFileDescriptorsStore"&gt;
&lt;parameter name="rootpath"&gt;/home/tbellemb/esup-serveur-WebDav-3.5/SlideData/metadata/store&lt;/parameter&gt;
&lt;parameter name="workpath"&gt;/home/tbellemb/esup-serveur-WebDav-3.5/SlideData/metadata/work&lt;/parameter&gt;
&lt;parameter name="defer-saving"&gt;true&lt;/parameter&gt;
&lt;parameter name="timeout"&gt;120&lt;/parameter&gt;
&lt;/nodestore&gt;
...
&lt;contentstore classname="org.apache.slide.store.txfile.TxFileContentStore"&gt;
&lt;parameter name="rootpath"&gt;/home/tbellemb/esup-serveur-WebDav-3.5/SlideData/content/store&lt;/parameter&gt;
&lt;parameter name="workpath"&gt;/home/tbellemb/esup-serveur-WebDav-3.5/SlideData/content/work&lt;/parameter&gt;
&lt;parameter name="defer-saving"&gt;true&lt;/parameter&gt;
&lt;parameter name="timeout"&gt;120&lt;/parameter&gt;
&lt;/contentstore&gt;
...</programlisting></para>

    <para>The <filename>*work*</filename> directories are used as temporary
    directories so we will leave them aside...</para>

    <para>We have then two branches :</para>

    <itemizedlist>
      <listitem>
        <para>[mySlideData]/metadata/store</para>
      </listitem>

      <listitem>
        <para>[mySlideData]/content/store</para>
      </listitem>
    </itemizedlist>

    <para>that will respectively store Slide metadata and content.</para>

    <para>Slide uses the same hierarchy to store content and metadata as the
    one created by users.</para>

    <para>Let's have a look to this hierarchy :</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="media/dataStructure.png"></imagedata>
      </imageobject>
    </mediaobject>

    <para>In the <filename>metadata</filename> branche, each directory
    contains descriptor files (*.def.xml) of its files and sub-directories.
    These xml files contain many informations such as the creation date, the
    display name or the permissions on the resource. Of course files and
    directories descriptors are a bit differents and contain specific
    informations. A directory descriptor enumerates its files and
    sub-directories, its parent and permissions.</para>

    <para>Descriptor of the <filename>/files</filename> directory :</para>

    <para><programlisting>&lt;children&gt;
 &lt;child name="quotas" uuri="/files/quotas"/&gt;
 &lt;child name="homedirs" uuri="/files/homedirs"/&gt;
 &lt;child name="partages" uuri="/files/partages"/&gt;
 &lt;child name="test" uuri="/files/test"/&gt;
&lt;/children&gt;
...
&lt;parents&gt;
 &lt;parent name="files" uuri="/"/&gt;
&lt;/parents&gt;
...
&lt;permissions&gt;
 &lt;permission subjectUri="/roles/uPortal/ToutLeMonde/Personnels/CRI/SI" actionUri="all" inheritable="true" negative="false" /&gt;
&lt;/permissions&gt;</programlisting></para>

    <para>The <filename>content</filename> branche contains files (in the
    meaning of binary content). The filenames are ended by the file revision
    number - always <varname>_1.0</varname> given that the ESUP WebDAV server
    does not use versioning.</para>

    <para>The content and metadata branches are strongly linked. Adding a file
    in the content branche would have no effect (the file would not be visible
    on the server) if you do not modify the descritptor of the directory you
    want to put the file in.<important>
        <para>1. Descriptors (.def.xml) files MUST NOT be modified while the
        server is running. This may crash the server.</para>

        <para>2. If you DO NOT modify a file descriptor correctly (not well
        formed xml, for example) this may crash the server.</para>
      </important></para>

    <para></para>
  </section>

  <section>
    <title>Backup/restore process</title>

    <para>There are two main ways to restore Slide data depending on the
    permissions put on the folder tree you want to restore. Any way, you have
    to ensure that the Slide backend ([myslideData]) is on a backed
    filesystem.</para>

    <section>
      <title>Folder tree with no or few permissions (like an homedir)</title>

      <para>Consider the following tree (resources with an * have access
      restrictions (permissions)) :</para>

      <para><programlisting>homedirs* -- tbellemb* -- c
                       -- b
                       -- a -- a1 -- foo3.doc
                            -- foo1.doc
                            -- foo2.doc</programlisting></para>

      <para>The user tbellemb deletes his "a" directory and would like it to
      be restored.</para>

      <para>The last saved backend is (content branche) :</para>

      <para><programlisting>content -- store -- homedirs -- tbellemb -- c
                                         -- b
                                         -- a -- a1 -- foo3.doc_1.0
                                              -- foo1.doc_1.0
                                              -- foo2.doc_1.0</programlisting></para>

      <para>To restore the "a" directory :</para>

      <itemizedlist>
        <listitem>
          <para>copy the "a" directory from the backend to a temporary
          directory</para>
        </listitem>

        <listitem>
          <para>remove all of the _1.0 extensions. This can be done by a
          simple Perl script below.</para>
        </listitem>

        <listitem>
          <para>with a DAV client put the "a" directory from the temporary
          directory to the user homedir</para>

          <para>Perl script to remove the _1.0 extensions :<programlisting>#!/usr/bin/perl
print "Debut programme: ".__FILE__." Ligne: ".__LINE__."\n\n";
chdir("$ARGV[0]");
opendir REP, ".";
$reponse=`find . -name "*_1.0"`;
@fics= split /\n/,$reponse;
closedir REP;
foreach $_ (@fics) { 
 $oldName = $_;
 print "Fichier a traiter: ".$oldName."\n";
 s/_1.0//;
 `mv "$oldName" "$_"`;
 print "Fichier traite: ".$_."\n";
}
print "\nFin normale programme: ".__FILE__." Ligne: ".__LINE__."\n";
exit;</programlisting></para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Folder tree with many permissions (like a shared space)</title>

      <para>Consider the following tree (resources with an * have access
      restrictions (permissions)) :</para>

      <programlisting>partages* -- SI* -- c*
                 -- b*
                 -- a* -- a1** -- a11* -- ..
                               -- a12* -- ..
                       -- foo1.doc
                       -- foo2.doc   </programlisting>

      <para>A user deletes the "a" directory and would like it to be
      restored.</para>

      <para>Using the first restore method would be a hard task and would
      force the administrator to put right access to each "a" sub-directory
      after the restoration.</para>

      <para>The last saved backend is (content and metadata branches)
      :<programlisting>content -- store -- partages -- SI -- c
                                   -- b
                                   -- a -- a1 -- a11 -- ..
                                              -- a12 -- ..
                                        -- foo1.doc_1.0
                                        -- foo2.doc_1.0

metadata -- store -- partages                    
                  -- [.def.xml]
                  -- [partages.def.xml]
                                        -- SI
                                        -- [SI.def.xml]
                                                        -- b
                                                        -- c
                                                        -- [a.def.xml]
                                                        -- [b.def.xml]
                                                        -- [c.def.xml]
                                                        -- a           -- foo1.doc.def.xml
                                                                       -- foo2.doc.def.xml    </programlisting>To
      restore the "a" directory :<itemizedlist>
          <listitem>
            <para>Stop the WebDAV server</para>
          </listitem>

          <listitem>
            <para>Copy the two "a" directories both from the content and
            metadata branches of the saved backend to the current
            backend.</para>
          </listitem>

          <listitem>
            <para>Modify the SI.def.xml file to add the restored "a" directory
            as shown below.</para>
          </listitem>

          <listitem>
            <para>Restart the server</para>
          </listitem>
        </itemizedlist></para>

      <para>SI.def.xml :</para>

      <programlisting>&lt;children&gt;
      &lt;child name="b" uuri="/partages/SI/b" /&gt;
      &lt;child name="c" uuri="/partages/SI/c" /&gt;
      &lt;!-- RESTORED DIRECTORY--&gt;
      &lt;child name="a" uuri="/partages/SI/a" /&gt;
&lt;/children&gt;</programlisting>

      <para></para>
    </section>
  </section>
</article>