pgoldstein 2002/12/01 01:55:01
Added: src/xdocs adding_users_2_1.xml build_instructions_2_1.xml
custom_mailet_2_1.xml custom_matcher_2_1.xml
fetchpop_configuration_2_1.xml
installation_instructions_2_1.xml
mailet_api_2_1.xml nntp_configuration_2_1.xml
pop3_configuration_2_1.xml provided_mailets_2_1.xml
provided_matchers_2_1.xml
remotemanager_configuration_2_1.xml
repositories_2_1.xml
serverwide_configuration_2_1.xml smtp_auth_2_1.xml
smtp_configuration_2_1.xml spoolmanager_2_1.xml
spoolmanager_configuration_2_1.xml summary_2_1.xml
table_of_contents_2_1.xml using_database_2_1.xml
Log:
Adding the first revision of the 2.1 guide xdocs.
These are incomplete, subject to future revision.
I'm checking them in now because they represent a substantial amount of work and I'd
like to have them in source control.
I'll add the HTML to www when everything is finished.
Revision Changes Path
1.1 jakarta-james/src/xdocs/adding_users_2_1.xml
Index: adding_users_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Adding Users</title>
</properties>
<body>
<section name="Creating User Accounts">
<p>User accounts are shared across services. A common user repository is shared
across James
services. That is, once you've created a POP3 mail account and set a password, that
same
account is available for authenticated SMTP and NNTP.</p>
<subsection name="Before You Add Accounts">
<p>In James, user accounts are created throught the RemoteManager. So, after
installation is complete, the first step to adding users
is to configure the RemoteManager. More information on RemoteManager configuration
can be found
<a href="remotemanager_2_1.html">here</a>. You will need to have configured at
least one administrator account and
ensured that the RemoteManager is enabled.</p>
<p>Also, you need to make sure that your user repository configuration is correct
before adding any users. If
you change your user repository type (i.e. file to database) or the configuration of
your user repository
(i.e. the file or database URL) after you have added users, you may lose your user
data. Please change these
values with care.</p>
<p>After you've done this, restart James to ensure that any changes you've made in
the configuration are incorporated into
the running system. You are now ready to create user accounts.</p>
</subsection>
<p>Once James is up and listening, adding a user is simple:</p>
1. Telnet to the host and port on which the RemoteManager is listening. For
command-line telnet clients
this is generally done by typing "telnet <host> <pass>" where
<host> is the James
hostname and <port> is the RemoteManager port specified in the James
config.xml.<br/><br/>
2. You will be prompted for your administrator userid and password. Enter the
values you specified
in the James config.xml.<br/><br/>
3. After logging in, type "adduser <user> <password>" where
<user> is the user name
and <password> is the password of the account you wish to create. Please note
that the user name
should NOT be a complete email address. Rather, all email addresses of the form
<user>@<domain>
(where <domain> is any of the values specified in the <servernames>
block) will be delivered to
this account by default. Mailet configuration can change this default
behavior.<br/><br/>
4. Repeat step 3 for all user accounts you wish to create.
<p>That's it. Your user accounts are now created and can be used by all James
services.</p>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/build_instructions_2_1.xml
Index: build_instructions_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Building James</title>
</properties>
<body>
<p>This step is not necessary to use the standard out of the box version of James.
A
pre-built binary version of James is available from the James download directory.
But
if you wish to customize the James source code, it will be necessary for you to
build the
distribution yourself.
</p>
<section name="Getting the Source Code">
<p>There are two ways to get the James source code.</p>
<p>1. Download the source distribution - the source is available from the
<a href="http://jakarta.apache.org/builds/jakarta-james/latest/";>James download
directory</a>.
Simply choose the version of James you'd like to download, navigate into the src
subdirectory
for that version, and pick the source distribution appropriate for your platform.
</p>
<p>2. Get the source code using CVS - this method gives you access to the cutting
edge code
base. Instructions on how to use CVS to get the James source code (the
jakarta-james distribution)
can be found <a href="http://jakarta.apache.org/site/cvsindex.html";>here</a>.
</p>
</section>
<section name="Required Tools">
<p>To run the build you need two third-party tools.</p>
<p>1. Java Development Kit - You must have a JDK of Java version 1.3 or higher
installed to build the
James distribution. The exact JDKs available depend on the platform. A JDK must be
downloaded and
installed before the build can run.</p>
<p>2. Ant - This is a Java-tailored, XML-configured, extensible build or make
system. The James
source tree includes Ant v1.5. You can get the latest version of Ant
<a href="http://jakarta.apache.org/ant";>here</a>. Since Ant is currently included
in the source
distribution, it is not necessary to download it separately.</p>
</section>
<section name="Building the Distribution">
<p>In the top level directory of the source distribution James includes two helper
scripts for running
the build. The script build.bat should be used on Windows systems, while build.sh
is appropriate for
Unix systems. Each script takes an optional set of arguments that tell the script
exactly what to build. </p>
<p>To use these scripts, simple set the environment variable JAVA_HOME to the base
directory of the
JDK. Then run the build script, optionally with any of the following command line
arguments:
<ul>
<li>clean - deletes the build directory, making the system ready for a clean
build.</li>
<li>compile - compiles the source code.</li>
<li>dist - generates all the James distributions, packed.</li>
<li>dist-lite - generates all the James distributions, unpacked. This is the
default argument.</li>
<li>javadocs - builds the James javadocs.</li>
<li>usage - prints out the usage instructions for the script.</li>
<li>website - builds the entirety of the James website.</li>
<li>xdocs - creates the documentaion for James.</li>
</ul>
</p>
<p>All build products are output in the dist subdirectory of the James source
distribution directory. There
is also a build subdirectory of the James source distribution directory that is
created during the build process. Both
of these directories will be deleted if you run build with the clean argument.</p>
<p> <strong>Warning!</strong> Any changes you've made in the 'dist' directory
will be lost after a recompilation. If you are making changes to the config.xml
or other files, we recommend you backup and then change the copies in src to
avoid losing work. </p>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/custom_mailet_2_1.xml
Index: custom_mailet_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Writing a Custom Mailet</title>
</properties>
<body>
<section name="Writing a Custom Mailet">
<p>Implementing a custom mailet is generally a simple task, most of whose complexity
lies in coding the actual work to be done by the mailet. This is largely due to the
simplicity of the Mailet interface and the fact that a GenericMailet class is
provided
as part of the Mailet package.</p>
<p>In this discussion we will assume that any mailet being implemented is a subclass
of
GenericMailet. The GenericMailet class serves to abstract away of the configuration
and
logging details. While it provides a noop implementation of the init() and
destroy() methods,
these can be easily overridden to provide useful functionality.</p>
<p>In general, the only four methods that you should need to implement are init(),
destroy(),
getMailetInfo(), and service(Mail). And only the last is required in all cases.</p>
<subsection name="Configuration">
<p>As described in the <a href="spoolmanager_configuration_2_1.html">SpoolManager
configuration
section</a>, mailets are configured with a set of String (name, value) pairs. These
values are
passed into the Mailet upon initialization (although the details of this process are
hidden by
the GenericMailet implementation). GenericMailet provides access to this
configuration
information through use of the getInitParameter(String) method. Passing in the name
of the
requested configuration value will yield the value if set, and null otherwise.
Configuration
values are available inside the init(), destroy(), and service(Mail) methods.</p>
</subsection>
<subsection name="Logging">
<p>There is a simple logging mechanism provided by the Mailet API. It does not
support
logging levels, so any log filtering will have to be implemented in the Mailet code.
Logging is done by calling one of the two logging methods on GenericMailet -
log(String)
or log(String,Throwable). Logging is available inside the init(), destroy(), and
service(Mail)
methods.</p>
<p>The value of getMailetInfo() for the Mailet is prepended to the log entries for
that
Mailet. So it may be desirable for you to override this method so you can
distinguish mailet
log entries by Mailet.</p>
</subsection>
<subsection name="Initialization">
<p>As part of the Mailet lifecycle, a Mailet is guaranteed to be initialized
immediately after
being instantiated. This happens once and only once for each Mailet instance. The
Initialization phase is where configuration parsing and per-Mailet resource creation
generally
take place. Depending on your Mailet, it may or may not be necessary to do any
initialization
of the mailet. Initialization logic is implemented by overriding the init() method
of
GenericMailet.</p>
</subsection>
<subsection name="Servicing">
<p>The bulk of the Mailet logic is expected to be invoked from the service(Mail)
method. This
method is invoked each time a mail message is to be processed by the mailet. The
message is
passed in as an instance of the Mail interface, which is part of the Mailet API.</p>
<p>The Mail interface is essentially a light wrapper around JavaMail's MimeMessage
class with a
few important differences..</p>
</subsection>
<subsection name="Destruction">
<p>As part of the Mailet lifecycle, a Mailet is guaranteed to be destroyed when the
container
cleans up the Mailet. This happens once and only once for each Mailet instance.
The
Destruction phase is where per-Mailet resource release generally takes place.
Depending
on your Mailet, it may or may not be necessary to do any destruction
of the mailet. Destruction logic is implemented by overriding the destroy() method
of
GenericMailet.</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/custom_matcher_2_1.xml
Index: custom_matcher_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Writing a Custom Matcher</title>
</properties>
<body>
<section name="Writing a Custom Matcher">
<p></p>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/fetchpop_configuration_2_1.xml
Index: fetchpop_configuration_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Configuring FetchPOP</title>
</properties>
<body>
<section name="FetchPOP Configuration">
<p>FetchPOP is controlled by a configuration block in the config.xml.
The fetchpop tag defines the boundaries of the configuration block. It encloses
all the relevant configuration for the FetchPOP scheduler. The behavior of the POP
service is
controlled by the attributes and children of this tag.</p>
<p>This tag has an optional boolean attribute - <strong>enabled</strong> - that
defines whether
the service is active or not. The value defaults to "false" if not present.</p>
<p>The only permitted children of the fetchpop tag are
<strong>fetch</strong>elements. Each of
these <strong>fetch</strong> tags defines a single FetchPOP task.</p>
<p>The <strong>fetch</strong> tag has a single required attribute,
<strong>name</strong>. The name
of each FetchPOP task must be unique.</p>
<p>In addition to the <strong>name</strong> attribute, the <strong>fetch</strong>
tag has four
children, all of which are required.</p>
<ul>
<li><strong>host</strong> - The host name or IP address of the POP3 server hosting
the mail to be fetched.</li>
<li><strong>user</strong> - The user name of the account whose mail is to be
fetched.</li>
<li><strong>password</strong> - The password for the account whose mail is to be
fetched.</li>
<li><strong>interval</strong> - A non-negative integer representing the number of
milliseconds between fetches.</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/installation_instructions_2_1.xml
Index: installation_instructions_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Installation</title>
</properties>
<body>
<section name="Requirements">
<p>James requires a Java Runtime Environment of Java version 1.3 or higher installed
to run the
James application. The exact JREs available depend on the platform. A JRE must be
downloaded and
installed before James can run. In addition, the environment variable JAVA_HOME
must be set to
the JRE home directory before running James.</p>
<p>
<strong>Warning!</strong> - Issues have been observed when using Sun's Java 1.3.0 on
older Linux
distributions. It is recommended that users of these platforms run James using a
more recent
Sun JRE or a JRE produced by an alternate vendor.
</p>
<p>
On Unix platforms, root access will be required to run James. On these platforms,
access to ports
below 1024 is generally restricted to the root user. As SMTP, POP3, and NNTP all
need to open
server sockets on such ports in standard configurations, James requires root access.
</p>
<p>
Obviously James also requires sufficient disk space, processor power, and network
bandwidth. But,
other than what's been discussed here, it has no additional special requirements.</p>
</section>
<section name="Installing the Binary">
<subsection name="Installing a Stand-alone James Server">
<p>Obtain the full James binary distribution from the <a
href="http://jakarta.apache.org/builds/jakarta-james/";>James
download directory</a>. It can be found in the bin subdirectory of the distribution
directory for the particular
build you are downloading. Unpack the archive into your James installation
directory. Go to the bin subdirectory of the
installation directory and run the "run" script (either run.sh or run.bat, depending
on your platform). The configuration
file is now unpacked and available for editing.</p>
</subsection>
<subsection name="Deploying a James Server in a Pre-Existing Phoenix Container">
<p><strong>Warning!</strong> - James requires Phoenix version 4.0.x to run. There
is a known issue with logging in Phoenix 4.0, so version
4.0.1 or higher is strongly recommended. Before attempting to deploy James in a
Phoenix container, please make sure
it meets these version criteria.</p>
<p>Deploying James in Phoenix is fairly easy. Obtain the james.sar file from the
<a href="http://jakarta.apache.org/builds/jakarta-james/";>James download
directory</a>. It can be found in the bin
subdirectory of the distribution directory for the particular build you are
downloading. After downloading the james.sar,
simply place it in the apps subdirectory of your Phoenix installation. Restart
Phoenix, and the james.sar should unpack and you
will be ready to configure your James installation.</p>
</subsection>
</section>
<section name="Initial Configuration">
<p>
After installing the binary, the next step is to adjust the initial configuration.
The most essential
configuration is set in the config.xml file. This file can be found in the
apps/james/SAR-INF subdirectory
of the installation directory.</p>
<p>The out of the box configuration makes certain assumptions and has some default
values that are unlikely to
be appropriate for real-world servers. There are a few issues that should be
addressed immediately upon installation:
</p>
<ul>
<li>RemoteManager Administrator Account - . More information can be found <a
href="remotemanager_configuration_2_1.html">here</a>.</li>
<li>DNS Servers - James needs to have access to a DNS server for domain resolution.
The out of the box
configuration assumes that there is a DNS server on localhost. In general
administrators will have to change
the configuration to point to a valid DNS server. This can be done by adjusting the
dnsserver configuration
block in the config.xml. More information can be found <a
href="serverwide_configuration_2_1.html">here</a>.</li>
<li>Managed Domain Names/IP - Out of the box, James only handles mail that is sent
to recipients at
localhost. It will attempt to deliver all other email to remote SMTP servers. To
allow James to handle email
for your domain or IP address, you simply need to add the appropriate domain name or
IP address to the servernames
section of the config.xml. More information can be found <a
href="serverwide_configuration_2_1.html">here</a>.</li>
</ul>
<p>
<b>Summary</b> (for impatient people)
</p>
<p> M$ users should just run /bin/run.bat. Unix users will find run.sh under the
same directory. A JVM must be present and its location specified in the JAVA_HOME
environment variable. Set this on windows at the command prompt with something
similar to "set JAVA_HOME=\jdk1.3\bin" on *nix with
JAVA_HOME=/jdk1.3/</p>
<p> Running [run* --help] will provide a simple command line help. </p>
<p>
Most UNIX systems require superuser privileges to open sockets below 1024,
which includes the IANA-standard SMTP (on port 25) and POP3 (on port 110).
These default ports can be changed in the config.xml file. (Obviously, you
would then need to reconfigure your clients. This may not be an option if
you want to receive mail from external mailservers.)
</p>
<p> The Avalon framework will unpack the necessary configuration files you will
need to start the server. Wait until it is running stop it again (ctrl-c) and
edit the configuration (thereafter *nix users can run the server in the background
using ./run.sh &). For basic use, you only need to set two items in the
config.xml file: a root password for the remote administration facility
and the IP address of a DNS server. Once you have edited the configuration files,
press 'Enter' on the terminal where Avalon is waiting. </p>
</section>
<section name="Step 4: Kickstart.">
<p>
Once started you'll see a message saying Avalon is running. This means that
Avalon has loaded JAMES and every other needed Block (see /logs/avalon.log)
and is now waiting for a socket request.
Since at the beginning James is empty, it will not have any local users
registered.
To register a local user open a telnet session with localhost on port 4555,
log in as root ("root[enter] <password-you-set-in-config.xml>[enter]") and
type "help" for a list of available commands in the "JAMES remote
administrator tool". It is really a basic set but should allow you to test
installation.
</p>
<p>
Once you have some local users registered, try sending mail to one of them
@localhost with SMTP (port 25) (assuming you have not changed the default
server names in the config.xml file). You'll see the mail appear under
../var/mail/localinbox/[user].
Try now to retrieve that mail using POP3 (port 110).
Trace out JAMES actions in /logs/*info.log.
Actions that will be taken by JAMES on incoming mail are configured in
the mailet pipe line (/SAR-INF/config.xml). Look at it if you want to
understand what's happening.
</p>
<p>
Good luck :)
</p>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/mailet_api_2_1.xml
Index: mailet_api_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Mailet API</title>
</properties>
<body>
<section name="Mailet API">
<p>The Mailet API is a simple API used to build mail processing applications. James
is a Mailet
container, allowing administrators to deploy Mailets (both custom and pre-made) to
carry out a
variety of complex mail processing tasks. In the default configuration James uses
Mailets to carry
out a number of tasks that are carried out deep in the source code of other mail
servers (i.e. list
processing, remote and local delivery).</p>
<p>
As it stands today, the Mailet API defines interfaces for both Matchers and
Mailets.</p>
<p>Matchers, as their name would suggest, match mail messages against certain
conditions. They
return some subset (possibly the entire set) of the original recipients of the
message if there
is a match. An inherent part of the Matcher contract is that a Matcher should not
induce any changes
in a message under evaluation.</p>
<p>Mailets are responsible for actually processing the message. They may alter the
message in any fashion,
or pass the message to an external API or component. This can include delivering a
message to its destination
repository or SMTP server.</p>
<p>The Mailet API is currently in its first revision, and is expected to undergo
substantial changes
in the near future. The Javadoc for the Mailet API can be found <a
href="/mailet/index.html">here</a>.</p>
<p>James bundles a number of Matchers and Mailets in its distribution. Descriptions
of provided matchers
can be found <a href="provided_matchers_2_1.html">here</a>, while descriptions of
provided mailets can be found
<a href="provided_mailets_2_1.html">here</a>.</p>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/nntp_configuration_2_1.xml
Index: nntp_configuration_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Configuring the NNTP Service</title>
</properties>
<body>
<section name="NNTP Configuration">
<p>The NNTP service is controlled by a two configuration blocks in the config.xml.
These are the nntpserver block and the nntp-repository block.</p>
<subsection name="The nntpserver block">
<p>The nntpserver tag defines the boundaries of the configuration block. It
encloses
much of the relevant configuration for the NNTP server.</p>
<p>This tag has an optional boolean attribute - <strong>enabled</strong> - that
defines whether the service is active or not. The value defaults to "true" if
not present.</p>
<p>The standard children of the nntpserver tag are:</p>
<ul>
<li><strong>port</strong> - This is an optional integer value. This value is the
port on which this NNTP server is configured
to listen.If the tag or value is omitted, the value will default to the standard
NNTP port, 119.</li>
<li><strong>bind</strong> - This is an optional value. If present, this value is a
string describing
the IP address to which this service should be bound. If the tag or value is absent
then the service
will bind to all network interfaces for the machine.</li>
<li><strong>useTLS</strong> - This is an optional boolean value. If this value is
true, then the "ssl"
server socket factory is used to generate the server socket for this service. If it
is false, the
"plain" server socket factory is used. In either case this behavior is overridden
by the serverSocketType
tag which is described under the expert configuration options.</li>
<li><strong>handler</strong> - This is an artifact preserved for backwards
compatibility. This tag
was used to group related parameters. It should disappear in future versions.</li>
<ul>
<li><strong>helloName</strong> - This is a required tag with an optional body that
defines the server name
used in the initial service greeting. The tag may have an optional attribute -
<strong>autodetect</strong>. If
the autodetect attribute is present and true, the service will use the local
hostname
returned by the Java libraries. If autodetect is absent or false, the body of the
tag will be used. In
this case, if no body is present, the value "localhost" will be used.</li>
<li><strong>connectionTimeout</strong> - This is an optional tag with a non-negative
integer body. </li>
<li><strong>authRequired</strong> - This is an optional tag with a boolean body. If
true, then the server will
require authentication before allowing the client to view news articles. If this
tag is absent, or the value
is false then the client will not be prompted for authentication. Only simple
user/password authentication is
supported at this time.</li>
</ul>
</ul>
<p>There are a few additional children of the nntpserver tag that are appropriate
for advanced
configurations. These should only be used by expert administrators. All tags in
this group are optional.</p>
<ul>
<li><strong>serverSocketFactory</strong> - This is an optional tag with a string
body. If the tag is present,
the body must be the name of one of the server socket factories specified in the
socket manager block. Any other
value will result in an error. If present, this tag overrides the useTLS tag.</li>
<li><strong>threadGroup</strong> - This is an optional tag with a string body. If
the tag is present,
the body must be the name of one of the thread groups specified in the thread
manager block. Any other
value will result in an error. This tag is best used to fine tune thread allocation
between the services.</li>
</ul>
</subsection>
<subsection name="The nntp-repository block">
The remainder of the NNTP service configuration is controlled by the nntp-repository
configuration block. This
section of configuration data relates to the server-side NNTP article repository.
<ul>
<li><strong>readOnly</strong> - This is a required boolean tag. If the value is
true, posting will not be
permitted by the NNTP server.</li>
<li><strong>rootPath</strong> - This is a required string tag. It must be in the
form of a URL with a "file:" prefix. This
specifies the root directory for the NNTP repository. Groups hosted on the NNTP
server will be represented as
folders under this root, and articles will be stored in the appropriate
folders.</li>
<li><strong>tempPath</strong> - This is a required string tag. It must be in the
form of a URL with a "file:" prefix. This
specifies the directory where the NNTP server will store posted articles before they
are added to the spool.</li>
<li><strong>articleIDPath</strong> - This is a required string tag. It must be in
the form of a URL with a "file:" prefix. This
specifies the directory where the NNTP server will store the mappings between
article ID and the groups containing that article.</li>
<li><strong>articleIDDomainSuffix</strong> - This is a required string tag. It is
the suffix appended to all article IDs generated
by this NNTP server.</li>
<li><strong>newsgroups</strong> - This is a required container tag. It has a single
<strong>newsgroup</strong> child for each newsgroup
hosted on the server. The body of each of those <strong>newsgroup</strong> tags is
the name of the newsgroup.</li>
</ul>
</subsection>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/pop3_configuration_2_1.xml
Index: pop3_configuration_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Configuring the POP3 Service</title>
</properties>
<body>
<section name="POP3 Configuration">
<p>The POP3 service is controlled by a configuration block in the config.xml.
The pop3server tag defines the boundaries of the configuration block. It encloses
all the relevant configuration for the POP3 server. The behavior of the POP service
is
controlled by the attributes and children of this tag.</p>
<p>This tag has an optional boolean attribute - <strong>enabled</strong> - that
defines whether the service is active or not. The value defaults to "true" if
not present.</p>
<p>The standard children of the pop3server tag are:</p>
<ul>
<li><strong>port</strong> - This is an optional integer value. This value is the
port on which this POP3 server is configured
to listen.If the tag or value is omitted, the value will default to the standard
POP3 port, 110.</li>
<li><strong>bind</strong> - This is an optional value. If present, this value is a
string describing
the IP address to which this service should be bound. If the tag or value is absent
then the service
will bind to all network interfaces for the machine.</li>
<li><strong>useTLS</strong> - This is an optional boolean value. If this value is
true, then the "ssl"
server socket factory is used to generate the server socket for this service. If it
is false, the
"plain" server socket factory is used. In either case this behavior is overridden
by the serverSocketType
tag which is described under the expert configuration options.</li>
<li><strong>handler</strong> - This is an artifact preserved for backwards
compatibility. This tag
was used to group related parameters. It should disappear in future versions.</li>
<ul>
<li><strong>helloName</strong> - This is a required tag with an optional body that
defines the server name
used in the initial service greeting. The tag may have an optional attribute -
<strong>autodetect</strong>. If
the autodetect attribute is present and true, the service will use the local
hostname
returned by the Java libraries. If autodetect is absent or false, the body of the
tag will be used. In
this case, if no body is present, the value "localhost" will be used.</li>
<li><strong>connectionTimeout</strong> - This is an optional tag with an integer
body. </li>
</ul>
</ul>
<p>There are a few additional children of the pop3server tag that are appropriate
for advanced
configurations. These should only be used by expert administrators. All tags in
this group are optional.</p>
<ul>
<li><strong>serverSocketFactory</strong> - This is an optional tag with a string
body. If the tag is present,
the body must be the name of one of the server socket factories specified in the
socket manager block. Any other
value will result in an error. If present, this tag overrides the useTLS tag.</li>
<li><strong>threadGroup</strong> - This is an optional tag with a string body. If
the tag is present,
the body must be the name of one of the thread groups specified in the thread
manager block. Any other
value will result in an error. This tag is best used to fine tune thread allocation
between the services.</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/provided_mailets_2_1.xml
Index: provided_mailets_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Provided Mailets</title>
</properties>
<body>
<section name="Mailets">
<p>James provides a number of implemented Mailets for use by James administrators in
their
configurations. These are primarily mailets that members of the James developer or
user
communities have found useful in their own configurations. A description of how to
configure
Mailets and use them in the James SpoolManager can be found <a
href="/spoolmanager_configuration_2_1.html">here</a>.</p>
<subsection name="AddFooter">
<p>Description: This mailet adds a text footer to the message.</p>
<p>Parameters:
<ul>
<li><strong>text</strong> (required) - the text that will be added as a footer to
the message.</li>
</ul>
</p>
</subsection>
<subsection name="AddHabeasWarrantMark">
<p>Description: This mailet adds a Habeas warrant mark (see <a
href="http://habeas.com";>http://habeas.com</a> for details) to the message.</p>
<p>Parameters: None.</p>
</subsection>
<subsection name="AddHeader">
<p>Description: This mailet adds a text header to the message.</p>
<p>Parameters:
<ul>
<li><strong>text</strong> (required) - the text that will be added as a header to
the message.</li>
</ul>
</p>
</subsection>
<subsection name="Forward">
<p>Description: This mailet forwards the message to a set of recipients.</p>
<p>Parameters:
<ul>
<li><strong>forwardto</strong> (required) - a comma delimited list of email
addresses.</li>
</ul>
</p>
</subsection>
<subsection name="JDBCAlias">
<p>Description: This mailet does alias translation for email addresses stored in a
database table.</p>
<p>Parameters:
<ul>
<li><strong>mappings</strong> (required) - a URL of the form
db://<data-source>/<table>, where
<table> is the table in the database containing the alias info and
<data-source> is the name
of the data-source in config.xml that is to be used.</li>
<li><strong>source_column</strong> (required) - the column containing the
aliases.</li>
<li><strong>target_column</strong> (required) - the column containing the alias
targets.</li>
</ul>
</p>
</subsection>
<subsection name="LocalDelivery">
<p>Description: This mailet delivers messages to local mailboxes.</p>
<p>Parameters: None.</p>
</subsection>
<subsection name="NotifyPostmaster">
<p>Description: This mailet forwards the message as an attachment to the James
postmaster.</p>
<p>Parameters:
<ul>
<li><strong>sendingAddress</strong> (optional) - the address from which the
forwarded email will be
sent. Defaults to the postmaster address.</li>
<li><strong>notice</strong> (optional) - the text message that will accompany the
forwarded message. Defaults
to "We were unable to deliver the attached message because of an error in the mail
server."</li>
<li><strong>attachStackTrace</strong> (optional) - whether an error stack trace is
attached to the forwarded message.</li>
</ul>
</p>
</subsection>
<subsection name="NotifySender">
<p>Description: This mailet forwards the message as an attachment to the original
sender.</p>
<p>Parameters:
<ul>
<li><strong>sendingAddress</strong> (optional) - the address from which the
forwarded email will be
sent. Defaults to the postmaster address.</li>
<li><strong>notice</strong> (optional) - the text message that will accompany the
forwarded message. Defaults
to "We were unable to deliver the attached message because of an error in the mail
server."</li>
<li><strong>attachStackTrace</strong> (optional) - whether an error stack trace is
attached to the forwarded message.</li>
</ul>
</p>
</subsection>
<subsection name="Null">
<p>Description: This mailet ends processing for this mail.</p>
<p>Parameters: None.</p>
</subsection>
<subsection name="PostmasterAlias">
<p>Description: Intercepts all mails addressed to postmaster@<domain> where
<domain> is one
of the domains managed by this James server and substitutes the configured James
postmaster address for
the original recipient address. This mailet is inserted automatically by James at
the head of the root
processor.</p>
<p>Parameters: None.</p>
</subsection>
<subsection name="RemoteDelivery">
<p>Manages delivery of messages to recipients on remote SMTP hosts.</p>
<p>Parameters:
<ul>
<li><strong>outgoing</strong> (required) - The URL for the repository that will hold
messages being processed
by the RemoteDelivery Mailet.</li>
<li><strong>delayTime</strong> (optional) - a non-negative Long value that is the
time in
milliseconds between redelivery attempts for a particular mail. Defaults to six
hours.</li>
<li><strong>maxRetries</strong> (optional) - a non-negative Integer value that is
number of times
the Mailet will attempt to deliver a particular mail. Defaults to five.</li>
<li><strong>timeout</strong> (optional) - The SMTP connection timeout for SMTP
connections generated
by this Mailet. Defaults to 60 seconds.</li>
<li><strong>deliveryThreads</strong> (optional) - The number of threads this Mailet
will use to generate
SMTP connections.</li>
<li><strong>gateway</strong> (optional) - The host name of the SMTP server to be
used as a gateway for
this server. If this value is set, then all messages will be delivered to the
gateway server,
regardless of recipient address. If this value is unset, delivery will occur to
SMTP servers resolved
by MX lookup.</li>
<li><strong>gatewayPort</strong> (optional) - The port number of the SMTP server to
be used as a gateway for
this server. This value is required if gateway is set.</li>
<li><strong>debug</strong> (optional) - a boolean value (true/false) indicating
whether debugging is
on. Defaults to false.</li>
</ul>
</p>
</subsection>
<subsection name="ServerTime">
<p>Description: This mailet sends a message to the sender of the original mail
message with a server timestamp.</p>
<p>Parameters: None.</p>
</subsection>
<subsection name="ToProcessor">
<p>Redirects processing of the mail message to the specified processor.</p>
<p>Parameters:
<ul>
<li><strong>processor</strong> (required) - the name of the processor to which the
message
is to be redirected.</li>
<li><strong>noticeText</strong> (optional) - a String value that, if present,
is set as the error message of the redirected message. If this value is not
present, no error message is set.</li>
</ul>
</p>
</subsection>
<subsection name="ToRepository">
<p>Places a copy of the message in the specified repository.</p>
<p>Parameters:
<ul>
<li><strong>repositoryPath</strong> (required) - the URL of the repository to which
the message
is to be added.</li>
<li><strong>passThrough</strong> (optional) - a boolean value (true/false)
indicating whether
processing should continue on the message is on. If false, the original message is
GHOSTed. Defaults to false.</li>
</ul>
</p>
</subsection>
<subsection name="UseHeaderRecipients">
<p>Description: Ignores the recipients associated with the Mail interface. Instead,
it regenerates the
mail recipients from the MimeMessage headers (To, Cc, Bcc) and inserts a new message
at the queue root
these new recipients. The original message is GHOSTed.</p>
<p>Parameters:
<ul>
<li><strong>debug</strong> (optional) - a boolean value (true/false) indicating
whether debugging is
on. Defaults to false.</li>
</ul>
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/provided_matchers_2_1.xml
Index: provided_matchers_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Provided Matchers</title>
</properties>
<body>
<section name="Matchers">
<p>James provides a number of implemented Matchers for use by James administrators
in their
configurations. These are primarily matchers that members of the James developer or
user
communities have found useful in their own configurations. A description of how to
configure
Matchers and use them in the James SpoolManager can be found <a
href="spoolmanager_configuration_2_1.html">here</a>.</p>
<subsection name="All">
<p>Description: This matcher is the trivial one - it matches all mails being
processed. All recipients are returned.</p>
<p>Configuration string: None.</p>
</subsection>
<subsection name="CommandForListserv">
<p>Description: The CommandForListserv matcher is used as a simple filter to
recognize emails that are list server
commands. It will match any email addressed to the list server host, as well as any
email that is addressed
to a user named <prefix>-on or <prefix>-off on any host. Only those
matching recipients will be returned.</p>
<p>Configuration string: An email address of the form <prefix>@<host>,
where host is the hostname used for the listserver and prefix is the command
prefix.</p>
</subsection>
<subsection name="FetchedFrom">
<p>Description: A matcher intended for use with the FetchPOP server. It matches a
custom header (X-fetched-from) that is
set by the FetchPOP server. FetchPOP sets this header to the email address for the
POP3 account from which
the mail was originally fetched. All recipients are returned.</p>
<p>Configuration string: The POP3 account from which the mail was originally
fetched.</p>
</subsection>
<subsection name="HasAttachment">
<p>Description: Matches those messages with a MIME type of "multipart/mixed". All
recipients are returned.</p>
<p>Configuration string: None.</p>
</subsection>
<subsection name="HasHabeasWarrantMark">
<p>Description: Matches mails that have the Habeas Warrant (see
http://www.habeas.com for details). All recipients are returned.</p>
<p>Configuration string: None.</p>
</subsection>
<subsection name="HasHeader">
<p>Description: Matches mails that have the specified header. All recipients are
returned.</p>
<p>Configuration string: The name of the header whose presence determines the
match.</p>
</subsection>
<subsection name="HostIs">
<p>Description: Matches mails that are sent to email addresses on hosts that are in
the configuration list. Only
recipients that are on one of the hosts are returned.</p>
<p>Configuration string: A list of host names, comma or space delimited.</p>
</subsection>
<subsection name="HostIsLocal">
<p>Description: Matches mails that are sent to email addresses on local hosts. Only
recipients that are on one of the local hosts are returned.</p>
<p>Configuration string: None.</p>
</subsection>
<subsection name="InSpammerBlacklist">
<p>Description: Checks the mail against one of a number of mail-abuse.org IP
lists.</p>
<p>Configuration string: One of three strings - "blackholes.mail-abuse.org",
"relays.mail-abuse.org", or "dialups.mail-abuse.org".</p>
</subsection>
<subsection name="IsSingleRecipient">
<p>Description: Matches those messages sent to only a single recipient. The single
recipient is returned.</p>
<p>Configuration string: None.</p>
</subsection>
<subsection name="NESSpamCheck">
<p>Description: A matcher derived from a Netscape Mail Server spam filter. If the
matcher detects headers that
indicate spam, the message is matched. All recipients are returned.</p>
<p>Configuration string: None.</p>
</subsection>
<subsection name="RecipientIs">
<p>Description: Matches mails that are sent to one of the recipients on a specified
list. Only
matching recipients are returned.</p>
<p>Configuration string: A list of recipient addresses, comma, tab, or space
delimited.</p>
</subsection>
<subsection name="RecipientIsLocal">
<p>Description: Matches mails that are sent to email addresses on local hosts with
users that have local acccunts. Only
matching recipients are returned.</p>
<p>Configuration string: None.</p>
</subsection>
<subsection name="RelayLimit">
<p>Description: Counts the number of Received headers in the mail (each of which
represents a server
in the relay chain). If the number equals or exceeds the specified limit, the mail
is
matched. All recipients are returned.</p>
<p>Configuration string: a positive integer that is the limit on the number of
relays.</p>
</subsection>
<subsection name="RemoteAddrInNetwork">
<p>Description: Checks the remote address from which the mail was received against
the configured list. If the address matches one on the list, the matcher considers it
a match. All recipients are returned.</p>
<p>Configuration string: A list of domain names, IP addresses, or wildcarded IP
subnets of any class. The
list may be comma or space delimited.</p>
</subsection>
<subsection name="RemoteAddrNotInNetwork">
<p>Description: Checks the remote address from which the mail was received against
the configured list. If the address doesn't match one on the list, the matcher
considers it a match. All recipients are returned.</p>
<p>Configuration string: A list of domain names, IP addresses, or wildcarded IP
subnets of any class. The
list may be comma or space delimited.</p>
</subsection>
<subsection name="SenderInFakeDomain">
<p>Description: Matches mails where the host name in the address of the sender
cannot be resolved. All
recipients are returned.</p>
<p>Configuration string: None.</p>
</subsection>
<subsection name="SenderIs">
<p>Description: Matches mails that are sent by one of the senders on a specified
list. All
recipients are returned.</p>
<p>Configuration string: A list of sender addresses, comma, tab, or space
delimited.</p>
</subsection>
<subsection name="SizeGreaterThan">
<p>Description: Matches emails with a total message size (headers and body) greater
than the specified limit. All recipients are returned.</p>
<p>Configuration string: a positive integer followed by an 'm' or a 'k'. This is
the maximum message size permitted specified in megabytes or kilobytes
respectively.</p>
</subsection>
<subsection name="SubjectIs">
<p>Description: Matches emails with the specified subject. All recipients are
returned.</p>
<p>Configuration string: The string against which mail subject headers are
matched.</p>
</subsection>
<subsection name="SubjectStartsWith">
<p>Description: Matches emails whose subject header starts with the specified
string. All recipients are returned.</p>
<p>Configuration string: The string against which mail subject headers are
matched.</p>
</subsection>
<subsection name="UserIs">
<p>Description: Matches mails that are sent to email addresses that have userids
that are in the configuration list. Only
matching recipients are returned.</p>
<p>Configuration string: A list of user names, comma or space delimited.</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/remotemanager_configuration_2_1.xml
Index: remotemanager_configuration_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Configuring the RemoteManager</title>
</properties>
<body>
<section name="RemoteManager Configuration">
<p>The RemoteManager is controlled by a configuration block in the config.xml.
The remotemanager tag defines the boundaries of the configuration block. It
encloses
all the relevant configuration for the RemoteManager. The behavior of the
RemoteManager is
controlled by the attributes and children of this tag.</p>
<p>This tag has an optional boolean attribute - <strong>enabled</strong> - that
defines whether the service is active or not. The value defaults to "true" if
not present.</p>
<p>The standard children of the remotemanager tag are:</p>
<ul>
<li><strong>port</strong> - This is an optional integer value. This value is the
port on which this POP3 server is configured
to listen.If the tag or value is omitted, the value will default to 4555.</li>
<li><strong>bind</strong> - This is an optional value. If present, this value is a
string describing
the IP address to which this service should be bound. If the tag or value is absent
then the service
will bind to all network interfaces for the machine.</li>
<li><strong>useTLS</strong> - This is an optional boolean value. If this value is
true, then the "ssl"
server socket factory is used to generate the server socket for this service. If it
is false, the
"plain" server socket factory is used. In either case this behavior is overridden
by the serverSocketType
tag which is described under the expert configuration options.</li>
<li><strong>handler</strong> - This is an artifact preserved for backwards
compatibility. This tag
was used to group related parameters. It should disappear in future versions.</li>
<ul>
<li><strong>helloName</strong> - This is a required tag with an optional body that
defines the server name
used in the initial service greeting. The tag may have an optional attribute -
<strong>autodetect</strong>. If
the autodetect attribute is present and true, the service will use the local
hostname
returned by the Java libraries. If autodetect is absent or false, the body of the
tag will be used. In
this case, if no body is present, the value "localhost" will be used.</li>
<li><strong>administrator_accounts</strong> - This is an required container tag. It
contains
one or more <strong>administrator_account</strong> elements, each of which has a
<strong>login</strong> attribute
and a <strong>password</strong> attribute. These two attributes correspond to the
login id and password for the
administrative account respectively. Obviously, for security reasons, these should
be set upon James installation.</li>
<li><strong>connectionTimeout</strong> - This is an optional tag with an integer
body. </li>
</ul>
</ul>
<p>There are a few additional children of the pop3server tag that are appropriate
for advanced
configurations. These should only be used by expert administrators. All tags in
this group are optional.</p>
<ul>
<li><strong>serverSocketFactory</strong> - This is an optional tag with a string
body. If the tag is present,
the body must be the name of one of the server socket factories specified in the
socket manager block. Any other
value will result in an error. If present, this tag overrides the useTLS tag.</li>
<li><strong>threadGroup</strong> - This is an optional tag with a string body. If
the tag is present,
the body must be the name of one of the thread groups specified in the thread
manager block. Any other
value will result in an error. This tag is best used to fine tune thread allocation
between the services.</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/repositories_2_1.xml
Index: repositories_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Repositories</title>
</properties>
<body>
<section name="Repositories">
<p>James uses a number of different repositories to both store message data (email,
news messages) and
user information. User repositories store user information, including user names,
authentication
information, and aliases. Mail repositories store messages that have been delivered
locally. Spool
repositories store messages that are still being processed. Finally, news
repositories are used to
store news messages.</p>
</section>
<section name="Storage Types">
<p>Aside from the type of data they store, repositories are distinguished by
where they store data. There are three types of storage - File, Database, and
DBFile.</p>
<subsection name="File Repositories">
<p>File-based repositories store all data in the file system. In general, these
repositories are extremely
simple to configure, but may compare poorly in terms of performance when compared to
other repository
types. File repositories are not recommended for large or performance-critical
configurations. In the
default configuration, all repositories are file repositories.</p>
<p>File repository paths typically begin with the prefix "file". Paths are relative
to the application
base directory, unless the path begins with a slash. As an example, assume that
James is running in
/usr/james/phoenix/apps/james. Then "file://var/mail/spool/" would refer to the
directory /usr/james/phoenix/apps/james/var/mail/spool.
And "file:///var/mail/spool/" (note the extra '/') would refer to the directory
/var/mail/spool.</p>
<p>All repository types (mail, spool, user, and news) have file-based
implementations. No special configuration is required to enable file-based
repositories</p>
</subsection>
<subsection name="Database (JDBC) Repositories">
<p>Database repositories store all data in an administrator-supplied database.
Configuration is somewhat
more complex, requiring that the administrator adjust the data-connections section.
Detailed directions
are included in the sample configuration file. The administrator will need to know
the JDBC driver class,
the appropriate URL for use with his database, and a valid username/password for the
database.</p>
<p>If the administrator wants to configure a database other than MySQL, it will be
necessary to add the jar
or zip file containing the JDBC driver classes to the lib subdirectory of the
installation directory. This
will allow Phoenix to properly load the driver when it is initializing the database
repository. The MySQL
driver is pre-packaged with James.</p>
<p>Database repository paths typically begin with the prefix "db". The format is
"db://<data-source>/<table>"
where <data-source> is the name of the data-source defined in the
data-connections section. And <table> is
the particular table associated with the repository.</p>
<p>Mail, spool, and user repositories have JDBC-based implementations.</p>
</subsection>
<subsection name="DBFile Repositories">
<p>This is a special repository type used only for mail repositories. DBFile
repositories store the body of
a mail message in the file system, while headers are stored in the database. This
allows the administrator
to minimize the size of data stored in the database, while conserving most of the
performance of the
database repository.</p>
<p>Only mail repositories have dbfile-based implementations.</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/serverwide_configuration_2_1.xml
Index: serverwide_configuration_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Global Server Configuration</title>
</properties>
<body>
<section name="Global Server Configuration">
<p>There are a number of global configuration values that do not fall into any one
component. </p>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/smtp_auth_2_1.xml
Index: smtp_auth_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Using Authenticated SMTP</title>
</properties>
<body>
<section name="Authenticated SMTP (SMTP AUTH)">
<p>Authenticated SMTP is a method of securing your SMTP server. With SMTP AUTH
enabled senders who wish to
relay mail through the SMTP server (that is, send mail that is eventually to be
delivered to another SMTP
server) must authenticate themselves to James before sending their message. Mail
that is to be delivered
locally does not require authentication. This method ensures that spammers cannot
use your SMTP server
to send unauthorized mail, while still enabling users who may not have fixed IP
addresses to send their
messages.</p>
<p>Mail servers that allow spammers to send unauthorized email are known as open
relays. So SMTP AUTH
is a mechanism for ensuring that your server is not an open relay .</p>
<p>At this time James only supports simple user name / password authentication.</p>
<subsection name="Configuring James for Authenticated SMTP">
<p>Configuring James for Authentication SMTP is a multi-step process. It requires
several adjustments of
the config.xml. To enable SMTP AUTH, do the following:</p>
<p>First, as mentioned above, SMTP AUTH requires that James be able to distinguish
between mail intended
for local delivery and mail intended for remote delivery. James makes this
determination by matching the
domain to which the mail was sent against the <servernames> element of the
James configuration block. Any
local domains should be explicitly listed as <servername> elements in this
section.</p>
<p>Second, James is configured out of the box so as to not serve as an open relay
for spammers. This is done
by restricting the IP addresses from which mail will be accepted using the
RemoteAddrNotInNetwork mailet. This
restriction must be lifted before users can send from arbitrary clients. To do
this, comment out or remove the
mailet tag containing the class attribute "RemoteAddrNotInNetwork". This tag can be
found in the spoolmanager
configuration block, in the root processor configuration.</p>
<p>Third, set the authRequired element of the smtpserver configuration block to
"true".</p>
<p>Fourth, if you wish to ensure that authenticated users can only send email from
their own account, you may
optionally set the verifyIdentity element of the smtpserver configuration block to
"true".</p>
<p>Fifth, restart James. This will pull in all of your configuration changes.</p>
</subsection>
<subsection name="Verifying Your Configuration">
<p>Finally, you need to verify that your configuration was done correctly. This
step is
<strong>important</strong> and should not be skipped.</p>
<p>Verify that you have not inadvertantly configured your server as an open relay.
This is most easily
accomplished by using the service provided at <a
href="http://www.ordb.org";>ORDB.org</a>. ORDB.org will
check your mail server and inform you if it is an open relay.</p>
<p>It is extremely important that your server not be configured as an open relay.
Aside from potential
costs associated with usage by spammers, connections from servers that are
determined to be open relays
are routinely rejected by SMTP servers. This can severely impede the ability of
your mail server to
send mail.</p>
<p>Of course it is also necessary to confirm that users and log in and send
mail through your server. This can be accomplished using any standard mail client
(i.e. Outlook,
Eudora, Evolution).</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/smtp_configuration_2_1.xml
Index: smtp_configuration_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Configuring the SMTP Service</title>
</properties>
<body>
<section name="SMTP Configuration">
<p>The SMTP service is controlled by a configuration block in the config.xml.
The smtpserver tag defines the boundaries of the configuration block. It encloses
all the relevant configuration for the SMTP server. The behavior of the SMTP
service is
controlled by the attributes and children of this tag.</p>
<p>This tag has an optional boolean attribute - <strong>enabled</strong> - that
defines whether the service is active or not. The value defaults to "true" if
not present.</p>
<p>The standard children of the smtpserver tag are:</p>
<ul>
<li><strong>port</strong> - This is an optional integer value. This value is the
port on which this SMTP server is configured
to listen.If the tag or value is omitted, the value will default to the standard
SMTP port, 25.</li>
<li><strong>bind</strong> - This is an optional value. If present, this value is a
string describing
the IP address to which this service should be bound. If the tag or value is absent
then the service
will bind to all network interfaces for the machine.</li>
<li><strong>useTLS</strong> - This is an optional boolean value. If this value is
true, then the "ssl"
server socket factory is used to generate the server socket for this service. If it
is false, the
"plain" server socket factory is used. In either case this behavior is overridden
by the serverSocketType
tag which is described under the expert configuration options.</li>
<li><strong>handler</strong> - This is an artifact preserved for backwards
compatibility. This tag
was used to group related parameters. It should disappear in future versions.</li>
<ul>
<li><strong>helloName</strong> - This is a required tag with an optional body that
defines the server name
used in the initial service greeting. The tag may have an optional attribute -
<strong>autodetect</strong>. If
the autodetect attribute is present and true, the service will use the local
hostname
returned by the Java libraries. If autodetect is absent or false, the body of the
tag will be used. In
this case, if no body is present, the value "localhost" will be used.</li>
<li><strong>connectionTimeout</strong> - This is an optional tag with a non-negative
integer body. </li>
<li><strong>authRequired</strong> - This is an optional tag with a boolean body. If
true, then the server will
require authentication before delivering mail to non-local email addresses. If this
tag is absent, or the value
is false then the client will not be prompted for authentication. Only simple
user/password authentication is
supported at this time.</li>
<li><strong>verifyIdentity</strong> - This is an optional tag with a boolean body.
This option can only be used
if SMTP authentication is required. If the parameter is set to true then the sender
address for the submitted message
will be verified against the authenticated subject.</li>
<li><strong>maxmessagesize</strong> - This is an optional tag with a non-negative
integer body. It specifies the maximum
size, in bytes, of any message that will be transmitted by this SMTP server. It is
a service-wide, as opposed to
a per user, limit. If the value is zero then there is no limit. If the tag isn't
specified, the service will
default to an unlimited message size.</li>
</ul>
</ul>
<p>There are a few additional children of the smtpserver tag that are appropriate
for advanced
configurations. These should only be used by expert administrators. All tags in
this group are optional.</p>
<ul>
<li><strong>serverSocketFactory</strong> - This is an optional tag with a string
body. If the tag is present,
the body must be the name of one of the server socket factories specified in the
socket manager block. Any other
value will result in an error. If present, this tag overrides the useTLS tag.</li>
<li><strong>threadGroup</strong> - This is an optional tag with a string body. If
the tag is present,
the body must be the name of one of the thread groups specified in the thread
manager block. Any other
value will result in an error. This tag is best used to fine tune thread allocation
between the services.</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/spoolmanager_2_1.xml
Index: spoolmanager_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - The SpoolManager, Matchers, and Mailets</title>
</properties>
<body>
<section name="The SpoolManager, Matchers, and Mailets">
<p>James separates the services that deliver mail to James (i.e. SMTP, FetchPOP)
from the engine that processes mail after it is received by James. The
SpoolManager component is James' mail processing engine. James' SpoolManager
component
is a Mailet container. It is these mailets and matchers that actually carry out
mail processing.</p>
<p>Core to the SpoolManager operation are Matchers and Mailets. A Matcher is a
simple object that checks whether a mail message matches a particular condition.
A mailet is another type object that processes an email message in some way. Some
typical tasks appropriate for a mailet would be adding a header, delivering the
message
to a local repository, or handling remote delivery. Both the Matcher and Mailet
APIs are
public, allowing James users to write their own custom matchers and mailets. James
comes with a large set of pre-built matchers and mailets.</p>
<p>Matchers and mailets are used in pairs. At each stage in processing a message is
checked
against a matcher. The matcher will attempt to match the mail message. The match
is not simply
a yes or no issue. Instead, the match method returns a collection of matched
recipients. If the
this collection of matched recipients is empty, the mailet is not invoked. If the
collection of
matched recipients is the entire set of original recipients, the mail is then
processed by the
associated mailet. Finally, if the matcher only matches a proper subset of the
original recipients,
the original mail is duplicated. The recipients for one message are set to the
matched recipients,
and that message is processed by the mailet. The recipients for the other mail are
set to the
non-matching recipients, and that message is not processed by the mailet.</p>
<p>More on matchers and mailets can be found <a
href="mailet_api_2_1.html">here</a>.</p>
<p>One level up from the matchers and mailets are the processors. Each processor
is a list of matcher/mailet pairs. During mail processing, mail messages will be
processed by each pair, in order. In most cases, the message will be processed by
all the pairs in the processor. However, it is possible for a mailet to change the
state of the mail message so it is immediately directed to another processor, and no
additional processing occurs in the current processor. Typically this occurs when
the mailet wants to prevent
future processing of this message (i.e. the mail message has been delivered locally,
and hence requires no further processing) or when the mail message has been
identified
as a candidate for special processing (i.e. the message is spam and thus should be
routed to the spam processor). Because of this redirection, the processors in the
SpoolManager form a tree. The root processor, which must be present, is the root of
this tree.</p>
<p>The SpoolManager continually checks for mail in the spool repository. When
mail is first found in the repository, it is delivered to the root processor.
Mail can be placed on this spool from a number of sources (SMTP, FetchPOP, a
custom component). This spool repository is also used for storage of mail that is
being redirected from one processor to another. Mail messages are driven through
the processor tree until they reach the end of a processor or are marked completed
by a mailet.</p>
<p>More on configuration of the SpoolManager can be found here.</p>
<p>Much of the power of James lies in the SpoolManager component. Custom matchers
and
mailets can be easily developed to address an administrator's particular needs. The
processor tree can easily be configured to sort, filter, and deliver mail based on
any
number of criteria. Mail administrators new to James should spend some time
learning how
to configure the SpoolManager to meet their needs.</p>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/spoolmanager_configuration_2_1.xml
Index: spoolmanager_configuration_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Configuring the SpoolManager</title>
</properties>
<body>
<section name="SpoolManager Configuration">
<p>The SpoolManager is controlled by a single configuration block in the config.xml.
The spoolmanager tag defines the boundaries of the configuration block. The
behavior of
the SpoolManager, most importantly the routing of mail messages through the
processor tree,
is controlled by this block.</p>
<p>The spoolmanager tag has a few simple children. These are:</p>
<ul>
<li><strong>threads</strong> - This is a required positive integer element. It
specifies
the number of threads the SpoolManager will use to process messages in the spool.
This
parameter tends to substantially impact performance, so it is advisable to tune it
in production
configurations.</li>
<li><strong>mailetpackages</strong> - This is a required container tag. It contains
some number
of <strong>mailetpackage</strong> children. The body of each of these
<strong>mailetpackage</strong>
elements is a Java package name. It is these packages that contain the classes to
be instantiated
as mailets.</li>
<li><strong>matcherpackages</strong> - This is a required container tag. It
contains some number
of <strong>matcherpackage</strong> children. The body of each of these
<strong>matcherpackage</strong>
elements is a Java package name. It is these packages that contain the classes to
be instantiated
as matchers.</li>
</ul>
<p>The remaining SpoolManager configuration elements are complex enough to require a
more in-depth
discussion.</p>
<subsection name="Processor Configuration">
<p>In addition to the child elements discussed above, the SpoolManager tag can have
several
<strong>processor</strong> children. It is these tags and their children that
define the processor tree
for the SpoolManager.</p>
<p>Each processor has a required attribute, <strong>name</strong>. The value of
this attribute must be
unique for each processor tag. The name of a processor is significant. Certain
processors are required
(specifically root and error). The name "ghost" is forbidden as a processor name,
as it is used to denote
a message that should not undergo any further processing.</p>
<p>The James SpoolManager creates a correspondance between processor names and the
"state" of a mail as defined
in the Mailet API. Specifically, after each mailet processes a mail, the state of
the message is examined. If
the state has been changed, the message does not continue in the current processor.
If the new state is "ghost"
then processing of that message terminates completely. If the new state is anything
else, the message is
re-routed to the processor with the name matching the new state.</p>
<p>The root processor is a required processor. All new messages that the
SpoolManager finds on the spool are
directed to this processor.</p>
<p>The error processor is another required processor. Under certain circumstances
James itself will redirect messages
to the error processor. It is also the standard processor to which mailets redirect
messages when an error
condition is encountered.</p>
<p>The transport and spam processors are two useful, but optional, processors that
are included in the out of
the box configuration. These processors include logic for actual mail delivery and
spam handling respectively. More
information on these processors can be found in the default config.xml.</p>
<p>Each processor element has zero or more <strong>mailet</strong> child elements.
Each of these elements describes a
matcher/mailet pair. The ordering of the <strong>mailet</strong> children is
crucial to the configuration, as
it is the order in which pairs will be traversed in the processor.</p>
<p>It is this <strong>mailet</strong> element that is at the core of the
SpoolManager configuration.</p>
</subsection>
<subsection name="The Mailet Tag">
<p>Consider the following simple <strong>mailet</strong> tag:</p>
<mailet match="RemoteAddrNotInNetwork=127.0.0.1" class="ToProcessor"><br/>
<processor>spam</processor><br/>
</mailet><br/>
<p>The mailet tag has two required attributes, <strong>match</strong> and
<strong>class</strong>.</p>
<p>The <strong>match</strong> attribute is set to the value of the specific Matcher
class to be instantiated with a an
optional argument. If present, the argument is separated from the Matcher class
name by an '='. Semantic
interpretation of the argument is left to the particular mailet.</p>
<p>The <strong>class</strong> attribute is set to the value of the Mailet class that
is to be instantiated.</p>
<p>Finally, the children of the <strong>mailet</strong> tag define the configuration
that is passed to the Mailet. The
tags used in this section should have no attributes or children. The names and
bodies of the elements will be passed to
the mailet as (name, value) pairs.</p>
<p>So in the example above, a Matcher instance of RemoteAddrNotInNetwork would be
instantiated, and the value "127.0.0.1"
would be passed to the matcher. The Mailet of the pair will be an instance of
ToProcessor, and it will be passed the (name, value)
pair of ("processor", "spam").</p>
<p>James includes a number of pre-packaged Mailets and Matchers. A list of provided
Mailets may be found
<a href="provided_mailets_2_1.html">here</a>. A list of provided Matchers may be
found <a href="provided_matchers_2_1.html">here</a>.</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/summary_2_1.xml
Index: summary_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Component Summary</title>
</properties>
<body>
<section name="The James Server">
<p>James is an open source project intended to produce a robust, flexible, and
powerful
enterprise class server that provides email and email-related services. It is also
designed to
be highly customizable, allowing administrators to configure James to process email
in a
nearly endless variety of fashions.</p>
<p>The James server is built on top of the Avalon Framework. The standard James
distribution
deploys inside the Phoenix Avalon Framework container. In addition to providing a
robust
server architecuture for James, the use of Phoenix allows James administrators to
deploy
their own applications inside the container. These applications can then be
accessed during
mail processing.</p>
<p>The James server is implemented as a complete collection of servers and related
components that, taken together,
provide an email solution. These components are described below.</p>
</section>
<section name="POP3 Service">
<p>The POP3 protocol allows users to retrieve email messages. It is the method
most commonly used by email clients to download and manage email messages.</p>
<p>The James version of the POP3 service is a simple and straightforward
implementation that
provides full compliance with the specification and maximum compatibility with
common
POP3 clients. In addition, James can be configured to require SSL/TLS connections
for
POP3 client connecting to the server.</p>
<p>More information on configuring the POP3 service can be found <a
href="pop3_configuration_2_1.html">here</a>.</p>
</section>
<section name="SMTP Service">
<p>SMTP (Simple Mail Transport Protocol) is the standard method of sending and
delivering
email on the internet. James provides a full-function implementation of the SMTP
specification,
with support for some optional features such as message size limits, SMTP auth, and
encrypted
client/server communication.</p>
<p>More information on configuring the SMTP service can be found <a
href="smtp_configuration_2_1.html">here</a>.</p>
</section>
<section name="NNTP Service">
<p>NNTP is used by clients to store messages on and retrieve messages from news
servers. James provides
the server side of this interaction by implementing the NNTP specification as well
as an appropriate
repository for storing news messages. The server implementation is simple and
straightforward, but
supports some additional features such as NNTP authentication and encrypted
client/server communication.</p>
<p>More information on configuring the NNTP service can be found <a
href="nntp_configuration_2_1.html">here</a>.</p>
</section>
<section name="FetchPOP">
<p>FetchPOP, unlike the other James components, is not an implementation of an RFC.
Instead, it's a
component that allows the administrator to configure James to retrieve email from a
number of POP3
servers and deliver them to the local spool. This is useful for consolidating mail
delivered to a
number of accounts on different machines to a single account.</p>
<p>More information on configuring FetchPOP can be found <a
href="fetchpop_configuration_2_1.html">here</a>.</p>
</section>
<section name="The SpoolManager, Matchers, and Mailets">
<p>James separates the services that deliver mail to James (i.e. SMTP, FetchPOP)
from the engine that processes mail after it is received by James. The
SpoolManager component is James' mail processing engine. James' SpoolManager
component
is a Mailet container. It is these mailets and matchers that actually carry out
mail processing.</p>
<p>More on the structure of the SpoolManager and the Mailet API can be found <a
href="spoolmanager_2_1.html">here</a>.</p>
</section>
<section name="Repositories">
<p>James uses a number of different repositories to both store message data (email,
news messages) and
user information. User repositories store user information, including user names,
authentication
information, and aliases. Mail repositories store messages that have been delivered
locally. Spool
repositories store messages that are still being processed. Finally, news
repositories are used to
store news messages. Aside from what type of data they store, repositories are
distinguished by
where they store data. There are three types of storage - File, Database, and
DBFile.</p>
</section>
<section name="RemoteManager">
<p>James provides a simple telnet-based interface for control. Through this
interface you can add
and delete users, configure per-user aliases and forward addresses, and shut down
the server.</p>
<p>More on the configuring the RemoteManager can be found <a
href="remotemanager_configuration_2_1.html">here</a>.</p>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/table_of_contents_2_1.xml
Index: table_of_contents_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Table of Contents</title>
</properties>
<body>
<section name="Table of Contents">
<p>
I. James Concepts
<ul>
<li><a href="summary_2_1.html">Summary</a></li>
<li><a href="spoolmanager_2_1.html">SpoolManager</a></li>
<li><a href="repositories_2_1.html">Repositories</a></li>
<li><a href="mailet_api_2_1.html">The Mailet API</a></li>
</ul>
II. How To Build James
<ul>
<li><a href="build_instructions_2_1.html">Building James</a></li>
</ul>
III. How To Install James
<ul>
<li><a href="installation_instructions_2_1.html">Installing James</a></li>
</ul>
IV. Configuring James
<ul>
<li><a href="pop3_configuration_2_1.html">POP3 Server Configuration</a></li>
<li><a href="smtp_configuration_2_1.html">SMTP Server Configuration</a></li>
<li><a href="nntp_configuration_2_1.html">NNTP Server Configuration</a></li>
<li><a href="fetchpop_configuration_2_1.html">FetchPOP Configuration</a></li>
<li><a href="remotemanager_configuration_2_1.html">RemoteManager
Configuration</a></li>
<li>Repository Configuration</li>
<li><a href="spoolmanager_configuration_2_1.html">SpoolManager
Configuration</a></li>
<li><a href="serverwide_configuration_2_1.html">Server-wide Configuration</a></li>
<li><a href="adding_users_2_1.html">Adding Users</a></li>
<li><a href="provided_matchers_2_1.html">Provided Matchers</a></li>
<li><a href="provided_mailets_2_1.html">Provided Mailets</a></li>
</ul>
V. Common Configurations
<ul>
<li><a href="smtp_auth_2_1.html">Using SMTP AUTH</a></li>
<li>Using a database to store user data</li>
<li>Using a database to store message data</li>
<li>Using TLS/SSL</li>
<li><a href="james_and_sendmail.html">James and Sendmail</a></li>
</ul>
VI. Customizing James
<ul>
<li><a href="custom_matcher_2_1.html">How to write a custom Matcher</a></li>
<li><a href="custom_mailet_2_1.html">How to write a custom Mailet</a></li>
</ul>
</p>
</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/using_database_2_1.xml
Index: using_database_2_1.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James 2.1 - Using a Database</title>
</properties>
<body>
<section name="Database Configuration">
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
