Modified: james/server/trunk/src/site/xdoc/common_configurations.xml URL: http://svn.apache.org/viewvc/james/server/trunk/src/site/xdoc/common_configurations.xml?rev=1001446&r1=1001445&r2=1001446&view=diff ============================================================================== --- james/server/trunk/src/site/xdoc/common_configurations.xml (original) +++ james/server/trunk/src/site/xdoc/common_configurations.xml Sun Sep 26 15:13:45 2010 @@ -24,311 +24,316 @@ </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> -<section name="Database Configuration"> -<p>James has the capacity to use a JDBC-compatible database for storage of both message and user -data. This section explains how to configure James to utilize a database for storage.</p> -<subsection name="Requirements"> -<p>Using James with a database backend has certain requirements. Database configuration is -extremely vendor-specific, so we can only state the requirements in general terms.</p> -<p>There must be a database instance accessible from the James server. An account with appropriate -privileges (select, insert, delete into tables, and on initial startup creation of tables) and -with sufficient quota for the data to be inserted into the database must be available. Also, -since James will use JDBC to access the database, an appropriate JDBC driver must be -available for installation.</p> -<p>It is important to verify the functionality of the database before attempting to configure -James to use it as a repository. This will help ensure that configuration issues are properly -identified.</p> -</subsection> -<subsection name="Connection Configuration"> -<p>Configuring the Phoenix container to work with JDBC is the first step in enabling James database support.</p> -<p>First, Phoenix must be able to load the JDBC classes. To make these classes available to Phoenix, place the -jar/zip files for the JDBC driver in the lib subdirectory of the James installation directory. Any additional -libraries upon which the JDBC library depends that are not part of the standard Java distribution should also be -added to this directory.</p> -<p>Second, the config.xml must be modified so that Phoenix initializes the database connections. The relevant -configuration is in the database-connections block. The database-connections tag has only a single child tag, -data-sources. This latter tag is a simple container tag for a number of child elements. It is these child -elements, <strong>data-source</strong> elements, that define the database connections.</p> -<p>Each <strong>data-source</strong> tag has a required attribute, <strong>name</strong>. This value -must be unique to each <strong>data-source</strong> element. It is this <strong>name</strong> that will -be used to specify the database connection in other parts of the config.xml file.</p> -<p>The <strong>data-source</strong> element has five children, all of whom are required. -<ul> -<li><strong>driver</strong> - The class name of the database driver to be used.</li> -<li><strong>dburl</strong> - The JDBC connection URL for your database/driver.</li> -<li><strong>user</strong> - The user id of the database account to be used by this connection.</li> -<li><strong>password</strong> - The password of the database account to be used by this connection.</li> -<li><strong>max</strong> - The maximum number of JDBC connections to be used concurrently by this data-source.</li> -</ul> -</p> - -<p>Generally, you simply configure these entries in the config.xml -file, which are commented, in order to use a database with James. You -would then use the db: or dbfile: prefix instead of the file: prefix -for a particular repository. You are currently free to mix and match -your use of these different storage types for different repositories. -See <a href="repositories.html">Repository Configuration</a> for -more details. A sample configuration is described below.</p> - -</subsection> -<subsection name="SQL Statement Configuration"> -<p>The precise SQL statements used by James to modify and view data stored in the database are specified in -an external configuration file. The sqlResources.xml file -(which can be found in the apps/james/conf directory) is a sample configuration file that contains the SQL -statements used by James. The purpose of each of these statements, as well as the repository with which -they are associated, is documented in situ.</p> - -<p>If you are using a SQL database with unusual SQL commands or data types, you may -need to add special entries to this file. The James team -does try to keep sqlResources.xml updated, so if you do run into a -special case, please let us know.</p> - -<p>Also, if the database tables are not created a priori, but rather are to be created by James -upon startup, special attention should be paid to the "create table" statements in this file. Such -statements tend to be both very database and very database instance specific.</p> -</subsection> -<subsection name="Sample James Configuration"> - -<p>The config.xml file has commented out examples for MySQL and -MSSQL data sources, and for each of the standard repositories. For -example, to use MySQL, you would uncomment and adjust the following -data-source element.</p> - -<p>You must create the database, in this case named -<strong>mail</strong>, the user, and assign the user privileges. -You may create the tables before running James or, if you so choose, James -will automatically create the tables it needs. In the latter case the user -must have table creation privileges.</p> - -<source> -<data-source name="maildb" class="org.apache.james.util.mordred.JdbcDataSource"> - <driver>com.mysql.jdbc.Driver</driver> - <dburl>jdbc:mysql://127.0.0.1/mail</dburl> - <user>username</user> - <password>password</password> - <max>20</max> -</data-source> -</source> - -<p>Once the data-source element has been created, it can be referenced elsewhere in the config.xml -file. For example, the following element tells James to use the maildb data-source and dbfile -storage mechanism for the message spool:</p> - -<source> -<spoolRepository> - <repository destinationURL="dbfile://maildb/spool/spool" type="SPOOL"/> -</spoolRepository> -</source> - -<p>The following element tells James to store mailboxes in a the maildb data-source:</p> - -<source> -<inboxRepository> - <repository destinationURL="db://maildb/inbox/" type="MAIL"/> -</inboxRepository> -</source> - -<p>The configuration file contains further examples.</p> -</subsection> -<subsection name="Known Issues"> -<p>There are some vendor-specific subtleties in using databases with James that have been observed -by some users. These issues (and methods to resolve them) are recorded on the -<a href="../FAQ.html">James FAQ</a> as they are reported. Please consult the FAQ if you encounter any -difficulties.</p> -</subsection> -</section> - -<section name="James 3.0 - Using TLS"> - -<p> -This document explains how to enable James 3.0 services to use Transport Layer Security (TLS) for encrypted client-server communication.</p> - -<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 -sockets. JSSE comes packaged with several vendor Java distributions (i.e. Sun Java 1.4.x, -IBM Java 1.3.x). For these distributions, please follow the vendor provided instructions for -configuring the JVM to use JSSE services.</p> - -<p>If you are using a Java distribution that does not include JSSE as part of the -distribution you will need to download the JSSE package separately. It can be obtained from -<a href="http://java.sun.com/products/jsse";>here</a>. Please follow Sun's instructions for installation -and configuration of JSSE.</p> -<p>In either case, you will need to statically define a JSSE TLS provider. In general, this -is the default installation.</p> -<p>Once you've installed JSSE, James still needs to be configured to take advantage of the JSSE -functionality.</p> -</subsection> -<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.html">SMTP</a>, -<a href="pop3_configuration.html">POP3</a>, <a href="nntp_configuration.html">NNTP</a>, -and <a href="remotemanager_configuration.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> -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> - -<section name="How To Create Mailing Lists"> -<p>One of the frequent questions on the James-User Mailing List is how -to create a mailing list. This document explains one way of using the -currently supplied Matchers and Mailets in James v3.0.</p> - -<p>Basically, the process requires creating two <mailet> entries -and a repository. The first mailet handles list commands (currently -only <i>list-name</i>-on and <i>list-name</i>-off). The second mailet -handles list messages. The repository will hold the e-mail addresses -of list subscribers.</p> - -<p>The mailets go into the processor chain (e.g., at the top of the -<i>transport</i> processor), the repository goes into the -<users-store> block.</p> - -<subsection name="Setting up the Mailets"> - -<p>You need to setup two mailets.</p> - -<p>The first mailet that you need to setup is an instance of the <a -href="provided_mailets.html#AvalonListservManager">Avalon Listserv -Manager</a> mailet. This will handle subscribing and unsubscribing. -[Note: the current code does not support confirmed opt-in, just basic -commands.] The <a -href="provided_matchers.html#CommandForListserv">CommandForListserv</a> -matcher is used to invoke match messages containing commands for the -mailing list.</p> - -<p>The second mailet is an instance of the <a -href="provided_mailets.html#AvalonListserv">Avalon Listserv</a> -mailet. That mailet actually receives messages for the list and -causes them to be distributed. The <a -href="provided_matchers.html#RecipientIs">RecipientIs</a> matcher -is used to match messages intended for the mailing list.</p> - -<p>The following illustrates the two <mailet> elements that need to be added:</p> - -<source> - <mailet match="CommandForListserv=<i>list-name</i>@<i>domain</i>" - class="AvalonListservManager"> - <repositoryName><i>list-name</i></repositoryName> - </mailet> - - <mailet match="RecipientIs=<i>list-name</i>@<i>domain</i>" class="AvalonListserv"> - <repositoryName><i>list-name</i></repositoryName> - ... list options ... - </mailet> -</source> - -</subsection> - -<subsection name="Setting up the Repository"> - -<p>The mailing list mailets need a repository within which to store -the subscriber list. There is a separate repository for each mailing -list, and is completely independent of the user repository used by -James to manage e-mail accounts. This is configured in the -<users-store> block of config.xml.</p> - -<p>The following illustrates a database-backed repository using JDBC -with the ListUsersJdbcRepository class. Notice that there will be a -single table, <i>lists</i>, created in the db://maildb resource -defined elsewhere. There are currently two columns: the list name and -the list subscriber.</p> - -<source> - <repository name="<i>list-name</i>" - class="org.apache.james.userrepository.ListUsersJdbcRepository" - destinationURL="db://maildb/lists/<i>list-name</i>"> - <sqlFile>file://conf/sqlResources.xml</sqlFile> - </repository> -</source> - -<p>The following illustrates a file-system repository using the -UsersFileRepository class. [Note: the destination URL is a child -element when configuring a file-system repository, and an attribute -when configuring a database-backed repository. This inconsistency -will be addressed in a future version of James.]</p> - -<source> - <repository name="<i>list-name</i>" - class="org.apache.james.userrepository.UsersFileRepository"> - <destination URL="file://var/lists/<i>list-name</i>/" /> - </repository> -</source> - -</subsection> -</section> + <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> + + <section name="Database Configuration"> + <p>James has the capacity to use a JDBC-compatible database for storage of both message and user + data. This section explains how to configure James to utilize a database for storage.</p> + <subsection name="Requirements"> + <p>Using James with a database backend has certain requirements. Database configuration is + extremely vendor-specific, so we can only state the requirements in general terms.</p> + <p>There must be a database instance accessible from the James server. An account with appropriate + privileges (select, insert, delete into tables, and on initial startup creation of tables) and + with sufficient quota for the data to be inserted into the database must be available. Also, + since James will use JDBC to access the database, an appropriate JDBC driver must be + available for installation.</p> + <p>It is important to verify the functionality of the database before attempting to configure + James to use it as a repository. This will help ensure that configuration issues are properly + identified.</p> + </subsection> + <subsection name="Connection Configuration"> + <p>Configuring the Phoenix container to work with JDBC is the first step in enabling James database support.</p> + <p>First, Phoenix must be able to load the JDBC classes. To make these classes available to Phoenix, place the + jar/zip files for the JDBC driver in the lib subdirectory of the James installation directory. Any additional + libraries upon which the JDBC library depends that are not part of the standard Java distribution should also be + added to this directory.</p> + <p>Second, the config.xml must be modified so that Phoenix initializes the database connections. The relevant + configuration is in the database-connections block. The database-connections tag has only a single child tag, + data-sources. This latter tag is a simple container tag for a number of child elements. It is these child + elements, <strong>data-source</strong> elements, that define the database connections.</p> + <p>Each <strong>data-source</strong> tag has a required attribute, <strong>name</strong>. This value + must be unique to each <strong>data-source</strong> element. It is this <strong>name</strong> that will + be used to specify the database connection in other parts of the config.xml file.</p> + <p>The <strong>data-source</strong> element has five children, all of whom are required. + <ul> + <li><strong>driver</strong> - The class name of the database driver to be used.</li> + <li><strong>dburl</strong> - The JDBC connection URL for your database/driver.</li> + <li><strong>user</strong> - The user id of the database account to be used by this connection.</li> + <li><strong>password</strong> - The password of the database account to be used by this connection.</li> + <li><strong>max</strong> - The maximum number of JDBC connections to be used concurrently by this data-source.</li> + </ul> + </p> + + <p>Generally, you simply configure these entries in the config.xml + file, which are commented, in order to use a database with James. You + would then use the db: or dbfile: prefix instead of the file: prefix + for a particular repository. You are currently free to mix and match + your use of these different storage types for different repositories. + See <a href="repositories.html">Repository Configuration</a> for + more details. A sample configuration is described below.</p> + + </subsection> + <subsection name="SQL Statement Configuration"> + <p>The precise SQL statements used by James to modify and view data stored in the database are specified in + an external configuration file. The sqlResources.xml file + (which can be found in the apps/james/conf directory) is a sample configuration file that contains the SQL + statements used by James. The purpose of each of these statements, as well as the repository with which + they are associated, is documented in situ.</p> + + <p>If you are using a SQL database with unusual SQL commands or data types, you may + need to add special entries to this file. The James team + does try to keep sqlResources.xml updated, so if you do run into a + special case, please let us know.</p> + + <p>Also, if the database tables are not created a priori, but rather are to be created by James + upon startup, special attention should be paid to the "create table" statements in this file. Such + statements tend to be both very database and very database instance specific.</p> + </subsection> + <subsection name="Sample James Configuration"> + + <p>The config.xml file has commented out examples for MySQL and + MSSQL data sources, and for each of the standard repositories. For + example, to use MySQL, you would uncomment and adjust the following + data-source element.</p> + + <p>You must create the database, in this case named + <strong>mail</strong>, the user, and assign the user privileges. + You may create the tables before running James or, if you so choose, James + will automatically create the tables it needs. In the latter case the user + must have table creation privileges.</p> + + <source> + <data-source name="maildb" class="org.apache.james.util.mordred.JdbcDataSource"> + <driver>com.mysql.jdbc.Driver</driver> + <dburl>jdbc:mysql://127.0.0.1/mail</dburl> + <user>username</user> + <password>password</password> + <max>20</max> + </data-source> + </source> + + <p>Once the data-source element has been created, it can be referenced elsewhere in the config.xml + file. For example, the following element tells James to use the maildb data-source and dbfile + storage mechanism for the message spool:</p> + + <source> + <spoolRepository> + <repository destinationURL="dbfile://maildb/spool/spool" type="SPOOL"/> + </spoolRepository> + </source> + + <p>The following element tells James to store mailboxes in a the maildb data-source:</p> + + <source> + <inboxRepository> + <repository destinationURL="db://maildb/inbox/" type="MAIL"/> + </inboxRepository> + </source> + + <p>The configuration file contains further examples.</p> + </subsection> + + <subsection name="Known Issues"> + <p>There are some vendor-specific subtleties in using databases with James that have been observed + by some users. These issues (and methods to resolve them) are recorded on the + <a href="../FAQ.html">James FAQ</a> as they are reported. Please consult the FAQ if you encounter any + difficulties.</p> + </subsection> + + </section> + + <section name="James 3.0 - Using TLS"> + + <p>This document explains how to enable James 3.0 services to use Transport Layer Security (TLS) for encrypted client-server communication.</p> + + <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 + sockets. JSSE comes packaged with several vendor Java distributions (i.e. Sun Java 1.4.x, + IBM Java 1.3.x). For these distributions, please follow the vendor provided instructions for + configuring the JVM to use JSSE services.</p> + + <p>If you are using a Java distribution that does not include JSSE as part of the + distribution you will need to download the JSSE package separately. It can be obtained from + <a href="http://java.sun.com/products/jsse";>here</a>. Please follow Sun's instructions for installation + and configuration of JSSE.</p> + <p>In either case, you will need to statically define a JSSE TLS provider. In general, this + is the default installation.</p> + <p>Once you've installed JSSE, James still needs to be configured to take advantage of the JSSE + functionality.</p> + </subsection> + <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.html">SMTP</a>, + <a href="pop3_configuration.html">POP3</a>, <a href="nntp_configuration.html">NNTP</a>, + and <a href="remotemanager_configuration.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> + 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> + + <section name="How To Create Mailing Lists"> + + <p>One of the frequent questions on the James-User Mailing List is how + to create a mailing list. This document explains one way of using the + currently supplied Matchers and Mailets in James v3.0.</p> + + <p>Basically, the process requires creating two <mailet> entries + and a repository. The first mailet handles list commands (currently + only <i>list-name</i>-on and <i>list-name</i>-off). The second mailet + handles list messages. The repository will hold the e-mail addresses + of list subscribers.</p> + + <p>The mailets go into the processor chain (e.g., at the top of the + <i>transport</i> processor), the repository goes into the + <users-store> block.</p> + + <subsection name="Setting up the Mailets"> + + <p>You need to setup two mailets.</p> + + <p>The first mailet that you need to setup is an instance of the <a + href="provided_mailets.html#AvalonListservManager">Avalon Listserv + Manager</a> mailet. This will handle subscribing and unsubscribing. + [Note: the current code does not support confirmed opt-in, just basic + commands.] The <a + href="provided_matchers.html#CommandForListserv">CommandForListserv</a> + matcher is used to invoke match messages containing commands for the + mailing list.</p> + + <p>The second mailet is an instance of the <a + href="provided_mailets.html#AvalonListserv">Avalon Listserv</a> + mailet. That mailet actually receives messages for the list and + causes them to be distributed. The <a + href="provided_matchers.html#RecipientIs">RecipientIs</a> matcher + is used to match messages intended for the mailing list.</p> + + <p>The following illustrates the two <mailet> elements that need to be added:</p> + + <source> + <mailet match="CommandForListserv=<i>list-name</i>@<i>domain</i>" + class="AvalonListservManager"> + <repositoryName><i>list-name</i></repositoryName> + </mailet> + + <mailet match="RecipientIs=<i>list-name</i>@<i>domain</i>" class="AvalonListserv"> + <repositoryName><i>list-name</i></repositoryName> + ... list options ... + </mailet> + </source> + + </subsection> + + <subsection name="Setting up the Repository"> + + <p>The mailing list mailets need a repository within which to store + the subscriber list. There is a separate repository for each mailing + list, and is completely independent of the user repository used by + James to manage e-mail accounts. This is configured in the + <users-store> block of config.xml.</p> + + <p>The following illustrates a database-backed repository using JDBC + with the ListUsersJdbcRepository class. Notice that there will be a + single table, <i>lists</i>, created in the db://maildb resource + defined elsewhere. There are currently two columns: the list name and + the list subscriber.</p> + + <source> + <repository name="<i>list-name</i>" + class="org.apache.james.userrepository.ListUsersJdbcRepository" + destinationURL="db://maildb/lists/<i>list-name</i>"> + <sqlFile>file://conf/sqlResources.xml</sqlFile> + </repository> + </source> + + <p>The following illustrates a file-system repository using the + UsersFileRepository class. [Note: the destination URL is a child + element when configuring a file-system repository, and an attribute + when configuring a database-backed repository. This inconsistency + will be addressed in a future version of James.]</p> + + <source> + <repository name="<i>list-name</i>" + class="org.apache.james.userrepository.UsersFileRepository"> + <destination URL="file://var/lists/<i>list-name</i>/" /> + </repository> + </source> + </subsection> + + </section> </body> + </document>
--------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
