{panel:bgColor=#F8F7EF} h1. ESUP WebDAV server *User guide* \\ Auteur : ([|http://]) {panel} {toc:style=disc\|indent=20px\|minLevel=1} h1. Introduction \\ The purpose of this document is to explain how to use the ESUP WebDAV server. In particular it focuses on the administration tool : ESUPWDServerManager. h1. 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\|media/ESUPWebDAV-eunis2006-extended-abstract.pdf\] to understand how quota are implemented on the ESUP WebDAV server. {info} About the ESUP storage channel : the v4.2 storage channel requires to use the ESUP WebDAV server V3.5 or higher and to have specific permissions and metadata set on homedirs. Please read carefully the section dealing with this topic both in this documentation and in the ESUP storage channel user guide. {info} h1. Pre-requisite \\ * an ESUP WebDAV server deployed and running h1. Naming conventions \\ * [package.home] : directory where the package is unzipped. * [deploy.home] : directory where the server is deployed. h1. User guide \\ h2. 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 h2. Changing the configuration \\ h3. Recommended method \\ Modify the [package.home]/esup-serveur-WebDav-3.5/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] * axis.trustedFilter.password h3. 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. h2. Running the tool \\ h3. 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. {info} Edit the run.bat or run.sh scripts (to specify paths). {info} {note} The run scripts copy (and overwrite) the [deploy.home]/ESUPWDServerManager-1.0/properties directory and the log4j.xml file in the execution directory ([deploy.home]/ESUPWDServerManager-1.0/build). {note} h3. Interactive mode \\ Execute the run.sh or run.bat script in the [deploy.home]/esup-serveur-WebDav-3.5/ESUPWDServerManager-1.0 directory : ./run.sh h3. Input command file mode \\ Execute the run.sh or run.bat script in the [deploy.home]/esup-serveur-WebDav-3.5/ESUPWDServerManager-1.0/build directory followed by the input file path: ./run.sh /data/ESUPStuff/commands.txt You will find commands.txt sample command file in the [deploy.home]/esup-serveur-WebDav-3.5/ESUPWDServerManager-1.0/properties directory : {code} # # 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 {code} h2. Commands overview \\ \!commandsOverview.png\!ESUPWDServerManager was made to work almost like a Unix shell, it means that you can navigate using {span:class=command}ls {span} and {span:class=command}cd {span} commands and create/delete directories with {span:class=command}mkdir {span} and {span:class=command}rmdir {span} 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 {span:class=command}connect {span} to connect to the ESUP WebDAV server. \\ The {span:class=command}help full {span} command gives the list and syntax of every command. \\ h2. Commands details \\ For a full command help type {span:class=command}help [commandName] {span} . \\ 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. h3. Basic commands \\ * {span:class=command}connect {span} : connects to the server * {span:class=command}quit {span} : leaves the program * {span:class=command}ls {span} : list current directory content * {span:class=command}cd {span} : changes current directory (relative or full path) * {span:class=command}menu {span} : displays the menu * {span:class=command}help {span} : displays the help (help full - help [commandName]) h3. Folder creation/deletion \\ * {span:class=command}mkdir {span} : creates a directory (relative or full path) * {span:class=command}rmdir {span} : deletes a directory (relative or full path) h3. Quota commands \\ * {span:class=command}treeinfo {span} [RC] : advanced ls command showing children and quota metadata of the current directory up to the given depth\- syntax : treeinfo [depth] \!treeInfo.png\!In the screenshot above the /files/quotas/samples/100k directory has a quota of 66500 + 33500 bytes = 100kb with 33500bytes used. * {span:class=command}getQUB {span} : displays the folder DAV:quota-used-bytes metadata - syntax getQUB ("fullPath") * {span:class=command}getQAB {span} : displays the folder DAV:quota-available-bytes metadata - syntax getQAB ("fullPath") * {span:class=command}getVR {span} : displays the folder ESUP:virtual-root metadata - syntax getVR ("fullPath") * {span:class=command}patchQUB {span} : changes the folder DAV:quota-used-bytes metadata - syntax patchQUB ("fullPath value) - You should not have to use this command given that when you set a quota on a folder the DAV:quota-used-bytes metadata can be automatically calculated. * {span:class=command}patchQAB {span} : changes the folder DAV:quota-available-bytes metadata - syntax patchQAB ("fullPath" value) * {span:class=command}setVR {span} [RC] : changes the folder ESUP:virtual-root metadata - automatically changes quota metadata of parent directories up to the root (or first virtual root) - syntax setVR ("fullPath" true\|false) * {span:class=command}setQuota {span} [RC] : changes the folder quota or quota of its children at a given depth. Can calculate the DAV:quota-used-bytes metadata if directories contain data. syntax setQuota ("fullPath" depth quota calculateQUB) - depth=0 means that you set the quota of the current directory - calculateQUB=true\|false\!setQuota.png\! h3. Space manager command \\ h4. Introduction \\ This new tool replaces the former "HomedirCreation" and "InjacSpacesCreation" tools. This is a generic tool to create folders and set permissions and metadata. h4. Syntax \\ {code} createSpace -path="spacePath" | -name="spaceName" or |_-ldap="ldapFilter" -ldapAttribute="uniqueLdapAttributeToRetrieve" (-regexp="regexp" -regexpSeparator="regexpSeparator" (-regexpPattern="regexpPattern")) (-templateFile="pathToTemplateFile") (-forceSetProperties="true|false") {code} \-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. \-regexpPattern="regexpPattern" Apply an additional transformation to "spaceName" or "uniqueLdapAttributeToRetrieve" before the regexp mechanism. Example: if uniqueLdapAttributeToRetrieve="uid" and for a user this uid value is "bourges" and regexpPattern=" {0}/foo" then regexp mechanism will work on "bourges/foo" string and not just "bourges" -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). h5. 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 : {code} <?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 > {code} {code} <properties> <property name="propertyName" (namespace="namespace") value="value" (type="type") /> <property ... /> ... </properties> <permissions> <permission subjectUri="subjectUri" actionUri="actionUri" negative="true|false" /> <permission ... /> ... </permissions> {code} The <properties> tag defines metadata : * name : property name - use only not protected property names except "owner" * namespace : property namespace - by default DAV: * value : property value * type : property type - by default null The <permissions> tag defines ACL's : * subjectUri : ACL principal * actionUri : action granted or denied * negative : if true then the action is denied - by default false Possible values for the actionUri tag : {code} read write write-acl read-acl all {code} Possible values for the subjectUri tag : {code} 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 {code} h5. Examples \\ h6. Creating a simple space without metadata nor permissions \\ Template file {code} <!-- this file will not be given in argument --> {code} Program call createSpace \-path="/files/ESUP_documents" \-name="WebDAVServer_documents"h6. Creating a simple space with metadata and permissions \\ Template file {code} <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> {code} Program call createSpace \-path="/files/ESUP_documents" \-name="WebDAVServer_documents" \-templateFile="/usr/local/src/templates/WebDAV_server-Rennes1_TEMPLATE.xml"h6. Creating a series of homedirs with metadata and permissions \\ Template file {code} <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> {code} 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 : * "uid" attributes matching the given LDAP filter are retrieved from the LDAP * The regexp is applied to each "uid" giving hashed paths like "t/tb/tbellemb" * The "path" is appended to each hashed path giving the final path like "/files/t/tb/tbellemb" {note}note that if a directory already exists, the pattern file will be applied according to the \-forceSetProperties parameter {note} h2. 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 {span:class=command}\-forceSetProperties {span} parameter set to true to set right properties and permissions. Use the following pattern : \\ {code} <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> {code} |