This document explains the JAMES.conf.xml file for James 2.0
JAMES 2.0 uses a date-stamped version of Avalon from late September 2001. The lib directory includes jars with date-stamped names for the Avalon libraries.
These tag elements control the JAMES spooling and identification settings.
| <name> | default value | meaning |
|---|---|---|
| postmaster | Postmaster@localhost | Is the source of error replies and the email users will mail to for any problem. You should change this to an address that can receive incoming messages. |
| helloName | attribute autodetect=TRUE and value of 'myMailServer' | The name by which James will identify itself in SMTP and POP3 greetings. If autodetect is TRUE James will attempt to detect automatically the name, failing which it will use 'localhost'. If autodetect is not TRUE, James will use the specified name or 'localhost' if none is specified. Look in jamesinfo.log for lines like "[...] Local host is: [servername] and [...] Hello Name is: [machine name]" |
| servernames/servername | attribute autodetect=TRUE and last value of 'localhost' | A list of host names James will consider as local. Any user [user]@[servername] will be considered to be local. If autodetect is TRUE James will attempt to detect automatically the name and use any names specified. Look in jamesinfo.log for a line like "[...] Handling mail for:: [domain/host]" |
| spoolRepository | file://var/mail/spool/ | This is the path where incoming messages are stored before beeing processed. |
| inboxRepository | file://var/mail/localinbox/ | This is the root for local users inbox. Each user will have a personal folder [inboxRepository]/[user] |
| spoolmanagerthreads | 5 | This is the number of thread that work polling mails from the spool and take care of processing them. |
These tag elements affect the SMTP listener (for incoming messages).
| <name> | default value | meaning |
|---|---|---|
| port | 25 | The port we are listening to. |
| bind | N.A. | Specific IP addresses that you wish to bind this service to. |
| smtphandler | N.A. | Parent for all SMTPHandler configuations. |
| connectiontimeout | 120000 | If nothing is received from an open connection for more than {timeout] mills the connection is closed. |
These tag elements affect the POP3 server (for message retrieval)
| <name> | default value | meaning |
|---|---|---|
| port | 110 | The port we are listening to. |
| bind | N.A. | Specific IP addresses that you wish to bind this service to. |
| useTLS | false | Whether you wish to require/use TLS (SSL) on this port. |
| pop3handler | N.A. | Parent for all POP3Handler configuations. |
| connectiontimeout | 120000 | If nothing is received from an open connection for more than {timeout] mills the connection is closed. |
These tag elements affect the configuration of the list of local users.
| <name> | default value | meaning |
|---|---|---|
| repository | file://var/users/ | The path where local mail account information are stored. |
These tag elements affect the remote manager, a telnet based utility to manage the User Manager.
| <name> | default value | meaning |
|---|---|---|
| port | 4555 | The port we are listening to. |
| bind | N.A. | Specific IP addresses that you wish to bind this service to. |
| useTLS | false | Whether you wish to require/use TLS (SSL) on this port. |
| administrator_accounts | N.A. | The parent of <account> |
| account | login="root" password="root" | A list of root account to administer JAMES. |
| connectiontimeout | 120000 | If nothing is received from an open connection for more than {timeout] mills |
These tag elements affect SMTP remote delivery, specifically, DNS lookup functionality.
| <name> | default value | meaning |
|---|---|---|
| dnsServer/servers/server | N.A. | This is a list of DNS to resolve external address. |
| authoritative | false | Whether to require authoritative (non-cached) DNS records. Should always be false unless you understand the implications. |
| repository | file://var/mail/delayed/ | This is a temp repository path shared with the name of "TMP_REPOSITORY". It is used by the RemoteDelivery Mailet to store mail for futher delivery. (Note: this is not very elegant and will probally change soon) |
| mailets | rootpath="org.apache.james.transport.mailets." | This is the parent node for all mailet configurations. The rootpath specify where mailet repository is. (Note: need to plug more than one repository) |
This is James sitemap. It defines how each incoming mail will be processed. Incoming mails begins their process at the first mailet in the pipe. Each step is described by a <servet> tag with some attributes: <mailet match="[matchClass]=[matchParameters]" class="[mailetClass]">. The Matcher class split the mail into two Collections: one with all recipients matching conditions and the other with all recipient not matching. All information in the mail except recipients cloned so the message that both matching and not matching are identical (again except recipients). The matching recipients and mail will be passed to the specified mailet for processing. After processing both mails, the untouched not-matching mail and the processed matching mail, each go to next step in the processor. Some mailets will indicate the mail should be consumed and no continue processing. The Null mailet for example will simply consume any incoming mail as will the RemoteDelivery since after delivery the mail needs no more processing.
The Matcher interface defines how match class should work. Their work is to split a Vector of recipients into two: the ones matching a specified condition and all others. Currently implemented matchers:
| class name | parameter | action | example |
|---|---|---|---|
| All | none | match all recipients. | match="All" |
| HasAttachment | none | match all recipients if the message has an attachment (if content type is multipart/mixed). | match="All" |
| HostIs | comma separated list of hosts names | match all recipients belonging to one of the specified hosts | match="HostIs=myHost.mydom.org,yourHost" |
| HostIsLocal | none | check recipients's hosts against the list of host names set in configuration for localhost (see <servername>). | match="HostIsLocal" |
| InSpammerBlacklist | DNS zone with blacklist | match all recipients if mail received from an IP address on the blacklist. | match="InSpammerBlacklist=blackholes.mail-abuse.org" |
| IsSingleRecipient | none | match mail if only has 1 recipient. | match="IsSingleRecipient" |
| NESSpamCheck | none | match all recipients if mail matches various spam detection rules. | match="NESSpamCheck" |
| RecipientIs | comma separated list of recipients | match all recipients defined in condition. | match="RecipientIs=root@localhost,admin@localhost" |
| RecipientIsLocal | none | match recipient which host is local (see HostIsLocal) and that are recognized by the Users Manager to be local accounts. | match="RecipientIsLocal" |
| RelayLimit | Maximum number of hops. | match all recipients if the message has more than the specified number of SMTP hops. Important to prevent race conditions in SMTP delivery. | match="RelayLimit=30" |
| RemoteAddrInNetwork | comma separated list of network addresses | match all recipients if the message was received from an IP address that matches the comma separated list. Wildcards are supposed, e.g., 192.168.0.* is a valid option. | match="RemoteAddrInNetwork=127.0.0.1,192.168.*" |
| RemoteAddrNotInNetwork | comma separated list of network addresses | match all recipients if the message was not received from an IP address that matches the comma separated list. Wildcards are supposed, e.g., 192.168.0.* is a valid option. | match="RemoteAddrNotInNetwork=127.0.0.1,192.168.*" |
| SenderInFakeDomain | none | match recipients who's domain name portion of their email address is invalid. Queries for A, CNAME, and MX record entries. | match="SenderInFakeDomain" |
| SenderIs | comma separated list of address. | match all recipients if sender is in the condition string, else match none. | match="SenderIs=badBay@badhost" |
| SizeGreaterThan | number of bytes. supports 'k' and 'm' suffixes. | match all recipients if message is larger than the given number of bytes, kilobytes, or megabytes. | match="SizeGreaterThan=1m" |
| SubjectIs | comma separated list of address. | match all recipients if the subject is equal to the condition string, else match none. | match="SubjectIs=REMOVE" |
| SubjectStartsWith | comma separated list of address. | match all recipients if the subject starts with the condition string, else match none. | match="SubjectStartsWith: [ADV]" |
| UserIs | comma separated list of accounts | match all recipients defined in condition regardless of host. | match="UserIs=root,admin" |
Some examples:
- <mailet match="RecipientIsLocal"
class="LocalDelivery">
- <mailet match="UserIs=root"
class="Forward">
- <mailet match="SenderIs=badBoy@myhost,badGirl@yourhost"
class="Null">
Mailet are classes that process a message. They are
passed a Mail object on which they can perform any kind of task.
Clever use of mailets allow you to write an email-based application.
Simple mailets provide basic mail functionality like mail forwarding,
mailing list, "I'm on vacation" message, mail logging etc. As simply as
these mailet, you can write and deploy your own mailet to perform any kind of task.
Here you are some of the mailets bundled with James along with their configuration:
Consume any incoming mail. No configuration needed.debug.Identity
<mailet match="SenderIs=badBoy@badhost" class="Null"> </mailet>
Leave any incoming mail untouched. A debug mailet (not really useful). No configuration needed.Forward
<mailet match="All" class="Identity"> </mailet>
ToProcessor
Replace the recipient list with recipient specified in configurations.
<mailet match="RecipientIs=root@localhost" class="Forward"></mailet>
<forwardto> green@blue.org </forwardto> <forwardto> red@yellow.com </forwardto>
Sends the incoming mail object to a new processor pipeline.ServerTimerootanderrorare special processors that should always be defined.
<mailet match="RecipientIsLocal" class="ToProcessor"><processor> localdelivery </processor></mailet>
Replies to the sender with a short message with the current time. No configuration needed.ToRepository
<mailet match="RecipientIs=time@localhost" class="ServerTime"> </mailet>
Stores mails in the specified MailRepository. Useful for mail logging etc. If the passThrough parameter is false the mail will be consumed, if true it will be returned untouched to the pipe.LocalDelivery
<mailet match="RecipientIs=root@localhost" class="ToRepository"></mailet>
<repositoryPath> file://var/mail/logAdmin </repositoryPath>
<passThrough> true </passThrough> (default false)
Store mail in the local inbox, one folder for each user.RemoteDelivery Relays mails to remote hosts. "delayTime" is the time in mills the mailet will wait before retrying sending a mail which fail at first time. "maxRetries" is the number of retries before sending back to sender the mail.
<mailet match="RecipientIsLocal" class="LocalDelivery"> </mailet>
<delayTime> 21600000 </delayTime>
<maxRetries> 5 </maxRetries>
</mailet>
RedirectHowever it is also designed to be easily subclassed to make authoring redirection
mailets simple.
By extending it and overriding one or more of its methods new behaviour can
be quickly created without the author having to address any other issue than
the relevant one. For more information see the javadocs
The configuration parameters are:
| param | desc |
|---|---|
| <recipients> | A comma delimited list of email addresses for recipients of this message, it will use the "to" list if not specified. These addresses will only appear in the To: header if no "to" list is supplied. |
| <to> | A comma delimited list of addresses to appear in the To: header, the
email will only be delivered to these addresses if they are in the recipients
list. The recipients list will be used if this is not supplied |
| <sender> | A single email address to appear in the From: header It can include constants "sender" and "postmaster" |
| <message> | A text message to be the body of the email. Can be omitted. |
| <inline> |
One of the following items:
|
| <attachment> |
One of the following items:
|
| <passThrough> | TRUE or FALSE, if true the original message continues in the mailet processor after this mailet is finished. False causes the original to be stopped. |
| <attachError> | TRUE or FALSE, if true any error message available to the mailet is appended to the message body (except in the case of inline == unaltered) |
| <replyto> | A single email address to appear in the Rely-To: header, can also be "sender" or "postmaster", this header is not set if this is omited. |
| <prefix> | An optional subject prefix prepended to the original message subject,
for example.. Undeliverable mail: |
| <static> |
TRUE or FALSE, if this is true it hints to the mailet that none of
the parameters are set dynamically, and therefore they can be set once
in the init method. This defaults to false. |
|
Example, creates a distribution list: |
|---|
|
<mailet match="RecipientIs=test@localhost" class="Redirect"> |
|
and this sends a spam notification to the postmaster |
|---|
|
<mailet match="All" class="Redirect"> |