You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by ie...@apache.org on 2012/05/14 10:45:06 UTC

svn commit: r1338063 [2/7] - in /james/site-cms/trunk: ./ content/ content/resources/ content/resources/css/ content/resources/images/ content/resources/images/conf/ content/resources/images/database/ content/resources/images/dns-mx/ content/resources/...

Added: james/site-cms/trunk/content/xdoc/config-fetchmail.xml
URL: http://svn.apache.org/viewvc/james/site-cms/trunk/content/xdoc/config-fetchmail.xml?rev=1338063&view=auto
==============================================================================
--- james/site-cms/trunk/content/xdoc/config-fetchmail.xml (added)
+++ james/site-cms/trunk/content/xdoc/config-fetchmail.xml Mon May 14 08:45:02 2012
@@ -0,0 +1,1045 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.    
+-->
+<document>
+
+ <properties>
+  <title>Apache James Server 3 - Fetchmail Configuration</title>
+ </properties>
+
+<body>
+
+  <section name="Fetchmail Configuration">
+
+    <p>Consult <a href="https://svn.apache.org/repos/asf/james/app/tags/apache-james-3.0-beta4/src/main/resources/fetchmail-template.conf">fetchmail-template.conf</a> in SVN to get some examples and hints.</p>
+
+    <p>Fetchmail acts as a gateway between an external message store such as an IMAP
+    or POP3 server and James. Mail is fetched from the external message store and
+    injected into the James input spool.</p>
+    
+    <p>Fetchmail  is useful when delivery via standard SMTP is not an option, as a
+    means of consolidating mail delivered to several external accounts into a single
+    James account, or to apply the mail processing capabilities of James to mail 
+    stored in an external message store.</p>
+    
+    <p>Fetchmail has several configuration options that control the fetching and 
+    filtering of mail injected into the James input spool. Once there, James' 
+    flexible mail processing engine can be used to further process the mail, just as
+    if it had been delivered via standard SMTP.</p>
+    
+    <p>
+    <a href="#How_Fetchmail_Works">How Fetchmail Works</a><br/>
+    <a href="#Fetchmail_Configuration_Parameters">Fetchmail Configuration Parameters</a><br/>
+    <a href="#Fetchmail_Examples">Fetchmail Examples</a><br/>
+    <a href="#Fetchmail_Caveats">Fetchmail Caveats</a><br/>
+    <a href="#Fetchmail_Gmail">Fetchmail Gmail</a>
+    </p>
+    
+  </section>
+  
+  <section name="How Fetchmail Works">
+  
+    <p>Mail is delivered by periodically running fetch tasks that read messages from
+    an external message store and injects them into the James input spool. Fetch 
+    tasks run concurrently.</p>
+    
+    <p>A set of filters applies to each fetch task. Each filter provides the ability
+    to reject a message that matches the filter criteria. Rejected messages are not
+    injected into the James input spool; they are either marked as seen or deleted.
+    When a filter is configured to accept a message that matches its criteria, 
+    messages are marked with a MailAttribute. This MailAttribute can be detected 
+    within the James matcher/mailet chain, allowing further processing as 
+    required.</p>
+    
+    <p>Each fetch task is associated with a single host server. Accounts are defined
+    to the fetch task for each mailbox on the server from which mail is to be
+    fetched. Accounts run consecutively.</p>
+    
+    <p>Optionally, the fetch task can be configured with an &lt;alllocal&gt; Account that
+    generates an Account entry for each user defined in the James user repository.
+    This removes the requirement to manually add or remove Account entries to the 
+    Fetchmail configuration each time a James user is added or removed. Currently 
+    this is only useful if the server supports virtual mailboxes that allow the same
+    password to apply to all users within a domain.</p>
+    
+    <p>Accounts can be configured to deliver all mail for an Account to a specified
+    recipient or to deduce the intended recipient from the mail headers.</p>
+    
+    <p>Accounts are normally configured to deliver all mail for an Account to a 
+    specified recipient, ignoring the recipient in the mail headers. This works well
+    in the majority of cases where a mailbox is guaranteed to contain mail for a sole
+    mailbox recipient.</p>
+    
+    <p>Accounts are configured to deduce the intended recipient from the mail headers
+    when a mailbox contains mail for several users, typically all users in a domain.
+    Used alone, this is not foolproof as there are circumstances when a single unique
+    recipient cannot be deduced from the mail headers alone. Used in conjunction with
+    an appropriately configured &lt;alllocal&gt; account, it is always possible to deduce 
+    the intended recipient when the recipient is a James user.</p>
+  </section>
+  
+  <section name="Fetchmail Configuration Parameters">
+  
+    <p>The Fetchmail configuration parameters are part of the James configuration, 
+    whose base file is <code>fetchmail.xml</code>. For clarity and flexibility, the 
+    Fetchmail configuration parameters are stored in the file 
+    <code>james-Fetchmail.xml</code>, which is referenced within 
+    <code>fetchmail.xml</code>.</p>
+    
+    <p>The configuration parameters are described below.</p>
+    
+    <subsection name="Fetchmail">
+    <p>The configuration block delimited by the <strong>Fetchmail</strong> tag 
+    controls Fetchmail.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>enabled</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, the fetch tasks will be run periodically. If &quot;false&quot;, 
+    no fetch tasks will be run. The default is &quot;false&quot;.</dd>
+    </dl>
+    </p>
+    
+    <p>The tag has these child tags (minimum cardinality, maximum cardinality):
+    <ul>
+    <li><strong><a href="#fetch">fetch</a></strong> (0, *)</li>
+    </ul>
+    </p>
+    
+    <p>
+    <source>
+    &lt;Fetchmail enabled=&quot;true&quot;&gt;
+    ...
+    &lt;/Fetchmail&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="fetch">
+    <p>The <strong>fetch</strong> tag defines a fetch task to be run 
+    periodically. Fetch tasks run concurrently.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>name</strong></dt>
+    <dd>A string uniquely identifying the fetch task.</dd>
+    </dl>
+    </p>
+    
+    <p>The tag has these child tags (minimum cardinality, maximum cardinality):
+    <ul>
+      <li><strong><a href="#accounts">accounts</a></strong> (1, 1)</li>
+      <li><strong><a href="#blacklist">blacklist</a></strong> (1, 1)</li>
+      <li><strong><a href="#defaultdomain">defaultdomain</a></strong> (0, 1)</li>
+      <li><strong><a href="#fetchall">fetchall</a></strong> (1, 1)</li>
+      <li><strong><a href="#fetched">fetched</a></strong> (1, 1)</li>
+      <li><strong><a href="#host">host</a></strong> (1, 1)</li>
+      <li><strong><a href="#interval">interval</a></strong> (1, 1)</li>
+      <li><strong><a href="#javaMailFolderName">javaMailFolderName</a></strong> (1, 1)</li>
+      <li><strong><a href="#javaMailProperties">javaMailProperties</a></strong> (0, 1)</li>
+      <li><strong><a href="#javaMailProviderName">javaMailProviderName</a></strong> (1, 1)</li>
+      <li><strong><a href="#maxmessagesize">maxmessagesize</a></strong> (0, 1)</li>
+      <li><strong><a href="#recipientnotfound">recipientnotfound</a></strong> (1, 1)</li>
+      <li><strong><a href="#recursesubfolders">recursesubfolders</a></strong> (1, 1)</li>
+      <li><strong><a href="#remoteReceivedHeader">remoteReceivedHeader</a></strong> (0, 1)</li>
+      <li><strong><a href="#remoterecipient">remoterecipient</a></strong> (1, 1)</li>
+      <li><strong><a href="#undeliverable">undeliverable</a></strong> (1, 1)</li>
+      <li><strong><a href="#userundefined">userundefined</a></strong> (1, 1)</li>
+    </ul>
+    </p>
+    
+    <p>
+    <source>
+    &lt;fetch name=&quot;mydomain.com&quot;&gt;
+    ...
+    &lt;/fetch&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="accounts">
+    <p>The <strong>accounts</strong> tag declares the accounts from which mail will 
+    be fetched by the fetch task. Accounts run concurrently.</p>
+    
+    <p>The tag has these child tags (minimum cardinality, maximum cardinality):
+    <ul>
+    <li><strong><a href="#account">account</a></strong> (0, *)</li>
+    <li><strong><a href="#alllocal">alllocal</a></strong> (0, 1)</li>
+    </ul>
+    </p>
+    
+    <p>
+    <source>
+    &lt;accounts&gt;
+    ...
+    &lt;/accounts&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="blacklist">
+    <p>The <strong>blacklist</strong> tag declares a list of recipient addresses 
+    for whom mail will be rejected and what happens to the rejected mail.</p>
+    
+    <p>The tag value is a tab, comma or space delimited list of recipient 
+    addresses, eg: <code>wibble@mydomain.com, flobble@mydomain.com</code>.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>reject</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for recipients in the blacklist will
+    not be injected into the James input spool. If &quot;false&quot;, mail for
+    recipients in the blacklist will be injected into the James input spool with the
+    Mail Attribute <code>org.apache.james.Fetchmail.isBlacklistedRecipient</code>
+    added to the mail.</dd>
+    <dt><strong>leaveonserver</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for recipients in the blacklist will be
+    left on the server. If &quot;false&quot;, mail for recipients in the blacklist 
+    will be marked for deletion.</dd>
+    <dt><strong>markseen</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for recipients in the blacklist will be
+    marked as seen on the server. If &quot;false&quot;, mail for recipients in the blacklist 
+    will not be marked as seen.</dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;blacklist 
+        reject=&quot;true&quot; 
+        leaveonserver=&quot;true&quot;
+        markseen=&quot;true&quot;&gt;
+    wibble@mydomain.com, flobble@mydomain.com
+    &lt;/blacklist&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="defaultdomain">
+    <p>The <strong>defaultdomain</strong> tag declares the domain name to be 
+    appended to the <code>From:</code> header of a mail that has a valid user part
+    but is missing the domain part.</p>
+    
+    <p>If not specified, the default behaviour is to append the canonical host name
+    of the James server.</p>
+    
+    <p>The tag value is the name of the server to append. The name must be a server
+    declared in the <strong>servernames</strong> tag of the <strong>James</strong>
+    block in the configuration or the name <code>localhost</code>.</p>
+    
+    <p>
+    <source>
+    &lt;defaultdomain&gt;
+        mydomain.com
+    &lt;/defaultdomain&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="fetchall">
+    <p>The <strong>fetchall</strong> tag declares if all mail should be fetched from
+    the server, or just unseen mail.</p>
+    
+    <p>The tag value is a boolean. If true, all mail is fetched. If false, only 
+    unseen mail is fetched.</p>
+    
+    <p>
+    <source>
+    &lt;fetchall&gt;false&lt;/fetchall&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="fetched">
+    <p>The <strong>fetched</strong> tag declares what will happen to mail on the
+    external server that is successfully injected into the James input spool.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>leaveonserver</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail injected into the James input spool 
+    will be left on the server. If &quot;false&quot;, mail injected into the James
+    input spool will be marked for deletion.</dd>
+    <dt><strong>markseen</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail injected into the James input spool 
+    will be marked as seen on the server. If &quot;false&quot;, mail injected into
+    the James input spool will not be marked as seen.</dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;fetched leaveonserver=&quot;true&quot; markseen=&quot;true&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="host">
+    <p>The <strong>host</strong> tag declares the IP address of the external
+    server from which mail is fetched.</p>
+    
+    <p>The tag value is the DNS name or IP address literal of the external
+    server.</p>
+    
+    <p>
+    <source>
+    &lt;host&gt;pop3.server.com&lt;/host&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="interval">
+    <p>The <strong>interval</strong> tag declares the period between invocations of
+    the fetch tasks. If a fetch task is still active from a previous invocation
+    when the period expires, the new invocation is skipped over.</p>
+    
+    <p>The tag value is an integer representing the number of milliseconds to elapse
+    between invocations of the fetch tasks.</p>
+    
+    <p>
+    <source>
+    &lt;interval&gt;60000&lt;/interval&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="javaMailFolderName">
+    <p>The <strong>javaMailFolderName</strong> tag declares the name of the root 
+    folder on the external server from which mail is fetched.</p>
+    
+    <p>The tag value is the cAsE-sEnSiTiVe name of the root folder on the external
+    server from which mail is fetched. For POP3 servers this is always 
+    <code>INBOX</code>.</p>
+    
+    <p>
+    <source>
+    &lt;javaMailFolderName&gt;INBOX&lt;/javaMailFolderName&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="javaMailProperties">
+    <p>The <strong>javaMailProperties</strong> tag declares the properties to be
+    applied to the JavaMail Session used by the fetch task. These override the
+    properties answered by <code>System.getProperties()</code>. Many JavaMail
+    properties are specific to the JavaMail Provider selected by the 
+    <a href="#javaMailProviderName">javaMailProviderName</a> tag.</p>
+    
+    <p><strong>Relying on the default values selected by the Provider can be
+    inappropriate.</strong> For instance, the default connection and I/O timeout 
+    values of infinite for the default IMAP and POP3 Providers is rarely what is
+    required. Consult the documentation of the Provider for details and options.</p>
+    
+    <p>Documentation for the default Provider for IMAP is located
+    <a href="http://java.sun.com/products/javamail/javadocs/com/sun/mail/imap/package-summary.html">
+    here</a>.</p>
+    
+    <p>Documentation for the default Provider for POP3 is located
+    <a href="http://java.sun.com/products/javamail/javadocs/com/sun/mail/pop3/package-summary.html">
+    here</a>.</p>
+    
+    <p>Details of how to change a Provider are located
+    <a href="http://java.sun.com/products/javamail/javadocs/javax/mail/Session.html">
+    here</a>.</p>
+    
+    <p>The tag has these child tags (minimum cardinality, maximum cardinality):
+    <ul>
+    <li><strong><a href="#property">property</a></strong> (0, *)</li>
+    </ul>
+    </p>
+    
+    <p>
+    <source>
+    &lt;javaMailProperties&gt;
+    ...
+    &lt;/javaMailProperties&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="javaMailProviderName">
+    <p>The <strong>javaMailProviderName</strong> tag selects the JavaMail protocol
+    Provider used to interact with the external server.</p>
+    
+    <p>The tag value is the name of a JavaMail supported protocol, such as 
+    <code>pop3</code> or <code>imap</code>. The name is used to select the default
+    Provider for the protocol.</p>
+    
+    <p>
+    <source>
+    &lt;javaMailProviderName&gt;pop3&lt;/javaMailProviderName&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="maxmessagesize">
+    
+      <p>The <strong>maxmessagesize</strong> tag declares the maximum permitted message
+      size for messages injected into the James input spool and what happens to fetched
+      messages that exceed this size.</p>
+      <p>The tag has these attributes:
+      <dl>
+        <dt><strong>limit</strong></dt>
+        <dd>An integer. The maximum message size expressed in Kilobytes. If 0, there is
+        no limit.</dd>
+        <dt><strong>reject</strong></dt>
+        <dd>A boolean. If &quot;true&quot;, mail whose message size exceeds the maximum
+        permitted size will not be injected into the James input spool. If 
+        &quot;false&quot;, mail whose message size exceeds the maximum permitted size will
+        have its contents removed, an explanatory error message and the Mail Attribute
+        <code>org.apache.james.Fetchmail.isMaxMessageSizeExceeded</code> added prior to 
+        injection into the James input spool, (see below for the location of an example).</dd>
+        <dt><strong>leaveonserver</strong></dt>
+        <dd>A boolean. If &quot;true&quot;, mail whose message size exceeds the maximum
+        permitted size will be left on the server. If &quot;false&quot;, mail whose message
+        size exceeds the maximum permitted size will be marked for deletion.</dd>
+        <dt><strong>markseen</strong></dt>
+        <dd>A boolean. If &quot;true&quot;, mail whose message size exceeds the maximum
+        permitted size will be marked as seen on the server. If &quot;false&quot;,
+        mail whose message size exceeds the maximum permitted size will not be marked as
+        seen.</dd>
+      </dl>
+      
+      </p>
+      
+      <p>
+      <source>
+      &lt;maxmessagesize 
+          limit=&quot;4096&quot;
+          reject=&quot;false&quot;
+          leaveonserver=&quot;false&quot;
+          markseen=&quot;false&quot;/&gt;
+      </source>
+      </p>
+      
+      <p>An example configuration using James mailet processing to bounce fetched
+      messages that exceed the maximum permitted size can be found in the file
+      <code>$PHOENIX_HOME/apps/james/conf/samples/Fetchmail/maxMessageSize.xml</code>.
+      </p>
+    </subsection>
+    
+    <subsection name="recipientnotfound">
+    <p>The <strong>recipientnotfound</strong> tag declares what happens to mail for
+    which a sole intended recipient cannot be found when attempting to determine
+    the recipient from the mail headers.</p>
+    
+    <p>In configurations with more than one account per fetch task, processing of
+    matched mail can be deferred to the next run of the fetch task. This gives 
+    other accounts that may be able to determine a sole intended recipient an
+    opportunity to do so before recipientnotfound processing is invoked.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>defer</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for which a sole intended recipient 
+    cannot be determined is left unprocessed until the next run of the fetch task.
+    If &quot;false&quot;, mail for which a sole intended recipient cannot be
+    determined is processed immediately.</dd>
+    <dt><strong>reject</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for which a sole intended recipient 
+    cannot be determined will not be injected into the James input spool. If 
+    &quot;false&quot;, mail for which a sole intended recipient cannot be 
+    determined will be injected into the James input spool using the recipient
+    attribute of the current account and with the Mail Attribute 
+    <code>org.apache.james.Fetchmail.isRecipientNotFound</code> added to the
+    mail.</dd>
+    <dt><strong>leaveonserver</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for which a sole intended recipient 
+    cannot be determined will be left on the server. If &quot;false&quot;, mail for
+    which a sole intended recipient cannot be determined will be marked for 
+    deletion.</dd>
+    <dt><strong>markseen</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for which a sole intended recipient 
+    cannot be determined will be marked as seen on the server. If &quot;false&quot;,
+    mail for which a sole intended recipient cannot be determined will not be marked
+    as seen.</dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;recipientnotfound 
+        defer=&quot;true&quot;
+        reject=&quot;true&quot;
+        leaveonserver=&quot;true&quot;
+        markseen=&quot;true&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="recursesubfolders">
+    <p>The <strong>recursesubfolders</strong> tag declares if mail should be fetched 
+    from sub-folders of the root folder, or just the root folder.</p>
+    
+    <p>The tag value is a boolean. If true, mail is fetched from the root folder and
+    its subfolders. If false, mail is fetched from just the root folder.</p>
+    
+    <p>
+    <source>
+    &lt;recursesubfolders&gt;false&lt;/recursesubfolders&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="remoteReceivedHeader">
+    <p>The <strong>remoteReceivedHeader</strong> tag declares the zero based
+    index of the RFC2822 compliant RECEIVED header used to determine the address and
+    host name of the remote MTA that sent a fetched message and what happens to 
+    messages when the specified header is invalid.</p>
+    
+    <p>Typically, the first (index = 0) RECEIVED header is for the local MTA that 
+    delivered the message to the message store and the second (index = 1) RECEIVED
+    header is for the remote MTA that delivered the message to the local MTA. When
+    this configuration applies, the <strong>remoteReceivedHeaderIndex</strong> should
+    be set to <strong>1</strong>.
+    </p>
+    
+    <p>To verify the correct setting, examine the RECEIVED headers for messages
+    delivered to the configured message store and locate the first one containing a
+    remote domain in the'from' field. Remembering that zero based indexing is used,
+    if this the second header, use an index of 1, if this is the third header, use an
+    index of 2, and so forth.</p>
+    
+    <p>Matchers such as InSpammerBlacklist use the remote address and/or remote host
+    name to identify illegitimate remote MTAs. If you do not use such matchers, the
+    <strong>remoteReceivedHeaderIndex</strong> tag may be omitted or the default
+    index value of -1 can be specified. This causes the remote address to be set to
+    <code>127.0.0.1</code> and the remote host name to be set to
+    <code>localhost</code>. Matchers almost always considered these values to be
+    legitimate.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>index</strong></dt>
+    <dd>An integer whose meaning is described above.
+    </dd>
+    <dt><strong>reject</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail whose specified recieved header is invalid
+    will not be injected into the James input spool. If &quot;false&quot;, mail whose 
+    specified recieved header is invalid will be injected into the James input spool with 
+    the Mail Attribute <code>org.apache.james.Fetchmail.isInvalidReceivedHeader</code>
+    added to the mail, the remote address set to <code>127.0.0.1</code> and the remote 
+    host name set to <code>localhost</code>.
+    </dd>
+    <dt><strong>leaveonserver</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail whose specified recieved header is invalid
+    will be left on the server. If &quot;false&quot;, mail whose specified recieved header
+    is invalid will be marked for deletion.</dd>
+    <dt><strong>markseen</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail whose specified recieved header is invalid
+    will be marked as seen on the server. If &quot;false&quot;, mail whose specified
+    recieved header is invalid will not be marked as seen.</dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;remoteReceivedHeader
+        index=&quot;1&quot; 
+        reject=&quot;true&quot;
+        leaveonserver=&quot;true&quot;
+        markseen=&quot;true&quot;/&gt;
+    </source>
+    </p>
+    
+    <p>An example configuration using James mailet processing to notify the postmaster
+    of fetched messages that contain an invalid Received header can be found in the file
+    <code>$PHOENIX_HOME/apps/james/conf/samples/Fetchmail/remoteReceivedHeader.xml</code>.
+    </p>
+    </subsection>
+    
+    <subsection name="remoterecipient">
+    <p>The <strong>remoterecipient</strong> tag declares what happens to mail for
+    which the domain part of the recipient is remote. A domain is remote if it is 
+    not a server declared in the <strong>servernames</strong> tag of the
+    <strong>James</strong> block in the configuration.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>reject</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for remote recipients will not be 
+    injected into the James input spool. If &quot;false&quot;, mail for remote
+    recipients will be injected into the James input spool with the Mail Attribute 
+    <code>org.apache.james.Fetchmail.isRemoteRecipient</code> added to the mail.
+    </dd>
+    <dt><strong>leaveonserver</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for remote recipients will be left on
+    the server. If &quot;false&quot;, mail for remote recipients will be marked for 
+    deletion.</dd>
+    <dt><strong>markseen</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for remote recipients will be marked as
+    seen on the server. If &quot;false&quot;, mail for remote recipients will not be
+    marked as seen.</dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;remoterecipient 
+        reject=&quot;true&quot;
+        leaveonserver=&quot;true&quot;
+        markseen=&quot;true&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="undeliverable">
+    <p>The <strong>undeliverable</strong> tag declares what happens to mail that
+    cannot be delivered.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>leaveonserver</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail that cannot be delivered will be left
+    on the server. If &quot;false&quot;, mail that cannot be delivered will be
+    marked for deletion.</dd>
+    <dt><strong>markseen</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for that cannot be delivered will be
+    marked as seen on the server. If &quot;false&quot;, mail that cannot be
+    delivered will not be marked as seen.</dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;undeliverable
+        leaveonserver=&quot;true&quot;
+        markseen=&quot;true&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="userundefined">
+    <p>The <strong>userundefined</strong> tag declares what happens to mail for
+    which the recipient is not defined as a James user.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>reject</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for recipients who are not defined as
+    James users will not be injected into the James input spool. If 
+    &quot;false&quot;, mail for recipients who are not defined as James users will
+    be injected into the James input spool with the Mail Attribute 
+    <code>org.apache.james.Fetchmail.isUserUndefined</code> added to the mail.
+    </dd>
+    <dt><strong>leaveonserver</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for recipients who are not defined as
+    James users will be left on the server. If &quot;false&quot;, mail for 
+    recipients who are not defined as James users will be marked for deletion.</dd>
+    <dt><strong>markseen</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail for recipients who are not defined as
+    James users will be marked as seen on the server. If &quot;false&quot;, mail
+    for recipients who are not defined as James users will not be marked as seen.
+    </dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;userundefined
+        reject=&quot;true&quot;
+        leaveonserver=&quot;true&quot;
+        markseen=&quot;true&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="account">
+    <p>The <strong>account</strong> tag declares an account on the external server
+    from which mail should be fetched.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>user</strong></dt>
+    <dd>The string to be passed as the user when connecting to the external server.
+    </dd>
+    <dt><strong>password</strong></dt>
+    <dd>The string to be passed as the password when connecting to the external 
+    server.</dd>
+    <dt><strong>recipient</strong></dt>
+    <dd>The recipient to whom messages will be delivered when the intended recipient
+    cannot be determined or when the intended recipient is to be ignored.</dd>
+    <dt><strong>ignorercpt-header</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail is always delivered to the recipient
+    declared in the <strong>recipient</strong> attribute above. If 
+    &quot;false&quot;, the intended recipient is determined from the mail headers or
+    the process declared by the <strong>recipientnotfound</strong> tag.
+    </dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;account
+        user=&quot;myaccount&quot;
+        password=&quot;mypassword&quot;
+        recipient=&quot;user@localhost&quot;
+        ignorercpt-header=&quot;true&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="alllocal">
+    <p>The <strong>alllocal</strong> tag declares the parameters to be applied to
+    dynamic accounts. The set of dynamic accounts is refreshed each time the fetch
+    task runs by combining the <strong>alllocal</strong> tag attributes with each of
+    the currently defined James users to create an account for every James user.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>userprefix</strong></dt>
+    <dd>The string to be added before the James user when constructing the string
+    passed as the user when connecting to the external server.
+    </dd>
+    <dt><strong>usersuffix</strong></dt>
+    <dd>The string to be added after the James user when constructing the string
+    passed as the user when connecting to the external server.
+    </dd>
+    <dt><strong>password</strong></dt>
+    <dd>The string to be passed as the password when connecting to the external 
+    server.</dd>
+    <dt><strong>recipientprefix</strong></dt>
+    <dd>The string to be added before the James user when constructing the recipient
+    to whom messages will be delivered when the intended recipient cannot be 
+    determined or when the intended recipient is to be ignored.</dd>
+    <dt><strong>recipientsuffix</strong></dt>
+    <dd>The string to be added after the James user when constructing the recipient
+    to whom messages will be delivered when the intended recipient cannot be 
+    determined or when the intended recipient is to be ignored.</dd>
+    <dt><strong>ignorercpt-header</strong></dt>
+    <dd>A boolean. If &quot;true&quot;, mail is always delivered to the recipient
+    constructed from the <strong>recipientprefix</strong> and 
+    <strong>recipientsuffix</strong> attributes above and the James user. If 
+    &quot;false&quot;, the intended recipient is determined from the mail headers or
+    the process declared by the <strong>recipientnotfound</strong> tag.
+    </dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;alllocal
+        userprefix=&quot;&quot;
+        usersuffix=&quot;@external.domain.com&quot;
+        password=&quot;mypassword&quot;
+        recipientprefix=&quot;&quot;
+        recipientsuffix=&quot;@mydomain.com&quot;
+        ignorercpt-header=&quot;true&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="property">
+    <p>The <strong>property</strong> tag declares a name/value pair.</p>
+    
+    <p>The tag has these attributes:
+    <dl>
+    <dt><strong>name</strong></dt>
+    <dd>The name of the property.
+    </dd>
+    <dt><strong>value</strong></dt>
+    <dd>The value of the property.</dd>
+    </dl>
+    </p>
+    
+    <p>
+    <source>
+    &lt;property
+        name=&quot;mail.pop3.connectiontimeout&quot;
+        value=&quot;180000&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+  
+  </section>
+  
+  <section name="Fetchmail Examples">
+  
+    <p>Full sources to the examples discussed below can be found in the directory
+    <code>$PHOENIX_HOME/apps/james/conf/samples/Fetchmail</code>.</p>
+    
+    <subsection name="One Account, One User">
+    <p>When all mail for an account is to be delivered to a single user, 
+    configure each account to ignore the recipient in the mail headers and deliver
+    to the specified recipient. The <strong>accounts</strong> block looks like 
+    this:</p>
+    
+    <p>
+    <source>
+    &lt;accounts&gt;
+        &lt;account
+            user=&quot;user1@external.domain.com&quot;
+            password=&quot;password1&quot;
+            recipient=&quot;user1@localhost&quot;
+            ignorercpt-header=&quot;true&quot;/&gt;
+    
+        &lt;account
+            user=&quot;user2@external.domain.com&quot;
+            password=&quot;password2&quot;
+            recipient=&quot;user2@localhost&quot;
+            ignorercpt-header=&quot;true&quot;/&gt;
+    
+        &lt;account
+            user=&quot;user3@external.domain.com&quot;
+            password=&quot;password3&quot;
+            recipient=&quot;user3@localhost&quot;
+            ignorercpt-header=&quot;true&quot;/&gt;
+    &lt;/accounts&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="One Account, Many Users">
+    <p>When an account contains mail to be delivered to many users, configure each
+    account to determine the recipient from the mail headers and deliver to that 
+    user. The <strong>accounts</strong> block looks like this:</p>
+    
+    <p>
+    <source>
+    &lt;accounts&gt;
+        &lt;account
+            user=&quot;global@external.domain.com&quot;
+            password=&quot;password&quot;
+            recipient=&quot;Fetchmail@localhost&quot;
+            ignorercpt-header=&quot;false&quot;/&gt;
+    &lt;/accounts&gt;
+    </source>
+    </p>
+    
+    <p>The <strong>recipientnotfound</strong> tag is used to declare what happens 
+    when the recipient cannot be determined from the mail headers. In the example 
+    below, mail is injected into the spool using the recipient declared in the
+    <strong>account</strong> tag:</p>
+    
+    <p>
+    <source>
+    &lt;recipientnotfound
+        defer=&quot;false&quot;
+        reject=&quot;false&quot;
+        leaveonserver=&quot;false&quot;
+        markseen=&quot;false&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="One Account, One User - Dynamic">
+    <p>When an external server supports virtual mailboxes, Fetchmail's dynamic 
+    account facility can be used. This greatly simplifies user configuration as 
+    the Fetchmail accounts for users are automatically synchronized with those
+    defined in the James user repository. This guarantees that mail for all local 
+    users will be fetched and delivered.</p>
+    
+    <p>Currently, there is a limitation that all virtual accounts and the global
+    account must share the same password.</p>
+    
+    <p>The <strong>alllocal</strong> tag declares the parameters for the dynamic 
+    accounts. The <strong>accounts</strong> block below will deliver mail for 
+    <code>user1@external.domain.com</code> to <code>user1@localhost</code>, 
+    <code>user2@external.domain.com</code> to <code>user2@localhost</code>,
+    <code>userZ@external.domain.com</code> to <code>userZ@localhost</code> etc.:</p>
+    
+    <p>
+    <source>
+    &lt;accounts&gt;
+        &lt;alllocal
+            userprefix=&quot;&quot;
+            usersuffix=&quot;@external.domain.com&quot;
+            password=&quot;mypassword&quot;
+            recipientprefix=&quot;&quot;
+            recipientsuffix=&quot;@localhost&quot;
+            ignorercpt-header=&quot;true&quot;/&gt;
+    &lt;/accounts&gt;
+    </source>
+    </p>
+    </subsection>
+    
+    <subsection name="One Account, Many Users - Dynamic">
+    
+    <p>The <a href="#One Account, One User - Dynamic">One Account, One User - Dynamic</a>
+    example guarantees delivery of mail for all local users, but leaves other mail
+    on the external server unprocessed. The 
+    <a href="#One Account, Many Users">One Account, Many Users</a> example
+    processes all mail on the external server, but cannot guarantee delivery to the
+    intended recipient. By combining the two, it is possible to guarantee the 
+    delivery of mail for all local users and process all mail.</p>
+    
+    <p>In the snippet below, the <strong>alllocal</strong> tag declares dynamic
+    accounts for all local users and the <strong>account</strong> tag configures an
+    account to fetch all mail.</p>
+    
+    <p>The <strong>recipientnotfound</strong> tag rejects mail for which a recipient
+    cannot be determined. By the time this processing is activated, the dynamic 
+    accounts will have processed mail for all local users, so the mail can 
+    only be mail for non-local users or newly arrived mail for local users. It is 
+    not possible to know which, but we want to leave mail for local users to be
+    dealt with by the dynamic accounts. The next time the dynamic accounts run any
+    newly arrived mail for local users will be processed. The remainder will be for
+    non-local users and can now be safely dealt with.</p>
+    
+    <p>The <code>&lt;recipientnotfound defer=&quot;true&quot;</code> attribute 
+    enables deferal of the processing of messages for which the recipient cannot be
+    determined to the next iteration of the fetch task, and is used here. The 
+    relevant tags are:</p>
+    
+    <p>
+    <source>
+    &lt;accounts&gt;
+        &lt;alllocal
+            userprefix=&quot;&quot;
+            usersuffix=&quot;@external.domain.com&quot;
+            password=&quot;mypassword&quot;
+            recipientprefix=&quot;&quot;
+            recipientsuffix=&quot;@localhost&quot;
+            ignorercpt-header=&quot;true&quot;/&gt;
+    
+        &lt;account
+            user=&quot;global@external.domain.com&quot;
+            password=&quot;password&quot;
+            recipient=&quot;Fetchmail@localhost&quot;
+            ignorercpt-header=&quot;false&quot;/&gt;
+    &lt;/accounts&gt;
+    
+    &lt;recipientnotfound
+        defer=&quot;true&quot;
+        reject=&quot;true&quot;
+        leaveonserver=&quot;true&quot;
+        markseen=&quot;true&quot;/&gt;
+    </source>
+    </p>
+    </subsection>
+  
+  </section>
+  
+  <section name="Fetchmail Caveats">
+  
+    <p>These are some things to be aware of when using Fetchmail:
+    
+    <ul>
+    
+      <li>As noted in the
+      <a href="#One Account, One User - Dynamic">One Account, One User - Dynamic</a>
+      example, all virtual accounts and the global account must share the same 
+      password. A future version might associate each James user to a set of account
+      credentials.</li>
+      
+      <li>When using dynamic accounts, an account is generated and an attempt made to
+      fetch mail for all James users defined to James even if there is no such mailbox
+      on the server. This is inefficient but not fatal. The solution is the same as 
+      described above.</li>
+      
+      <li>When using dynamic accounts, as described in the
+      <a href="#One Account, Many Users - Dynamic">One Account, Many Users - Dynamic</a>
+      example, the user name used to fetch the mail for all accounts must not be
+      defined as a James user. If it is, a dynamic account will be generated for it
+      and fetch all the mail before the account declared to process mail for all users
+      has an opportunity to run!</li>
+      
+      <li>The now deprecated fetchPOP interacted with the <code>FetchedFrom</code> 
+      matcher to detect mail injected by fetchPOP. This will not work with Fetchmail. 
+      Compared to fetchPOP, there are far fewer occasions when mail injected by 
+      Fetchmail requires special processing. When it does, use the HasMailAttribute 
+      matcher to match the attribute named 
+      <code>org.apache.james.Fetchmail.taskName</code> to detect all mail injected by
+      Fetchmail. To detect mail injected by a specific fetch task, use one of the 
+      HasMailAttributeWithValue matchers to match on the attribute name and the
+      attribute value. The attribute value is the name of the fetch task that 
+      injected the mail.</li>
+      
+      <li>The POP3 protocol does not enforce support of any of the Flags associated 
+      with messages other than DELETED. This means that 
+      <code>markseen=&quot;true&quot;</code> will most likely have no effect and 
+      therefore, the <strong>fetchall</strong> tag will be inoperative. In this 
+      situation, the only way to avoid repeatedly fetching the same mail is to delete
+      it from the server using <code>leaveonserver=&quot;false&quot;/&gt;</code>.</li>
+      
+      <li>If using a Exchange 2000 or Exchange 2003 server get sure you fix the CLRF bug. 
+      See <a href="http://support.microsoft.com/kb/816896/en-us"> Bug description and fix</a></li>
+    </ul>
+
+    </p>
+
+  </section>
+
+  <section name="Fetchmail Gmail">
+  
+    <p>Use this configuration to fetch Gmail via POP3. Please don't forget to enable POP3 in Gmail (<a href="http://mail.google.com/support/bin/answer.py?answer=13273">read how-to</a>).</p>
+  
+    <source>
+&lt;fetchmail enabled=&quot;true&quot;&gt;
+&lt;fetch name=&quot;gmail.com&quot;&gt;
+&lt;accounts&gt;
+&lt;account user=&quot;YOUR_USER@gmail.com&quot; password=&quot;YOUR_PASSWORD&quot; recipient=&quot;YOUR_EMAIL_ADDRESS_IN_JAMES&quot; ignorercpt-header=&quot;true&quot;/&gt;
+&lt;/accounts&gt;
+&lt;host&gt;pop.gmail.com&lt;/host&gt;
+&lt;interval&gt;600000&lt;/interval&gt;
+&lt;javaMailProviderName&gt;pop3&lt;/javaMailProviderName&gt;
+&lt;javaMailFolderName&gt;INBOX&lt;/javaMailFolderName&gt;
+&lt;javaMailProperties&gt;
+&lt;property name=&quot;mail.pop3.ssl.enable&quot; value=&quot;true&quot;/&gt;
+&lt;/javaMailProperties&gt;
+&lt;fetchall&gt;false&lt;/fetchall&gt;
+&lt;recursesubfolders&gt;false&lt;/recursesubfolders&gt;
+&lt;defaultdomain&gt;localhost&lt;/defaultdomain&gt;
+&lt;fetched leaveonserver=&quot;true&quot; markseen=&quot;true&quot;/&gt;
+&lt;remotereceivedheader index=&quot;1&quot; reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot;/&gt;
+&lt;maxmessagesize limit=&quot;0&quot; reject=&quot;false&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot;/&gt;
+&lt;undeliverable leaveonserver=&quot;true&quot; markseen=&quot;false&quot;/&gt;
+&lt;recipientnotfound defer=&quot;true&quot; reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot;/&gt;
+&lt;blacklist reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot;&gt; wibble@localhost, flobble@localhost&lt;/blacklist&gt;
+&lt;userundefined reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot; /&gt;
+&lt;remoterecipient reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot; /&gt;
+&lt;/fetch&gt;
+&lt;/fetchmail&gt;
+    </source>
+  
+    <p>Use this configuration to fetch Gmail via IMAP4. Please don't forget to enable IMAP4 in Gmail (<a href="http://mail.google.com/support/bin/answer.py?answer=77695">read how-to</a>).</p>
+  
+    <source>
+&lt;fetchmail enabled=&quot;true&quot;&gt;
+&lt;fetch name=&quot;gmail.com&quot;&gt;
+&lt;accounts&gt;
+&lt;account user=&quot;YOUR_USER@gmail.com&quot; password=&quot;YOUR_PASSWORD&quot; recipient=&quot;YOUR_EMAIL_ADDRESS_IN_JAMES&quot; ignorercpt-header=&quot;true"/&gt;
+&lt;/accounts&gt;
+&lt;host&gt;imap.gmail.com&lt;/host&gt;
+&lt;interval&gt;600000&lt;/interval&gt;
+&lt;javaMailProviderName&gt;imap&lt;/javaMailProviderName&gt;
+&lt;javaMailFolderName&gt;INBOX&lt;/javaMailFolderName&gt;
+&lt;javaMailProperties&gt;
+&lt;property name=&quot;mail.imap.ssl.enable&quot; value=&quot;true&quot;/&gt;
+&lt;/javaMailProperties&gt;
+&lt;fetchall&gt;false&lt;/fetchall&gt;
+&lt;recursesubfolders&gt;false&lt;/recursesubfolders&gt;
+&lt;defaultdomain&gt;localhost&lt;/defaultdomain&gt;
+&lt;fetched leaveonserver=&quot;true&quot; markseen=&quot;true&quot;/&gt;
+&lt;remotereceivedheader index=&quot;1&quot; reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot;/&gt;
+&lt;maxmessagesize limit=&quot;0&quot; reject=&quot;false&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot;/&gt;
+&lt;undeliverable leaveonserver=&quot;true&quot; markseen=&quot;false&quot;/&gt;
+&lt;recipientnotfound defer=&quot;true&quot; reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot;/&gt;
+&lt;blacklist reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot;&gt; wibble@localhost, flobble@localhost&lt;/blacklist&gt;
+&lt;userundefined reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot; /&gt;
+&lt;remoterecipient reject=&quot;true&quot; leaveonserver=&quot;true&quot; markseen=&quot;false&quot; /&gt;
+&lt;/fetch&gt;
+&lt;/fetchmail&gt;
+    </source>
+  
+  </section>
+
+</body>
+
+</document>

Propchange: james/site-cms/trunk/content/xdoc/config-fetchmail.xml
------------------------------------------------------------------------------
    svn:executable = *

Propchange: james/site-cms/trunk/content/xdoc/config-fetchmail.xml
------------------------------------------------------------------------------
    svn:keywords = Id Author Revision HeadURL

Added: james/site-cms/trunk/content/xdoc/config-imap4.xml
URL: http://svn.apache.org/viewvc/james/site-cms/trunk/content/xdoc/config-imap4.xml?rev=1338063&view=auto
==============================================================================
--- james/site-cms/trunk/content/xdoc/config-imap4.xml (added)
+++ james/site-cms/trunk/content/xdoc/config-imap4.xml Mon May 14 08:45:02 2012
@@ -0,0 +1,83 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.    
+-->
+<document>
+
+ <properties>
+  <title>Apache James Server 3 - IMAP4 Configuration</title>
+ </properties>
+
+<body>
+
+<section name="IMAP4 Configuration">
+
+      <p>Consult <a href="https://svn.apache.org/repos/asf/james/app/tags/apache-james-3.0-beta4/src/main/resources/imapserver-template.conf">imapserver-template.conf</a> in SVN to get some examples and hints.</p>
+
+    <p>The IMAP4 service is controlled by a configuration block in the imap4server.xml.
+       The imap4server tag defines the boundaries of the configuration block.  It encloses 
+       all the relevant configuration for the IMAP4 server.  The behavior of the IMAP4 service is
+       controlled by the attributes and children of this tag.</p>
+    
+    <p>This tag has an optional boolean attribute - <strong>enabled</strong> - that defines whether the service is active or not.  The value defaults to "true" if
+       not present.</p>
+    
+    <p>The standard children of the imapserver tag are:</p>
+
+      <dl>
+        <dt><strong>bind</strong></dt>
+        <dd>Configure this to bind to a specific inetaddress. This is an optional integer value.  This value is the port on which this IMAP4 server is configured 
+      to listen. If the tag or value is absent then the service 
+      will bind to all network interfaces for the machine If the tag or value is omitted, the value will default to the standard IMAP4 port
+      port 143 is the well-known/IANA registered port for IMAP 
+     port 993 is the well-known/IANA registered port for IMAPS  ie over SSL/TLS</dd>
+        <dt><strong>connectionBacklog</strong></dt>
+        <dd></dd>
+        <dt><strong>compress</strong></dt>
+        <dd>true or false - Use or don't use COMPRESS extension.</dd>
+        <dt><strong>maxLineLength</strong></dt>
+        <dd>Maximal allowed line-length before a BAD response will get returned to the client
+            This should be set with caution as a to high value can make the server a target for DOS (Denial of Service)!</dd>
+        <dt><strong>inMemorySizeLimit</strong></dt>
+        <dd>10MB size limit before we will start to stream to a temporary file</dd>
+        <dt><strong>tls</strong></dt>
+        <dd>Set to true to support STARTTLS or SSL for the Socket.
+         To use this you need to copy sunjce_provider.jar to /path/james/lib directory. To create a new keystore execute:
+             keytool -genkey -alias james -keyalg RSA -keystore /path/to/james/conf/keystore</dd>
+        <dt><strong>handler.helloName</strong></dt>
+        <dd>This is the name used by the server to identify itself in the IMAP4 
+        protocol.  If autodetect is TRUE, the server will discover its 
+        own host name and use that in the protocol.  If discovery fails, 
+        the value of 'localhost' is used.  If autodetect is FALSE, James 
+        will use the specified value.</dd>
+        <dt><strong>handler.connectiontimeout</strong></dt>
+        <dd>Connection timeout in secconds</dd>
+        <dt><strong>handler.connectionLimit</strong></dt>
+        <dd>Set the maximum simultaneous incoming connections for this service</dd>
+        <dt><strong>handler.connectionLimitPerIP</strong></dt>
+        <dd>Set the maximum simultaneous incoming connections per IP for this service</dd>
+        <dt><strong>handler.handlerchain</strong></dt>
+        <dd>This loads the core CommandHandlers. Only remove this if you really 
+             know what you are doing</dd>
+      </dl>
+
+</section>
+
+</body>
+
+</document>

Propchange: james/site-cms/trunk/content/xdoc/config-imap4.xml
------------------------------------------------------------------------------
    svn:keywords = Id Author Revision HeadURL

Added: james/site-cms/trunk/content/xdoc/config-listmanager.xml
URL: http://svn.apache.org/viewvc/james/site-cms/trunk/content/xdoc/config-listmanager.xml?rev=1338063&view=auto
==============================================================================
--- james/site-cms/trunk/content/xdoc/config-listmanager.xml (added)
+++ james/site-cms/trunk/content/xdoc/config-listmanager.xml Mon May 14 08:45:02 2012
@@ -0,0 +1,157 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.    
+-->
+<document>
+
+ <properties>
+  <title>Apache James Server 3 - List Manager Configuration</title>
+ </properties>
+
+<body>
+
+<p>
+    <div class="ui-widget">
+      <div class="ui-state-error ui-corner-all" style="padding: 0 .7em;"> 
+        <p><span class="ui-icon ui-icon-alert" style="float: left; margin-right: .3em;"></span> 
+        <strong>This page still contains text related to James 2.3 and needs to 
+        be updated for James 3.0</strong>
+		</p>
+      </div>
+    </div>
+</p>
+
+<section name="List Manager Configuration">
+
+  <subsection>
+
+    <p>Consult <a href="https://svn.apache.org/repos/asf/james/app/tags/apache-james-3.0-beta4/src/main/resources/james-listmanager-template.conf">james-listmanager.conf</a> in SVN to get some examples and hints.</p>
+
+    <p>One of the frequent questions on the James-User Mailing List is how
+    to create a mailing list. This document explains one way of using the
+    currently supplied Matchers and Mailets in James v3.0.</p>
+    
+    <p>Basically, the process requires creating two &lt;mailet&gt; entries
+    and a repository.  The first mailet handles list commands (currently
+    only <i>list-name</i>-on and <i>list-name</i>-off).  The second mailet
+    handles list messages.  The repository will hold the e-mail addresses
+    of list subscribers.</p>
+    
+    <p>The mailets go into the processor chain (e.g., at the top of the
+    <i>transport</i> processor), the repository goes into the
+    &lt;users-store&gt; block.</p>
+    
+  </subsection>
+    
+    <subsection name="Setting up the Repository">
+    
+    <p>The mailing list mailets need a repository within which to store
+    the subscriber list.  There is a separate repository for each mailing
+    list, and is completely independent of the user repository used by
+    James to manage e-mail accounts.  This is configured in the
+    &lt;users-store&gt; block of james-listmanager.xml.</p>
+    
+    <p>The following illustrates a database-backed repository using JDBC
+    with the ListUsersJdbcRepository class.  Notice that there will be a
+    single table, <i>lists</i>, created in the db://maildb resource
+    defined elsewhere.  There are currently two columns: the list name and
+    the list subscriber.</p>
+    
+    <source>
+&lt;repository name="<i>list-name</i>"
+               class="org.apache.james.userrepository.ListUsersJdbcRepository"
+               destinationURL="db://maildb/lists/<i>list-name</i>"&gt;
+  &lt;sqlFile&gt;file://conf/sqlResources.xml&lt;/sqlFile&gt;
+&lt;/repository&gt;
+    </source>
+    
+    <p>The following illustrates a file-system repository using the
+    UsersFileRepository class. [Note: the destination URL is a child
+    element when configuring a file-system repository, and an attribute
+    when configuring a database-backed repository.  This inconsistency
+    will be addressed in a future version of James.]</p>
+    
+    <source>
+&lt;repository name="<i>list-name</i>"
+               class="org.apache.james.userrepository.UsersFileRepository"&gt;
+  &lt;destination URL="file://var/lists/<i>list-name</i>/" /&gt; 
+&lt;/repository&gt;
+    </source>
+    
+    </subsection>
+        
+    <subsection name="Alternate Explanation">
+    
+        <p>James currently includes only the most basic list functionality, users can subscribe and unsubscribe, but there is no moderation of messages or subscriptions</p>
+        <p>To enable a list you need the following in config.xml in the root processor block and above the final mailet block -</p>
+        <source>
+&lt;mailet match="CommandForListserv=james@localhost"
+    class="AvalonListservManager">
+    &lt;repositoryName>list-james&lt;/repositoryName>
+&lt;/mailet>
+</source>
+        <p>that will intercept the command emails sent to
+<ul>
+            <li>james-on@localhost to subscribe the sender</li>
+            <li>james-off@localhost to unsubscribe the sender</li>
+          </ul>
+        </p>
+        <p>and-</p>
+        <source>
+&lt;mailet match="RecipientIs=james@localhost" class="AvalonListserv">
+    &lt;membersonly> false &lt;/membersonly>
+    &lt;attachmentsallowed> true &lt;/attachmentsallowed>
+    &lt;replytolist> true &lt;/replytolist>
+    &lt;repositoryName>list-james&lt;/repositoryName>
+    &lt;subjectprefix>JamesList&lt;/subjectprefix>
+&lt;/mailet>
+</source>
+        <p>Which will distribute the mail to the current subscribers</p>
+        <p>in addition to the above you need to have a repository configured in the users-store block(usually near the bottom of config.xml) like so (database)-</p>
+        <source>
+&lt;repository name="list-james"
+    class="org.apache.james.userrepository.ListUsersJdbcRepository"
+    destinationURL="db://maildb/lists/list-james">
+    &lt;sqlFile>file://conf/sqlResources.xml&lt;/sqlFile>
+&lt;/repository>
+</source>
+        <p>Database users will also need to ensure that they have <a href="2.3.1/using_database.html">configured a data-source</a> named to match the destination URL</p>
+        <p>Using the filesystem:-</p>
+        <source>
+&lt;repository name="list-james"
+    class="org.apache.james.userrepository.UsersFileRepository">
+    &lt;destination URL="file://var/lists/list-james/"/>
+&lt;/repository>
+</source>
+        <p>Restart James, send a mail to james-on@localhost and you should be subscribed.</p>
+        <p>The repository, be it a database table or directory in the filesystem will be created automatically.</p>
+        <p>Database users can manipulate the users repository using SQL, and hence any application capable of running SQL queries against it.</p>
+
+    </subsection>
+    
+  </section>
+  
+  <section name="miResources.xml">
+  
+    <p>Consult <a href="https://svn.apache.org/repos/asf/james/app/tags/apache-james-3.0-beta4/src/main/resources/miResources.xml">miResources.xml</a> in SVN to get some examples and hints.</p>
+
+  </section>
+  
+</body>
+
+</document>

Propchange: james/site-cms/trunk/content/xdoc/config-listmanager.xml
------------------------------------------------------------------------------
    svn:keywords = Id Author Revision HeadURL

Added: james/site-cms/trunk/content/xdoc/config-mailbox.xml
URL: http://svn.apache.org/viewvc/james/site-cms/trunk/content/xdoc/config-mailbox.xml?rev=1338063&view=auto
==============================================================================
--- james/site-cms/trunk/content/xdoc/config-mailbox.xml (added)
+++ james/site-cms/trunk/content/xdoc/config-mailbox.xml Mon May 14 08:45:02 2012
@@ -0,0 +1,46 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.    
+-->
+<document>
+
+ <properties>
+  <title>Apache James Server 3 - Mailbox Configuration</title>
+ </properties>
+
+<body>
+
+  <section name="Mailbox Configuration">
+
+    <p>Consult <a href="https://svn.apache.org/repos/asf/james/app/tags/apache-james-3.0-beta4/src/main/resources/mailbox-template.conf">mailbox-template.conf</a> in SVN to get some examples and hints.</p>
+    
+    <p>Use this configuration to define the type of mailbox storage used to persist the user's mails.</p>
+    
+    <p>Under maibox tag, define the provider.</p>
+
+      <dl>
+        <dt><strong>provider</strong></dt>
+        <dd>Supported providers are: jpa (default), jcr, maildir, memory. Be aware that maildir will only work on unix like operation systems!</dd>
+      </dl>
+
+  </section>
+
+</body>
+
+</document>
+

Propchange: james/site-cms/trunk/content/xdoc/config-mailbox.xml
------------------------------------------------------------------------------
    svn:keywords = Id Author Revision HeadURL

Added: james/site-cms/trunk/content/xdoc/config-mailetcontainer.xml
URL: http://svn.apache.org/viewvc/james/site-cms/trunk/content/xdoc/config-mailetcontainer.xml?rev=1338063&view=auto
==============================================================================
--- james/site-cms/trunk/content/xdoc/config-mailetcontainer.xml (added)
+++ james/site-cms/trunk/content/xdoc/config-mailetcontainer.xml Mon May 14 08:45:02 2012
@@ -0,0 +1,160 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.    
+-->
+<document>
+
+ <properties>
+  <title>Apache James Server 3 - Mailet Container Configuration</title>
+ </properties>
+
+<body>
+
+  <section name="Mailet Container Configuration">
+
+    <p>Consult <a href="https://svn.apache.org/repos/asf/james/app/tags/apache-james-3.0-beta4/src/main/resources/mailetcontainer-template.conf">mailetcontainer-template.conf</a> in SVN to get some examples and hints.</p>
+    
+    <p>Changes between 3.0-M2 and 3.0-beta3:</p>
+    <ul>
+      <li>No more mailetpackage specification in mailetcontainer.xml</li>
+      <li>Exactly one standard package, hard-coded in source code</li>
+      <li>Standard package applied to mailet classnames without package prefix</li>
+      <li>All custom mailets must be specified with full package prefix</li>
+      <li>Package prefixed custom mailet names will be searched across the entire applicable class path</li>
+      <li>Composite matchers</li>
+    </ul>
+<!-- 
+<matcher name="anyname" match="org.apache.james.mailetcontainer.lib.matcher.And">
+<matcher match="SenderIs...."/>
+<matcher match="SubjectStartsWith...."/>
+</matcher>
+<mailet match="anyname" class="MailetX"/>
+-->
+      <p>This configuration block is defined by the <strong>mailserver</strong> tag.  All administrators 
+      need to adjust the <strong>mailserver</strong> block upon installation.</p>
+
+      <dl>
+        <dt><strong>context.postmaster</strong></dt>
+        <dd>The body of this element is the address that the server 
+            will consider its postmaster address.  This address will be listed as the sender address 
+            of all error messages that originate from James.  Also, all messages addressed to 
+            postmaster@&lt;servername&gt;, where &lt;servername&gt; is one of the domain names whose 
+            mail is being handled by James, will be redirected to this email address.
+            Set this to the appropriate email address for error reports 
+            If this is set to a non-local email address, the mail server
+            will still function, but will generate a warning on startup.</dd>
+      <dt><strong>spooler.threads</strong></dt>
+      <dd>Number of simultaneous threads used to spool the mails.</dd>
+      </dl>
+    
+<!--   
+    <p>The SpoolManager is controlled by a single configuration block in the mailetcontainer.xml.
+    The spoolmanager tag defines the boundaries of the configuration block.  The behavior of 
+    the SpoolManager, most importantly the routing of mail messages through the processor tree,
+    is controlled by this block.</p>
+    
+    <p>The spoolmanager tag has only one children.  It is:</p>
+    <ul>
+      <li><strong>threads</strong> - This is a required positive integer element.  It specifies 
+          the number of threads the SpoolManager will use to process messages in the spool.  This 
+          parameter tends to substantially impact performance, so it is advisable to tune it in production 
+          configurations.</li>
+    </ul>
+
+    <p>Spoolmanager depends on mailet and matcher packages, configured by these tags:</p>
+    <ul>
+      <li><strong>mailetpackages</strong> - This is a required container tag.  It contains some number 
+          of <strong>mailetpackage</strong> children.  The body of each of these <strong>mailetpackage</strong> 
+          elements is a Java package name.  It is these packages that contain the classes to be instantiated
+          as mailets.</li>
+      <li><strong>matcherpackages</strong> - This is a required container tag.  It contains some number 
+          of <strong>matcherpackage</strong> children.  The body of each of these <strong>matcherpackage</strong> 
+          elements is a Java package name.  It is these packages that contain the classes to be instantiated
+          as matchers.</li>
+    </ul>
+
+    <p>The remaining SpoolManager configuration elements are complex enough to require a more in-depth
+       discussion.</p>
+    
+    <subsection name="Processor Configuration">
+    
+      <p>In addition to the child elements discussed above, the SpoolManager tag can have several 
+      <strong>processor</strong> children.  It is these tags and their children that define the processor tree 
+      for the SpoolManager.</p>
+      
+      <p>Each processor has a required attribute, <strong>name</strong>.  The value of this attribute must be 
+      unique for each processor tag.  The name of a processor is significant.  Certain processors are required 
+      (specifically root and error).  The name "ghost" is forbidden as a processor name, as it is used to denote 
+      a message that should not undergo any further processing.</p>
+      
+      <p>The James SpoolManager creates a correspondance between processor names and the "state" of a mail as defined 
+      in the Mailet API.  Specifically, after each mailet processes a mail, the state of the message is examined.  If
+      the state has been changed, the message does not continue in the current processor.  If the new state is "ghost"
+      then processing of that message terminates completely.  If the new state is anything else, the message is 
+      re-routed to the processor with the name matching the new state.</p>
+      <p>The root processor is a required processor.  All new messages that the SpoolManager finds on the spool are 
+      directed to this processor.</p>
+      
+      <p>The error processor is another required processor.  Under certain circumstances James itself will redirect messages
+      to the error processor.  It is also the standard processor to which mailets redirect messages when an error
+      condition is encountered.</p>
+      
+      <p>The transport and spam processors are two useful, but optional, processors that are included in the out of
+      the box configuration.  These processors include logic for actual mail delivery and spam handling respectively.  More
+      information on these processors can be found in the default mailetcontainer.xml.</p>
+      
+      <p>Each processor element has zero or more <strong>mailet</strong> child elements.  Each of these elements describes a 
+      matcher/mailet pair.  The ordering of the <strong>mailet</strong> children is crucial to the configuration, as 
+      it is the order in which pairs will be traversed in the processor.</p>
+      
+      <p>It is this <strong>mailet</strong> element that is at the core of the SpoolManager configuration.</p>
+      
+    </subsection>
+-->    
+    <subsection name="The Mailet Tag">
+    
+      <p>Consider the following simple <strong>mailet</strong> tag:</p>
+      &lt;mailet match="RemoteAddrNotInNetwork=127.0.0.1" class="ToProcessor"&gt;<br/>
+      &lt;processor&gt;spam&lt;/processor&gt;<br/>
+      &lt;/mailet&gt;<br/>
+      
+      <p>The mailet tag has two required attributes, <strong>match</strong> and <strong>class</strong>.</p>
+      
+      <p>The <strong>match</strong> attribute is set to the value of the specific Matcher class to be instantiated with a an 
+      optional argument.  If present, the argument is separated from the Matcher class name by an '='.  Semantic 
+      interpretation of the argument is left to the particular mailet.</p>
+      
+      <p>The <strong>class</strong> attribute is set to the value of the Mailet class that is to be instantiated.</p>
+      
+      <p>Finally, the children of the <strong>mailet</strong> tag define the configuration that is passed to the Mailet.  The 
+      tags used in this section should have no attributes or children.  The names and bodies of the elements will be passed to 
+      the mailet as (name, value) pairs.</p>
+      
+      <p>So in the example above, a Matcher instance of RemoteAddrNotInNetwork would be instantiated, and the value "127.0.0.1" 
+      would be passed to the matcher.  The Mailet of the pair will be an instance of ToProcessor, and it will be passed the (name, value) 
+      pair of ("processor", "spam").</p>
+      
+      <p>Apache James Server includes a number of pre-packaged Mailets and Matchers.  A list of provided Mailets may be found 
+      <a href="dev-provided-mailets.html">here</a>.  A list of provided Matchers may be found <a href="dev-provided-matchers.html">here</a>.</p>
+    
+    </subsection>
+  
+  </section>
+
+</body>
+</document>

Propchange: james/site-cms/trunk/content/xdoc/config-mailetcontainer.xml
------------------------------------------------------------------------------
    svn:keywords = Id Author Revision HeadURL

Added: james/site-cms/trunk/content/xdoc/config-mailrepositorystore.xml
URL: http://svn.apache.org/viewvc/james/site-cms/trunk/content/xdoc/config-mailrepositorystore.xml?rev=1338063&view=auto
==============================================================================
--- james/site-cms/trunk/content/xdoc/config-mailrepositorystore.xml (added)
+++ james/site-cms/trunk/content/xdoc/config-mailrepositorystore.xml Mon May 14 08:45:02 2012
@@ -0,0 +1,109 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.    
+-->
+<document>
+
+ <properties>
+  <title>Apache James Server 3 - Mail Repository Store Configuration</title>
+ </properties>
+
+<body>
+
+  <section name="Mail Repository Store Configuration">
+  
+    <subsection name="Introduction">
+
+      <p>Read <a href="feature-persistence.html">documentation about persistence</a> for a description of the Mail Repository Store functionality.</p>
+    
+      <p>Consult <a href="https://svn.apache.org/repos/asf/james/app/tags/apache-james-3.0-beta4/src/main/resources/mailrepositorystore-template.conf">mailrepositorystore-template.conf</a> in SVN to get some examples and hints.</p>
+
+      <p>Mail Repository Stores are distinguished by where they store data.  There are five types of 
+        storage: File, Database, DBFile, MBox and JCR.</p>
+        
+    </subsection>
+        
+    <subsection name="File Repositories">
+    
+      <p>File-based repositories store all data in the file system.  In general, these repositories are extremely
+      simple to configure, but may compare poorly in terms of performance when compared to other repository
+      types.  File repositories are not recommended for large or performance-critical configurations.  In the
+      default configuration, all repositories are file repositories.</p>
+      
+      <p>File repository paths typically begin with the prefix "file".  Paths are relative to the application
+      base directory, unless the path begins with a slash.  As an example, assume that James is running in 
+      /usr/james/phoenix/apps/james.  Then "file://var/mail/spool/" would refer to the directory /usr/james/phoenix/apps/james/var/mail/spool.  
+      And "file:///var/mail/spool/" (note the extra '/') would refer to the directory /var/mail/spool.</p>
+      
+      <p>All repository types (mail, spool, user, and news) have file-based implementations.  No special configuration is required to enable file-based repositories</p>
+    
+    <!-- File based repositories.  These repositories store all message data -->
+        <!-- in the file system. -->
+        
+    </subsection>
+    
+    <subsection name="Database (JDBC) Repositories">
+    
+      <p>These repositories store all message data in the database.</p>
+    
+      <p>Database repositories store all data in an administrator-supplied database.  Configuration is somewhat
+      more complex, requiring that the administrator adjust the data-connections section.  Detailed directions 
+      are included in the sample configuration file.  The administrator will need to know the JDBC driver class,
+      the appropriate URL for use with his database, and a valid username/password for the database.</p>
+      
+      <p>If the administrator wants to configure a database other than MySQL, it will be necessary to add the jar 
+      or zip file containing the JDBC driver classes to the lib subdirectory of the installation directory.  This
+      will allow Apache James Server to properly load the driver when it is initializing the database repository.</p>
+      
+      <p>Database repository paths typically begin with the prefix "db".  The format is "db://&lt;data-source&gt;/&lt;table&gt;" 
+      where &lt;data-source&gt; is the name of the data-source defined in the data-connections section.  And &lt;table&gt; is 
+      the particular table associated with the repository.</p>
+      
+    </subsection>
+    
+    <subsection name="DBFile Repositories">
+    
+      <p>These repositories store message delivery and headers in the DB, and the body to the filesystem.</p>
+    
+      <p>This is a special repository type used only for mail repositories.  DBFile repositories store the body of
+      a mail message in the file system, while headers are stored in the database.  This allows the administrator 
+      to minimize the size of data stored in the database, while conserving most of the performance of the 
+      database repository.</p>
+      
+    </subsection>
+    
+    <subsection name="MBox Repositories">
+    
+     <p>The MBox file format repository.</p>
+
+    </subsection>
+
+    <subsection name="JCR Repositories">
+    
+      <p>Store mails in a JCR (Java Content Repository) based implementation.</p>
+    
+      <p>If you enable this you need to make sure that embedded Jackrabbit instance is started as well. Check the container configuration</p>
+        
+    </subsection>
+  
+  </section>
+
+</body>
+
+</document>
+

Propchange: james/site-cms/trunk/content/xdoc/config-mailrepositorystore.xml
------------------------------------------------------------------------------
    svn:keywords = Id Author Revision HeadURL

Added: james/site-cms/trunk/content/xdoc/config-nntp.xml
URL: http://svn.apache.org/viewvc/james/site-cms/trunk/content/xdoc/config-nntp.xml?rev=1338063&view=auto
==============================================================================
--- james/site-cms/trunk/content/xdoc/config-nntp.xml (added)
+++ james/site-cms/trunk/content/xdoc/config-nntp.xml Mon May 14 08:45:02 2012
@@ -0,0 +1,98 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.    
+-->
+<document>
+
+ <properties>
+  <title>Apache James Server 3 - Configuring the NNTP Service</title>
+ </properties>
+
+<body>
+<section name="NNTP Configuration">
+<p>The NNTP service is controlled by a two configuration blocks in the config.xml.  These are the nntpserver block and the nntp-repository block.</p>
+<subsection name="The nntpserver block">
+<p>The nntpserver tag defines the boundaries of the configuration block.  It encloses 
+much of the relevant configuration for the NNTP server.</p>
+
+<p>This tag has an optional boolean attribute - <strong>enabled</strong> - that defines whether the service is active or not.  The value defaults to "true" if
+not present.</p>
+<p>The standard children of the nntpserver tag are:</p>
+<ul>
+<li><strong>port</strong> - This is an optional integer value.  This value is the port on which this NNTP server is configured 
+to listen.If the tag or value is omitted, the value will default to the standard NNTP port, 119.</li>
+<li><strong>bind</strong> - This is an optional value.  If present, this value is a string describing 
+the IP address to which this service should be bound.  If the tag or value is absent then the service 
+will bind to all network interfaces for the machine.</li>
+<li><strong>useTLS</strong> - This is an optional boolean value.  If this value is true, then the "ssl"
+server socket factory is used to generate the server socket for this service.  If it is false, the 
+"plain" server socket factory is used.  In either case this behavior is overridden by the serverSocketType 
+tag which is described under the expert configuration options.</li>
+<li><strong>handler</strong> - This is an artifact preserved for backwards compatibility.  This tag 
+was used to group related parameters.  It should disappear in future versions.</li>
+<ul>
+<li><strong>helloName</strong> - This is a required tag with an optional body that defines the server name 
+used in the initial service greeting.  The tag may have an optional attribute - <strong>autodetect</strong>.  If 
+the autodetect attribute is present and true, the service will use the local hostname
+returned by the Java libraries.  If autodetect is absent or false, the body of the tag will be used.  In
+this case, if no body is present, the value "localhost" will be used.</li>
+<li><strong>connectionTimeout</strong> - This is an optional tag with a non-negative integer body.  </li>
+<li><strong>authRequired</strong> - This is an optional tag with a boolean body.  If true, then the server will 
+require authentication before allowing the client to view news articles.  If this tag is absent, or the value 
+is false then the client will not be prompted for authentication.  Only simple user/password authentication is
+supported at this time.</li>
+</ul>
+</ul>
+<p>There are a few additional children of the nntpserver tag that are appropriate for advanced 
+configurations.  These should only be used by expert administrators.  All tags in this group are optional.</p>
+<ul>
+<li><strong>serverSocketFactory</strong> - This is an optional tag with a string body.  If the tag is present, 
+the body must be the name of one of the server socket factories specified in the socket manager block.  Any other 
+value will result in an error.  If present, this tag overrides the useTLS tag.</li>
+<li><strong>threadGroup</strong> - This is an optional tag with a string body.  If the tag is present, 
+the body must be the name of one of the thread groups specified in the thread manager block.  Any other 
+value will result in an error.  This tag is best used to fine tune thread allocation between the services.</li>
+<li><strong>connectionLimit</strong> - The connectionLimit parameter specifies the maximum number of client 
+connections that this service will allow.  If no value is specified, the value defaults to that specified in 
+the connectionmanager block.  A value of 0 means that there is no limit imposed 
+by the service, although resource limitations imposed by other components 
+(i.e. max # of threads) may serve to limit the number of open connections.</li>
+</ul>
+</subsection>
+<subsection name="The nntp-repository block">
+The remainder of the NNTP service configuration is controlled by the nntp-repository configuration block.  This
+section of configuration data relates to the server-side NNTP article repository.
+<ul>
+<li><strong>readOnly</strong> - This is a required boolean tag.  If the value is true, posting will not be 
+permitted by the NNTP server.</li>
+<li><strong>rootPath</strong> - This is a required string tag.  It must be in the form of a URL with a "file:" prefix.  This 
+specifies the root directory for the NNTP repository.  Groups hosted on the NNTP server will be represented as 
+folders under this root, and articles will be stored in the appropriate folders.</li>
+<li><strong>tempPath</strong> - This is a required string tag.  It must be in the form of a URL with a "file:" prefix.  This 
+specifies the directory where the NNTP server will store posted articles before they are added to the spool.</li>
+<li><strong>articleIDPath</strong> - This is a required string tag.  It must be in the form of a URL with a "file:" prefix.  This 
+specifies the directory where the NNTP server will store the mappings between article ID and the groups containing that article.</li>
+<li><strong>articleIDDomainSuffix</strong> - This is a required string tag.  It is the suffix appended to all article IDs generated
+by this NNTP server.</li>
+<li><strong>newsgroups</strong> - This is a required container tag.  It has a single <strong>newsgroup</strong> child for each newsgroup 
+hosted on the server.  The body of each of those <strong>newsgroup</strong> tags is the name of the newsgroup.</li>
+</ul>
+</subsection>
+</section>
+</body>
+</document>

Propchange: james/site-cms/trunk/content/xdoc/config-nntp.xml
------------------------------------------------------------------------------
    svn:keywords = Id Author Revision HeadURL

Added: james/site-cms/trunk/content/xdoc/config-pop3.xml
URL: http://svn.apache.org/viewvc/james/site-cms/trunk/content/xdoc/config-pop3.xml?rev=1338063&view=auto
==============================================================================
--- james/site-cms/trunk/content/xdoc/config-pop3.xml (added)
+++ james/site-cms/trunk/content/xdoc/config-pop3.xml Mon May 14 08:45:02 2012
@@ -0,0 +1,77 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.    
+-->
+<document>
+
+ <properties>
+  <title>Apache James Server 3 - Configuring the POP3 Service</title>
+ </properties>
+
+<body>
+
+  <section name="POP3 Configuration">
+  
+    <p>Consult <a href="https://svn.apache.org/repos/asf/james/app/tags/apache-james-3.0-beta4/src/main/resources/pop3server-template.conf">pop3server-template.conf</a> in SVN to get some examples and hints.</p>
+
+    <p>The POP3 service is controlled by a configuration block in the pop3server.xml.
+       The pop3server tag defines the boundaries of the configuration block.  It encloses 
+       all the relevant configuration for the POP3 server.  The behavior of the POP service is
+       controlled by the attributes and children of this tag.</p>
+    
+    <p>This tag has an optional boolean attribute - <strong>enabled</strong> - that defines whether the service is active or not.  The value defaults to "true" if
+       not present.</p>
+    
+    <p>The standard children of the pop3server tag are:</p>
+
+      <dl>
+        <dt><strong>bind</strong></dt>
+        <dd>Configure this to bind to a specific inetaddress. This is an optional integer value.  This value is the port on which this POP3 server is configured 
+      to listen. If the tag or value is absent then the service 
+      will bind to all network interfaces for the machine If the tag or value is omitted, the value will default to the standard POP3 port, 11
+    port 995 is the well-known/IANA registered port for POP3S  ie over SSL/TLS 
+    port 110 is the well-known/IANA registered port for Standard POP3</dd>
+        <dt><strong>connectionBacklog</strong></dt>
+        <dd></dd>
+        <dt><strong>tls</strong></dt>
+        <dd>Set to true to support STARTTLS or SSL for the Socket.
+         To use this you need to copy sunjce_provider.jar to /path/james/lib directory. To create a new keystore execute:
+             keytool -genkey -alias james -keyalg RSA -keystore /path/to/james/conf/keystore</dd>
+        <dt><strong>handler.helloName</strong></dt>
+        <dd>This is the name used by the server to identify itself in the POP3 
+        protocol.  If autodetect is TRUE, the server will discover its 
+        own host name and use that in the protocol.  If discovery fails, 
+        the value of 'localhost' is used.  If autodetect is FALSE, James 
+        will use the specified value.</dd>
+        <dt><strong>handler.connectiontimeout</strong></dt>
+        <dd>Connection timeout in secconds</dd>
+        <dt><strong>handler.connectionLimit</strong></dt>
+        <dd>Set the maximum simultaneous incoming connections for this service</dd>
+        <dt><strong>handler.connectionLimitPerIP</strong></dt>
+        <dd>Set the maximum simultaneous incoming connections per IP for this service</dd>
+        <dt><strong>handler.handlerchain</strong></dt>
+        <dd>This loads the core CommandHandlers. Only remove this if you really 
+             know what you are doing</dd>
+      </dl>
+
+  </section>
+
+</body>
+
+</document>
+

Propchange: james/site-cms/trunk/content/xdoc/config-pop3.xml
------------------------------------------------------------------------------
    svn:keywords = Id Author Revision HeadURL



---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org