http://git-wip-us.apache.org/repos/asf/james-site/blob/f81a00ef/content/server/config-events.html ---------------------------------------------------------------------- diff --git a/content/server/config-events.html b/content/server/config-events.html new file mode 100644 index 0000000..28d1b17 --- /dev/null +++ b/content/server/config-events.html @@ -0,0 +1,488 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";> +<!-- Generated by Apache Maven Doxia at 2016-12-06 --> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <title>Apache James Server 3.0 - + Apache James Server 3 - Quota Configuration</title> + <style type="text/css" media="all"> + @import url("./css/james.css"); + @import url("./css/maven-base.css"); + @import url("./css/maven-theme.css"); + @import url("./css/site.css"); + @import url("./js/jquery/css/custom-theme/jquery-ui-1.8.5.custom.css"); + @import url("./js/jquery/css/print.css"); + @import url("./js/fancybox/jquery.fancybox-1.3.4.css"); + </style> + <script type="text/javascript" src="./js/jquery/js/jquery-1.4.2.min.js"></script> + <script type="text/javascript" src="./js/jquery/js/jquery-ui-1.8.5.custom.min.js"></script> + <script type="text/javascript" src="./js/fancybox/jquery.fancybox-1.3.4.js"></script> + <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" /> + <meta name="Date-Revision-yyyymmdd" content="20161206" /> + <meta http-equiv="Content-Language" content="en" /> + +<link title="DOAP" rel="meta" type="application/rdf+xml" href="http://james.apache.org//doap_james-project.rdf"/> + + <!-- Google Analytics --> + <script type="text/javascript"> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-1384591-1']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script').item(0); s.parentNode.insertBefore(ga, s); + })(); + + </script> + </head> + <body class="composite"> + <div id="banner"> + <a href="../index.html" id="bannerLeft" title="james-logo.png"> + + + <img src="images/logos/james-logo.png" alt="Apache James Server 3.0" /> + </a> + <a href="http://www.apache.org/index.html"; id="bannerRight"> + + + <img src="images/logos/asf_logo_small.png" alt="The Apache Software Foundation" /> + </a> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + <div class="xleft"> + <span id="publishDate">Last Published: 2016-12-06</span> + </div> + <div class="xright"> <a href="../../index.html" title="Home">Home</a> + | + <a href="../index.html" title="Server">Server</a> + | + <a href="../../hupa/index.html" title="Hupa">Hupa</a> + | + <a href="../../protocols/index.html" title="Protocols">Protocols</a> + | + <a href="../../mailet/index.html" title="Mailets">Mailets</a> + | + <a href="../../mailbox/index.html" title="Mailbox">Mailbox</a> + | + <a href="../../mime4j/index.html" title="Mime4J">Mime4J</a> + | + <a href="../../jsieve/index.html" title="jSieve">jSieve</a> + | + <a href="../../jspf/index.html" title="jSPF">jSPF</a> + | + <a href="../../jdkim/index.html" title="jDKIM">jDKIM</a> + | + <a href="../../mpt/index.html" title="MPT">MPT</a> + | + <a href="../../postage/index.html" title="Postage">Postage</a> + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + <h5>Overview</h5> + <ul> + <li class="none"> + <a href="index.html" title="Introduction">Introduction</a> + </li> + <li class="none"> + <a href="release-notes.html" title="Release Notes">Release Notes</a> + </li> + </ul> + <h5>Features</h5> + <ul> + <li class="none"> + <a href="feature-mailetcontainer.html" title="Mailet Container">Mailet Container</a> + </li> + <li class="none"> + <a href="feature-queue-priority.html" title="Queue Priority">Queue Priority</a> + </li> + <li class="none"> + <a href="feature-persistence.html" title="Persistence">Persistence</a> + </li> + <li class="none"> + <a href="feature-protocols.html" title="Protocols">Protocols</a> + </li> + <li class="none"> + <a href="feature-smtp-hooks.html" title="SMTP Hooks">SMTP Hooks</a> + </li> + <li class="none"> + <a href="feature-performance.html" title="Performance">Performance</a> + </li> + <li class="none"> + <a href="feature-security.html" title="Security">Security</a> + </li> + </ul> + <h5>User Manual</h5> + <ul> + <li class="none"> + <a href="quick-start.html" title="1. Quick Start">1. Quick Start</a> + </li> + <li class="none"> + <a href="install.html" title="2. Install James">2. Install James</a> + </li> + <li class="collapsed"> + <a href="config.html" title="3. Configure James">3. Configure James</a> + </li> + <li class="collapsed"> + <a href="manage.html" title="4. Manage">4. Manage</a> + </li> + <li class="collapsed"> + <a href="monitor.html" title="5. Monitor">5. Monitor</a> + </li> + <li class="collapsed"> + <a href="upgrade.html" title="6. Upgrade">6. Upgrade</a> + </li> + </ul> + <h5>Developers Corner</h5> + <ul> + <li class="none"> + <a href="dev.html" title="Architecture">Architecture</a> + </li> + <li class="none"> + <a href="dev-build.html" title="Build from source">Build from source</a> + </li> + <li class="none"> + <a href="dev-database-schema.html" title="Database Schema">Database Schema</a> + </li> + <li class="collapsed"> + <a href="dev-extend.html" title="Develop Extensions">Develop Extensions</a> + </li> + <li class="collapsed"> + <a href="dev-provided.html" title="Provided Extensions">Provided Extensions</a> + </li> + </ul> + <h5>References</h5> + <ul> + <li class="none"> + <a href="apidocs/index.html" title="Javadoc">Javadoc</a> + </li> + <li class="none"> + <a href="https://issues.apache.org/jira/browse/JAMES"; title="Issue Tracker">Issue Tracker</a> + </li> + </ul> + <h5>About James</h5> + <ul> + <li class="none"> + <a href="../../index.html" title="Overview">Overview</a> + </li> + <li class="none"> + <a href="../../newsarchive.html" title="News">News</a> + </li> + <li class="none"> + <a href="../../mail.html" title="Mailing Lists">Mailing Lists</a> + </li> + <li class="none"> + <a href="../../contribute.html" title="Contributing">Contributing</a> + </li> + <li class="none"> + <a href="../../guidelines.html" title="Guidelines">Guidelines</a> + </li> + <li class="none"> + <a href="http://wiki.apache.org/james"; title="Wiki">Wiki</a> + </li> + <li class="none"> + <a href="../../team-list.html" title="Who We Are">Who We Are</a> + </li> + <li class="none"> + <a href="../../license.html" title="License">License</a> + </li> + <li class="none"> + <a href="../../thanks.html" title="Thanks">Thanks</a> + </li> + <li class="none"> + <a href="../../support.html" title="Professional support">Professional support</a> + </li> + </ul> + <h5>Download</h5> + <ul> + <li class="none"> + <a href="../../download.cgi" title="Releases">Releases</a> + </li> + </ul> + <h5>Apache Software Foundation</h5> + <ul> + <li> + <strong> + <a title="ASF" href="http://www.apache.org/";>ASF</a> + </strong> + </li> + <li> + <a title="Get Involved" href="http://www.apache.org/foundation/getinvolved.html";>Get Involved</a> + </li> + <li> + <a title="FAQ" href="http://www.apache.org/foundation/faq.html";>FAQ</a> + </li> + <li> + <a title="License" href="http://www.apache.org/licenses/"; >License</a> + </li> + <li> + <a title="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a> + </li> + <li> + <a title="Thanks" href="http://www.apache.org/foundation/thanks.html";>Thanks</a> + </li> + <li> + <a title="Security" href="http://www.apache.org/security/";>Security</a> + </li> + </ul> + <a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"> + <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /> + </a> + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <!-- 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. --> + + + + <div class="section"> +<h2>Events System Configuration<a name="Events_System_Configuration"></a></h2> + + +<p>Consult <a class="externalLink" href="https://github.com/apache/james-project/tree/master/server/app/src/main/resources/events-template.xml";>events-template.xml</a> in GIT to get some examples and hints.</p> + + +<p>Use this configuration to define the type of Event System you want.</p> + + +<p> + James relies on an event system. Each operations performed on the mailbox will trigger related events. Some software + components (MailboxListeners) can register themselves on this event system to be called when an event is fired. + </p> + + +<p> + Here are typical use cases for Mailbox Listeners (non exhaustive list) : + </p> +<ul> + +<li>Message search indexation, for instance in Lucene or ElasticSearch</li> + +<li>Local cache invalidation (caching mailbox project)</li> + +<li>Quota calculation</li> + +<li>IMAP IDLE feature : live notification of actions performed on a mailbox, allowing publish subscribe on mailboxes events</li> + +<li>Message Sequence Number consistence</li> + </ul> + The Mailbox Listeners can be classified in two categories : + +<ul> + +<li>Mailbox registered : The mailbox listener is only notified on events affecting this mailbox. IDLE is a good example of this.</li> + +<li>Global Listeners : This event listener is triggered upon each events.</li> + </ul> + Note that Global Listeners can also be classified in two categories : + +<ul> + +<li>Those which needs to be triggered only once in your cluster. For instance ElasticSearch indexing is an example of this.</li> + +<li>Those which needs to be triggered on each servers. For instance, each Lucene indexer needs to be triggered on each server + for the search feature to stay consistent.</li> + </ul> + + + +<p> + The default implementation is a synchronous in memory event system. The performance are really good, as their is no need to serialize + events, and no network overhead. However, this event system is limited to one computer and you might want a distributed systems. + </p> + + +<p> + Other implementations, distributed environment friendly are available. + </p> + + +<p> + The simplest one is broadcast based. Each James servers listen the same message queue, and each James server will be notified upon events. + Here are the pros and cons of this implementations : + </p> +<ul> + Pros: + +<li>It supports every type of listener described above</li> + +<li>It allows you to scale your James infrastructure without changing your middlewares. You just need a message queue</li> + Cons : + +<li>Your scalability is limited as each servers is notified on all events</li> + +<li>Network overhead on event transmissions</li> + +<li>Event serialization and deserialization</li> + </ul> + To use this implementation, you need two other components (that will be discussed) : a publishing system and an event serializer + + + +<p> + The other mode is based on registrations. + Each server reads messages from a dedicated message queue, and other servers send messages addressed to this sever on this message queue. + Registrations are performed on an eternal data-store supporting document deletion after a fixed amount of time. + These registrations are periodically refreshed. This data-store is then triggered on event generation, that, if needed are serialized and + send to the given queues. + The pros and cons of this implementations are : + </p> +<ul> + Pros : + +<li>Linear scalability</li> + +<li>A server receives only events concerning him</li> + Cons : + +<li>Possible event serialization costs</li> + +<li>Registration and registration refresh costs</li> + +<li>Need to find interested servers on event delivery</li> + +<li>Network overhead on event transmissions</li> + </ul> + + + +<div class="section"> +<h2>Failure modes<a name="Failure_modes"></a></h2> + + +<ul> + Default implementation : + +<li>The default implementation might not deliver some events on server stop.</li> + </ul> + + +<ul> + Broadcast implementation : + +<li>The broadcast implementation might not deliver some events on server stop.</li> + +<li>The broadcast implementation is tight to limitation of the underlying publisher.</li> + </ul> + + +<ul> + Registered implementation : + +<li>The registered implementation might not deliver some events on server stop.</li> + +<li>The registered implementation is tight to limitation of the underlying publisher, and underlying registration system.</li> + </ul> + + +<div class="section"> +<h2>Publisher<a name="Publisher"></a></h2> + + +<p> + Available implementation is Kafka based. Kafka ensure at least one delivery. This means some messages might be + delivered two times. You need to compile and run James using Java 8 in order to use the Kafka messaging system. + </p> + + +<div class="section"> +<h2>Event serializer<a name="Event_serializer"></a></h2> + + +<p>There are two types of event serialization systems : + </p> +<ul> + +<li>Json : events are converted to JSON</li> + +<li>Message Pack : a binary representation of JSON. 2 times smaller in average but two times longer to compute. It allows you to trade + bandwidth and data readability against CPU time.</li> + </ul> + + + +<div class="section"> +<h2>Registration systems<a name="Registration_systems"></a></h2> + + +<p> + Available implementation is based on Cassandra. It is used on an AP fashion, enforcing availability instead of consistency. Some + messages might get delivered to no more registered servers. This is just extra work. Worst, messages might not be delivered to + recently registered servers. But we make sure that we have the more up to date version of the registrations we can, and will not time out in + the face of network partitions, nor enforce some default behaviour. + </p> + + </div> + + + + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">Copyright © 2002-2016 + <a href="https://www.apache.org/";>The Apache Software Foundation</a>. + All Rights Reserved. + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
http://git-wip-us.apache.org/repos/asf/james-site/blob/f81a00ef/content/server/config-fetchmail.html ---------------------------------------------------------------------- diff --git a/content/server/config-fetchmail.html b/content/server/config-fetchmail.html new file mode 100644 index 0000000..66d84fe --- /dev/null +++ b/content/server/config-fetchmail.html @@ -0,0 +1,1728 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";> +<!-- Generated by Apache Maven Doxia at 2016-12-06 --> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <title>Apache James Server 3.0 - + Apache James Server 3 - Fetchmail Configuration</title> + <style type="text/css" media="all"> + @import url("./css/james.css"); + @import url("./css/maven-base.css"); + @import url("./css/maven-theme.css"); + @import url("./css/site.css"); + @import url("./js/jquery/css/custom-theme/jquery-ui-1.8.5.custom.css"); + @import url("./js/jquery/css/print.css"); + @import url("./js/fancybox/jquery.fancybox-1.3.4.css"); + </style> + <script type="text/javascript" src="./js/jquery/js/jquery-1.4.2.min.js"></script> + <script type="text/javascript" src="./js/jquery/js/jquery-ui-1.8.5.custom.min.js"></script> + <script type="text/javascript" src="./js/fancybox/jquery.fancybox-1.3.4.js"></script> + <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" /> + <meta name="Date-Revision-yyyymmdd" content="20161206" /> + <meta http-equiv="Content-Language" content="en" /> + +<link title="DOAP" rel="meta" type="application/rdf+xml" href="http://james.apache.org//doap_james-project.rdf"/> + + <!-- Google Analytics --> + <script type="text/javascript"> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-1384591-1']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script').item(0); s.parentNode.insertBefore(ga, s); + })(); + + </script> + </head> + <body class="composite"> + <div id="banner"> + <a href="../index.html" id="bannerLeft" title="james-logo.png"> + + + <img src="images/logos/james-logo.png" alt="Apache James Server 3.0" /> + </a> + <a href="http://www.apache.org/index.html"; id="bannerRight"> + + + <img src="images/logos/asf_logo_small.png" alt="The Apache Software Foundation" /> + </a> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + <div class="xleft"> + <span id="publishDate">Last Published: 2016-12-06</span> + </div> + <div class="xright"> <a href="../../index.html" title="Home">Home</a> + | + <a href="../index.html" title="Server">Server</a> + | + <a href="../../hupa/index.html" title="Hupa">Hupa</a> + | + <a href="../../protocols/index.html" title="Protocols">Protocols</a> + | + <a href="../../mailet/index.html" title="Mailets">Mailets</a> + | + <a href="../../mailbox/index.html" title="Mailbox">Mailbox</a> + | + <a href="../../mime4j/index.html" title="Mime4J">Mime4J</a> + | + <a href="../../jsieve/index.html" title="jSieve">jSieve</a> + | + <a href="../../jspf/index.html" title="jSPF">jSPF</a> + | + <a href="../../jdkim/index.html" title="jDKIM">jDKIM</a> + | + <a href="../../mpt/index.html" title="MPT">MPT</a> + | + <a href="../../postage/index.html" title="Postage">Postage</a> + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + <h5>Overview</h5> + <ul> + <li class="none"> + <a href="index.html" title="Introduction">Introduction</a> + </li> + <li class="none"> + <a href="release-notes.html" title="Release Notes">Release Notes</a> + </li> + </ul> + <h5>Features</h5> + <ul> + <li class="none"> + <a href="feature-mailetcontainer.html" title="Mailet Container">Mailet Container</a> + </li> + <li class="none"> + <a href="feature-queue-priority.html" title="Queue Priority">Queue Priority</a> + </li> + <li class="none"> + <a href="feature-persistence.html" title="Persistence">Persistence</a> + </li> + <li class="none"> + <a href="feature-protocols.html" title="Protocols">Protocols</a> + </li> + <li class="none"> + <a href="feature-smtp-hooks.html" title="SMTP Hooks">SMTP Hooks</a> + </li> + <li class="none"> + <a href="feature-performance.html" title="Performance">Performance</a> + </li> + <li class="none"> + <a href="feature-security.html" title="Security">Security</a> + </li> + </ul> + <h5>User Manual</h5> + <ul> + <li class="none"> + <a href="quick-start.html" title="1. Quick Start">1. Quick Start</a> + </li> + <li class="none"> + <a href="install.html" title="2. Install James">2. Install James</a> + </li> + <li class="expanded"> + <a href="config.html" title="3. Configure James">3. Configure James</a> + <ul> + <li class="none"> + <a href="config-system.html" title="System">System</a> + </li> + <li class="none"> + <a href="config-domainlist.html" title="Domain List">Domain List</a> + </li> + <li class="none"> + <a href="config-users.html" title="Users">Users</a> + </li> + <li class="none"> + <a href="config-recipientrewritetable.html" title="Recipient Rewrite">Recipient Rewrite</a> + </li> + <li class="none"> + <a href="config-mailbox.html" title="Mailbox">Mailbox</a> + </li> + <li class="none"> + <a href="config-mailrepositorystore.html" title="Mail Repository Stores">Mail Repository Stores</a> + </li> + <li class="none"> + <a href="config-dnsservice.html" title="DNS Service">DNS Service</a> + </li> + <li class="none"> + <a href="config-smtp-lmtp.html" title="SMTP LMTP">SMTP LMTP</a> + </li> + <li class="none"> + <a href="config-pop3.html" title="POP3">POP3</a> + </li> + <li class="none"> + <a href="config-imap4.html" title="IMAP4">IMAP4</a> + </li> + <li class="none"> + <a href="config-mailetcontainer.html" title="Mailet Container">Mailet Container</a> + </li> + <li class="none"> + <strong>FetchMail</strong> + </li> + <li class="none"> + <a href="config-ssl-tls.html" title="SSL/TLS">SSL/TLS</a> + </li> + <li class="none"> + <a href="config-sieve.html" title="Sieve">Sieve</a> + </li> + <li class="none"> + <a href="config-antispam.html" title="Anti Spam">Anti Spam</a> + </li> + </ul> + </li> + <li class="collapsed"> + <a href="manage.html" title="4. Manage">4. Manage</a> + </li> + <li class="collapsed"> + <a href="monitor.html" title="5. Monitor">5. Monitor</a> + </li> + <li class="collapsed"> + <a href="upgrade.html" title="6. Upgrade">6. Upgrade</a> + </li> + </ul> + <h5>Developers Corner</h5> + <ul> + <li class="none"> + <a href="dev.html" title="Architecture">Architecture</a> + </li> + <li class="none"> + <a href="dev-build.html" title="Build from source">Build from source</a> + </li> + <li class="none"> + <a href="dev-database-schema.html" title="Database Schema">Database Schema</a> + </li> + <li class="collapsed"> + <a href="dev-extend.html" title="Develop Extensions">Develop Extensions</a> + </li> + <li class="collapsed"> + <a href="dev-provided.html" title="Provided Extensions">Provided Extensions</a> + </li> + </ul> + <h5>References</h5> + <ul> + <li class="none"> + <a href="apidocs/index.html" title="Javadoc">Javadoc</a> + </li> + <li class="none"> + <a href="https://issues.apache.org/jira/browse/JAMES"; title="Issue Tracker">Issue Tracker</a> + </li> + </ul> + <h5>About James</h5> + <ul> + <li class="none"> + <a href="../../index.html" title="Overview">Overview</a> + </li> + <li class="none"> + <a href="../../newsarchive.html" title="News">News</a> + </li> + <li class="none"> + <a href="../../mail.html" title="Mailing Lists">Mailing Lists</a> + </li> + <li class="none"> + <a href="../../contribute.html" title="Contributing">Contributing</a> + </li> + <li class="none"> + <a href="../../guidelines.html" title="Guidelines">Guidelines</a> + </li> + <li class="none"> + <a href="http://wiki.apache.org/james"; title="Wiki">Wiki</a> + </li> + <li class="none"> + <a href="../../team-list.html" title="Who We Are">Who We Are</a> + </li> + <li class="none"> + <a href="../../license.html" title="License">License</a> + </li> + <li class="none"> + <a href="../../thanks.html" title="Thanks">Thanks</a> + </li> + <li class="none"> + <a href="../../support.html" title="Professional support">Professional support</a> + </li> + </ul> + <h5>Download</h5> + <ul> + <li class="none"> + <a href="../../download.cgi" title="Releases">Releases</a> + </li> + </ul> + <h5>Apache Software Foundation</h5> + <ul> + <li> + <strong> + <a title="ASF" href="http://www.apache.org/";>ASF</a> + </strong> + </li> + <li> + <a title="Get Involved" href="http://www.apache.org/foundation/getinvolved.html";>Get Involved</a> + </li> + <li> + <a title="FAQ" href="http://www.apache.org/foundation/faq.html";>FAQ</a> + </li> + <li> + <a title="License" href="http://www.apache.org/licenses/"; >License</a> + </li> + <li> + <a title="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a> + </li> + <li> + <a title="Thanks" href="http://www.apache.org/foundation/thanks.html";>Thanks</a> + </li> + <li> + <a title="Security" href="http://www.apache.org/security/";>Security</a> + </li> + </ul> + <a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"> + <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /> + </a> + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <!-- 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. --> + + + + <div class="section"> +<h2>Fetchmail Configuration<a name="Fetchmail_Configuration"></a></h2> + + +<p>Consult <a class="externalLink" href="https://github.com/apache/james-project/tree/master/server/app/src/main/resources/fetchmail-template.xml";>fetchmail-template.xml</a> in GIT 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> + + </div> + + +<div class="section"> +<h2>How Fetchmail Works<a name="How_Fetchmail_Works"></a></h2> + + +<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 <alllocal> 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 <alllocal> account, it is always possible to deduce + the intended recipient when the recipient is a James user.</p> + </div> + + +<div class="section"> +<h2>Fetchmail Configuration Parameters<a name="Fetchmail_Configuration_Parameters"></a></h2> + + +<p>The Fetchmail configuration parameters are part of the James configuration, + whose base file is <tt>fetchmail.xml</tt>. For clarity and flexibility, the + Fetchmail configuration parameters are stored in the file + <tt>james-Fetchmail.xml</tt>, which is referenced within + <tt>fetchmail.xml</tt>.</p> + + +<p>The configuration parameters are described below.</p> + + +<div class="section"> +<h3>Fetchmail<a name="Fetchmail"></a></h3> + +<p>The configuration block delimited by the <b>Fetchmail</b> tag + controls Fetchmail.</p> + + +<p>The tag has these attributes: + </p> +<dl> + +<dt><b>enabled</b></dt> + +<dd>A boolean. If "true", the fetch tasks will be run periodically. If "false", + no fetch tasks will be run. The default is "false".</dd> + </dl> + + + +<p>The tag has these child tags (minimum cardinality, maximum cardinality): + </p> +<ul> + +<li><b><a href="#fetch">fetch</a></b> (0, *)</li> + </ul> + + + +<p> + </p> +<div class="source"> +<pre> + <Fetchmail enabled="true"> + ... + </Fetchmail> + </pre></div> + + </div> + + +<div class="section"> +<h3>fetch<a name="fetch"></a></h3> + +<p>The <b>fetch</b> tag defines a fetch task to be run + periodically. Fetch tasks run concurrently.</p> + + +<p>The tag has these attributes: + </p> +<dl> + +<dt><b>name</b></dt> + +<dd>A string uniquely identifying the fetch task.</dd> + </dl> + + + +<p>The tag has these child tags (minimum cardinality, maximum cardinality): + </p> +<ul> + +<li><b><a href="#accounts">accounts</a></b> (1, 1)</li> + +<li><b><a href="#blacklist">blacklist</a></b> (1, 1)</li> + +<li><b><a href="#defaultdomain">defaultdomain</a></b> (0, 1)</li> + +<li><b><a href="#fetchall">fetchall</a></b> (1, 1)</li> + +<li><b><a href="#fetched">fetched</a></b> (1, 1)</li> + +<li><b><a href="#host">host</a></b> (1, 1)</li> + +<li><b><a href="#interval">interval</a></b> (1, 1)</li> + +<li><b><a href="#javaMailFolderName">javaMailFolderName</a></b> (1, 1)</li> + +<li><b><a href="#javaMailProperties">javaMailProperties</a></b> (0, 1)</li> + +<li><b><a href="#javaMailProviderName">javaMailProviderName</a></b> (1, 1)</li> + +<li><b><a href="#maxmessagesize">maxmessagesize</a></b> (0, 1)</li> + +<li><b><a href="#recipientnotfound">recipientnotfound</a></b> (1, 1)</li> + +<li><b><a href="#recursesubfolders">recursesubfolders</a></b> (1, 1)</li> + +<li><b><a href="#remoteReceivedHeader">remoteReceivedHeader</a></b> (0, 1)</li> + +<li><b><a href="#remoterecipient">remoterecipient</a></b> (1, 1)</li> + +<li><b><a href="#undeliverable">undeliverable</a></b> (1, 1)</li> + +<li><b><a href="#userundefined">userundefined</a></b> (1, 1)</li> + </ul> + + + +<p> + </p> +<div class="source"> +<pre> + <fetch name="mydomain.com"> + ... + </fetch> + </pre></div> + + </div> + + +<div class="section"> +<h3>accounts<a name="accounts"></a></h3> + +<p>The <b>accounts</b> 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): + </p> +<ul> + +<li><b><a href="#account">account</a></b> (0, *)</li> + +<li><b><a href="#alllocal">alllocal</a></b> (0, 1)</li> + </ul> + + + +<p> + </p> +<div class="source"> +<pre> + <accounts> + ... + </accounts> + </pre></div> + + </div> + + +<div class="section"> +<h3>blacklist<a name="blacklist"></a></h3> + +<p>The <b>blacklist</b> 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: <tt>[email protected], [email protected]</tt>.</p> + + +<p>The tag has these attributes: + </p> +<dl> + +<dt><b>reject</b></dt> + +<dd>A boolean. If "true", mail for recipients in the blacklist will + not be injected into the James input spool. If "false", mail for + recipients in the blacklist will be injected into the James input spool with the + Mail Attribute <tt>org.apache.james.Fetchmail.isBlacklistedRecipient</tt> + added to the mail.</dd> + +<dt><b>leaveonserver</b></dt> + +<dd>A boolean. If "true", mail for recipients in the blacklist will be + left on the server. If "false", mail for recipients in the blacklist + will be marked for deletion.</dd> + +<dt><b>markseen</b></dt> + +<dd>A boolean. If "true", mail for recipients in the blacklist will be + marked as seen on the server. If "false", mail for recipients in the blacklist + will not be marked as seen.</dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <blacklist + reject="true" + leaveonserver="true" + markseen="true"> + [email protected], [email protected] + </blacklist> + </pre></div> + + </div> + + +<div class="section"> +<h3>defaultdomain<a name="defaultdomain"></a></h3> + +<p>The <b>defaultdomain</b> tag declares the domain name to be + appended to the <tt>From:</tt> 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 <b>servernames</b> tag of the <b>James</b> + block in the configuration or the name <tt>localhost</tt>.</p> + + +<p> + </p> +<div class="source"> +<pre> + <defaultdomain> + mydomain.com + </defaultdomain> + </pre></div> + + </div> + + +<div class="section"> +<h3>fetchall<a name="fetchall"></a></h3> + +<p>The <b>fetchall</b> 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> + </p> +<div class="source"> +<pre> + <fetchall>false</fetchall> + </pre></div> + + </div> + + +<div class="section"> +<h3>fetched<a name="fetched"></a></h3> + +<p>The <b>fetched</b> 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: + </p> +<dl> + +<dt><b>leaveonserver</b></dt> + +<dd>A boolean. If "true", mail injected into the James input spool + will be left on the server. If "false", mail injected into the James + input spool will be marked for deletion.</dd> + +<dt><b>markseen</b></dt> + +<dd>A boolean. If "true", mail injected into the James input spool + will be marked as seen on the server. If "false", mail injected into + the James input spool will not be marked as seen.</dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <fetched leaveonserver="true" markseen="true"/> + </pre></div> + + </div> + + +<div class="section"> +<h3>host<a name="host"></a></h3> + +<p>The <b>host</b> 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> + </p> +<div class="source"> +<pre> + <host>pop3.server.com</host> + </pre></div> + + </div> + + +<div class="section"> +<h3>interval<a name="interval"></a></h3> + +<p>The <b>interval</b> 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> + </p> +<div class="source"> +<pre> + <interval>60000</interval> + </pre></div> + + </div> + + +<div class="section"> +<h3>javaMailFolderName<a name="javaMailFolderName"></a></h3> + +<p>The <b>javaMailFolderName</b> 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 + <tt>INBOX</tt>.</p> + + +<p> + </p> +<div class="source"> +<pre> + <javaMailFolderName>INBOX</javaMailFolderName> + </pre></div> + + </div> + + +<div class="section"> +<h3>javaMailProperties<a name="javaMailProperties"></a></h3> + +<p>The <b>javaMailProperties</b> tag declares the properties to be + applied to the JavaMail Session used by the fetch task. These override the + properties answered by <tt>System.getProperties()</tt>. Many JavaMail + properties are specific to the JavaMail Provider selected by the + <a href="#javaMailProviderName">javaMailProviderName</a> tag.</p> + + +<p><b>Relying on the default values selected by the Provider can be + inappropriate.</b> 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 class="externalLink" 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 class="externalLink" 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 class="externalLink" 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): + </p> +<ul> + +<li><b><a href="#property">property</a></b> (0, *)</li> + </ul> + + + +<p> + </p> +<div class="source"> +<pre> + <javaMailProperties> + ... + </javaMailProperties> + </pre></div> + + </div> + + +<div class="section"> +<h3>javaMailProviderName<a name="javaMailProviderName"></a></h3> + +<p>The <b>javaMailProviderName</b> 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 + <tt>pop3</tt> or <tt>imap</tt>. The name is used to select the default + Provider for the protocol.</p> + + +<p> + </p> +<div class="source"> +<pre> + <javaMailProviderName>pop3</javaMailProviderName> + </pre></div> + + </div> + + +<div class="section"> +<h3>maxmessagesize<a name="maxmessagesize"></a></h3> + + +<p>The <b>maxmessagesize</b> 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: + </p> +<dl> + +<dt><b>limit</b></dt> + +<dd>An integer. The maximum message size expressed in Kilobytes. If 0, there is + no limit.</dd> + +<dt><b>reject</b></dt> + +<dd>A boolean. If "true", mail whose message size exceeds the maximum + permitted size will not be injected into the James input spool. If + "false", mail whose message size exceeds the maximum permitted size will + have its contents removed, an explanatory error message and the Mail Attribute + <tt>org.apache.james.Fetchmail.isMaxMessageSizeExceeded</tt> added prior to + injection into the James input spool, (see below for the location of an example).</dd> + +<dt><b>leaveonserver</b></dt> + +<dd>A boolean. If "true", mail whose message size exceeds the maximum + permitted size will be left on the server. If "false", mail whose message + size exceeds the maximum permitted size will be marked for deletion.</dd> + +<dt><b>markseen</b></dt> + +<dd>A boolean. If "true", mail whose message size exceeds the maximum + permitted size will be marked as seen on the server. If "false", + mail whose message size exceeds the maximum permitted size will not be marked as + seen.</dd> + </dl> + + + + +<p> + </p> +<div class="source"> +<pre> + <maxmessagesize + limit="4096" + reject="false" + leaveonserver="false" + markseen="false"/> + </pre></div> + + + +<p>An example configuration using James mailet processing to bounce fetched + messages that exceed the maximum permitted size can be found in the file + <tt>$PHOENIX_HOME/apps/james/conf/samples/Fetchmail/maxMessageSize.xml</tt>. + </p> + </div> + + +<div class="section"> +<h3>recipientnotfound<a name="recipientnotfound"></a></h3> + +<p>The <b>recipientnotfound</b> 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: + </p> +<dl> + +<dt><b>defer</b></dt> + +<dd>A boolean. If "true", mail for which a sole intended recipient + cannot be determined is left unprocessed until the next run of the fetch task. + If "false", mail for which a sole intended recipient cannot be + determined is processed immediately.</dd> + +<dt><b>reject</b></dt> + +<dd>A boolean. If "true", mail for which a sole intended recipient + cannot be determined will not be injected into the James input spool. If + "false", 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 + <tt>org.apache.james.Fetchmail.isRecipientNotFound</tt> added to the + mail.</dd> + +<dt><b>leaveonserver</b></dt> + +<dd>A boolean. If "true", mail for which a sole intended recipient + cannot be determined will be left on the server. If "false", mail for + which a sole intended recipient cannot be determined will be marked for + deletion.</dd> + +<dt><b>markseen</b></dt> + +<dd>A boolean. If "true", mail for which a sole intended recipient + cannot be determined will be marked as seen on the server. If "false", + mail for which a sole intended recipient cannot be determined will not be marked + as seen.</dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <recipientnotfound + defer="true" + reject="true" + leaveonserver="true" + markseen="true"/> + </pre></div> + + </div> + + +<div class="section"> +<h3>recursesubfolders<a name="recursesubfolders"></a></h3> + +<p>The <b>recursesubfolders</b> 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> + </p> +<div class="source"> +<pre> + <recursesubfolders>false</recursesubfolders> + </pre></div> + + </div> + + +<div class="section"> +<h3>remoteReceivedHeader<a name="remoteReceivedHeader"></a></h3> + +<p>The <b>remoteReceivedHeader</b> 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 <b>remoteReceivedHeaderIndex</b> should + be set to <b>1</b>. + </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 + <b>remoteReceivedHeaderIndex</b> tag may be omitted or the default + index value of -1 can be specified. This causes the remote address to be set to + <tt>127.0.0.1</tt> and the remote host name to be set to + <tt>localhost</tt>. Matchers almost always considered these values to be + legitimate.</p> + + +<p>The tag has these attributes: + </p> +<dl> + +<dt><b>index</b></dt> + +<dd>An integer whose meaning is described above. + </dd> + +<dt><b>reject</b></dt> + +<dd>A boolean. If "true", mail whose specified recieved header is invalid + will not be injected into the James input spool. If "false", mail whose + specified recieved header is invalid will be injected into the James input spool with + the Mail Attribute <tt>org.apache.james.Fetchmail.isInvalidReceivedHeader</tt> + added to the mail, the remote address set to <tt>127.0.0.1</tt> and the remote + host name set to <tt>localhost</tt>. + </dd> + +<dt><b>leaveonserver</b></dt> + +<dd>A boolean. If "true", mail whose specified recieved header is invalid + will be left on the server. If "false", mail whose specified recieved header + is invalid will be marked for deletion.</dd> + +<dt><b>markseen</b></dt> + +<dd>A boolean. If "true", mail whose specified recieved header is invalid + will be marked as seen on the server. If "false", mail whose specified + recieved header is invalid will not be marked as seen.</dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <remoteReceivedHeader + index="1" + reject="true" + leaveonserver="true" + markseen="true"/> + </pre></div> + + + +<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 + <tt>$PHOENIX_HOME/apps/james/conf/samples/Fetchmail/remoteReceivedHeader.xml</tt>. + </p> + </div> + + +<div class="section"> +<h3>remoterecipient<a name="remoterecipient"></a></h3> + +<p>The <b>remoterecipient</b> 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 <b>servernames</b> tag of the + <b>James</b> block in the configuration.</p> + + +<p>The tag has these attributes: + </p> +<dl> + +<dt><b>reject</b></dt> + +<dd>A boolean. If "true", mail for remote recipients will not be + injected into the James input spool. If "false", mail for remote + recipients will be injected into the James input spool with the Mail Attribute + <tt>org.apache.james.Fetchmail.isRemoteRecipient</tt> added to the mail. + </dd> + +<dt><b>leaveonserver</b></dt> + +<dd>A boolean. If "true", mail for remote recipients will be left on + the server. If "false", mail for remote recipients will be marked for + deletion.</dd> + +<dt><b>markseen</b></dt> + +<dd>A boolean. If "true", mail for remote recipients will be marked as + seen on the server. If "false", mail for remote recipients will not be + marked as seen.</dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <remoterecipient + reject="true" + leaveonserver="true" + markseen="true"/> + </pre></div> + + </div> + + +<div class="section"> +<h3>undeliverable<a name="undeliverable"></a></h3> + +<p>The <b>undeliverable</b> tag declares what happens to mail that + cannot be delivered.</p> + + +<p>The tag has these attributes: + </p> +<dl> + +<dt><b>leaveonserver</b></dt> + +<dd>A boolean. If "true", mail that cannot be delivered will be left + on the server. If "false", mail that cannot be delivered will be + marked for deletion.</dd> + +<dt><b>markseen</b></dt> + +<dd>A boolean. If "true", mail for that cannot be delivered will be + marked as seen on the server. If "false", mail that cannot be + delivered will not be marked as seen.</dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <undeliverable + leaveonserver="true" + markseen="true"/> + </pre></div> + + </div> + + +<div class="section"> +<h3>userundefined<a name="userundefined"></a></h3> + +<p>The <b>userundefined</b> tag declares what happens to mail for + which the recipient is not defined as a James user.</p> + + +<p>The tag has these attributes: + </p> +<dl> + +<dt><b>reject</b></dt> + +<dd>A boolean. If "true", mail for recipients who are not defined as + James users will not be injected into the James input spool. If + "false", mail for recipients who are not defined as James users will + be injected into the James input spool with the Mail Attribute + <tt>org.apache.james.Fetchmail.isUserUndefined</tt> added to the mail. + </dd> + +<dt><b>leaveonserver</b></dt> + +<dd>A boolean. If "true", mail for recipients who are not defined as + James users will be left on the server. If "false", mail for + recipients who are not defined as James users will be marked for deletion.</dd> + +<dt><b>markseen</b></dt> + +<dd>A boolean. If "true", mail for recipients who are not defined as + James users will be marked as seen on the server. If "false", mail + for recipients who are not defined as James users will not be marked as seen. + </dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <userundefined + reject="true" + leaveonserver="true" + markseen="true"/> + </pre></div> + + </div> + + +<div class="section"> +<h3>account<a name="account"></a></h3> + +<p>The <b>account</b> tag declares an account on the external server + from which mail should be fetched.</p> + + +<p>The tag has these attributes: + </p> +<dl> + +<dt><b>user</b></dt> + +<dd>The string to be passed as the user when connecting to the external server. + </dd> + +<dt><b>password</b></dt> + +<dd>The string to be passed as the password when connecting to the external + server.</dd> + +<dt><b>recipient</b></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><b>ignorercpt-header</b></dt> + +<dd>A boolean. If "true", mail is always delivered to the recipient + declared in the <b>recipient</b> attribute above. If + "false", the intended recipient is determined from the mail headers or + the process declared by the <b>recipientnotfound</b> tag. + </dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <account + user="myaccount" + password="mypassword" + recipient="user@localhost" + ignorercpt-header="true"/> + </pre></div> + + </div> + + +<div class="section"> +<h3>alllocal<a name="alllocal"></a></h3> + +<p>The <b>alllocal</b> 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 <b>alllocal</b> 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: + </p> +<dl> + +<dt><b>userprefix</b></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><b>usersuffix</b></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><b>password</b></dt> + +<dd>The string to be passed as the password when connecting to the external + server.</dd> + +<dt><b>recipientprefix</b></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><b>recipientsuffix</b></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><b>ignorercpt-header</b></dt> + +<dd>A boolean. If "true", mail is always delivered to the recipient + constructed from the <b>recipientprefix</b> and + <b>recipientsuffix</b> attributes above and the James user. If + "false", the intended recipient is determined from the mail headers or + the process declared by the <b>recipientnotfound</b> tag. + </dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <alllocal + userprefix="" + usersuffix="@external.domain.com" + password="mypassword" + recipientprefix="" + recipientsuffix="@mydomain.com" + ignorercpt-header="true"/> + </pre></div> + + </div> + + +<div class="section"> +<h3>property<a name="property"></a></h3> + +<p>The <b>property</b> tag declares a name/value pair.</p> + + +<p>The tag has these attributes: + </p> +<dl> + +<dt><b>name</b></dt> + +<dd>The name of the property. + </dd> + +<dt><b>value</b></dt> + +<dd>The value of the property.</dd> + </dl> + + + +<p> + </p> +<div class="source"> +<pre> + <property + name="mail.pop3.connectiontimeout" + value="180000"/> + </pre></div> + + </div> + + </div> + + +<div class="section"> +<h2>Fetchmail Examples<a name="Fetchmail_Examples"></a></h2> + + +<p>Full sources to the examples discussed below can be found in the directory + <tt>$PHOENIX_HOME/apps/james/conf/samples/Fetchmail</tt>.</p> + + +<div class="section"> +<h3>One Account, One User<a name="One_Account_One_User"></a></h3> + +<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 <b>accounts</b> block looks like + this:</p> + + +<p> + </p> +<div class="source"> +<pre> + <accounts> + <account + user="[email protected]" + password="password1" + recipient="user1@localhost" + ignorercpt-header="true"/> + + <account + user="[email protected]" + password="password2" + recipient="user2@localhost" + ignorercpt-header="true"/> + + <account + user="[email protected]" + password="password3" + recipient="user3@localhost" + ignorercpt-header="true"/> + </accounts> + </pre></div> + + </div> + + +<div class="section"> +<h3>One Account, Many Users<a name="One_Account_Many_Users"></a></h3> + +<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 <b>accounts</b> block looks like this:</p> + + +<p> + </p> +<div class="source"> +<pre> + <accounts> + <account + user="[email protected]" + password="password" + recipient="Fetchmail@localhost" + ignorercpt-header="false"/> + </accounts> + </pre></div> + + + +<p>The <b>recipientnotfound</b> 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 + <b>account</b> tag:</p> + + +<p> + </p> +<div class="source"> +<pre> + <recipientnotfound + defer="false" + reject="false" + leaveonserver="false" + markseen="false"/> + </pre></div> + + </div> + + +<div class="section"> +<h3>One Account, One User - Dynamic<a name="One_Account_One_User_-_Dynamic"></a></h3> + +<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 <b>alllocal</b> tag declares the parameters for the dynamic + accounts. The <b>accounts</b> block below will deliver mail for + <tt>[email protected]</tt> to <tt>user1@localhost</tt>, + <tt>[email protected]</tt> to <tt>user2@localhost</tt>, + <tt>[email protected]</tt> to <tt>userZ@localhost</tt> etc.:</p> + + +<p> + </p> +<div class="source"> +<pre> + <accounts> + <alllocal + userprefix="" + usersuffix="@external.domain.com" + password="mypassword" + recipientprefix="" + recipientsuffix="@localhost" + ignorercpt-header="true"/> + </accounts> + </pre></div> + + </div> + + +<div class="section"> +<h3>One Account, Many Users - Dynamic<a name="One_Account_Many_Users_-_Dynamic"></a></h3> + + +<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 <b>alllocal</b> tag declares dynamic + accounts for all local users and the <b>account</b> tag configures an + account to fetch all mail.</p> + + +<p>The <b>recipientnotfound</b> 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 <tt><recipientnotfound defer="true"</tt> 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> + </p> +<div class="source"> +<pre> + <accounts> + <alllocal + userprefix="" + usersuffix="@external.domain.com" + password="mypassword" + recipientprefix="" + recipientsuffix="@localhost" + ignorercpt-header="true"/> + + <account + user="[email protected]" + password="password" + recipient="Fetchmail@localhost" + ignorercpt-header="false"/> + </accounts> + + <recipientnotfound + defer="true" + reject="true" + leaveonserver="true" + markseen="true"/> + </pre></div> + + </div> + + </div> + + +<div class="section"> +<h2>Fetchmail Caveats<a name="Fetchmail_Caveats"></a></h2> + + +<p>These are some things to be aware of when using Fetchmail: + + </p> +<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 <tt>FetchedFrom</tt> + 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 + <tt>org.apache.james.Fetchmail.taskName</tt> 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 + <tt>markseen="true"</tt> will most likely have no effect and + therefore, the <b>fetchall</b> 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 <tt>leaveonserver="false"/></tt>.</li> + + +<li>If using a Exchange 2000 or Exchange 2003 server get sure you fix the CLRF bug. + See <a class="externalLink" href="http://support.microsoft.com/kb/816896/en-us";> Bug description and fix</a></li> + </ul> + + + + </div> + + +<div class="section"> +<h2>Fetchmail Gmail<a name="Fetchmail_Gmail"></a></h2> + + +<p>Use this configuration to fetch Gmail via POP3. Please don't forget to enable POP3 in Gmail (<a class="externalLink" href="http://mail.google.com/support/bin/answer.py?answer=13273";>read how-to</a>).</p> + + +<div class="source"> +<pre> +<fetchmail enabled="true"> +<fetch name="gmail.com"> +<accounts> +<account user="[email protected]" password="YOUR_PASSWORD" recipient="YOUR_EMAIL_ADDRESS_IN_JAMES" ignorercpt-header="true"/> +</accounts> +<host>pop.gmail.com</host> +<interval>600000</interval> +<javaMailProviderName>pop3</javaMailProviderName> +<javaMailFolderName>INBOX</javaMailFolderName> +<javaMailProperties> +<property name="mail.pop3.ssl.enable" value="true"/> +</javaMailProperties> +<fetchall>false</fetchall> +<recursesubfolders>false</recursesubfolders> +<defaultdomain>localhost</defaultdomain> +<fetched leaveonserver="true" markseen="true"/> +<remotereceivedheader index="1" reject="true" leaveonserver="true" markseen="false"/> +<maxmessagesize limit="0" reject="false" leaveonserver="true" markseen="false"/> +<undeliverable leaveonserver="true" markseen="false"/> +<recipientnotfound defer="true" reject="true" leaveonserver="true" markseen="false"/> +<blacklist reject="true" leaveonserver="true" markseen="false"> wibble@localhost, flobble@localhost</blacklist> +<userundefined reject="true" leaveonserver="true" markseen="false" /> +<remoterecipient reject="true" leaveonserver="true" markseen="false" /> +</fetch> +</fetchmail> + </pre></div> + + +<p>Use this configuration to fetch Gmail via IMAP4. Please don't forget to enable IMAP4 in Gmail (<a class="externalLink" href="http://mail.google.com/support/bin/answer.py?answer=77695";>read how-to</a>).</p> + + +<div class="source"> +<pre> +<fetchmail enabled="true"> +<fetch name="gmail.com"> +<accounts> +<account user="[email protected]" password="YOUR_PASSWORD" recipient="YOUR_EMAIL_ADDRESS_IN_JAMES" ignorercpt-header="true"/> +</accounts> +<host>imap.gmail.com</host> +<interval>600000</interval> +<javaMailProviderName>imap</javaMailProviderName> +<javaMailFolderName>INBOX</javaMailFolderName> +<javaMailProperties> +<property name="mail.imap.ssl.enable" value="true"/> +</javaMailProperties> +<fetchall>false</fetchall> +<recursesubfolders>false</recursesubfolders> +<defaultdomain>localhost</defaultdomain> +<fetched leaveonserver="true" markseen="true"/> +<remotereceivedheader index="1" reject="true" leaveonserver="true" markseen="false"/> +<maxmessagesize limit="0" reject="false" leaveonserver="true" markseen="false"/> +<undeliverable leaveonserver="true" markseen="false"/> +<recipientnotfound defer="true" reject="true" leaveonserver="true" markseen="false"/> +<blacklist reject="true" leaveonserver="true" markseen="false"> wibble@localhost, flobble@localhost</blacklist> +<userundefined reject="true" leaveonserver="true" markseen="false" /> +<remoterecipient reject="true" leaveonserver="true" markseen="false" /> +</fetch> +</fetchmail> + </pre></div> + + </div> + + + + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">Copyright © 2002-2016 + <a href="https://www.apache.org/";>The Apache Software Foundation</a>. + All Rights Reserved. + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
