Zimbra Intercepting Proxy

This software is used to intercept and apply modifications to the traffic between a Zimbra Proxy and Zimbra Mailboxes. If you don't know what a Zimbra Proxy is, You can read about it here: https://wiki.zimbra.com/wiki/Zimbra_Proxy_Guide

This work for all kind of client access:

  • POP3
  • IMAP
  • Webmail
  • ActiveSync
  • Zimbra Outlook Connector

What this try to solve?

Zimbra Migrations

Suppose you need to move a lot of users and data from one Zimbra Platform to another, like we do at ZBox, and given the size of the migration, you can't move all the mailboxes at once, so you have to do it in groups.

This procedure have the following inconvenients:

  • You have to update the configuration of the clients for all the migrated users,
  • Your users will need to learn a new Webmail URL,
  • It's not transparent for the end user,
  • It's a lot of work for you

Network and OpenSource Deployments

Not a hot topic for Zimbra Inc., sorry guys, but lets be honest about it, some companies can't afford Zimbra Network for all the employees, so they use two setup platform.

The main problem with this is that you have to configure your clients with to kind of information.

How Zimbra Intercepting Proxy Works

Zimbra Intercepting Proxy reads a map file, a YAML file, in which you indicate the pair username:zimbraID of the users located on the other Mailbox.

Based on this information, ZIP tell the Zimbra Proxy to which Mailbox it should communicate with.

Instalation and configuration


This has been tested with:

  • Zimbra >= 7
  • Ruby >= 2.0
  • Zimbra Proxy

You need to have direct access to the 7072 port of both Mailboxes.


It's recommended to install it on the same Zimbra Proxy server. All you need to do is run:

$ gem install zimbra_intercepting_proxy

Zimbra Mailbox IP Whitelist

Since version 8, Zimbra has a DDoS protection system that blocks IP's address with many failed login connections. It's adviced by the Zimbra Docs to Whitelist the IP's address that you trust.

You have to do this on the NEW_MAILBOX to whitelist connections from the IP from where you are migrating

$ zmprov mcf +zimbraHttpThrottleSafeIPs NEW_MAILBOX_IP
$ zmmailboxdctl restart

Zimbra Proxy Modification

Important Note You are going to modify Zimbra template files, used to build the configuration files of Nginx. Take some backups!!

  • All the files are located in /opt/zimbra/conf/nginx/templates.
  • <, config being replaced
  • >, new config

You have to make this modifications

 # nginx.conf.mail.template
<     ${mail.:auth_http}
>     auth_http  localhost:9072/service/extension/nginx-lookup;
 # nginx.conf.web.template
<         #${web.upstream.:servers}
>         server localhost:9080;
<     #${web.:routehandlers}
>     zmroutehandlers localhost:9072/service/extension/nginx-lookup;

Next restart. You should restart memcached and nginx, but just to be sure:

$ zmcontrol restart

Starting Zimbra Intercepting Proxy

You have to start 2 instances of ZIP:

  • One on port 9080 for Web and SOAP Auth Requests, and
  • One on port 9072 for Route-Handler, this is how the Proxy knows to which Mailbox redirect the traffic.

So the first one:

$ zimbra_intercepting_proxy -d example.com -f /root/users.yml -o oldmailbox.example.com --newmailbox= -b 9080 --newmailboxlocalip=192.168.0.

And the second one:

$ zimbra_intercepting_proxy -d example.com -f /root/users.yml -o oldmailbox.example.com --newmailbox= -b 9072 --newmailboxlocalip=192.168.0.


  • -d, the domain, in case the user only enters the username,
  • -o, the default or old Mailbox,
  • --newmailbox, the other or new Mailbox,
  • -f, the YAML map file, with the list of users on the --newmailbox,
  • -b, the bind port
  • --newmailboxlocalip, the LAN IP address of the --newmailbox

The Map File

It's a simple YAML file with a email:zimbraId pair, like

[email protected]: "7b562c60-be97-0132-9a66-482a1423458f"
[email protected]: "7b562ce0-be97-0132-9a66-482a1423458f"
[email protected]: "251b1902-2250-4477-bdd1-8a101f7e7e4e"
[email protected]: "7b562dd0-be97-0132-9a66-482a1423458f"

Updating the file does not require a restart.

You can get the zimbraId with:

$ zmprov ga [email protected] zimbraId
Error in Map File

If you have an error in your file, ZIP will return the on memory Map, this way we can keep the service up. In this event you should see this on STDOUT:

ERROR Yaml File: (./test/fixtures/users.yml): could not find expected ':' while scanning a simple key at line 7

Init scripts

In the examples directory you have the following files:

  • zip_9072, to start the server on port 9072
  • zip_9080, you know

Copy both files to the /etc/init.d/ directory and then enable the services like this:

$ chkconfig --add zip_9072
$ chkconfig --add zip_9080


It may be posible that ZIP crash for some reason, it's a new software after all. To reduce the down time we recomend to use Monit to monitor and restart the ZIP in case of trouble.

Check the examples directory for config files.



  1. Fork it ( https://github.com/pbruna/zimbra_intercepting_proxy/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request