[CalendarServer-changes] [4667] CalendarServer/trunk/doc/Admin

source_changes at macosforge.org source_changes at macosforge.org
Thu Oct 29 13:30:04 PDT 2009


Revision: 4667
          http://trac.macosforge.org/projects/calendarserver/changeset/4667
Author:   wsanchez at apple.com
Date:     2009-10-29 13:30:00 -0700 (Thu, 29 Oct 2009)
Log Message:
-----------
New docs

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

Added: CalendarServer/trunk/doc/Admin/DirectoryService-XML.txt
===================================================================
--- CalendarServer/trunk/doc/Admin/DirectoryService-XML.txt	                        (rev 0)
+++ CalendarServer/trunk/doc/Admin/DirectoryService-XML.txt	2009-10-29 20:30:00 UTC (rev 4667)
@@ -0,0 +1,175 @@
+XML Directory Service
+=====================
+
+The XML directory service provides principal information that is read
+from an XML file.
+
+One advantage to this directory service implementation is that it does
+not require a networked directory server to be running somewhere,
+instead simply relying on a file.
+
+Configuring the Calendar Server
+-------------------------------
+
+The full name of the service is
+``twistedcaldav.directory.xmlfile.XMLDirectoryService`` and the
+service takes an ``xmlFile`` parameter which contains the name of the
+XML file to read principal information from.
+
+For example:
+
+::
+
+  <!--  XML File Directory Service -->
+  <key>DirectoryService</key>
+  <dict>
+    <key>type</key>
+    <string>twistedcaldav.directory.xmlfile.XMLDirectoryService</string>
+
+    <key>params</key>
+    <dict>
+      <key>xmlFile</key>
+      <string>/etc/caldavd/accounts.xml</string>
+    </dict>
+  </dict>
+
+The service re-reads the XML file if it's timestamp changes, so edits
+to the XML file do not require a server restart.
+
+Configuring Principals
+----------------------
+
+Principals are expressed in an XML document. The root element
+``accounts`` has an attribute ``realm`` which describes the
+authentication realm. It contains principal elements which in turn
+contain elements describing the principal. The element itself denotes
+the principal type.
+
+The principal types supported by the XML directory service are:
+
+users
+
+  Individual (typically human) users of the system. XML element: ``user``
+
+groups
+
+  Principals that contain other principals ("members"). Members can be
+  principals of any type, including other group principals.  XML
+  element: ``group``
+
+locations
+
+  Locations that can be scheduled. XML element: ``location``
+
+resources
+
+  Other resources (eg. projectors) which can be scheduled. XML
+  element: ``resource``
+
+Principal elements can contain the following elements which provide
+information about the principal:
+
+``uid``
+
+  The login identifier for the principal (ie. "username" or "short name").
+
+``guid``
+
+  A globally unique identifier for the principal. Must be a UUID
+  string that complies with `RFC 4122`_.
+
+  .. _RFC 4122: http://tools.ietf.org/html/rfc4122
+
+``password``
+
+  The principal's password in plain text.
+
+``name``
+
+  The principal's full name (or description).
+
+``members``
+
+  A list of uids for the principals which are members of the principal
+  being defined. Only group principals may have members. The
+  ``members`` element has ``member`` sub-elements used to specify each
+  member. The member element has a type attribute that defines the
+  principal type of the member (one of ``users``, ``groups``,
+  ``locations`` and ``resources``), and the text value inside the
+  ``member`` element is the corresponding uid of the principal being
+  referenced. Any principal may be a member of a group, including
+  other groups. One should avoid creating "loops" by having two groups
+  include each other.
+
+``cuaddr``
+
+  A "calendar user address" for the principal. Principals may have
+  multiple calendar user addresses, but a calendar user addresses must
+  be unique to one principal. A calendar user address must be a URI_.
+
+  .. _URI: http://tools.ietf.org/html/rfc2396
+
+  Note that calendar user addresses here supplement any calendar user
+  addresses that are assigned by the server based on other principal
+  information.
+  
+``disable-calendar``
+
+  When present, this element indicates that the principal is able to
+  login to the calendar server, but is not provided a calendar home
+  and therefore cannot do scheduling. This type of principal is
+  typically used to allow access to the calendars of other principals
+  or other data on the server. This element may only pecified for user
+  principals.
+
+``auto-schedule``
+
+  Indicates that the server will automatically process scheduling
+  messages for the corresponding principal. For example, when a
+  scheduling message arrives, if it does not conflict with an existing
+  meeting it will be automatically accepted into the principal's main
+  calendar; if it does conflict it will be automatically
+  declined. This element can only be defined on location and resource
+  principals.
+
+``proxies``
+
+  Contains a list of ``member`` elements that define which other
+  principals have read-write proxy access to the corresponding
+  principal's calendar data.
+
+An example:
+
+::
+
+  <?xml version="1.0" encoding="utf-8"?>
+  <accounts realm="Test Realm">
+    <user>
+      <uid>admin</uid>
+      <password>admin</password>
+      <name>Super User</name>
+    </user>
+    <user>
+      <uid>test</uid>
+      <password>test</password>
+      <name>Test User</name>
+      <cuaddr>mailto:testuser at example.com</cuaddr>
+    </user>
+    <group>
+      <uid>users</uid>
+      <password>users</password>
+      <name>Users Group</name>
+      <members>
+        <member type="users">test</member>
+      </members>
+    </group>
+    <location>
+      <uid>mercury</uid>
+      <password>mercury</password>
+      <name>Mecury Conference Room, Building 1, 2nd Floor</name>
+      <auto-schedule/>
+      <proxies>
+        <member type="users">test</member>
+      </proxies>
+    </location>
+  </accounts>


Property changes on: CalendarServer/trunk/doc/Admin/DirectoryService-XML.txt
___________________________________________________________________
Added: svn:mime-type
   + text/plain

Added: CalendarServer/trunk/doc/Admin/DirectoryServices.txt
===================================================================
--- CalendarServer/trunk/doc/Admin/DirectoryServices.txt	                        (rev 0)
+++ CalendarServer/trunk/doc/Admin/DirectoryServices.txt	2009-10-29 20:30:00 UTC (rev 4667)
@@ -0,0 +1,70 @@
+Directory Services
+==================
+
+The Calendar Server needs to be able to obtain information about the
+users, groups and resources ("principals") which access and/or have a
+presence on the server.
+
+About Principals
+----------------
+
+All principals have a "principal resource" on the server which
+represents the principal in the form of an HTTP resource. This is
+useful for obtaining information about a principal, such as the URL of
+the principal's calendar home, the principal's members and/or
+memberships, and so on. This information is exposed via WebDAV
+properties on the principal resource.
+
+Principals can be used to configure access controls for resources on
+the server by granting or denying various privileges to the principal.
+Privileges granted or denied to group principals are also granted or
+denied to all members of the group.
+
+Some principals (often, but not necessarily all) are also given a
+calendar home collection on the server, in which the principal may
+have one or more calendar collections, as well as special collections
+which allow the principals to schedule meetings with others, and so
+on.
+
+The Role of a Directory Service
+-------------------------------
+
+A "directory service" is simply an entity which contains information
+about principals.
+
+Directory services are interchangeable, which allows the server to
+obtain this information from a variety of data stores, such as
+configuration files or network directory systems like LDAP.
+
+Most directory services refer to principals as "records" in their
+databases. Internally, Calendar Server will map records from a
+directory service to WebDAV principals.
+
+A given directory service may classify records into "types" such as
+users, groups, resources, and so on. Calendar Server keeps this
+distinction, and some types are treated specially.
+
+For example, only user principals are allowed to authenticate with
+(log into) the server. Only group principals have members, and group
+principals do not have calendars.
+
+The directory service used by the server is configured in the
+``caldavd.plist`` file by specifying the directory service
+implementation to use, as well as its configuration options. Options
+are specified as a dictionary.
+
+The configuration syntax looks like this:
+
+::
+
+  <key>DirectoryService</key>
+  <dict>
+    <key>type</key>
+    <string>ExampleService</string>
+
+    <key>params</key>
+    <dict>
+      <key>option</key>
+      <string>value</string>
+    </dict>
+  </dict>


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


More information about the calendarserver-changes mailing list