pgoldstein 2002/12/11 02:47:12
Modified: src/xdocs usingTLS_2_1.xml custom_matcher_2_1.xml
custom_mailet_2_1.xml
src/xdocs/stylesheets project.xml
Added: src/xdocs rfclist.xml
Log:
More documentation changes.
Revision Changes Path
1.2 +35 -37 jakarta-james/src/xdocs/usingTLS_2_1.xml
Index: usingTLS_2_1.xml
===================================================================
RCS file: /home/cvs/jakarta-james/src/xdocs/usingTLS_2_1.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- usingTLS_2_1.xml 2 Dec 2002 11:31:56 -0000 1.1
+++ usingTLS_2_1.xml 11 Dec 2002 10:47:12 -0000 1.2
@@ -12,7 +12,6 @@
<p>
This document explains how to enable James 2.1 services to use Transport Layer
Security (TLS) for encrypted client-server communication.</p>
-</section>
<subsection name="Making TLS/SSL Server Sockets Available Inside James">
<p>James uses the Sun Java Secure Sockets Extension (JSSE) infrastructure to
provide TLS/SSL
@@ -29,45 +28,44 @@
<p>Once you've installed JSSE, James still needs to be configured to take advantage
of the JSSE
functionality.</p>
</subsection>
-<section name="Enable TLS">
-
- <p>
- Using JAMES with TLS. You need to do three things over and above the
- normal operation of James:
- <ul>
- <li>In config.xml, uncomment the TLS listener defintion.</li>
- <li>In config.xml, uncomment the <useTLS>TRUE</useTLS> element
- for the service you want to use TLS. It is currently available for
- remote manager and POP3. (If using POP3 over TLS, it is probably best
- to change port to 995, which is the IANA designated POP3S port).</li>
- <li> Ensure that avalonTestKeys is in the conf directory. You may need
- to manually extract this from the Avalon.jar (with: jar xvf Avalon.jar
- conf/avalonTestKeys). Note that this is a self-signed certificate for
- test purposes only. You can specify a different server certificate in
- the config.xml file.</li>
- </ul>
- </p>
- <p>
- Start James
- </p>
-</section>
-
-<section name="Verifying a TLS-enabled James Service">
-<p>After you've configured a particular service to use TLS/SSL connections, it
should no longer
-accept normal TCP/IP connections. You can execute this negative test case by using
a telnet
+<subsection name="Certificate Keystores">
+<p>To use TLS/SSL inside James you will need a certificate keystore.</p>
+</subsection>
+<subsection name="Configuring the Server Socket Factory">
+<p>The out of the box configuration file contains a template for the SSL
configuration in place. Specifically,
+in the sockets block, under the server-sockets element, there is a commented out
factory with the
+name "ssl". The first step to configuring the server socket factory is
uncommenting out this element.</p>
+<p>The factory element contains several children. Of these, it should only be
necessary to adjust two or three children.</p>
+<p>The required file element specifies the location of the keystore to be used by
the factory. This is specified
+as a file path using Unix-style formatting. The path is taken to be relative to
the apps/james/ subdirectory of
+the application installation directory unless an absolute path is specified.</p>
+<p>The password element should be set to the keystore password. This password
should have been specified
+when the keystore was created, and it is required to open the keystore. This value
is required.</p>
+<p>Finally, it may be necessary to adjust the type element. This element can take
on any keystore type
+supported by the JSSE provider being used (see the JSSE documentation for details).
The out of the box
+configuration specifies JKS (Java Keystore).</p>
+<p>The remaining children should not need to be deleted or adjusted.</p>
+</subsection>
+<subsection name="Configuring a Service to Use TLS">
+<p>Each of the services - <a href="smtp_configuration_2_1.html">SMTP</a>,
+<a href="pop3_configuration_2_1.html">POP3</a>, <a
href="nntp_configuration_2_1.html">NNTP</a>,
+and <a href="remotemanager_configuration_2_1.html">RemoteManager</a> - supports use
of TLS. Each of
+these services has an optional boolean configuration element <b>useTLS</b> which is
used to toggle
+use of TLS for the service. When this value is set to true, that particular
service will use the "ssl"
+server socket factory to spawn server sockets.</p>
+</subsection>
+<subsection name="Verifying a TLS-enabled James Service">
+<p>After you've configured a particular service to use TLS/SSL connections, the
service port
+should no longer accept unencrypted TCP/IP connections. This can be tested by
using a telnet
client to directly connect to the service port. The telnet connection should
simply hang until
the client times out.</p>
<p>
- (Positive Test) Use an SSL client to open a socket to the appropriate port.
- I used openssl from www.openssl.org to test this.
- E.g. openssl s_client -connect localhost:4555. You should see the normal
- remote manager or POP3 server greeting and have normal operation.
- <br>
- - If, using openssl s_client, you get a connection refused/ error no
- 111, just try again. This probably means you got to the port before it
- was ready.
- </br>
- </p>
+To validate that the port is properly accepting SSL connections an SSL client can
be used to
+open a connection to the service port. One such client is OpenSSL, available from
the
+<a href="http://www.openssl.org";>OpenSSL web site</a>. Follow the instructions
provided with
+the SSL client to create a connection to the service port. Upon connection, the
usual
+service greeting should appear.</p>
+</subsection>
</section>
</body>
1.4 +34 -0 jakarta-james/src/xdocs/custom_matcher_2_1.xml
Index: custom_matcher_2_1.xml
===================================================================
RCS file: /home/cvs/jakarta-james/src/xdocs/custom_matcher_2_1.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- custom_matcher_2_1.xml 7 Dec 2002 20:38:20 -0000 1.3
+++ custom_matcher_2_1.xml 11 Dec 2002 10:47:12 -0000 1.4
@@ -73,5 +73,39 @@
GenericMatcher/GenericRecipientMatcher.</p>
</subsection>
</section>
+<section name="Deploying a Custom Matcher">
+<p>Once a Matcher has been successfully implemented there are only a couple of
+additional steps necessary to actually deploy the Matcher.</p>
+<subsection name="Adding Your Matcher to the Classpath">
+<p>
+The Matcher must be added to James' classpath so that the Matcher can be loaded by
James. There
+are two ways to add a custom Matcher to the classpath so that James will be able to
load the
+Matcher. These are:
+</p>
+<p>
+1. Download the source distribution, add a jar file containing the custom files to
the lib
+directory of the unpacked source distribution, and build a new .sar file by
following the
+directions <a href="build_instructions_2_1.html">here</a>. This new .sar file will
now
+include your custom classes.
+</p>
+<p>
+or
+</p>
+<p>
+2. Place a jar file containing the custom class files in the lib subdirectory of
the James
+installation. It will also be necessary to unpack the JavaMail and James jar files
from
+the provided .sar file and add them to this directory.
+</p>
+</subsection>
+<subsection name="James Configuration">
+<p>Configuration of the processor chain is discussed
+<a href="spoolmanager_configuration_2_1.html">elsewhere</a> in this documentation.
The
+details of configuring matcher deployment is discussed at length. Here we will
only comment
+that it is important to add the appropriate matcher package for your custom matcher
to the
+<matcherpackages> list and that the name of your matcher should not conflict
with any of
+the matchers described <a href="provided_matchers_2_1.html">here</a>.
+</p>
+</subsection>
+</section>
</body>
</document>
1.4 +34 -0 jakarta-james/src/xdocs/custom_mailet_2_1.xml
Index: custom_mailet_2_1.xml
===================================================================
RCS file: /home/cvs/jakarta-james/src/xdocs/custom_mailet_2_1.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- custom_mailet_2_1.xml 7 Dec 2002 20:38:20 -0000 1.3
+++ custom_mailet_2_1.xml 11 Dec 2002 10:47:12 -0000 1.4
@@ -62,5 +62,39 @@
GenericMailet.</p>
</subsection>
</section>
+<section name="Deploying a Custom Mailet">
+<p>Once a Mailet has been successfully implemented there are only a couple of
+additional steps necessary to actually deploy the Mailet.</p>
+<subsection name="Adding Your Mailet to the Classpath">
+<p>
+The Mailet must be added to James' classpath so that the Mailet can be loaded by
James. There
+are two ways to add a custom Mailet to the classpath so that James will be able to
load the
+Mailet. These are:
+</p>
+<p>
+1. Download the source distribution, add a jar file containing the custom files to
the lib
+directory of the unpacked source distribution, and build a new .sar file by
following the
+directions <a href="build_instructions_2_1.html">here</a>. This new .sar file will
now
+include your custom classes.
+</p>
+<p>
+or
+</p>
+<p>
+2. Place a jar file containing the custom class files in the lib subdirectory of
the James
+installation. It will also be necessary to unpack the JavaMail and James jar files
from
+the provided .sar file and add them to this directory.
+</p>
+</subsection>
+<subsection name="James Configuration">
+<p>Configuration of the processor chain is discussed
+<a href="spoolmanager_configuration_2_1.html">elsewhere</a> in this documentation.
The
+details of configuring mailet deployment is discussed at length. Here we will only
comment
+that it is important to add the appropriate mailet package for your custom mailet
to the
+<mailetpackages> list and that the name of your mailet should not conflict
with any of
+the mailets described <a href="provided_mailets_2_1.html">here</a>.
+</p>
+</subsection>
+</section>
</body>
</document>
1.1 jakarta-james/src/xdocs/rfclist.xml
Index: rfclist.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>James - RFC Directory</title>
</properties>
<body>
<section name="RFC Directory">
<p>This document contains a list of and links to RFCs relevant to James.</p>
<subsection name="General RFCs">
<a href="rfclist/basic/rfc0822.txt">RFC 822: Mail Message Format</a><br/>
<a href="rfclist/basic/rfc1123.txt">RFC 1123: Requirements for Internet Hosts --
Application and Support (updated by RFC 2821)</a><br/>
<a href="rfclist/basic/rfc2045.txt">RFC 2045: Multipurpose Internet Mail Extensions
(MIME) Part One: Format of Internet Message Bodies</a><br/>
<a href="rfclist/basic/rfc2822.txt">RFC 2822: Internet Message Format</a><br/>
</subsection>
<subsection name="SMTP RFCs">
<a href="rfclist/smtp/rfc0821.txt">RFC 821: SMTP Protocol</a><br/>
<a href="rfclist/smtp/rfc0974.txt">RFC 974: Mail Routing and the Domain
System</a><br/>
<a href="rfclist/smtp/rfc1652.txt">RFC 1652: SMTP Service Extension for
8bit-MIMEtransport (elective, but widely adopted)</a><br/>
<a href="rfclist/smtp/rfc1830.txt">RFC 1830: SMTP Service Extensions for
Transmission of Large and Binary MIME Messages (experimental, but cool idea)</a><br/>
<a href="rfclist/smtp/rfc1869.txt">RFC 1869: SMTP Service Extensions</a><br/>
<a href="rfclist/smtp/rfc1870.txt">RFC 1870: SMTP Service Extension for Message Size
Declaration</a><br/>
<a href="rfclist/smtp/rfc1891.txt">RFC 1891: SMTP Service Extension for Delivery
Status Notifications (elective)</a><br/>
<a href="rfclist/smtp/rfc1893.txt">RFC 1893: Enhanced Mail System Status Codes
(experimental)</a><br/>
<a href="rfclist/smtp/rfc1985.txt">RFC 1985: SMTP Service Extension for Remote
Message Queue Starting (elective)</a><br/>
<a href="rfclist/smtp/rfc2034.txt">RFC 2034: SMTP Service Extension for Returning
Enhanced Error Codes (elective)</a><br/>
<a href="rfclist/smtp/rfc2142.txt">RFC 2142: Mailbox Names For Common Services,
Roles And Functions</a><br/>
<a href="rfclist/smtp/rfc2197.txt">RFC 2197: SMTP Service Extension for Command
Pipelining (elective)</a><br/>
<a href="rfclist/smtp/rfc2554.txt">RFC 2554: SMTP Service Extension for
Authentication</a><br/>
<a href="rfclist/smtp/rfc2821.txt">RFC 2821: Simple Mail Transfer Protocol</a><br/>
</subsection>
<subsection name="POP3 RFCs">
<a href="rfclist/pop3/rfc1725.txt">RFC 1725: POP3 Protocol</a><br/>
<a href="rfclist/pop3/rfc1734.txt">RFC 1734: POP3 AUTHentication command</a><br/>
</subsection>
<subsection name="IMAP RFCs">
<a href="rfclist/imap4/rfc1731.txt">RFC 1731: IMAP4 Authentication
Mechanisms</a><br/>
<a href="rfclist/imap4/rfc2060.txt">RFC 2060: IMAP Version 4rev1</a><br/>
<a href="rfclist/imap4/rfc2086.txt">RFC 2086: IMAP4 ACL extension</a><br/>
<a href="rfclist/imap4/rfc2087.txt">RFC 2087: IMAP4 QUOTA extension</a><br/>
<a href="rfclist/imap4/rfc2088.txt">RFC 2088: IMAP4 non-synchronizing
literals</a><br/>
<a href="rfclist/imap4/rfc2177.txt">RFC 2177: IMAP4 IDLE command</a><br/>
<a href="rfclist/imap4/rfc2180.txt">RFC 2180: IMAP4 Multi-accessed Mailbox
Practice</a><br/>
<a href="rfclist/imap4/rfc2192.txt">RFC 2192: IMAP URL Scheme</a><br/>
<a href="rfclist/imap4/rfc2193.txt">RFC 2193: IMAP4 Mailbox Referrals</a><br/>
<a href="rfclist/imap4/rfc2195.txt">RFC 2195: IMAP/POP AUTHorize Extension for
Simple Challenge/Response</a><br/>
<a href="rfclist/imap4/rfc2221.txt">RFC 2221: IMAP4 Login Referrals</a><br/>
<a href="rfclist/imap4/rfc2342.txt">RFC 2342: IMAP4 Namespace (elective)</a><br/>
<a href="rfclist/imap4/rfc2359.txt">RFC 2359: IMAP4 UIDPLUS extension
(elective)</a><br/>
<a href="rfclist/imap4/rfc2595.txt">RFC 2595: Using TLS with IMAP, POP and
ACAP</a><br/>
<a href="rfclist/imap4/rfc2683.txt">RFC 2683: IMAP4 Implementation
Recommendations</a><br/>
</subsection>
<subsection name="NNTP RFCs">
<a href="rfclist/nntp/rfc0977.txt">RFC 977 : NNTP Protocol</a><br/>
<a href="rfclist/nntp/rfc1036.txt">RFC 1036: Format of News Messages</a><br/>
<a href="rfclist/nntp/rfc2980.txt">RFC 2980: Common NNTP Extensions</a><br/>
<a href="http://www.academ.com/academ/nntp/";>NNTP Working Group</a><br/>
</subsection>
<subsection name="LDAP RFCs">
</subsection>
</section>
</body>
</document>
1.19 +1 -1 jakarta-james/src/xdocs/stylesheets/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-james/src/xdocs/stylesheets/project.xml,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- project.xml 9 Dec 2002 05:08:07 -0000 1.18
+++ project.xml 11 Dec 2002 10:47:12 -0000 1.19
@@ -26,7 +26,7 @@
<item name="Mailet API" href="/mailet/index.html"/>
<item name="James and sendmail" href="/james_and_sendmail.html"/>
- <item name="Useful RFCs (web)"
href="http://jakarta.apache.org/james/rfclist"/>
+ <item name="Useful RFCs" href="/rfclist.html"/>
</menu>
<menu name="Older Documentation">
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
