OpsEmailImapProxy

Installing the default cache database (ops_email_cachedb)

OPS e-mail uses a cache for message-id/projectGuid pairs to increase performance, these pairs are stored in a database by the OPS IMAP proxy. The standard database used for this is a HSQLDB database. If deploying it on the same machine the webservices and the IMAP proxy are installed there is no need to adjust the configuration.

Important: For best security and performance it is recommended to run the database on the same server as the IMAP proxy and webservices. When doing so make sure the database is not accessible from outside, configure your firewall to block traffic to it. Default database port is 3636.

Changing settings

Settings of the HSQLDB can be changed in "server.properties". If you don't want to run the cache database on the same server as the IMAP proxy and the OPS webservices, you'll have to change the configuration for those OPS parts. So they can still connect to the database.

Starting the database not using the startup script

Just start the database by running "startdb.sh", or "startdb.bat" under Windows.

Generating self signed certificate (ops_email_imapproxy/etc)

It's recommended to run the OPS IMAP proxy using SSL. When using the IMAP protocol without SSL, username and password information will be send in plain text! If you don't have any certificates signed by an official certificate authority you can create self signed certificates. To create certificates for the OPS IMAP proxy a script is included which generates self signed certificates. Before running the script you should change the settings. For Windows use "generatekeys.bat", for any Unix OS use "generatekeys.sh". After the certificates have been generated you can import "ops_client.cer" in the "cacerts" file used by OpsProject. For more information see: adding a trusted certificate

Copy "keystore.jks" and "clientkeystore.jks" to "ops_email_imapproxy/bin". (Default certificates are already in there)

Using existing certificates

A tutorial on importing existing certificates into your Java keystore can be found here.

Importing an existing certificate and private key can be somewhat of a hassle. I achieved it the following way. You need:

• a private key with which you generated the certificate request for your certificate (in this example: mailserver.key)
• the certificate, signed by your Certificate Authority (mailserver.cer)
• openssl (which you should already have installed and used to generate the key and csr (certificate request)
• pkeytool, a tool to import private keys into the keystore

Take the following steps:

• unpack pkeytool.zip
• convert the private key to pkcs#8 format: openssl pkcs8 -nocrypt -topk8 < /path/to/mailserver.key > mailserverkey.pk8
• make sure you have a 'stripped' mailserver certificate, ie only the encoded part (between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)
• import key and certificate in the keystore: java -jar pkeytool.jar -importkey -keyfile /path/to/mailserverkey.pk8 -certfile /path/to/mailserver.cer -keystore keystore.jks
• check if it was imported ok: keytool -list -keystore keystore.jks. The certificate should be listed as a 'keyEntry', not a 'trustedCertificate'.

-- ThijsSchnitger - 06 Apr 2006

Installing the OPS IMAP proxy(ops_email_imapproxy)

From .zip

• Extract the .ZIP file to a specified folder
• IMAP proxy start/stop script
  • Set the right directories for Java and the IMAP proxy in the script
  • Set the right directory for the cache database, in case any other is used, remove the start of the cache database
  • Copy the script from "ect/" to your script folder
• Configure the IMAP proxy by changing settings in "imapproxy.properties"

Build from source

• get source at svn
• run: $ mvn clean:clean assembly:assembly from the project directory. This will get you a zip file with all the dependencies and all scripts, configuration files and so on.
• Extract the .zip file from the target directory to a specified folder.
• IMAP proxy start/stop script
  • Set the right directories for Java and the IMAP proxy in the script
  • Set the right directory for the cache database, in case any other is used, remove the start of the cache database
  • Copy the script from "ect/" to your script folder
• Configure the IMAP proxy by changing settings in "imapproxy.properties"

Configuring IMAP

The IMAP proxy must be the only means of reaching the IMAP server, if this condition is not met the cache database can get out of sync with the IMAP server! To do this it's easiest and probably safest to run the IMAP server on the same server as the IMAP proxy and make the IMAP server not accessible from the outside. The default is to run the IMAP server on port 3737 and close off this port from the outside with a firewall.

Running, not using the startup script

To start the IMAP proxy use the command, from the IMAP proxy folder:

java -cp lib/activation.jar:lib/commons-logging.jar:lib/DDConnectionBroker.jar:lib/hsqldb.jar:lib/log4j-1.2.8.jar:lib/mail.jar:. org.openprojectservices.imapproxy.ImapProxyServer

Note: When starting the IMAP proxy for the first time, add the "-sync" parameter at the end to initialize the database. Whenever the database has gone corrupt or out of sync start the IMAP proxy using this command.

Starting the IMAP proxy and cache databse

Included in the "etc/" of the IMAP proxy there is a script called "imapproxy", with this script the cache database and IMAP proxy can be started, stopped, restarted and synced.

-- BastiaanGrutters - 03 Jan 2006