<?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>ESUP WebDAV server V4 (and 3.5)</title>

  <subtitle>Installation</subtitle>

  <section>
    <title>Introduction</title>

    <note>
      <para>About the V3.5 and V4 versions</para>

      <para>The ESUP consortium has released a V4 version of the ESUP WebDAV
      server with quota support and a new administration tool. This V4 version
      is based on the Jakarta Slide 2.2b server. But Slide 2.2 encounters
      encoding problems with accents whereas the 2.1 stable version has not
      this problem. So we have decided to release a 3.5 version of the ESUP
      WebDAV server based on Slide 2.1 slightly modified to support quota and
      improve permission management. The 3.5 and 4 versions have exactly the
      same fonctionalitities.</para>
    </note>

    <para>The purpose of this document is to explain how to install the ESUP
    WebDAV server V4. The installation procedure is exactly the same for the
    V4 and V3.5 versions of the server. Many features have been modified or
    improved since the previous versions. Therefore the WebDAV server V4 is
    <emphasis>not compliant with the versions 2.* or lower</emphasis>. You
    will find a FAQ (under construction) at the end of this document. Please
    <emphasis>DO NOT contact directly the developpers</emphasis> neither by
    mail nor by phone. Use instead the
    <literal>injac-utilisateurs@esup-portail.org</literal> mailing list. When
    you request the mailing list please ensure to attach the logs of the
    server in debug mode AND your build.properties file (remove every critical
    entry). See the section "Logging".</para>
  </section>

  <section>
    <title>Important notes</title>

    <para>The packaging and configuration file have been slightly modified
    since the previous version. Read carefully this documention before
    deploying the server.</para>

    <para>The ESUP WebDAV server V4 is in beta version because it is based on
    a beta version of the Jakarta Slide server - this version has to be used
    only for development purposes.</para>

    <para>In a production environment you HAVE TO use the V3.5 version.</para>
  </section>

  <section>
    <title>Main new features and improvements</title>

    <formalpara>
      <title>Quota management</title>

      <para>The ESUP WebDAV server V4 supports quotas according to the <ulink
      url="http://www.ietf.org/internet-drafts/draft-ietf-webdav-quota-07.txt">WebDAV
      quota RFC</ulink>.</para>
    </formalpara>

    <formalpara>
      <title>Administration tool</title>

      <para>A new administration tool - ESUPWDServerManager - replaces the
      previous administration tools (HomedirCreation, InjacSpacesCreation) and
      adds some functionalities.</para>
    </formalpara>

    <formalpara>
      <title>Packaging</title>

      <para>The packaging has been modified to be compliant with the ESUP
      packaging standard.</para>
    </formalpara>
  </section>

  <section>
    <title>Components</title>

    <para>The ESUP WebDAV server V4 is composed of :<itemizedlist>
        <listitem>
          <para>a <ulink url="http://jakarta.apache.org/slide/">Jakarta
          Slide</ulink> V2.2beta server (V2.1 for the ESUP WebDAV server
          V3.5)</para>
        </listitem>

        <listitem>
          <para>a <ulink url="http://tomcat.apache.org/">Jakarta
          Tomcat</ulink> 5.028 server</para>
        </listitem>

        <listitem>
          <para>an uPortal group store</para>
        </listitem>

        <listitem>
          <para>a quota listener</para>
        </listitem>

        <listitem>
          <para>a quota management Web service</para>
        </listitem>

        <listitem>
          <para>an authentication layer to manage SSO-CAS, LDAP and Trusted
          authentication</para>
        </listitem>

        <listitem>
          <para>an administration tool: ESUPWDServerManager</para>
        </listitem>
      </itemizedlist></para>
  </section>

  <section>
    <title>Pre-requisite</title>

    <itemizedlist>
      <listitem>
        <para>an ESUP-Portail esupdev-2.4.2 or higher version (the WebDAV
        server is compatible with ESUP-Portail 2.5) - with the "PortalGroup"
        Web service deployed and running</para>
      </listitem>

      <listitem>
        <para>an LDAP directory (compliant with the Inet Org Person standard
        (SUPANN for France))</para>
      </listitem>

      <listitem>
        <para>a jdk 1.4 - you can encounter problems trying to deploy the
        server with a jdk 1.5</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Naming conventions</title>

    <itemizedlist>
      <listitem>
        <para><varname>[package.home]</varname> : directory where the package
        is unzipped.</para>
      </listitem>

      <listitem>
        <para><varname>[deploy.home]</varname> : directory where the server is
        deployed.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Installation</title>

    <section>
      <title>Getting the package</title>

      <para>Download the package esup-serveur-WebDav-4.0beta (or
      esup-serveur-WebDav-3.5) in the <ulink
      url="http://www.esup-portail.org/consortium/espace/download/_index.html">download
      page</ulink>. Unzip it in a choosen directory.</para>
    </section>

    <section>
      <title>Preparing the deployment</title>

      <para>Open and edit the
      <filename>[package.home]/esup-serveur-WebDav-4.0beta/build.properties</filename>
      file</para>

      <important>
        <para>It is STRONGLY recommended to fill this file in carefully given
        that some parameters (written as [FINAL]) can NOT be re-configured
        once the server is deployed and started.</para>

        <para>Each parameter HAS TO BE filled in except those written as
        [OPTIONAL]</para>

        <para>You can keep the value of parameters written as
        [DEFAULT]=defaultValue - the others MUST be modified</para>
      </important>

      <para><filename>build.properties</filename> files :</para>

      <para>The <filename>build.properties</filename> file contains all of the
      explanation needed to fill it in. This document focuses only on some
      points.</para>

      <formalpara>
        <title>Tomcat/Apache parameters</title>

        <para><itemizedlist>
            <listitem>
              <para><userinput>webdavServer.url</userinput> : URL used by
              WebDAV clients such as the administration tool - change this
              value according to your system configuration (especially if you
              have an apache running in front of the WebDAV server)</para>
            </listitem>
          </itemizedlist></para>
      </formalpara>

      <formalpara>
        <title>LDAP parameters</title>

        <para><itemizedlist>
            <listitem>
              <para><userinput>slide.ldap.Scope</userinput> : this parameter
              has change since the last version - scope = SCOPE_SUBTREE_LEVEL
              | SCOPE_ONE_LEVEL | SCOPE_OBJECT_LEVEL</para>
            </listitem>

            <listitem>
              <para><userinput>slide.ldap.Filter</userinput> : replace
              <varname>&amp;</varname> by <varname>&amp;amp;</varname> and
              <varname>|</varname> by <varname>&amp;#124;</varname></para>
            </listitem>
          </itemizedlist></para>
      </formalpara>

      <formalpara>
        <title>backend parameters</title>

        <para><itemizedlist>
            <listitem>
              <para><userinput>slide.content****Store</userinput> : path where
              to store Slide content</para>
            </listitem>

            <listitem>
              <para><userinput>slide.metadata****Store</userinput> : path
              where to store Slide metadata</para>
            </listitem>
          </itemizedlist><important>
            <para>It is strongly recommended to store Slide content and
            metadata on a fast machine.</para>
          </important><note>
            <para>If you want to keep data of a previous installed version of
            the server (higher than V3), keep the same values for these
            parameters.</para>
          </note></para>
      </formalpara>

      <formalpara>
        <title>ESUP-Portail portal connection</title>

        <para><itemizedlist>
            <listitem>
              <para><userinput>slide.uPStore.DisableCache</userinput> : you
              are advised against disabling the cache, this could affect both
              the WebDAV server and the portal performance</para>
            </listitem>
          </itemizedlist></para>
      </formalpara>

      <formalpara>
        <title>root user</title>

        <para><itemizedlist>
            <listitem>
              <para><userinput>slide.rootUser</userinput> : administrator uid
              (must be registered in the LDAP)</para>
            </listitem>
          </itemizedlist></para>
      </formalpara>

      <formalpara>
        <title>authentication router properties</title>

        <para>Please fill in this section carefully. Most of the problems are
        due to a wrong configuration of the authentication layer.</para>
      </formalpara>

      <formalpara>
        <title>security</title>

        <para><note>
            <para>The security of the ESUP WebDAV server is performed by both
            an IP adresses control and a password control. The authentication
            layer ensures that the client trying to connect to the server is
            one of the portal IP adresses and that the password contained in
            the request is correct.</para>
          </note><itemizedlist>
            <listitem>
              <para><userinput>slide.trustedFilter.password</userinput> :
              enter here your trusted password - this password is used by the
              storage channel and administration tool
              (<literal>ESUPWDServerManager</literal>) to access the ESUP
              WebDAV server. It must be complex enough.</para>
            </listitem>

            <listitem>
              <para><userinput>slide.trustedFilter.users</userinput> : leave
              this parameter empty</para>
            </listitem>

            <listitem>
              <para><userinput>axis.trustedFilter.password</userinput> : you
              have to set the same password as
              slide.trustedFilter.password</para>
            </listitem>

            <listitem>
              <para><userinput>axis.trustedFilter.users</userinput> : you can
              restrict here the people who can access the quota Web service
              and then use the ESUPWDServerManager administration tool
              (<varname>user1:user2:user3:...</varname>)</para>
            </listitem>
          </itemizedlist></para>
      </formalpara>
    </section>

    <section>
      <title>Deploying the server</title>

      <para>Execute the ANT <varname>deploy</varname> target.</para>
    </section>

    <section>
      <title>Customizing the deployment</title>

      <para>You can personalize your installation thanks to the
      <varname>perso</varname> directory ("ESUP-like" packaging). You will
      find in particular <filename>log4j.xml</filename> files to configure
      logging (see the logging section for more details).</para>
    </section>

    <section>
      <title>Starting and stopping the server</title>

      <para>Execute the <varname>server.start</varname> and
      <varname>server.stop</varname> ANT targets.</para>
    </section>

    <section>
      <title>Re-configuring the server</title>

      <para>Modify the
      <filename>[package.home]/esup-serveur-WebDav-4.0beta/build.properties</filename>
      files and run the <varname>init</varname> ANT target. Restart the
      server.</para>
    </section>

    <section>
      <title>Logging</title>

      <section>
        <title>WebDAV events logging</title>

        <para>WebDAV events logging are configured by the
        <varname>slide.webdavLogging*</varname> parameters in the
        <filename>[package.home]/esup-serveur-WebDav-4.0beta/build.properties</filename>
        file.</para>
      </section>

      <section>
        <title>Other logging</title>

        <para>More generally you can configure logging using
        <filename>log4j.xml</filename> files in the
        <varname>[package.home]/esup-serveur-WebDav-4.0beta/perso</varname>
        directory (do not forget to init and restart the server). By default,
        this directories contains files to log the authentication layer,
        uPortal store (group management), quota listener (quota management)
        and the administration tool. You can add entries as needed.</para>
      </section>
    </section>

    <section>
      <title>Recommended configuration</title>

      <para>Will come soon...</para>
    </section>

    <section>
      <title>In case of problems...</title>

      <procedure>
        <step>
          <para>Read and read again the documentation and comments in the
          <filename>build.properties</filename> file. Most of the problems are
          due to a wrong configuration.</para>
        </step>
      </procedure>

      <procedure>
        <step>
          <para>Read the <ulink url="FAQ.html">FAQ</ulink>.</para>
        </step>
      </procedure>

      <procedure>
        <step>
          <para>Log the server in debug mode.</para>
        </step>
      </procedure>

      <procedure>
        <step>
          <para>Contact the <literal>injac-utilisateurs</literal> mailing list
          providing your <filename>build.properties</filename> file (remove
          critical entries) and your logs in debug mode.</para>
        </step>
      </procedure>

      <procedure>
        <step>
          <para>Pray... ;-)</para>
        </step>
      </procedure>
    </section>

    <section>
      <title>Links in this page</title>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="http://www.esup-portail.org/consortium/espace/download/_index.html">the
          ESUP download page</ulink></para>
        </listitem>
      </itemizedlist>
    </section>
  </section>
</article>