[CalendarServer-changes] [4669] CalendarServer/trunk/doc/Admin/DirectoryService-Apache.txt

[source_changes at macosforge.org]

Revision: 4669
          http://trac.macosforge.org/projects/calendarserver/changeset/4669
Author:   wsanchez at apple.com
Date:     2009-10-29 14:26:08 -0700 (Thu, 29 Oct 2009)
Log Message:
-----------
New docs

Added Paths:
-----------
    CalendarServer/trunk/doc/Admin/DirectoryService-Apache.txt

Added: CalendarServer/trunk/doc/Admin/DirectoryService-Apache.txt
===================================================================
--- CalendarServer/trunk/doc/Admin/DirectoryService-Apache.txt	                        (rev 0)
+++ CalendarServer/trunk/doc/Admin/DirectoryService-Apache.txt	2009-10-29 21:26:08 UTC (rev 4669)
@@ -0,0 +1,112 @@
+Apache Directory Services
+=========================
+
+**WARNING:** *This directory service implementation is experimental,
+incomplete and not supported.*
+
+The Apache directory services provide principal information that is
+read from configuration files in the `same formats`_ as used by the
+`Apache HTTP server`_, allowing you to easily share user and group
+information with an Apache server.
+
+.. _same formats: http://httpd.apache.org/docs/2.3/howto/auth.html
+.. _Apache HTTP server: http://httpd.apache.org/
+
+The Apache directory services provide principal information for users
+and groups. They do not provide principal information for locations or
+resources.
+
+Configuring the Calendar Server
+-------------------------------
+
+The full name of the service is either
+``twistedcaldav.directory.apache.BasicDirectoryService`` or
+``twistedcaldav.directory.apache.DigestDirectoryService``. These
+services implement `basic and digest HTTP authentication`_,
+respectively.
+
+.. _basic and digest HTTP authentication: http://www.ietf.org/rfc/rfc2617.txt
+
+Both services take a ``userFile`` parameter which contains the name of
+the file to read user principal information from and an optional
+``groupFile`` parameter which contains the name of the file to read
+group principal information from.
+
+For example, if you are using digest:
+
+::
+
+  <!--  Apache-style Digest Directory Service -->
+  <key>DirectoryService</key>
+  <dict>
+    <key>type</key>
+    <string>twistedcaldav.directory.apache.DigestDirectoryService</string>
+  
+    <key>params</key>
+    <dict>
+      <key>userFile</key>
+      <string>conf/digest</string>
+      <key>groupFile</key>
+      <string>conf/group</string>
+    </dict>
+  </dict>
+
+The service re-reads the user and group files if either file's
+timestamp changes, so edits to the files do not require a server
+restart.
+
+Note that basic authentication is highly insecure because it sends
+password information in plain text over the network (where is may be
+intercepted) and should not be enabled on a server unless all
+connections are somehow secured by another means, such as by enabling
+SSL and disabling non-SSL connections.
+
+Configuring Principals
+----------------------
+
+In the case of ``BasicDirectoryService``, the user file must be in the
+form generated by the Apache ``htpasswd`` command; in the case of
+``DigestDirectoryService``, the user file must be in the form
+generated by the Apache ``htdigest`` command.
+
+Both user file formats contain a single entry per line, with fields
+separated by the colon (``:``) character. The basic format has two
+fields, one containing a user identifier and the second containing the
+user's password in the UNIX crypt format. The digest format has three
+fields: a user identifier, a realm name, and the user's hashed
+password.
+
+An example basic user file:
+
+::
+
+  wsanchez:Cytm0Bwm7CPJs
+  cdaboo:I.Ef5FJl5GVh2
+  dreid:LVhqAv4qSrYPs
+  lecroy:/7/5VDrkrLxY.
+
+And an example digest user file:
+
+::
+
+  wsanchez:Test:decbe233ab3d997cacc2fc058b19db8c
+  cdaboo:Test:61164bf3d607d072fe8a7ac420b24aac
+  dreid:Test:8ee67801004b2752f72b84e7064889a6
+  lecroy:Test:60d4feb424430953be045738041e51be
+
+The group file is in a similar format, with one entry of
+colon-separated field per line. Each line has two fields: a group
+identifier, and a comma- (``,``) separated list of user identifiers
+which identify the members of the group.
+
+And example group file:
+
+::
+
+  managers: lecroy
+  grunts: wsanchez, cdaboo, dreid
+  right_coast: cdaboo
+  left_coast: wsanchez, dreid, lecroy
+
+The user files should be edited using the ``htpasswd`` and
+``htdigest`` tools. The group file is typically edited by hand.


Property changes on: CalendarServer/trunk/doc/Admin/DirectoryService-Apache.txt
___________________________________________________________________
Added: svn:mime-type
   + text/plain
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20091029/072b0c17/attachment-0001.html>