Installation of Exim Webapp

If you use a UNIX variant with poor startup scripts, like a *BSD or SCO, things will be more difficult (this doesn't apply to Exim Webapp more than any other application). If you run Linux or Solaris, this will be a snap.

I don't want to clutter up this section with stuff about security, since a common scenario is to get things working in a secured environment and open the server up to the public only after you get it working and tightened down. If your target server is open to the public right now, then read the Security section before this section.

Install Java 1.4

To make my life easier, I use features of Java 1.4, so earlier versions of Java won't work. I don't enjoy working with old software, so I don't expect to ever back-port. http://java.sun.com/j2se/1.4.2/download.html

Install Tomcat 5

http://jakarta.apache.org/tomcat/tomcat-5.0-doc/index.html You can use other versions, and even other servlet containers. These instructions cover Tomcat 5 though, because, even though it is imperfect, the deployment gui is nice, and I like it. The rest of these instructions call your base Tomcat directory CATALINA_HOME.

If you are savvy enough to be using CATALINA_BASE, then you should know when to use CATALINA_HOME and when to use CATALINA_BASE, otherwise, always use CATALINA_HOME.

Fix up Tomcat 5.

If you already have Tomcat set up, then skip this section completely.

If you are running a Tomcat distribution that sets up owners and init scripts for you, then skip this paragraph. Choose/create a Tomcat user and group, fix permissions up, then run it. Example.

              groupadd tomcat
              useradd tomcat
              cd /usr/local
              unzip /path/to/...jakarta-tomcat*.zip
              mv jakarta-tomcat* tomcat-5.0.16
              cd tomcat-5.0.16
              chown -R tomcat:tomcat conf logs temp webapps work
          

If you're running a binary Tomcat distro for *BSD or SCO, you'll have to figure out Tomcat environment setup on your own, because I've wasted enough of my life catering to idiosyncracies of those systems.

For mainstream UNIXes, just create a file CATALINA_HOME/bin/setenv.sh with contents like

              JAVA_HOME=/usr/java/j2sdk1.4.2_02  # User your real Java home dir.
              umask 02
              cd $CATALINA_HOME    # Type it in exactly like this.
          

(You don't need to make setenv.sh executable since it is sourced, not executed. (The umask command permits developers in the Tomcat group to modify logs and web applications). Note that you don't need to export JAVA_HOME. The cd is needed so log files specified in commons/log4j config files can use relative paths.

Edit CATALINA_HOME/conf/tomcat-users.xml and add an account for yourself with role manager.

Start up Tomcat

For a distro with an init script, run /etc/init.d/tomcat start. (Like I said, *BSD and SCO users are on your own). If you have no init script, then run catalina.sh as the Tomcat user.

              bin/catalina.sh start
          OR
              su tomcat -c "/path/to/CATALINA_HOME/bin/catalina.sh start"
          

(If you have locked down the Tomcat account, you will need to enable logins in order to su).

Make sure your Tomcat user has needed Exim permissions.

The Tomcat user needs to have permission to read the Exim log files and to execute privileged exim commands.

With my several exiscan installations, this is easily accomplished by adding the user Tomcat to the privileged Exim OS group. If you have a less accommodating or an older Exim build, you may have to set up the privileged group settings in Exim before this will work.

Do a ls -l on the logging directory. Most often the logs are group-readable to the same privileged group as above. If it is some other group, then you will need to add the Tomcat user to that group too.

The definitive test to verify that your permissions are all set up is to su to the account and verify.

              su - tomcat
              tail /path/to/main/exim/main.log.file
              /path/to/exim -bp
          

(If you have locked down the Tomcat account, you will need to enable logins in order to su). If the tail and the exim commands succeed, you're all set.

Deploy exim-webapp.war

Right click on http://admc.com/dist/exim-webapp.war and download it (if you're reading this in a web page). Use a browser to connect to http://localhost:8080 (or wherever you configured it to run. In the left column, click Tomcat Manager. In the bottom text field, click in the path to the exim-webapp.war file that you downloaded and click the Deploy button. (The app won't work right yet, because you have to make deployment settings... plus the app didn't have time to create the logging directory yet).

Make deployment settings.

Edit the file CATALINA_HOME/webapps/exim/WEB-INF/web.xml. There are about 6 settings like @this@ for which you need to substitute the real values. For example, change

              @emailadmin.emailaddr@
          TO
              youremailaddr@somewhere.com
          

See the Security section below for how to add usernames/passwords.

Restart your Tomcat server, like

              /etc/init.d/tomcat restart
          OR
              /path/to/CATALINA_HOME/bin/catalina.stop &&
              /path/to/CATALINA_HOME/bin/catalina.start
          

Drop me a line & Use the app

Please email me at blaine.simpson@admc.com just to say that you're installing. You don't have to, of course, but I'd like to have some idea of how many people are using Exim Webapp so I know whether to expend additional effort on enhancements, etc. Let me know if you want to know about fixes and/or enhancements. (See the feature section above for upcoming improvements).

To access your web interface to Exim, use a browser to go to http://localhost:8080/exim-webapp/, or /exim at whatever host and port you are running Tomcat on.

You can tell what version of Exim Webapp you're running in three different ways. It's in the display-name in the web.xml file. It's shown in the Tomcat Application Manager applications listing (by virtue of the display-name). It's shown in the footer of most of the pages for the application.

If you like Exim Webapp, It'd be cool if you could put a link to this Howto on your web site, if you have one. (Besides direct publicity, this moves the Howto up in search engine ratings).