- This is certified documentation and is protected for editing by Zimbra Employees & Moderators only.

- This article is a Work in Progress, and may be unfinished or missing sections.

Recommended Way To Deploy Proxy In Existing Non-Proxy Environments

Using new servers

Here you are installing the proxy on a brand new server and having all your existing mailbox servers being accessed through the proxy on this new server. Simply use the installer script (install.sh) and select the proxy and memcached packages ('Y' by default with ZCS 8.5+, just need to hit enter). This will ask you for LDAP hostname/password, Bind password for nginx ldap user which you need to provide (do 'zmlocalconfig -s ldap_nginx_password' on the host running ldap to get this) and then the Proxy configuration menu would be displayed which would look like this.

If you need to change any of these intentionally, you can do that now by selecting the corresponding config item from the menu (say for eg. to disable POP/IMAP proxy, select '2' from the above menu). Otherwise, just proceed with all the defaults and you would have the proxy+memcached installed on this new server.
Now, to have all the mailbox servers use the proxy, simply set the zimbraMailReferMode to reverse-proxied on each mailbox server and restart mailboxd to have all the traffic go through the proxy.

Using existing servers

Assuming you are running a 8.0 or earlier version ZCS with no proxy/memcached, zimbraMailMode as https and now want to upgrade to 8.5+ along with adding proxy & memcached, you need to follow the following steps

Now, to have all the mailbox servers use the proxy, simply set the zimbraMailReferMode to reverse-proxied on each mailbox server and restart mailboxd to have all the traffic go through the proxy. Do a 'zmcontrol restart' on this node and you should be up and running.

Test if Proxy is listening properly

Verify if nginx is listening on port 443, you must see something like the next:

Manually Modifying Proxy & related Variables via CLI

Simple Command With Defaults

The zmproxyconfig command can be run with limited arguments if the command defaults are acceptable. Run /opt/zimbra/libexec/zmproxyconfig to view all the argument options and the usage

Protocol Requirements Including HTTPS Redirect

HTTP proxy can support protocol modes for HTTP or HTTPS only, both HTTP and HTTPS, mixed HTTP and HTTPS or HTTPS redirect from HTTP. Redirect is a popular configuration. This configuration must be made to the proxy servers.

HTTPS redirect from HTTP

zmprov ms proxy.server.name zimbraReverseProxyMailMode redirect

HTTP and HTTPS (support both)

zmprov ms proxy.server.name zimbraReverseProxyMailMode both

HTTPS only

zmprov ms proxy.server.name zimbraReverseProxyMailMode https

HTTP only

zmprov ms proxy.server.name zimbraReverseProxyMailMode http

"mixed" will cause only authentication to be sent over HTTPS

zmprov ms proxy.server.name zimbraReverseProxyMailMode mixed

Documents & Sharing

It is important to consider access to documents (Briefcase) and shares when setting up HTTP proxy. A publicly reachable address must be configured to be used for the REST and SOAP proxy interfaces otherwise components requiring access to these interfaces will fail. Calendar sharing is an example of one component. Set zimbraPublicServiceHostname, zimbraPublicServiceProtocol, and zimbraPublicServicePort when applicable. These values are usually not required without proxy since the REST and SOAP proxy interfaces take the value of the Zimbra mailbox service hostname by default. These attributes can be set globally to be inherited by all domains or per domain.

Set zimbraPublicServiceHostname to the value of the host that will be used in the URL for access to the HTTP proxy.

This command sets mail.domain.com as the public hostname to be used for access to all domains in the Zimbra directory:

zmprov mcf zimbraPublicServiceHostname mail.domain.com

This command sets mail.domaina.com as the public hostname to be used for access to domaina.com domain:

zmprov md domaina.com zimbraPublicServiceHostname mail.domaina.com

Set zimbraPublicServiceProtocol to http or https depending on the protocol requirements for HTTP proxy:

zmprov md domaina.com zimbraPublicServiceProtocol https

Set zimbraPublicServicePort to the value that corresponds to the HTTP proxy port used in the URL (optional if standard ports 80 or 443 are used for proxy listeners):

zmprov md domaina.com zimbraPublicServicePort 443

Troubleshooting

Proxy Login Slow

A common nginx misconfiguration is to have incorrectly designated non-mailbox servers as routing/zmlookup handlers. Only mailbox servers can perform route handler functions. To view the zmlookup lookup handlers, review the zm_lookup_handlers parameter in /opt/zimbra/conf/nginx/includes/nginx.conf.zmlookup