[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