Configuring Perdition

Admin Article

Article Information

This article applies to the following ZCS versions.

ZCS 4.5 Article ZCS 4.5


Perdition use cases

Perdition is a proxy for the POP and IMAP protocols that allows a user to connect to any Perdition server, regardless of their account's zimbraMailHost, and use a POP or IMAP client to access their mail.

Perdition is useful in multi-node installations, where several mailstore servers may be accessed through the same hostname (either via round-robin DNS or a load balancer).

Perdition is also useful for offloading the SSL connection from the tomcat server, and handling it in the proxy. This can reduce the load on the mailstore server, as well as work around some IMAP SSL bugs.

Note: Perdition only proxies IMAP and POP - it is not an HTTP/S proxy.

Perdition can proxy these services:

  • IMAP (default port 143)
  • IMAPS (default port 993)
  • POP3 (default port 110)
  • POP3S (default port 995)

Requirements

Perdition requires version 3.1.4 or better of the Zimbra Collaboration Suite to operate correctly. Currently, it is installed on the same server as the tomcat mailstore server.

Setting the ports

"Real" and proxied ports

In any perdition setup, there are 2 ports defined for every service. The real port is the port that tomcat listens on to handle connections. The proxied port is the port that perdition listens on for client connections. When perdition is configured, the client connects to the proxied port, and perdition connects to the tomcat server on the real port. The real ports can (and probably should) be blocked from access to the outside world by your firewall.

zimbraPop3BindPort
This is the real port for cleartext POP connections
zimbraPop3SSLBindPort
This is the real port for SSL POP connections
zimbraPop3ProxyBindPort
This is the proxied port for cleartext POP connections
zimbraPop3SSLProxyBindPort
This is the proxied port for SSL POP connections
zimbraImapBindPort
This is the real port for cleartext IMAP connectionsions
zimbraImapSSLBindPort
This is the real port for SSL IMAP connectionsions
zimbraImapProxyBindPort
This is the proxied port for cleartext IMAP connectionsions
zimbraImapSSLProxyBindPort
This is the proxied port for SSL IMAP connections

Port consistency

When configuring perdition in a multi server environment, all of the servers should have the same ports defined for the real ports, and the same ports for the proxied ports. That is, all servers should have the zimbraImapSSLBindPort defined the same. Failure to do so will prevent perdition from operating correctly.

Additionally, all of the ports should be unique on a server - so none of the ports on a given server should be used for any other service on that server.

Cleartext and encrypted connections

By default, the server will not accept IMAP and POP login over a cleartext (non-encrypted) connection. If cleartext connections to the server are enabled, the perdition proxy will forward SSL connections to the cleartext port on the real server port, offloading the SSL processing from the tomcat server. This is the recommended configuration

Enabling cleartext IMAP/POP connections

To enable cleartext connections on the server server.example.com:

zmprov ms server.example.com zimbraImapCleartextLoginEnabled TRUE zimbraPop3CleartextLoginEnabled TRUE

This requires a tomcat restart.

Perdition certificates

Perdition uses the certificate in /opt/zimbra/conf/perdition.pem and the key in /opt/zimbra/conf/perdition.key. These are created on installation, or can be recreated manually.

Perdition log levels

The default ZCS perdition.conf has connection and debug logging enabled. This will send extremely verbose information to the /var/log/zimbra.log. To reduce this, you can disable the debug and connection logging. Look for these lines in the file /opt/zimbra/conf/perdition.conf.in:

   C
   d

Comment those lines out and add a line with "q" for quiet:

   #C
   #d
   q

Then run "zmperditionctl restart". Verify that the changes have propagated to the /opt/zimbra/conf/perdition.conf; if not, edit that file to make the same changes manually and restart perdition again.

Note: If there were already any imap connections to perdition, they will continue the verbose logging until they are closed.

Enabling the service

Enabling at install time

If you are installing zimbra, perdition can be enabled at install time under the store menu. Enabling it at install time will automatically set the ports correctly and enable the service, and none of the other instructions in this section are needed.

Set the ports

To enable perdition on the host server.example.com with proxied ports 110, 143, 993, and 995 and real ports of 7110, 7143, 7993 and 7995: Set the proxied Ports

zmprov ms server.example.com zimbraPop3ProxyBindPort 110 zimbraImapProxyBindPort 143 zimbraPop3SSLProxyBindPort 995 zimbraImapSSLProxyBindPort 993

Set the real Ports

zmprov ms server.example.com zimbraPop3BindPort 7110 zimbraImapBindPort 7143 zimbraPop3SSLBindPort 7995 zimbraImapSSLBindPort 7993

Enable the proxy service

zmprov ms server.example.com +zimbraServiceEnabled imapproxy

Start the services

Restart tomcat

tomcat stop; tomcat start

Start perdition

zmperditionctl start

Disabling the service

To disable Perdition, perform the steps to enable in reverse order.

Stop the service

zmperditionctl stop

Disable the proxy service

zmprov -- ms server.example.com -zimbraServiceEnabled imapproxy

Unset the proxy ports

zmprov ms server.example.com zimbraPop3ProxyBindPort "" zimbraImapProxyBindPort "" zimbraPop3SSLProxyBindPort "" zimbraImapSSLProxyBindPort ""

Set the real ports

zmprov ms server.example.com zimbraPop3BindPort 110 zimbraImapBindPort 143 zimbraPop3SSLBindPort 995 zimbraImapSSLBindPort 993

Restart Tomcat

tomcat stop
tomcat start


Verified Against: ZCS 4.5.x Date Created: 7/25/2006
Article ID: https://wiki.zimbra.com/index.php?title=Configuring_Perdition Date Modified: 2015-03-24



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search