<?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>unzip, ANT init and ANT deploy</varname>
      targets, in this order.</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 ANT init and ANT deploy targets. Restart the
      server.</para>
    </section>

    <section>
      <title>The ANT targets</title>

      <para>The ANT targets are very close to the ones present in the
      ESUP-Portail portal.</para>

      <para>Run the ANT help target to have a short description of the most
      common used targets.</para>

      <para>- <emphasis>buildEclipseProject</emphasis> : for developpers,
      check out the project from the SN (trunk), run the buildEclipseProject
      and unzip targets and you will have a well configured environment to
      modify the source code.</para>

      <para>- <emphasis>buildZip / buildTar</emphasis> : build packaging of
      the server (with Slide and Tomcat - no Internet connection is required
      to install the server).</para>

      <para>- <emphasis>clean</emphasis> : for developpers, clean the
      project</para>

      <para>- <emphasis>compile</emphasis> : for developpers, compile the
      application, administrator do not need to run this target given that it
      is called by the deploy target.</para>

      <para>- <emphasis>config</emphasis> : quick reconfigure the server, but
      use ANT init and ANT deploy instead.</para>

      <para>- <emphasis>deploy</emphasis> : deploy the server - for a full
      deployment run ANT unzip, ANT init and ANT deploy.</para>

      <para>- <emphasis>getComponents / removeComponents</emphasis> : retrieve
      remote files and libraries, administrator do not need to run this target
      given that it is called by the init target.</para>

      <para>- <emphasis>help</emphasis> : display a quick help</para>

      <para>- <emphasis>init</emphasis> : initialize the application for
      compilation</para>

      <para>- <emphasis>runClient</emphasis> : do nothing... :-)</para>

      <para>- <emphasis>unzip</emphasis> : unzip Tomcat in the deployment
      directory and Slide in the working directory</para>

      <para>- <emphasis>server.start / server.stop</emphasis> : start and stop
      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>It seems (we're not sure of that, it's a recommendation) to be
      more convenient for some webdav clients to use "" as the context path of
      slide. That is to say, http://webdav.univ-rennes1.fr for example should
      be directly the webdav server (and not
      http://applis.univ-rennes1.f/mywebdav for example). It can avoid some
      authentications problems for some OS (Windows, MacOs or others) For
      that, in build.properties put <userinput>slide.context =</userinput> Be
      carreful to not put a "/", just nothing. The goal is to make a 'Context
      path="" ' in the server.xml file for slide application.</para>

      <para>You can use Slide with or without a web server behind Tomcat.
      There are many reasons to use a web server behind Tomcat : <itemizedlist>
          <listitem>
            <para>You have already others Applications on your server.</para>
          </listitem>

          <listitem>
            <para>It can be also for deploying load balancing.</para>
          </listitem>

          <listitem>
            <para>It's a good way also to make HTTPS (SSL).</para>
          </listitem>

          <listitem>
            <para>It's very useful to make many virtual hosts and configure
            some authentication possibilities
            (http://webdav-ldap.univ-rennes1.fr,
            http://webdav-noauth.univ-rennes1.fr,
            http://webdav-trusted.univ-rennes1.fr, ...), see comments in
            build.properties in the section about web.xml and the
            authentication filters.</para>
          </listitem>

          <listitem>
            <para>Others ...</para>
          </listitem>
        </itemizedlist> But just keep in your mind that you can use Tomcat
      Standalone (without another webserver in frontend).</para>

      <section>
        <title>Apache/Tomcat</title>

        <para>Before to configure an Apache/Tomcat binding make sure that you
        have no problems using webdav directly on Tomcat. Indeed, you can use
        Slide in 2 modes together (in the same time), that is to say with and
        without web server frontend. Look at build.properties for
        options.</para>

        <para>The "web server" is usually Apache. You can use different
        version of Apache : <itemizedlist>
            <listitem>
              <para>Apache 1.3,</para>
            </listitem>

            <listitem>
              <para>Apache 2.0,</para>
            </listitem>

            <listitem>
              <para>Apache 2.2.</para>
            </listitem>
          </itemizedlist></para>

        <para>And you can use also different ajp13 connector. See official
        documentation for that : <itemizedlist>
            <listitem>
              <para>mod jk 2 -&gt; <ulink
              url="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html">http://tomcat.apache.org/connectors-doc-archive/jk2/index.html</ulink></para>
            </listitem>

            <listitem>
              <para>mod jk -&gt; <ulink
              url="http://tomcat.apache.org/connectors-doc/">http://tomcat.apache.org/connectors-doc/</ulink></para>
            </listitem>

            <listitem>
              <para>AJP Proxy (&gt; Apache 2.1) -&gt; <ulink
              url="http://tomcat.apache.org/connectors-doc/proxy.html">http://tomcat.apache.org/connectors-doc/proxy.html</ulink></para>
            </listitem>
          </itemizedlist></para>

        <para>If using Apache2.2, use together AJP Proxy. Apache2.2 is a very
        new version of Apache, so it's not included in the stable packages
        suite of distributions like debian for example :(</para>

        <para>mod jk 2 is no more supported, use mod jk instead</para>

        <para>Apache2 is easier to configure, if you can, use it.</para>

        <note>
          <para>When you use a frontend web server behind Tomcat, HTTP
          requests and responses are alterate (keep in your mind, some options
          can be important).</para>

          <para>With mod jk 2, mod jk and (not sure, AJP Proxy seems to be
          better) AJP Proxy, you can have authentication problem between
          apache and some mricrosoft webdav client (mostly Windows XP).
          Indeed, the session doesn't persist between 2 requests, so
          authentication prompt is always displayed (even if authentication
          works well). You can notice this in debug mode (put
          org.esupportail.filter in debug mode via log4j.xml),
          AuthenticationRouter class logs the session id for each
          request.</para>

          <para>Tips (maybe it can help, but we're not sure at all :S) :
          <itemizedlist>
              <listitem>
                <warning><para>This tip with jvm route is maybe unuseful
                ...</para></warning>

                <para>Use jvm route even if you don't use load balancing
                :</para>

                <itemizedlist><listitem> <para>Modify ther server.xml file in
                adding <userinput>jvmRoute="jvm1"</userinput> to the Engine
                tag : </para> <para><userinput> &lt;Engine name="Catalina"
                defaultHost="localhost" debug="0"
                jvmRoute="jvm1"&gt;&lt;/Engine&gt; </userinput> </para>
                </listitem> <listitem> <para>Next you should define the jvm1
                jvm route in your mod jk, mod jk2 or ajp proxy configuration.
                For exemple for mod jk, you will have a workers.properties
                with this line :</para> <para>
                <userinput>worker.ajp13.jvm_route=jvm1</userinput> (you can
                use another name that ajp13 for worker, see official doc).
                </para> </listitem></itemizedlist>
              </listitem>

              <listitem>
                <para>On the client try to connect with a dummy user, next try
                to connect with a real user. You can try to cancel first and
                next to try to login really ...</para>
              </listitem>

              <listitem>
                <important><para>Maybe the most useful Tip
                here.</para></important>

                <para>Use HTTPS instead HTTP, that is to say configure your
                Apache Server to make SSL (via the mod ssl). It seems there is
                no more problem of lost sessions (tested with Apache2.0 and
                mod jk). Note however that some webdav clients don't support
                HTTPS.</para>
              </listitem>
            </itemizedlist></para>
        </note>
      </section>
    </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>