pnever 2004/02/23 06:00:29
Modified: src/doc project.xml
Added: src/doc howto-deltav.xml howto-bind.xml howto-acl.xml
Log:
Added docu (Administrator's Guide) for DeltaV, ACL and binding
Revision Changes Path
1.28 +4 -1 jakarta-slide/src/doc/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-slide/src/doc/project.xml,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- project.xml 19 Feb 2004 13:55:33 -0000 1.27
+++ project.xml 23 Feb 2004 14:00:29 -0000 1.28
@@ -30,8 +30,11 @@
<item name="Configuration" href="conf-lib.html"/>
<item name="Tomcat Bundle" href="howto-tomcat.html"/>
<!-- This is very valuable stuff, but unfortunately does not fit Slide 2.0.
Comment it out for now -->
- <!--item name="Understanding Domain.xml" href="config_file.html"/-->
+ <!--item name="Understanding Domain.xml" href="config_file.html"/-->
<item name="J2EE Integration" href="howto-j2eestore.html"/>
+ <item name="Security" href="howto-acl.html"/>
+ <item name="Version Control" href="howto-deltav.html"/>
+ <item name="Binding" href="howto-bind.html"/>
</menu>
<menu name="Programmer's Corner">
<item name="Getting Started using Eclipse" href="getting-started.html"/>
1.1 jakarta-slide/src/doc/howto-deltav.xml
Index: howto-deltav.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Peter Nevermann</author>
<title>DeltaV Howto</title>
</properties>
<body>
<section name="Introduction">
<p>
Slide supports DeltaV (version control) according to the <a
href="http://webdav.org/deltav";>WebDAV DeltaV specification</a>.
</p>
</section>
<section name="Enabling or disabling version control">
<p>
By default, version control is enabled in Slide.
</p>
<p>
To disable version control, search for a configuration file named
<i>slide.properties</i> in the classpath
(if not there, you can create a new one at e.g.
$CATALINA_HOME/common/classes)
and set or add:
<pre>org.apache.slide.versioncontrol=false</pre>
</p>
</section>
<section name="Other parameters (Domain.xml)">
<p>
There are some more global parameters in the Slide configuration file
<i>Domain.xml</i>, which influence the version control
behavior of the server.
</p>
<p>
<font color="red"><b>IMPORTANT NOTE:</b></font><br/>Under no
circumstances the values of the following three parameters should be changed
while there are any stores configured or data exists for any store, as
no migration of the data will take place:<br/>
<b>historypath</b>, <b>workspacepath</b>, <b>workingresourcepath</b>.
</p>
<ul>
<li>
<i>historypath</i><br/> (xpath: <font color="blue"><code>/slide/[EMAIL
PROTECTED]"historypath"]</code></font>):<br/>
Specifies a Slide path which determines the location where this DeltaV
server stores history data.<br/>
Default value is <code>/history</code>.
</li>
<li>
<i>workspacepath</i><br/> (xpath: <font color="blue"><code>/slide/[EMAIL
PROTECTED]"workspacepath"]</code></font>):<br/>
Specifies a Slide path which determines the location where this DeltaV
server allows workspaces to reside.<br/>
Default value is <code>/workspace</code>.
</li>
<li>
<i>workingresourcepath</i><br/> (xpath: <font
color="blue"><code>/slide/[EMAIL PROTECTED]"workingresourcepath"]</code></font>):<br/>
Specifies a Slide path which determines the location where this DeltaV
server stores working resources.<br/>
Default value is <code>/workingresource</code>.
</li>
<li>
<i>versioncontrol-exclude</i><br/> (xpath: <font
color="blue"><code>/slide/[EMAIL
PROTECTED]"versioncontrol-exclude"]</code></font>):<br/>
Specifies a Slide path which determines resources which are excluded
from version-control.<br/>
Default value is <code>""</code>.
</li>
<li>
<i>auto-version-control</i><br/> (xpath: <font
color="blue"><code>/slide/[EMAIL PROTECTED]"auto-version-control"]</code></font>):<br/>
Indicates whether newly created resources are to be set under
version-control automatically.<br/>
Default value is <code>false</code>.
</li>
<li>
<i>auto-version</i><br/> (xpath: <font color="blue"><code>/slide/[EMAIL
PROTECTED]"auto-version"]</code></font>):<br/>
Specifies the default initial value of the <i>DAV:auto-version</i>
property for newly created version controlled resources.
For the complete list the possible values refer to section 3.2.2 of the
<a href="http://ietf.org/rfc/rfc3253.txt";>DeltaV specification</a>.<br/>
Default value is <code>checkout-checkin</code>.
</li>
<li>
<i>checkout-fork</i><br/> (xpath: <font color="blue"><code>/slide/[EMAIL
PROTECTED]"checkout-fork"]</code></font>):<br/>
Specifies the default initial value of the <i>DAV:checkout-fork</i>
property for newly created version resources.
For the complete list the possible values refer to section 4.1.1 of the
<a href="http://ietf.org/rfc/rfc3253.txt";>DeltaV specification</a>.<br/>
Default value is <code>forbidden</code>.
</li>
<li>
<i>checkin-fork</i><br/> (xpath: <font color="blue"><code>/slide/[EMAIL
PROTECTED]"checkin-fork"]</code></font>):<br/>
Specifies the default initial value of the <i>DAV:checkin-fork</i>
property for newly created version resources.
For the complete list the possible values refer to section 4.1.2 of the
<a href="http://ietf.org/rfc/rfc3253.txt";>DeltaV specification</a>.<br/>
Default value is <code>forbidden</code>.
</li>
</ul>
</section>
<section name="More parameters (web.xml)">
<p>
There exist some servlet init parameters in the webapp deployment
descriptor, i.e. <code>WEB-INF/web.xml</code>
in the webapp directory, which influence the version control behavior of
the server at the WebDAV level.
</p>
<ul>
<li>
<i>extendedAllprop</i><br/> (xpath: <font
color="blue"><code>/web-app/servlet/init-param[param-name="extendedAllprop"]</code></font>):<br/>
According to WebDAV DeltaV, ACL and Binding specifications,
a DAV:allprop PROPFIND should <b>not</b> return any of the properties
defined
in any of those documents.
For testing purposes, the specified behaviour can be disabled by
setting this parameter "true".
</li>
</ul>
<p>
</p>
</section>
</body>
</document>
1.1 jakarta-slide/src/doc/howto-bind.xml
Index: howto-bind.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Peter Nevermann</author>
<title>Binding Howto</title>
</properties>
<body>
<section name="Introduction">
<p>
Slide supports binding according to draft 2.1 of the <a
href="http://webdav.org/bind";>WebDAV BIND specification</a>.
It allows multiple URIs to be mapped to the same resource.
</p>
</section>
<section name="Enabling binding">
<p>
Enabling binding for a store is simple. It is done by referencing the
<i>BindingStore</i> implementation
through the classname attribute of the store element when configuring
the store in Domain.xml:
<pre>
<store name="mystore" classname="org.apache.slide.store.BindingStore">
<nodestore classname=...>
...
</nodestore>
...
</store>
</pre>
<font color="red"><b>IMPORTANT NOTE:</b></font><br/>Under no
circumstances the binding configuration of a store should be changed from
disabled to enabled, or vice-versa, while the store contains data, as no
migration of the data will take place!
</p>
</section>
<section name="Some parameters (web.xml)">
<p>
There exist some servlet init parameters in the webapp deployment
descriptor, i.e. <code>WEB-INF/web.xml</code>
in the webapp directory, which influence the binding behavior of the
server at the WebDAV level.
</p>
<ul>
<li>
<i>extendedAllprop</i><br/> (xpath: <font
color="blue"><code>/web-app/servlet/init-param[param-name="extendedAllprop"]</code></font>):<br/>
According to WebDAV DeltaV, ACL and Binding specifications,
a DAV:allprop PROPFIND should <b>not</b> return any of the properties
defined
in any of those documents.
For testing purposes, the specified behaviour can be disabled by
setting this parameter "true".
</li>
</ul>
<p>
</p>
</section>
</body>
</document>
1.1 jakarta-slide/src/doc/howto-acl.xml
Index: howto-acl.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Peter Nevermann</author>
<title>Security Howto</title>
</properties>
<body>
<section name="Introduction">
<p>
Slide supports ACL (access control) according to draft 12 of the <a
href="http://webdav.org/acl";>WebDAV ACL specification</a>.
</p>
<p>
By default, when running inside Tomcat, authentication for the WebDAV
servlet is controlled by the realm
<code>wrappers.catalina.SlideRealm</code>
which accesses user names and passwords directly from the Slide
namespace at <code>/slide/users</code>.
</p>
<p>
In Slide, authentication and authorization (access control) can be en-
or disabled independently from each other.
</p>
</section>
<section name="Enabling or disabling authentication ">
<p>
By default, authentication is enabled in Slide.
</p>
<p>
To disable authentication, open the webapp deployment descriptor, i.e.
<code>WEB-INF/web.xml</code> in the webapp directory,
and uncomment the two elements given by the xpath expressions
<font color="blue"><code>/web-app/security-constraint</code></font> and
<font color="blue"><code>/web-app/login-config</code></font>:
<pre><font color="gray"><b><!--</b>
<security-constraint>
<web-resource-collection>
<web-resource-name>DAV resource</web-resource-name>
<url-pattern>/*</url-pattern>
<http-method>COPY</http-method>
[...]
<http-method>REBIND</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>root</role-name>
<role-name>guest</role-name>
<role-name>user</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>Slide DAV Server</realm-name>
</login-config>
<b>--></b></font>
</pre>
</p>
</section>
<section name="Enabling or disabling authorization (access control)">
<p>
By default, access control is enabled in Slide. If authentication is
disabled (see above), the current user is "unauthenticated"
and he/she has all permissions granted to DAV:unauthenticated.
</p>
<p>
To disable access control, search for a configuration file named
<i>slide.properties</i> in the classpath
(if not there, you can create a new one at e.g.
$CATALINA_HOME/common/classes)
and set or add:
<pre>org.apache.slide.security=false</pre>
</p>
</section>
<section name="Other parameters (Domain.xml)">
<p>
There are some other namespace-specific parameters in the Slide
configuration file <i>Domain.xml</i>, which
influence the access control behavior of the server.
</p>
<ul>
<li>
<i>acl_semantics</i><br/> (xpath: <font
color="blue"><code>/slide/namespace/configuration/[EMAIL
PROTECTED]"acl_semantics"]</code></font>):<br/>
Class name of the access control implementation. Default value is
<i>org.apache.slide.security.ACLSecurityImpl</i>.
Allows to plug-in a customized security implementation.
</li>
<li>
<i>acl_inheritance_type</i><br/> (xpath: <font
color="blue"><code>/slide/namespace/configuration/[EMAIL
PROTECTED]"acl_inheritance_type"]</code></font>):<br/>
Controls inheritance of ACEs over the namespace hierarchy.
Can be one of <i>none</i> (no inheritance takes place), <i>root</i>
(ACEs are inherited only from the root node),
<i>path</i> (ACEs are inherited over the URI path) or <i>full</i> (ACEs
are inherited over all available parent
bindings). Default value is <i>path</i>, <i>full</i> is not yet
implemented.
</li>
<li>
<i>nested_roles_maxdepth</i><br/> (xpath: <font
color="blue"><code>/slide/namespace/configuration/[EMAIL
PROTECTED]"nested_roles_maxdepth"]</code></font>):<br/>
Defines the max. depth of nested roles/groups hierarchies. Default value
is 0 (meaning no nesting). Value 1 means one sublevel, and so forth.
</li>
</ul>
</section>
<section name="More parameters (web.xml)">
<p>
There exist some servlet init parameters in the webapp deployment
descriptor, i.e. <code>WEB-INF/web.xml</code>
in the webapp directory, which influence the access control behavior of
the server at the WebDAV level.
</p>
<ul>
<li>
<i>extendedAllprop</i><br/> (xpath: <font
color="blue"><code>/web-app/servlet/init-param[param-name="extendedAllprop"]</code></font>):<br/>
According to WebDAV DeltaV, ACL and Binding specifications,
a DAV:allprop PROPFIND should <b>not</b> return any of the properties
defined
in any of those documents.
For testing purposes, the specified behaviour can be disabled by
setting this parameter "true".
</li>
<li>
<i>lockdiscoveryIncludesPrincipalURL</i><br/> (xpath: <font
color="blue"><code>/web-app/servlet/init-param[param-name="lockdiscoveryIncludesPrincipalURL"]</code></font>):<br/>
As proposed on February 08, 2003 by Lisa Dusseault in
[EMAIL PROTECTED], the DAV:lockdiscovery property should
include an element DAV:principal-URL with the semantics of the
WebDAV/ACL specification. This feature can be switched-off in case
of interoperability problems.
</li>
</ul>
<p>
</p>
</section>
<section name="Creation and maintenance principal resources (users,
roles/groups) through WebDAV">
<p>
Although the creation and maintenance of principal resources (users,
roles/groups) is out of scope of the WebDAV/ACL
specification, in Slide it is currently possible through a proprietary
extension to the MKCOL method, provided the
<i>SlideRealm</i> (<code>wrappers.catalina.SlideRealm</code>) is active.
</p>
<p>
Resources created by MKCOL at the locations specified by the parameters:
<li><i>userspath</i> (xpath: <font
color="blue"><code>/slide/namespace/configuration/userspath</code></font>,</li>
<li><i>groupspath</i> (xpath: <font
color="blue"><code>/slide/namespace/configuration/groupspath</code></font>), or</li>
<li><i>rolespath</i> (xpath: <font
color="blue"><code>/slide/namespace/configuration/rolespath</code></font>)</li>
<br/>
automatically become principals,
i.e. the property <i>DAV:resourcetype</i> automatically will contain the
<i>DAV:principal</i> element.
</p>
<p>
To set the password of a user, issue a PROPPATCH request setting the
<i>password</i> property (namespace of the property:
<i>http://jakarta.apache.org/slide/</i>).
</p>
<p>
To associate users to a role/group, issue a PROPPATCH request setting
the <i>DAV:group-member-set</i> property.<br/>
<b><font color="red">NOTE:</font></b> to add a user(s) to a role/group,
the value of the <i>DAV:group-member-set</i> property must
list <b>all</b> members of the role/group, not just the user(s) being
added.
</p>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
