Up to Index

Configuration

JAMES 1.2

Configuration

This document explains the JAMES.conf.xml file.
JAMES is currently based on an older version of Avalon, specifically the avalon-james-1-1b1 branch in CVS.

James Server Configuration

James Configuration

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 1 This is the number of thread that work polling mails from the spool and take care of processing them.

SMTP Server

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.

POP3 Server

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.

Users Manager

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 informations are stored.

Remote Manager

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

Transport

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)

<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	1	This is the number of thread that work polling mails from the spool and take care of processing them.

<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.

<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.

<name>	default value	meaning
repository	file://../var/users/	The path where local mail account informations are stored.

<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

<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)

The Mailet processor pipeline

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 Match class split the mail into two: one with all recipients matching conditions and the other with all recipient not matching. All information in the mail except recipients cloned so bot matching and not matching are identical (again except recipients). The matching mail will be passed to the specified mailet for processing. After processing both mails, the untoched not matching and the processed matching, goes to next step in pipe. Some mailet will not return anything after process. The Null mailet for example will simply destroy any incoming mail or the RemoteDelivery since after delivery the mail needs no more processing.

Matches

The Match 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. Condition may or may not be present. You can make one simple boolean operation merging two matches into one or you can write your own class implementing the Match interface. Currently implemented match:

class name parameter action example

All none match all recipients. match="All"

HostIs comma separated list of hosts names match all recipient belonging to one of the specified hosts match="HostIs=myHost.mydom.org,yourHost"

RecipientIs comma separated list of recipients match all recipients defined in condition. match="RecipientIs=root@localhost,admin@localhost"

UserIs comma separated list of accounts match all recipients defined in condition regardless of host. match="UserIs=root,admin"

HostIsLocal none check recipients's hosts against the list of host names set in configuration for localhost (see <servername>). match="HostIsLocal"

RecipientIsLocal none match recipient which host is local (see HostIsLocal) and that are recognized by the Users Manager to be local accounts. match="RecipientIsLocal"

SenderIs comma separated list of address. match all recipients if sender is in the condition string, else match none. match="SenderIs=badBay@badhost"

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"

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]"

Some examples:
- <mailet match="RecipientIsLocal" class="LocalDelivery">

- <mailet match="UserIs=root & HostIsLocal" class="Forward">

- <mailet match="SenderIs=badBoy@myhost,badGirl@yourhost" class="Null">

Mailet

Mailet are the ones performing a process on a message. They are provided with a Mail object on which thy can perform any kind of task and they reply with another Mail object containing the response. Wise use of mailet allow to write any mail based application as http application using mailet. Simple mailet provides 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 mailet samples with their configuration:
Null
Destroy any incoming mail. No configuration needed.

<mailet match="SenderIs=badBoy@badhost" class="Null">
</mailet>

Identity
Leave any incoming mail untoched.Sort of debug mailet (not really useful). No configuration needed.

<mailet match="All" class="Identity">
</mailet>

Forward
Replace the recipient list with recipient specified in configurations.

<mailet match="RecipientIs=root@localhost" class="Forward">

<forwardto> green@blue.org </forwardto>
<forwardto> red@yellow.com </forwardto>

</mailet>

ToProcessor
Sends the incoming mail object to a new processor pipeline. root and error are special processors that should always be defined.

<mailet match="RecipientIsLocal" class="ToProcessor">

<processor> localdelivery </processor>

</mailet>

ServerTime
Replies to the sender with a short message with the current time. No configuration needed.

<mailet match="RecipientIs=time@localhost" class="ServerTime">
</mailet>

ToRepository
Stores mails in the specified MailRepository. Useful for mail logging etc. If the passThrough is false the mail will be destroyed, if true it will be returned untouched to the pipe.

<mailet match="RecipientIs=root@localhost" class="ToRepository">

<repositoryPath> file://../var/mail/logAdmin </repositoryPath>
<passThrough> true </passThrough> (default false)

</mailet>

LocalDelivery
Store mail in the local inbox, one folder for each user.

<mailet match="RecipientIsLocal" class="LocalDelivery">
</mailet>

RemoteDelivery
Realy 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="RemoteDelivery">

<delayTime> 21600000 </delayTime>
<maxRetries> 5 </maxRetries>

</mailet>

.

class name	parameter	action	example
All	none	match all recipients.	match="All"
HostIs	comma separated list of hosts names	match all recipient belonging to one of the specified hosts	match="HostIs=myHost.mydom.org,yourHost"
RecipientIs	comma separated list of recipients	match all recipients defined in condition.	match="RecipientIs=root@localhost,admin@localhost"
UserIs	comma separated list of accounts	match all recipients defined in condition regardless of host.	match="UserIs=root,admin"
HostIsLocal	none	check recipients's hosts against the list of host names set in configuration for localhost (see <servername>).	match="HostIsLocal"
RecipientIsLocal	none	match recipient which host is local (see HostIsLocal) and that are recognized by the Users Manager to be local accounts.	match="RecipientIsLocal"
SenderIs	comma separated list of address.	match all recipients if sender is in the condition string, else match none.	match="SenderIs=badBay@badhost"
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"
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]"