ZCS Administrator's Guide, Network Edition 5.0 (Rev 5.0.19 September 2009)
Table of Contents Previous Next Index


Working with Zimbra Proxy

Working with Zimbra Proxy
Zimbra Proxy is a high performance proxy server that can be configured as a POP and IMAP proxy server and for reverse proxy HTTP requests.
The Zimbra proxy package is installed and configured during the ZCS installation. This package can be installed on mailbox servers, MTA servers or on their own independent servers. When the zimbra-proxy package is installed, the proxy feature is enabled. In most cases, no modification is necessary.
Note: Zimbra Mobile Connector for BlackBerry Enterprise Server does not support Zimbra Proxy.
Zimbra Proxy Components
Zimbra Proxy is designed to provide a proxy that is quick, reliable, and scalable. Zimbra Proxy includes the following:
Nginx. A high performance IMAP/POP3 proxy server which handles all incoming POP/IMAP requests.
Memcached. A high performance, distributed memory object caching system. Route information is cached for further use in order to increase performance.
Zimbra Proxy Route Lookup Handler. This is a servlet located on the ZCS mailbox server. This servlet handles queries for the user account route information (the server and port number where the user account resides).
Zimbra Proxy Architecture and Flow
The following sequence shows the architecture and flow of Zimbra Proxy.
1.
2.
When Zimbra Proxy receives an incoming connection, the Nginx component sends an HTTP request to the Zimbra Proxy Route Lookup Handler component.
3.
Zimbra Proxy Route Lookup Handler locates the route information for the account being accessed and returns this information to Nginx.
4.
The Memcached component stores the route information for the configured period of time. By default, this time is one hour. Nginx will use this route information until the default period of time has expired, instead of querying the Zimbra Proxy Route Lookup Handler .
5.
6.
Zimbra Proxy connects to Zimbra Mailbox and initiates the mail proxy session. The end client behaves as if it is connecting directly to Zimbra Mailbox.
Customizing Zimbra Proxy Configuration
When Zimbra proxy is configured, the Zimbra proxy config performs keyword substitution as necessary with values from the ZCS LDAP configuration and localconfig.
If changes are required after the Zimbra Proxy is set up, you modify the Zimbra LDAP attributes or localconfig values, and run zmmtaconfig to generate the updated Zimbra Proxy configuration. The Zimbra proxy configuration file is in /opt/zimbra/conf/nginx.conf. The nginx.conf includes the main config, memcache config, mail config, and web config files.
Common changes to Zimbra Proxy configuration are:
GSSAPI authentication for Kerberos. In this case you manually identify the location of the Kerberos Keytab file, including Zimbra Proxy password
Zimbra IMAP/POP Proxy
Zimbra IMAP/POP Proxy allows end users to access their Zimbra Collaboration Suite (ZCS) account using end clients such as Microsoft Outlook, Mozilla Thunderbird, or other POP/IMAP end client software. End users can connect using POP3, IMAP, POP3S (Secure POP3), or IMAPS (Secure IMAP).
For example, proxying allows users to enter imap.example.com as their IMAP server. The proxy running on imap.example.com inspects their IMAP traffic, does a lookup to determine which backend mailbox server a user’s mailbox lives on and transparently proxies the connection from user’s IMAP client to the correct mailbox server.
Zimbra Proxy Ports for POP/IMAP
The following ports are used either by Zimbra Proxy or by Zimbra Mailbox. If you have any other services running on these ports, turn them off.
End clients connect directly to Zimbra Proxy, using the Zimbra Proxy Ports. Zimbra Proxy connects to the Route Lookup Handler or Zimbra Mailbox using the Zimbra Mailbox Ports.
 
Setting up IMAP/POP Proxy after HTTP Proxy
Zimbra Proxy is installed with ZCS and is set up during Installation from the ZCS configuration menus. Zimbra proxy must be installed on the identified proxy nodes in order to set up HTTP proxy. No other configuration is usually required.
To set up IMAP/POP proxy after you have already installed Zimbra http proxy, set up the Zimbra mailbox server and the proxy node as described in the following two sections.
Note: You can run the command as zmproxyinit -r, to run against a remote host. Note that this requires the server to be properly configured in the LDAP master.
Setting Up IMAP/POP Proxy With Separate Proxy Node
When your configuration includes a separate proxy server follow these steps.
Setup Zimbra Mailbox Servers
1.
/opt/zimbra/libexec/zmproxyinit -e -m -H mailbox.node.service.hostname
This configures the following:
2.
a.
b.
Setup Proxy Node
1.
/opt/zimbra/libexec/zmproxyinit -e -m -H proxy.node.service.hostname
This configures the following:
Setting Up a Single Node
When Zimbra proxy is installed along with ZCS on the same server, follow this step.
1.
/opt/zimbra/libexec/zmproxyinit -e -m -H mailbox.node.service.hostname
This configures the following:
2.
a.
b.
Configuring ZCS HTTP Proxy (Beta)
In addition to IMAP/POP3 proxying, the Zimbra proxy package based on nginx is also able to reverse proxy HTTP requests to the right backend server.
Using an nginx-based reverse proxy for HTTP helps to hide names of backend mailbox servers from end users.
For example, users can always use their web browser to visit the proxy server at http://mail.example.com. The connection from users whose mailboxes live on mbs1. example.com is proxied to mbs1.example.com by the proxy running on the mail.example.com server. In addition to the ZCS web interface, clients such as REST and CalDAV clients, Zimbra Connector for Outlook, and Zimbra Mobile Sync devices are also supported by the proxy.
HTTP reverse proxy routes requests as follows:
If the request has an auth token cookie (ZM_AUTH_TOKEN), the request is routed to the backend mailbox server of the authenticated user.
If the requesting URL can be examined to determine the user name, then the request is routed to the backend mailbox server of the user in the URL. REST, Ca lDAV, and Zimbra Mobile Sync are supported through this mechanism.
If the above methods do not work, the IP hash method is used to load balance the requests across the backend mailbox servers which are able to handle the request or do any necessary internal proxying.
Setting up HTTP Proxy after IMAP/POP Proxy is set up
Zimbra Proxy is installed with ZCS and is set up during Installation from the ZCS configuration menus. Zimbra proxy must be installed on the identified proxy nodes in order to set up HTTP proxy. No other configuration is usually required.
To set up http (s) proxy after you have already installed zimbra proxy for IMAP/POP, set up the Zimbra mailbox server and the proxy node as described in the following two sections.
Note: You can run the command as zmproxyinit -r, to run against a remote host. Note that this requires the server to be properly configured in the LDAP master.
Setting Up HTTP Proxy With Separate Proxy Node
When your configuration includes a separate proxy server follow these steps.
 
Setup Zimbra Mailbox Servers
1.
/opt/zimbra/libexec/zmproxyinit -e -w -H mailbox.node.service.hostname
This configures the following:
zimbraMailReferMode to reverse-proxied. See Note below.
zimbraMailPort to 8080, to avoid port conflicts.
zimbraMailSSLPort to 8443, to avoid port conflicts.
zimbraMailMode to http. This is the only supported mode.
2.
a.
b.
3.
Configure each domain with the public service host name to be used for REST URLs, commonly used in sharing Document Notebooks, email and Briefcase folders. Run
zmprov modifyDomain <domain.com> zimbraPublicServiceHostname <hostname.domain.com>
Setup Proxy Node
1.
/opt/zimbra/libexec/zmproxyinit -e -w -H proxy.node.service.hostname
This configures the following:
zimbraMailReferMode to reverse-proxied. See Note below.
zimbraMailProxyPort to 80, to avoid port conflicts.
zimbraMailSSLProxyPort to 443, to avoid port conflicts.
zimbraReverseProxyHttpEnabled to TRUE to indicate that Web proxy is enabled.
zimbraReverseProxyMailMode defaults to both.
If you want to set the proxy server mail mode, add to the command the -x option with the mode you desire: http, https, both, redirect, mixed.
Setting Up a Single Node for HTTP Proxy
When Zimbra proxy is installed along with ZCS on the same server, follow this step.
1.
/opt/zimbra/libexec/zmproxyinit -e -w -H mailbox.node.service.hostname
This configures the following:
zimbraMailReferMode to reverse-proxied. See Note below.
zimbraMailPort to 8080, to avoid port conflicts.
zimbraMailSSLPort to 8443, to avoid port conflicts.
zimbraMailMode to http. This is the only supported mode.
zimbraMailReferMode to reverse-proxied. See Note below.
zimbraMailProxyPort to 80, to avoid port conflicts.
zimbraMailSSLProxyPort to 443, to avoid port conflicts.
zimbraReverseProxyHttpEnabled to TRUE to indicate that Web proxy is enabled.
zimbraReverseProxyMailMode defaults to both.
If you want to set the proxy server mail mode, add to the command the -x option with the mode you desire: http, https, both, redirect, mixed.
2.
a.
b.
3.
Configure each domain with the public service host name to be used for REST URLs, commonly used in sharing Document Notebooks, email and Briefcase folders. Run
zmprov modifyDomain <domain.com> zimbraPublicServiceHostname <hostname.domain.com>
REST URL Generation
When HTTP proxy is enabled, the following attributes can be set globally or by domain for REST URL
When generating REST URL’s:
If domain.zimbraPublicServiceHostname is set, use zimbraPublicServiceProtocol + zimbraPublicServiceHostname + zimbraPublicServicePort
Otherwise it falls back to the server (account's home server) attributes:
- protocol is computed from server.zimbraMailMode
- hostname is server.zimbraServiceHostname
- port is computed from the protocol.
 
Note: Why use zimbraMailReferMode - In earlier versions of Zimbra, a local config variable called zimbra_auth_always_send_refer was used to determine what the backend server did when a user whose mailbox did not reside on that server logged in on that server. the default value of FALSE meant that the backend server would only redirect the user if the user was logging in on the wrong backend host.
On a multi-server ZCS, however, if a load balanced name was needed to create a friendly landing page, a user would always have to be redirected. In that case, zimbra_auth_always_send_refer was set to TRUE.
Now with a full-fledged reverse proxy, users do not need to be redirected. The localconfig variable zimbraMailReferMode is used with nginx reverse proxy.
Configuring Zimbra Proxy for Kerberos Authentication
If you use the Kerberos5 authenticating mechanism, use the following steps to configure IMAP and POP proxy.
Note: Make sure that your Kerberos5 authentication mechanism is correctly configured before you do this. See the "Zimbra Directory Service" Kerberos5 Authentication Mechanism.
1.
To set the default Kerberos domain for authentication, on each proxy node, set the zimbraReverseProxyDefaultRealm server attribute to the realm name corresponding to the proxy server. For example, enter as:
zmprov ms [DNS name.isp.net] zimbraReverseProxyDefaultRealm [ISP.NET]
2.
Each proxy IP address where email clients connect must be configured for GSSAPI authentication by the mail server. On each proxy node for each of the proxy IP addresses, enter the following command:
zmprov mcf +zimbraReverseProxyAdminIPAddress [IP address]
3.
zmprov ms [proxyexample.net] zimbraReverseProxyImapSaslGssapiEnabled TRUE
zmprov ms proxyl.isp.net zimbraReverseProxyPop3SaslGssapiEnabled TRUE
4.
zmproxyctl stop
zmproxyctl start

Working with Zimbra Proxy

Table of Contents Previous Next Index
ZCS Administrator's Guide, Network Edition 5.0 (Rev 5.0.19 September 2009)
Copyright © 2009 Zimbra Inc.