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

source_changes at macosforge.org source_changes at macosforge.org
Sat Sep 22 07:13:18 PDT 2012


Revision: 9837
          http://trac.calendarserver.org//changeset/9837
Author:   dre at apple.com
Date:     2012-09-22 07:13:18 -0700 (Sat, 22 Sep 2012)
Log Message:
-----------
Rename files for RST linkage

Added Paths:
-----------
    CalendarServer/trunk/doc/Admin/DirectoryService-Apache.rst
    CalendarServer/trunk/doc/Admin/DirectoryService-OpenDirectory.rst
    CalendarServer/trunk/doc/Admin/DirectoryService-XML.rst
    CalendarServer/trunk/doc/Admin/DirectoryServices.rst
    CalendarServer/trunk/doc/Admin/ExtendedLogItems.rst

Copied: CalendarServer/trunk/doc/Admin/DirectoryService-Apache.rst (from rev 9835, CalendarServer/trunk/doc/Admin/DirectoryService-Apache.txt)
===================================================================
--- CalendarServer/trunk/doc/Admin/DirectoryService-Apache.rst	                        (rev 0)
+++ CalendarServer/trunk/doc/Admin/DirectoryService-Apache.rst	2012-09-22 14:13:18 UTC (rev 9837)
@@ -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.

Copied: CalendarServer/trunk/doc/Admin/DirectoryService-OpenDirectory.rst (from rev 9835, CalendarServer/trunk/doc/Admin/DirectoryService-OpenDirectory.txt)
===================================================================
--- CalendarServer/trunk/doc/Admin/DirectoryService-OpenDirectory.rst	                        (rev 0)
+++ CalendarServer/trunk/doc/Admin/DirectoryService-OpenDirectory.rst	2012-09-22 14:13:18 UTC (rev 9837)
@@ -0,0 +1,44 @@
+Open Directory Service
+======================
+
+The Open Directory directory service provides principal information
+that is obtained using Apple's Open Directory service.
+
+Open Directory provides principal information for users, groups,
+locations, and resources.
+
+For more information about configuring Open Directory and running Open
+Directory services, see Apple's `Open Directory Administration`_
+document.
+
+.. _Open Directory Administration: http://images.apple.com/server/macosx/docs/Open_Directory_Admin_v10.6.pdf
+
+Configuring the Calendar Server
+-------------------------------
+
+The full name of the service is
+``twistedcaldav.directory.appleopendirectory.OpenDirectoryService``
+and the service takes a ``node`` parameter which contains the name of
+the directory node to bind to.
+
+For example:
+
+::
+
+  <!-- Open Directory Service -->
+  <key>DirectoryService</key>
+  <dict>
+    <key>type</key>
+    <string>twistedcaldav.directory.appleopendirectory.OpenDirectoryService</string>
+  
+    <key>params</key>
+    <dict>
+      <key>node</key>
+      <string>/Search</string>
+    </dict>
+  </dict>
+
+The special Open Directory node ``/Search`` causes the server to use
+the default directory search path that the host system the server is
+running on is configured to use. To bind to a specific LDAP service, a
+node in the form ``/LDAPv3/ldapserver.example.com`` may be specified.

Copied: CalendarServer/trunk/doc/Admin/DirectoryService-XML.rst (from rev 9835, CalendarServer/trunk/doc/Admin/DirectoryService-XML.txt)
===================================================================
--- CalendarServer/trunk/doc/Admin/DirectoryService-XML.rst	                        (rev 0)
+++ CalendarServer/trunk/doc/Admin/DirectoryService-XML.rst	2012-09-22 14:13:18 UTC (rev 9837)
@@ -0,0 +1,159 @@
+XML Directory Service
+=====================
+
+The XML directory service provides principal information that is read
+from an XML file.
+
+The XML file provides principal information for users, groups,
+locations, and resources.
+
+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
+(``user``, ``group``, ``location``, ``resource``) denotes the
+principal type.
+
+Principal elements can contain the following elements which provide
+information about the principal:
+
+``uid``
+
+  The login identifier for the principal (ie. "user name" 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>

Copied: CalendarServer/trunk/doc/Admin/DirectoryServices.rst (from rev 9835, CalendarServer/trunk/doc/Admin/DirectoryServices.txt)
===================================================================
--- CalendarServer/trunk/doc/Admin/DirectoryServices.rst	                        (rev 0)
+++ CalendarServer/trunk/doc/Admin/DirectoryServices.rst	2012-09-22 14:13:18 UTC (rev 9837)
@@ -0,0 +1,93 @@
+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.
+
+Principal types commonly provided by directory services include:
+
+users
+
+  Individual (typically human) users of the system.
+
+groups
+
+  Principals that contain other principals ("members"). Members can be
+  principals of any type, including other group principals.
+
+locations
+
+  Locations that can be scheduled.
+
+resources
+
+  Other resources (eg. projectors) which can be scheduled.
+
+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.
+
+
+Configuration
+=============
+
+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>

Copied: CalendarServer/trunk/doc/Admin/ExtendedLogItems.rst (from rev 9835, CalendarServer/trunk/doc/Admin/ExtendedLogItems.txt)
===================================================================
--- CalendarServer/trunk/doc/Admin/ExtendedLogItems.rst	                        (rev 0)
+++ CalendarServer/trunk/doc/Admin/ExtendedLogItems.rst	2012-09-22 14:13:18 UTC (rev 9837)
@@ -0,0 +1,110 @@
+Apache-style Access Log Extensions
+==================================
+
+Calendar Server extends the Apache log file format it uses by:
+
+ * Adding a "sub-method" to the HTTP method field.
+ * Adding key-value pairs at the end of log lines.
+
+The sub-method is adding by appending the name of the sub-method in
+parentheses to the original HTTP request method.  This is used to
+clarify what operation is going on for HTTP methods that are commonly
+used to tunnel other operations, such as ``POST`` and ``REPORT``.  For
+example, CalDAV uses ``POST`` for free/busy lookups, and ``REPORT``
+can be used to make any sort of query.
+
+Key-value pairs are used to provide additional details about the
+request.  They are added to the end of the line as new fields in the
+form ``key=value``.
+
+These keys are always emitted:
+
+  ``i``
+
+    the port number of the server instance emitting the log
+
+  ``t``
+
+    the amount of time spent processing the request (in milliseconds).
+
+  ``or``
+
+    the number of outstanding requests enqueued for the server
+    instance emitting the log entry.
+
+Keys that may be emitted depending on the client request and server
+response include:
+
+  ``rcount``
+
+    the number of resources specified in a ``MULTIGET`` request.
+
+  ``responses``
+
+    the number of responses included in a ``multi-status`` response to
+    a ``PROPFIND`` request or a CalDAV ``calendar-query`` request.
+
+  ``recipients``
+
+    the number of recipients in a CalDAV scheduling request via
+    ``POST`` (which are typically only free/busy requests).
+
+  ``itip.requests``
+
+    the number of attendees in a scheduling operation triggered by an
+    Organizer.
+
+  ``itip.refreshes``
+
+    the number of attendee refreshes completed after a scheduling
+    operation.
+
+  ``itip.auto``
+
+    the number of auto-accept attendees specified
+
+  ``itip.reply``
+
+    Either ``reply`` or ``cancel`` depending on...???
+
+  ``fwd``
+
+    the value of the X-Forwarded-For header, if present
+
+In the following example, we see a ``CalDAV:calendar-multiget``
+``REPORT`` for 32 resources in a user's calendar, which was handled by
+instance ``8459`` in 183.0ms, with one outstanding request (the one
+being logged):
+
+::
+
+  17.108.160.37 - scastillo [15/Sep/2009:20:10:23 +0000] "REPORT(CalDAV:calendar-multiget) /calendars/__uids__/B8CE9430-965B-11DE-B626-EC2E9DB52B69/calendar/ HTTP/1.1" 207 149285 "-" "DAVKit/4.0 (729); CalendarStore/4.0 (965); iCal/4.0 (1362); Mac OS X/10.6.1 (10B504)" i=8459 t=183.0 or=1 rcount=32
+
+
+
+**Fine-grained request time logging**
+
+If the configuration key EnableExtendedTimingAccessLog is set to true, additional key-value pairs will be logged with each request. The overall request time "t" is broken into four phases, and the elapsed time for each phase is logged. The new keys representing the four request phases are:
+
+  ``t-req-proc``
+
+    time elapsed from when a request object is created up until renderHTTP is about to be called.
+    This is the overhead of parsing the request headers and locating the target resource.
+
+  ``t-resp-gen``
+
+    time elapsed from t-req-proc up until the response is ready to write
+
+  ``t-resp-wr``
+
+    time elapsed from t-resp-gen up until response is written
+
+  ``t-log``
+
+    time from t-resp-wr up until log entry is ready to write to master
+
+A sample log line with EnableExtendedTimingAccessLog enabled is shown below:
+
+::
+
+  17.209.103.42 - wsanchez [24/Jul/2012:17:51:29 +0000] "REPORT(CalDAV:calendar-multiget) /calendars/__uids__/F114CA1D-295F-42A5-A5BD-D1A1B19FC049/60E68E32-4C87-4E63-9BF2-12A25E8F2623/ HTTP/1.1" 207 114349 "-" "CalendarStore/5.0.2 (1166); iCal/5.0.2 (1571); Mac OS X/10.7.3 (11D50d)" i=7 or=1 t=764.7 t-req-proc=4.8 t-resp-gen=754.5 t-resp-wr=5.1 t-log=0.2 rcount=2
\ No newline at end of file
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20120922/e910e085/attachment-0001.html>


More information about the calendarserver-changes mailing list