[{TableOfContents }]
\\

__Note:__ At the moment, these directions are primarily aimed at a deployment of JSPWiki on Tomcat 6.0. However, you will find essential hints on configuring JSPWiki's newly added ([NewIn2.6]) support for container-managed e-mail factories here. Feel free to extend this page regarding other servlet containers!

For some general information on JNDI with Tomcat 6 see [Apache Tomcat 6.0 JNDI Resources HOW-TO|http://tomcat.apache.org/tomcat-6.0-doc/jndi-resources-howto.html].

!!!Resources

* [MultipleWikis] - Excellent discussion of how to install JSPWiki regardless whether you're installing one or multiple instances. 
* [Configurations To Be Edited|JNDI Mail Configuration#Configurations To Be Edited]
** [Global Naming Resources|JNDI Mail Configuration#GlobalNamingResources]
** [JSPWiki Context|JNDI Mail Configuration#JSPWiki Context]
** [Mail Session Resource Reference|JNDI Mail Configuration#Mail Session Resource Reference]
** [JSPWiki Mail Properties|JNDI Mail Configuration#JSPWiki Mail Properties]
* [Files to be moved|JNDI Mail Configuration#FilesToBeMoved]
** activation.jar and mail.jar

!!!Process
* Install JSPWiki
* Edit Configurations
* Move Files

!!!Configurations To Be Edited
!!Global Naming Resources

Update {{<TOMCAT_HOME>/conf/server.xml}} as appropriate for your mail server and account.
{{{
<GlobalNamingResources>
    <!-- JavaMail JNDI Mail Session -->
    
    <Resource name="mail/Session" auth="Container"
        type="javax.mail.Session"
        username="<mail account username>"
        password="<mail account password>"
        mail.debug="false"
        mail.user="<mail account username>"
        mail.from="My wiki &lt;email@domain.com&gt;"
        mail.transport.protocol="smtp" 
        mail.smtp.host= "<smtp mail host>"
        mail.smtp.auth= "true"
        mail.smtp.port= "<SMTP Server Port>" <!-- Default 25 -->
        mail.smtp.starttls.enable="true"
        description="Global E-Mail Resource"
    />
}}}

If anything goes wrong, you may want to set {{mail.debug="true"}} here and {{log4j.rootCategory}} from {{INFO}} to {{DEBUG}} in {{jspwiki.properties}}.

If {{mail.from}} is defined here, you'll have to escape the "less than" and "greater than" characters via {{&amp;lt;}} and {{&amp;gt;}}, since we're speaking XML here: {{mail.from="My wiki &amp;lt;email@domain.com&amp;gt;"}}\\
In this case, the defined value is used by JSPWiki, too.\\
If {{mail.from}} is not defined here, you can configure which address to use in {{jspwiki.properties}}.

__Note__ if you're using an SMTP mail server that requires authentication: This won't work if only {{mail.user}} and {{mail.password}} are set because these aren't
automatically used for authentication. Therefore, you have to set {{username}} and {{password}} to the same values (or other
values that authenticate you properly).
For details see [http://forum.java.sun.com/thread.jspa?threadID=615393&messageID=3422166]

!!JSPWiki Context
Next you have to link the global resource into JSPWiki's Context. For Tomcat 6, there are several ways to do this (for details see [Apache Tomcat Configuration Reference - The Context Container|http://tomcat.apache.org/tomcat-6.0-doc/config/context.html]).

The Context can be defined for example in:
* {{<TOMCAT_HOME>/conf/catalina/localhost/<your JSPWiki name>.xml}}
* {{<TOMCAT_HOME>/webapps/<Your JSPWiki Name>/META-INF/context.xml}}

The first location allows the JSPWiki Context to remain in place through multiple deployments.
{{{
<Context path="/Wiki" docBase="C:/Apps/Tools/JSPWiki/JSPWiki.war" debug="true">
    <Parameter name="jspwiki.propertyfile"
        value="C:/WebContent/Wiki/jspwiki.properties" override="false"
    />
    <ResourceLink
        name="mail/Session"
        global="mail/Session"
        type="javax.mail.Session"
    />
</Context>
}}}

!!Mail Session Resource Reference
Location: {{<TOMCAT_HOME>/webapps/<your JSPWiki name>/WEB-INF/web.xml}}

Edit {{web.xml}} and uncomment the following lines:
{{{
<resource-ref>
    <description>Resource reference to a container-managed JNDI JavaMail factory for sending e-mails.</description>
    <res-ref-name>mail/Session</res-ref-name>
    <res-type>javax.mail.Session</res-type>
    <res-auth>CONTAINER</res-auth>
</resource-ref>
}}}

!!JSPWiki Mail Properties
Location: {{<TOMCAT_HOME>/webapps/<your JSPWiki name>/WEB-INF/jspwiki.properties}} or as defined and relocated in the JSPWiki Context specification.

{{{
###########################################################################
#
#  JavaMail configuration 
#  If you wish to allow your users to recover their passwords via email,
#  you should configure these properties. JavaMail can use either a 
#  container-managed JNDI resource factory (recommended, and the default), 
#  or a stand-alone factory whose properties are configured with mail.* 
#  properties in this file (below).

#  The address from which the email appears to come. This is required
#  for either of the mail configuration methods
mail.from =JSPWiki <email@my domain>
#
#  A. JNDI Resource Factory Configuration. JSPWiki will try this first.
#     You will need to configure your container to provide a JavaMail
#     resource factory. See your container documentation, or check our
#     fairly complete documentation (with examples for Tomcat) in
#     the JavaDocs for com.ecyrd.jspwiki.util.MailUtil.
#
#  JNDI resource name. (mail/Session is the default)
jspwiki.mail.jndiname = mail/Session

}}}

!!!Files To Be Moved
Location: {{<TOMCAT_HOME>/webapps/<your JSPWiki name>/WEB-INF/lib}}

!!mail.jar
Move (don't copy) {{mail.jar}} to Tomcat's lib directory ({{<TOMCAT_HOME>/lib}}).

!!activation.jar
If you are using Java Runtime Environment (JRE) 1.5 or earlier, move {{activation.jar}} to Tomcat's lib same as {{mail.jar}}. If you are using JRE 1.6 or greater, then the {{activation.jar}} is included in it, so simply delete JSPWiki's copy of it.

!!!Acknowledgment 

Thanks to [Florian Holeczek] for identifying the needed configuration and a bug in the JSPWiki code. He identified the crucial information that allowed the Mail Session to be correctly authenticated.

Thanks to [Dave Wolf] for creating the initial version of this page and testing these configuration hints.

----

[Category Documentation]\\
[Category Tips]