Zimbra Proxy Manual:Miscellaneous Topics

Zimbra Proxy: Miscellaneous Topics

   KB 21176        Last updated on 2016-06-7  

(0 votes)

Miscellaneous Topics

Set Up Proxy to use Clear Text for Upstream Connections

Source : Admin Guide Draft, 'Set Up Proxy to use Clear Text for Upstream Connections'

When setting up the proxy to use clear text for upstream connections, set zimbraReverseProxySSLToUpstreamEnabled to FALSE.

This attribute defaults to TRUE. In an "out of the box" proxy set up, the upstream communication defaults to SSL.

Proxy Interaction With zimbraMailMode

The following table documents the supported combinations of the following three settings:

  • zimbraReverseProxySSLToUpstreamEnabled
  • zimbraReverseProxyMailMode
  • zimbraMailMode
zimbraReverseProxySSLToUpstreamEnabled zimbraReverseProxyMailMode zimbraMailMode
TRUE both both
https both or https
mixed both
redirect both or https
FALSE both both
http both or http

The recommended way to update the value of zimbraMailMode is via the use of the zmtlsctl command. This command will query the appropriate proxy server and ensure that the new value you are specifying is compatible with the proxy settings. In addition, it will warn you if the setting of zimbraReverseProxyMailMode is not compatible with zimbraReverseProxySSLToUpstreamEnabled.

If the zmtlsctl command is being run on a node that is not a target of the proxy, or if you are not using a proxy, then no restrictions are placed on the new setting for zimbraMailMode.

REST URL Generation

Source : Admin Guide Draft, 'REST URL Generation'

For REST URL, you set the host name, service protocol, and services port globally or for a specific domain from the following attributes.

  • zimbraPublicServiceHostname
  • zimbraPublicServiceProtocol
  • zimbraPublicServicePort

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, a local config variable called zimbra_auth_always_send_refer determined which action the back-end server took when a user’s mailbox did not reside on the server that the user logged in to. The default value of FALSE redirected the user if the user was logging in on the wrong backend host.

On a multiserver ZCS, 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.

Set Proxy Trusted IP Addresses

Source : Admin Guide Draft, 'Set Proxy Trusted IP Addresses'

When a proxy is configured with ZCS, each proxy server’s IP address must be configured in LDAP attribute zimbraMailTrustedIP to identify the proxy addresses as trusted when users log in through the proxy. The proxy IP address is added to the X-Forwarded-For header information. The X-Forwarded-For header is automatically added to the localconfig zimbra_http_originating_ip_header attribute. When a user logs in, this IP address and the user’s address are verified in the Zimbra mailbox log.

Set each proxy IP address in the attribute. For example, if you have two proxy servers: zmprov mcf +zimbraMailTrustedIP {IP of nginx-1} +zimbraMailTrustedIP {IP of nginx-2}

Note: To verify that X-Forwarded-For was correctly added to the localconfig, type zmlocalconfig | grep -i http. You should see zimbra_http originating_ip_header = X-Forwarded-For.

Zimbra Proxy Performance Tuning

See the following unresolved RFE:

Details On Some Of The Zimbra Customization To The Proxy Components

Source : [Internal Eng. Wiki /index.php/Zimbra/Admin/Proxy/Overview#Motivation_behind_Expanding_Nginx ]

Motivation behind Expanding Nginx

Although official Nginx is powerful, it can't meed all the needs of Zimbra.


Nginx's AUTH_HTTP protocol (described in http://wiki.nginx.org/NginxMailCoreModule#Authentication) is borrowed to implement the lookup with NLE. However, official Nginx's mail AUTH_HTTP config can only specify one NLE URL (auth_http directive). We wish to extend this support so that NZ can use more than one NLE. When a great load of user logins come, NZ can dispatch the load to multiple NLE running in different zimbra servers. This will end up not overloading a single NLE. In a production set-up, it is likely that there will be many different NZ identically configured, and so the relationship between the NZ set and the server set running NLE is a many-to-many relationship.

Besides, the lookup is also necessary for zimbra web accessing, which is not supported by official Nginx. Therefore, this lookup and upstream choose function must also be implemented as an nginx http module.

Finally, because Zimbra doesn't use AUTH_HTTP protocol for real authentication, it might add some custom HTTP headers (such as "Auth-ID") and avoid some useless content transmit (such as password via "Auth-Pass").

All of these above have to be extended by Zimbra.

Memcache Module

It is likely that a single user may log in many times via NZ in a short time, or one http request will generate a great many of sub requests, all of which contains the same login information and thus will get the same route lookup result. In such cases, NZ will have to contact the NLE many times. It is not likely that the upstream server information for a particular client will change frequently. (A change in the upstream server usually corresponds to a user's mailbox being migrated to a different server). And at the same time NLE is relative much slower than Nginx, becoming the bottle neck.

As such, it will be beneficial if NZ is able to cache such information so that repeated trips to the NLE servers are avoided. Also, this cached information must be made available to possibly multiple NZ instances. Hence, "memcached" (http://www.danga.com/memcached/) was introduced for this purpose. Memcached is a high-performance, distributed memory object caching system.

Although official Nginx has a build-in "ngx_http_memcache" module, it can only be used for "URL->web page" cache. Therefore, a global "ngx_memcache" module is implemented in NZ which could be accessed by both web and mail modules. Memcached is used to cache 5 kinds of information as follows. The 4th and 5th are used in mail throttle control, which will be described in [Zimbra/Admin/Proxy/Throttle Control]:

  • alias-->account name
  • account name->route information
  • account id-->route information
  • login IP address->login count (IP throttle control)
  • account name->login count (user throttle control)

Enhanced Mail Protocol Support

Compared to the web proxy part, official nginx is relative weak in mail proxy, such as:

  • Official nginx cannot completely support IMAP ID command, which is required for the logging of upstream zimbra servers
  • Official nginx can't echo the [ALERT] msg before authenticating to the upstream server
  • Official nginx does not support GSSAPI authentications.
  • Official nginx does not support upstream SSL connection, that is, using POP3S and IMAPS protocol connecting nginx and upstream server.

These features are critical for a mail system of enterprise level. ZCS' mail server support these, so NZ has to support them as well.

Unlike web proxy, during which nginx simply proxies all the requests, in mail proxy nginx has to handle some mail protocol commands rather than proxy them to upstream before login is given. The reason is before getting route from NLE, NZ doesn't know to use which upstream server. These commands include "ID", "NOOP", "LOGIN", "CAPABILITY", "AUTHENTICATE", "LOGOUT", "STARTTLS" for IMAP, and "USER", "CAPA", "PASS", "NOOP", "STLS", "QUIT" for POP3. Although official nginx support most of them, but it has several bugs (like IMAP tag/untag responses), which are fixed by NZ.

SMTP proxy os nginx is not used in Zimbra so this part is not touched. Besides, some authentication methods supported by official nginx like SASL LOGIN, SALS CRAM-MD5 and APOP won't work because NLE can't support them.

Throttle Control

To reject DoS like attack, NZ will count the number of logins per IP/username in periods and deny the login if it's beyond a certain configured threshold value. This functionality is called Throttle Control. There are 2 kinds of them: IP Throttle Control and User Throttle Control. IP Throttle Control counts the login by client's IP address. But sometimes, this throttle control is not suitable for some cases (for example, many clients who locate in an internal network and thus have the same outside IP address of the gateway). Therefore, User Throttle Control is also introduced, which counts the login by client's user name. All these counters are stored in memcached so it's not persistent. And its algorithm is not quite accurate, but simple and feasible in practice. It's beneficial to implement Throttle Control in NZ because it can block the attacks before they touch real upstream mail servers.

Currently Throttle Control is only implemented for mail proxy. For web proxy, users can manually configure nginx with "deny" & "allow" directive. The following LDAP attributes have to be set to use this feature which get written using the corresponding nginx directives added for this module in /opt/zimbra/conf/nginx/templates/nginx.conf.mail.template configuration file.

zimbraReverseProxyIPLoginLimit    ->   mail_login_ip_max               ${mail.ipmax};
zimbraReverseProxyIPLoginLimitTime    ->   mail_login_ip_ttl               ${mail.ipttl};
zimbraReverseProxyIpThrottleMsg    ->   mail_login_ip_rejectmsg         "${mail.iprej}";
zimbraReverseProxyUserLoginLimit    ->   mail_login_user_max             ${mail.usermax};
zimbraReverseProxyUserLoginLimitTime    ->   mail_login_user_ttl             ${mail.userttl};
zimbraReverseProxyUserThrottleMsg    ->   mail_login_user_rejectmsg       "${mail.userrej}";

Cert Per Virtual Host Name

Many ZCS host thousands of domains, each of which has several virtual host names. Each domain may own its own SSL certificate/private key. If nginx is deployed, nginx can't proxy the SSL handshake to the upstream. So NZ has to support this "cert per domain" feature. Actually, the upstream Jetty server doesn't implement this feature. Therefore, NZ is critical in this use case. See the following for SSL Certificates Per Domain Set Up.

Jump to: navigation, search