Zimbra Proxy Manual:Advanced Proxy Configuration Examples via CLI

Zimbra Proxy Manual: Advanced Proxy Configuration Examples via CLI

   KB 21168        Last updated on 06/7/2016  




0.00
(0 votes)
Article-check.png  - 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.

Advanced Proxy Configuration Examples via CLI

Configure Zimbra Proxy For POP[S] And IMAP[S] Only


Disabling Zimbra Proxy For POP[S] And IMAP[S] Only

Configure Zimbra Proxy For POP[S] And IMAP[S] After A HTTP[S] Configuration


Source: Admin Guide

If you need to set up IMAP/POP proxy after you have already installed Zimbra HTTP proxy, do the following below. Assumption is a Zimbra mailbox server/s and the proxy node/s are already setup and running.

Note - This section doesn't make sense - this needs to be technically proofed.

* The first to setup headers don't make sense. Is the first one when your setting up a NEW proxy host but have other ones already deployed that will continue to do just HTTP ? The second header, is this reconfiguring a proxy host? The assumptions to this exercise is that HTTP proxy is already deployed some where in the environment.

* In the first section, why is it - "On each Zimbra mailbox server" ? There's no configuration being ran on the proxy nodes at all in this example.

Set Up IMAP/POP Proxy with Separate Proxy Node

If your configuration includes a separate proxy server, you must do the following.

1. 	On each Zimbra mailbox server that you want to proxy with, enable the proxy for IMAP/POP proxy. 
/opt/zimbra/libexec/zmproxyconfig -e -m -H mailbox.node.service.hostname
This configures the following:
• 	zimbraImapBindPort to 7143
• 	zimbraImapProxyBindPort to 143
• 	zimbraImapSSLBindPort to 7993
• 	zimbraImapSSLProxyBindPort to 993
• 	zimbraPop3BindPort to 7110
• 	zimbraPop3ProxyBindPort to110
• 	zimbraPop3SSLBindPort to 7995
• 	zimbraPop3SSLProxyBindPort to 995
• 	zimbralmapCleartextLoginEnabled to TRUE
• 	zimbraReverseProxyLookupTarget to TRUE
• 	zimbraPop3CleartextLoginEnabled to TRUE
2.   	Restart services on the proxy and mailbox servers.
zmcontrol restart


Set Up Proxy Node

1. 	On each proxy node that has the proxy service installed, enable the proxy for the web. 
/opt/zimbra/libexec/zmproxyconfig -e -m -H proxy.node.service.hostname
This configures the following:
• 	zimbraImapBindPort to 7143
• 	zimbraImapProxyBindPort to 143
• 	zimbraImapSSLBindPort to 7993
• 	zimbraImapSSLProxyBindPort to 993
• 	zimbraPop3BindPort to 7110
• 	zimbraPop3ProxyBindPort to110
• 	zimbraPop3SSLBindPort to 7995
• 	zimbraPop3SSLProxyBindPort to 995
• 	zimbraReverseProxyMailEnabled to TRUE


Set Up a Single Node
If Zimbra proxy is installed with Zimbra Collaboration on the same server, do the following. 

1. 	Enable the proxy for the web. 
/opt/zimbra/libexec/zmproxyconfig -e -m -H mailbox.node.service.hostname
This configures the following:
• 	zimbraImapBindPort to 7143
• 	zimbraImapProxyBindPort to 143
• 	zimbraImapSSLBindPort to 7993
• 	zimbraImapSSLProxyBindPort to 993
• 	zimbraPop3BindPort to 7110
• 	zimbraPop3ProxyBindPort to110
• 	zimbraPop3SSLBindPort to 7995
• 	zimbraPop3SSLProxyBindPort to 995
• 	zimbraImapCleartextLoginEnabled to TRUE
• 	zimbraReverseProxyLookupTarget to TRUE
• 	zimbraPop3CleartextLoginEnabled to TRUE
• 	zimbraReverseProxyMailEnabled to TRUE
2.   	Restart services on the proxy and mailbox servers.
zmcontrol restart

Disabling Zimbra Proxy For POP[S] And IMAP[S] Only

Configure Zimbra Proxy For POP[S] Only


Disabling Zimbra Proxy For POP[S] Only

Configure Zimbra Proxy For POP[S] And HTTP[S] Only



Disabling Zimbra Proxy For POP[S] And HTTP[S] Only

Configure Zimbra Proxy For IMAP[S] Only



Disabling Zimbra Proxy For IMAP[S] Only

Configure Zimbra Proxy For IMAP[S] And HTTP[S] Only



Disabling Zimbra Proxy For IMAP[S] And HTTP[S] Only

Configure Zimbra Proxy For HTTP[S] Only


Source: Admin Guide Draft 'Setting Up HTTP Proxy'

To set up HTTP proxy, Zimbra Proxy must be installed on the identified nodes.
Note: You can run the command as /opt/zimbra/libexec/zmproxyconfig -r, to run against a 
remote host. Note that this requires the server to be properly configured in the LDAP master.

Set Up HTTP Proxy as a Separate Proxy Node

When your configuration includes a separate proxy server follow these steps.

1. 	On each Zimbra mailbox server that you want to proxy with, enable the proxy for the web. 
/opt/zimbra/libexec/zmproxyconfig -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.
• 	zimbraReverseProxyLookupTarget to TRUE
• 	zimbraMailMode to http. This is the only supported mode. 

2.   	Restart services on the proxy and mailbox servers.
zmcontrol restart

3.   	Configure each domain with the public service host name to be used for REST URLs, email, 
and Briefcase folders. 
zmprov modifyDomain <domain.com> zimbraPublicServiceHostname <hostname.domain.com>

Set Up Proxy Node

1. 	On each proxy node that has the proxy service installed, enable the proxy for the web. 
/opt/zimbra/libexec/zmproxyconfig -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 HTTP.
To set the proxy server mail mode, add the -x option to the command with the specific mode: http, https, 
both, redirect, mixed.

Set Up a Single Node for HTTP Proxy

If Zimbra proxy is installed along with ZCS on the same server, follow this step.

1. 	On each zimbra mailbox server that you want to proxy with, enable the proxy for the web. 
/opt/zimbra/libexec/zmproxyconfig -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.
• 	zimbraReverseProxyLookupTarget to TRUE
• 	zimbraMailMode to http. This is the only supported mode. 
• 	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 HTTP.
To set the proxy server mail mode, add the -x option to the command with the specific mode: http, https, 
both, redirect, mixed.

2.   	Restart services on the proxy and mailbox servers.
zmcontrol restart

Configure each domain with the public service host name to be used for REST URLs, email and Briefcase 
folders. 
zmprov modifyDomain <domain.com> zimbraPublicServiceHostname <hostname.domain.com>

Disabling Zimbra Proxy For HTTP[S] Only

Configure Or Customize The Zimbra Proxy For The Admin Console


Please be aware of the following variable, zimbraWebClientAdminReference, if changing the default admin port of 7071.

Disabling Or Customize The Zimbra Proxy For The Admin Console

Configure Zimbra Proxy For Kerberos Authentication


Source: Admin Guide Draft, 'Configure Zimbra Proxy for Kerbose Authentication'

If you use the Kerberos5 authenticating mechanism, you can configure it for the IMAP and POP proxy.

Note: Make sure that your Kerberos5 authentication mechanism is correctly configured. See Chapter 5, Zimbra LDAP Service.

  • On each proxy node, set the zimbraReverseProxyDefaultRealm server attribute to the realm name corresponding to the proxy server. For example:
zmprov ms [DNS name.isp.net] zimbraReverseProxyDefaultRealm [ISP.NET]
  • 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:
zmprov mcf +zimbraReverseProxyAdminIPAddress [IP address]
  • On each proxy server:
zmprov ms [proxyexample.net] zimbraReverseProxyImapSaslGssapiEnabled TRUE
zmprov ms proxyl.isp.net zimbraReverseProxyPop3SaslGssapiEnabled TRUE
  • Restart the proxy server
zmproxyctl restart


Disabling Zimbra Proxy For Kerberos Authentication

Configure Zimbra Proxy For AUTH GSSAPI


Source: http://wiki.zimbra.com/index.php?title=NGINX_Configuration_Tips#AUTH_GSSAPI

Nginx supports the SASL GSSAPI Authentication Mechanism for POP and IMAP through the zimbraReverseProxyPop3SaslGssapiEnabled and zimbraReverseProxyImapSaslGssapiEnabled attributes respectively.

Set them to true to enable GSSAPI Authentication for Nginx

zmprov ms <server> zimbraReverseProxyPop3SaslGssapiEnabled TRUE
zmprov ms <server> zimbraReverseProxyImapSaslGssapiEnabled TRUE

Set these attributes to FALSE to disable GSSAPI Authentication.

Disabling Zimbra Proxy For AUTH GSSAPI

Configure Zimbra Proxy For AUTH PLAIN


Source: http://wiki.zimbra.com/index.php?title=NGINX_Configuration_Tips#AUTH_PLAIN

Nginx supports enablement of the SASL PLAIN Authentication Mechanism (RFC 4616) for POP and IMAP through the zimbraReverseProxyPop3SaslPlainEnabled and zimbraReverseProxyImapSaslPlainEnabled attributes respectively.

Set them to true to enable PLAIN Authentication for Nginx

zmprov ms <server> zimbraReverseProxyPop3SaslPlainEnabled TRUE
zmprov ms <server> zimbraReverseProxyImapSaslPlainEnabled TRUE

Set them to false to disable PLAIN Authentication for Nginx

zmprov ms <server> zimbraReverseProxyPop3SaslPlainEnabled FALSE
zmprov ms <server> zimbraReverseProxyImapSaslPlainEnabled FALSE


Disabling Zimbra Proxy For AUTH PLAIN

Configure Zimbra Proxy For Clear-Text Logins


Source: http://wiki.zimbra.com/index.php?title=NGINX_Configuration_Tips#Allow.2FDisallow_Clear-Text_Logins

To configure Nginx to allow/disallow cleartext logins on non SSL/TLS connections, use the zimbraReverseProxyPop3StartTlsMode and zimbraReverseProxyImapStartTlsMode attributes.

To allow clear-text logins for POP and IMAP (respectively) over non-SSL/TLS connections, run these commands

zmprov ms <server> zimbraReverseProxyPop3StartTlsMode on
zmprov ms <server> zimbraReverseProxyImapStartTlsMode on

To disallow clear-text logins for POP and IMAP (respectively) over non-SSL/TLS connections, run these commands

zmprov ms <server> zimbraReverseProxyPop3StartTlsMode only
zmprov ms <server> zimbraReverseProxyImapStartTlsMode only

Disabling Zimbra Proxy For Clear-Text Logins

To disallow clear-text logins for POP and IMAP (respectively) over non-SSL/TLS connections, run these commands

zmprov ms <server> zimbraReverseProxyPop3StartTlsMode only
zmprov ms <server> zimbraReverseProxyImapStartTlsMode only

SSL Certificates Per Domain Set Up


Source:

This document explains how to add per domain cert on a ZCS running 7.x version.

Until ZCS 6.x, per domain ssl certificate or multiple ssl certificates on a single ZCS was not supported. RFE #8128. From ZCS 7.x, the feature is been added.

In this example, I am adding a new domain called example.com and deploying a new certificate for example.com.

Prerequisites

  • Zimbra proxy service must be installed and enabled on the server. In multi server environment, do these steps on the proxy node.
  • You should have a signed certificate + matching key pair and the trusted chain certs from your CA (Certificate Authority) .
  • You will need to add ipv4 addresses per domain which will pair to the respective domain name. For example:
 1.1.1.1 => example.com
 2.2.2.2 => otherdomain.com
 3.3.3.3 => yetanotherdomain.com

Configure Zimbra Proxy Server

1. Make sure Zimbra proxy service is configured correctly and serving https. If not, configure proxy now, run following as zimbra. It will set "zimbraReverseProxyMailMode" to both.

 su - zimbra
 /opt/zimbra/libexec/zmproxyconfig -m -w -e -x both -H `zmhostname`

2. Restart proxy service

 zmproxyctl restart
  • If its already configured - skip to next section.

Configuring IP address and domain

1. Add a new ipv4 address to the server which will pair to name example.com (via the example virtual hostname mail.example.com). You can do it using IP address aliasing. For example, the new address can be assigned to eth0:1 device. Lets consider the new ipv4 address is 1.2.3.4 which should be an A record for mail.example.com. The IP address could be public (if server is on Internet) or internal (if the server is behind firewall/NAT'ed).

2. Add the new domain example.com. Set zimbraVirtualHostName to mail.example.com and zimbraVirtualIPAddress to 1.2.3.4. Make sure the zimbraVirtualHostName is set to the name which will be used to access the domain (URL) and the SSL certificate is signed for same name.

 zmprov cd example.com zimbraVirtualHostName "mail.example.com" zimbraVirtualIPAddress "1.2.3.4"

NOTE: If the server is behind firewall and NAT'ed with external address, make sure the external requests for "mail.example.com" hits the aliased IP address and not the actual local IP of server.

Verifying and Preparing the Certificates

We have three files received from the CA. The server (domain) certificate, two chain certs. And we have existing key file (which was used to generate the csr)

1. Save the example.com certificate, key and chain files to a directory /tmp/example.com. You can receive single or multiple chain certs from your CA. Here we have two chain certs from the CA. i.e. example.com.root.crt and example.com.intermediate.crt.

 ls /tmp/example.com
 example.com.key
 example.com.crt
 example.com.root.crt
 example.com.intermediate.crt

2. Add the chain certs to a single file called example.com_ca.crt

 cat example.com.root.crt example.com.intermediate.crt >> example.com_ca.crt

3. Confirm if the key and certificate matches and chain certs completes the trust.

 /opt/zimbra/bin/zmcertmgr verifycrt comm /tmp/example.com/example.com.key /tmp/example.com/example.com.crt /tmp/example.com/example.com_ca.crt
  • Check the output, it should say something like this. If not, make sure you have correct key and chain cert files.
 ** Verifying example.com.crt against example.com.key
 Certificate (example.com.crt) and private key (example.com.key) match.
 Valid Certificate: example.com.crt: OK

Deploying the Certificate on domain

1. Add the domain certificate and chain files to a single file called example.com.bundle

 cat example.com.crt example.com_ca.crt >> example.com.bundle

2. Run following to save the certificates and key in ldap database.

 /opt/zimbra/libexec/zmdomaincertmgr savecrt example.com example.com.bundle example.com.key
  • The syntax is:
 /opt/zimbra/libexec/zmdomaincertmgr savecrt <domainname> <certificate with chain certs> <keyfile>

3. Run following to deploy the domain certificate. This will save the certificate and key as /opt/zimbra/conf/domaincerts/example.com

 /opt/zimbra/libexec/zmdomaincertmgr deploycrts

4. Make sure the example.com is resolving to its local IP address from Zimbra host. Or make an similar entry in /etc/hosts file.

 1.2.3.4      example.com

5. Restart proxy service to take the changes in effect.

 zmproxyctl restart

6. Once the restart is successfull, try to access the domain using the URL which is set in "zimbraVirtualHostName" over https. And check the certificate loaded in the browser. In this case the URL will be https://example.com

Testing

Run this command locally on zimbra server to check if the correct domain cert is offered while accessing the domain with "zimbraVirtualHostName" or "zimbraVirtualIPAddress"

 openssl s_client -connect example.com:443
 openssl s_client -connect 1.2.3.4:443

Troubleshooting

  • If you do not see domain cert by accessing the domain with its zimbraVirtualHostName (example.com). Make sure the https connection from Internet/intranet is going to server's local IP address which is defined in zimbraVirtualIPAddress.
  • If the proxy startup gives following error, try to change the order of certificates in /opt/zimbra/conf/domaincerts/example.com.crt file and restart proxy.
 Starting nginx...nginx: [emerg] SSL_CTX_use_PrivateKey_file("/opt/zimbra/conf/domaincerts/example.com.key") failed 
   (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)
  • If you are using multiple proxy servers or adding new proxy servers, make sure you copy all the contents of /opt/zimbra/conf/domaincerts/ among all proxy servers. Otherwise proxy service will fail to start.
Jump to: navigation, search