1. Introduction

The purpose of this document is to explain how to use the ESUP WebDAV server V4 (and 3.5). In particular it focuses on the administration tool : ESUPWDServerManager. The user guide is exactly the same for the V4 and V3.5 versions of the server.

2. Important notes

Note that some actions done by the administration tool are resource consuming. These actions are identified by the [RC] tag in this document.

Do not forget that the DAV:quota-available-bytes metadata represents the space left on a folder and not the quota. The quota is the sum of the DAV:quota-used-bytes and DAV:quota-available-bytes metadata.

You are adviced of reading the paper submitted to EUNIS 2006 to understand how quota are implemented on the ESUP WebDAV server.

3. Main new features and improvements

ESUPWDServerManager is new and replaces the former administration tools.

4. Components

5. Pre-requisite

6. Naming conventions

Please see the installation page.

7. User guide

7.1. Deploying and configuring the tool

ESUPWDServerManager is automatically deployed and configured with the ESUP WebDAV server.

folders

• source : Java source files

• properties : properties files, sample input file and space manager sample pattern file

• lib : libraries

• dist : package directory

• build : execution directory

7.2. Changing the configuration

7.2.1. Recommended method

Modify the [package.home]/esup-serveur-WebDav-4.0beta/build.properties files and execute the init ANT target. Note that this action can also modify the server configuration. These parameters are marked with the [S] flag in the following list.

build.properties file parameters involving ESUPWDServerManager

• webdavServer.url

• slide.ldap.Url : [S]

• slide.ldap.Port : [S]

• slide.ldap.Scope : [S]

• slide.ldap.Principal : [S]

• slide.ldap.Credential : [S]

• slide.ldap.MaxResults : [S]

• slide.ldap.BaseDn : [S]

• slide.quotaListener.WebServiceUrl

• slide.rootUser : [S]

• slide.trustedFilter.password : [S]

7.2.2. Alternate method

Modify the [deploy.home]/properties/configuration.xml file. Note that if you execute the init ANT target ([package.home]/esup-serveur-WebDav-4.0beta directory), your modifications will be lost.

7.3. Running the tool

7.3.1. Execution modes

ESUPWDServerManager can be either runned in interactive mode (like an Unix shell) or provinding an input command file.

It is planned to develop a graphic mode.

7.3.2. Interactive mode

Execute the run.sh or run.bat script in the [deploy.home]/esup-serveur-WebDav-4.0beta/ESUPWDServerManager-1.0 directory :

./run.sh

7.3.3. Input command file mode

Execute the run.sh or run.bat script in the [deploy.home]/esup-serveur-WebDav-4.0beta/ESUPWDServerManager-1.0/build directory followed by the input file path:

./run.sh /data/ESUPStuff/commands.txt

You will find a sample command file in the [deploy.home]/esup-serveur-WebDav-4.0beta/ESUPWDServerManager-1.0/properties directory :

#
# ESUP WebDAV server manager command file
#
# you can add comment like this
//or like this
/*
  or like this
*/
# --> modifying some parameters
setConfig connectUserName="tbellemb"
setConfig connectPassword="trusted"
# --> connecting to the server
connect
# --> deleting the test tree
rmdir -f /files/quotas
# --> trying an impossible action (for test)
mkdir /files/repQuiExistePas/newRep
# --> building a new test tree
mkdir /files/quotas
mkdir /files/quotas/goodGuys
mkdir /files/quotas/goodGuys/jedi
mkdir /files/quotas/goodGuys/jedi/yoda
mkdir /files/quotas/goodGuys/jedi/quiGonJin
mkdir /files/quotas/badGuys
mkdir /files/quotas/badGuys/sith
mkdir /files/quotas/badGuys/sith/darkVador
mkdir /files/quotas/badGuys/sith/darkMaul
mkdir /files/quotas/badGuys/sith/darkMaul/babyDarkMaul
mkdir /files/quotas/badGuys/sith/darkMaul/doggyDarkMaul
# --> setting up quotas
setquota "/files/quotas" 0 7000 false
//for goodGuys badGuys
setquota "/files/quotas" 1 5000 false
//for yoda quiGonJin darkVador darkMaul
setquota "/files/quotas" 3 2000 false
setquota "/files/quotas/badGuys/sith/darkMaul/babyDarkMaul" 0 2000 true
//darkMaul is a VR
setVR "/files/quotas/badGuys/sith/darkMaul" true
# --> creating spaces with metadata
createSpace -path="/files/quotas" -ldap="(&(&(ur1typeentree=pers)(departmentNumber=57SI*))(uid=b*))" -ldapAttribute="uid"
            -templateFile="properties/folderManager_pattern.xml" -regexp="^(.).*:^(..).*:^(.*)" -regexpSeparator=":"
createSpace -path="/files/quotas" -name="myNewSpace"
# --> setting some properties
patchQAB "/files/quotas/badGuys/sith/darkMaul/babyDarkMaul" 2500
# --> getting some properties
getQAB "/files/quotas/badGuys/sith/darkMaul/babyDarkMaul"
# --> removing quota
removeQuota "/files/quotas" false
# --> displaying the result
cd /files
treeinfo 5
# --> leaving the program
quit

7.4. Commands overview

ESUPWDServerManager was made to work almost like a Unix shell, it means that you can navigate using ls and cd commands and create/delete directories with mkdir and rmdir commands.

Most of the commands have several syntax so that they can be use both with the interactive or input file mode.

The first command to run is connect to connect to the ESUP WebDAV server.

The help full command gives the list and syntax of every command.

7.5. Commands details

For a full command help type help [commandName].

Optional arguments are in brackets. Optional arguments have to be fill in with the input command file mode. In the interactive mode, if you do not provide the optional arguments, you will be prompted.

7.5.1. Basic commands

7.5.2. Folder creation/deletion

7.5.3. Quota commands

7.5.4. Space manager command

7.5.4.1. Introduction

This new tool replaces the former "HomedirCreation" and "InjacSpacesCreation" tools.

This is a generic tool to create folders and set permissions and metadata.

7.5.4.2. Syntax

createSpace
    -path="spacePath"
   | -name="spaceName"
or |_-ldap="ldapFilter" -ldapAttribute="uniqueLdapAttributeToRetrieve"
   (-regexp="regexp" -regexpSeparator="regexpSeparator")
   (-templateFile="pathToTemplateFile")
   (-forceSetProperties="true|false")

-path

Specifies the space path. This path must exist. Do not specify the context !

-name="folderName" or -ldap="ldapFilter" -ldapAttribute="uniqueLdapAttributeToRetrieve"

Specifies or retrieves name(s) of directory(ies) to create.

+ Either the name is specified with the -name attribute (creation of only one space).

+ Or they are retrieved from an LDAP with the -ldap and -ldapAttribute parameters. The -ldapAttribute parameter specifies the unique LDAP attribute used for space names.

-regexp="regexp" -regexpSeparator="regexpSeparator"

Optional parameters to transform the full space paths.

With a regexp you can specify a hash method to create homedirs and then improve the server performance. All of the sub-directories are automatically created.

-templateFile="pathToTemplateFile"

Specifies a template file to set permissions and metadata on spaces. Results retrieved from the LDAP can be used in the template file with the {0} expression.

-forceSetProperties="true|false" - default=false

Specifies if properties have to be written even if space(s) already exist. You can use this parameter to (re)initialize permissions and add metadata to existing space(s).

7.5.4.2.1. Template file

Contains two sections : permissions and properties. Remove one of them to put only permissions or metadata.

This file has to be compliant with the [deploy.home]/ESUPWDServerManager1.0/properties/folderManager_pattern.dtd file :

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT folderPattern (properties, permissions)>
<!ELEMENT properties (property)+>
<!ELEMENT permissions (permission)+>
<!ELEMENT property EMPTY>
<!ELEMENT permission EMPTY>
<!ATTLIST property
name CDATA #REQUIRED
namespace CDATA #IMPLIED
value CDATA #REQUIRED
type CDATA #IMPLIED
>
<!ATTLIST permission
subjectUri CDATA #REQUIRED
actionUri (read | write | read-acl| write-act | all) #REQUIRED
negative (true | false) #REQUIRED
>

<properties>
    <property name="propertyName" (namespace="namespace") value="value" (type="type") />
    <property ... />
...
</properties>
<permissions>
    <permission subjectUri="subjectUri" actionUri="actionUri" negative="true|false" />
    <permission ... />
...
</permissions>

The <properties> tag defines metadata :

The <permissions> tag defines ACL's :

Possible values for the actionUri tag :

read
write
write-acl
read-acl
all

Possible values for the subjectUri tag :

all : all of the users
authenticated : authenticated user
unauthenticated : unauthenticated user
self : // do not use this subject
owner : user owner
/users/john : a user
/roles/admin : a group

7.5.4.2.2. Examples

7.5.4.2.2.1. Creating a simple space without metadata nor permissions

Template file

<!-- this file will not be given in argument -->

Program call

createSpace -path="/files/ESUP_documents"
              -name="WebDAVServer_documents"

7.5.4.2.2.2. Creating a simple space with metadata and permissions

Template file

<properties>
    <property name="displayname" value="WebDAV_server-Rennes1" />
</properties>
<permissions>
    <permission subjectUri="/users/tbellemb" actionUri="all" negative="false" />
    <permission subjectUri="/roles/ESUPGroup" actionUri="/actions/read" negative="false" />
    <permission subjectUri="all" actionUri="all" negative="true" />
</permissions>

Program call

createSpace -path="/files/ESUP_documents"
              -name="WebDAVServer_documents"
              -templateFile="/usr/local/src/templates/WebDAV_server-Rennes1_TEMPLATE.xml"

7.5.4.2.2.3. Creating a series of homedirs with metadata and permissions

Template file

<properties>
    <property name="owner" namespace="DAV:" value="{0}" protected=true />
</properties>
<permissions>
    <permission subjectUri="/roles/local/root" actionUri="all" negative="false" />
    <permission subjectUri="/users/{0}" actionUri="all" negative="false" />
    <permission subjectUri="all" actionUri="all" negative="true" />
</permissions>

Program call

createSpace -path="/files"
              -ldap="(|(&(type=pers)(department=123))(uid=55*))"
              -ldapAttribute="uid"
              -templateFile="/usr/local/src/templates/homedirs.xml"
              -regexp="^(/files)/.*:^(.).*:^/files/(.).*:^(.).*:^/files/(..).*:^(.).*:^/files/(.*)"
              -regexpSeparator=":" -forceSetProperties="true"

Consequences of this command :

7.5.4.2.2.4. Creating an inJAC space

Template file

<properties>
    <property name="managers" namespace="INJAC:" value="%3Cmanagers%3E%3Cmanager+type%3D%22user%22+key%3D%22ycolmant%22+displayName%3D%22Yohan+Colmant%22%2F%3E%3C%2Fmanagers%3E" type="" protected="false">
    <property name="injac-type" namespace="INJAC:" value="space" type="" protected="false">
</properties>
<permissions>
    <permission subjectUri="/users/slide.rootUser" actionUri="all" negative="false" />
    <permission subjectUri="all" actionUri="read" negative="false" />
    <permission subjectUri="all" actionUri="all" negative="true" />
</permissions>

Program call

createSpace -path="/files/injac"
              -name="myInjacSpace"
              -templateFile="/usr/local/src/templates/myInjacSpace.xml"

7.6. In case of problems...

Follow the installation recommandations ;-)

7.7. The ESUP storage channel (V4.2 and higher)

The v4.2 storage channel requires to set specific permissions and metadata on homedirs. More precisely, the channels relies on the owner metadata to manage permissions. Whether you already have or not homedirs on you WebDAV server, you can use the createSpace command with the -forceSetProperties parameter set to true to set right properties and permissions. Use the following pattern :

<properties>
    <property name="owner" namespace="DAV:" value="{0}" protected=true />
</properties>
<permissions>
    <permission subjectUri="/roles/local/root" actionUri="all" negative="false" />
    <permission subjectUri="/users/{0}" actionUri="all" negative="false" />
    <permission subjectUri="all" actionUri="all" negative="true" />
</permissions>

7.8. Links in this page