Zimbra Proxy Manual:Installing , Configuring, Disabling the Zimbra Proxy

Revision as of 21:14, 10 September 2014 by Ajcody (talk | contribs)
General Proxy Overview
Overview And Planning For Zimbra Proxy Installing , Configuring, Disabling the Zimbra Proxy Zimbra Proxy Related CLI Commands Troubleshooting Zimbra Proxy

Advanced Topics
Configuration And Template Files And Proxy Related Variables Advanced Proxy Configuration Examples via CLI Miscellaneous Topics Zimbra Proxy Manual:Adding Additional Reverse Proxy To Zimbra Proxy


Admin Article

Article Information

This article applies to the following ZCS versions.

ZCS 8.5 Article ZCS 8.5 ZCS 8.0 Article ZCS 8.0


Installing , Configuring, Disabling the Zimbra Proxy

Things To Review First

Prerequisite Variables To Check First

zimbraPublicServiceHostname zimbraPublicServiceProtocol and zimbraPublicServicePort

* Needs more details, incomplete right now.

In order for the change password link, calendar launching in separate window, and other various functionality to work correctly - meaning, to use the proxy instead of mailbox server, the following LDAP attributes have to be set to the proxy values:

  • zimbraPublicServiceHostname(Name to be used in public API such as REST or SOAP proxy) - proxy hostname
  • zimbraPublicServiceProtocol(Protocol to be used in public API such as REST or SOAP proxy) - proxy protocol (http or https)
  • zimbraPublicServicePort(Port to be used in public API such as REST or SOAP proxy) - proxy port

zimbraVirtualHostname

* Needs more details, incomplete right now.

zimbra_auth_always_send_refer

The zmlocalconfig key zimbra_auth_always_send_refer is now obsolete. Its been replaced by LDAP attribute zimbraMailReferMode. Now with a full-fledged reverse proxy, users do not need to be redirected. The LDAP attribute zimbraMailReferMode is used directly by the Nginx reverse proxy.

zmtlsctl

* Needs more details, incomplete right now.

zmtlsctl sets the zimbraMailMode , this is different than the zimbraReverseProxyMailMode .

zmtlsctl help
Usage: /opt/zimbra/bin/zmtlsctl [mixed|both|http|https|redirect]
$ zmprov desc -a zimbraMailMode                
zimbraMailMode
    whether to run HTTP or HTTPS or both/mixed mode or redirect mode. See
    also related attributes zimbraMailPort and zimbraMailSSLPort

               type : enum
              value : http,https,both,mixed,redirect
           callback : LocalBind
          immutable : false
        cardinality : single
         requiredIn : 
         optionalIn : globalConfig,server
              flags : serverInherited
           defaults : 
                min : 
                max : 
                 id : 308
    requiresRestart : 
              since : 
    deprecatedSince : 
$ zmprov desc -a zimbraReverseProxyMailMode
zimbraReverseProxyMailMode
    whether to run proxy in HTTP, HTTPS, both, mixed, or redirect mode.
    See also related attributes zimbraMailProxyPort and
    zimbraMailSSLProxyPort

               type : enum
              value : http,https,both,mixed,redirect
           callback : 
          immutable : false
        cardinality : single
         requiredIn : 
         optionalIn : globalConfig,server
              flags : serverInherited
           defaults : 
                min : 
                max : 
                 id : 685
    requiresRestart : nginxproxy
              since : 5.0.7
    deprecatedSince : 

From a single ZCS 8.5 server install:

$ zmprov gs `zmhostname` | grep MailMode
zimbraMailMode: https
zimbraReverseProxyMailMode: https

The New WebApp Services In ZCS 8.5 and zm_auth_token

Source: From admin guide draft under 'Configur Zimbra HTTP Proxy'

* Needs more details, incomplete right now.

Note - <<need to add split node feature info in this section. Affects zm_auth_token>> [From Admin Guide Draft]

New ZCS Deployment

Single ZCS Server Environment

* Needs more details, incomplete right now.


Multi-Server ZCS Environment

* Needs more details, incomplete right now.

Adding Zimbra Proxy Services To Existing Non-Proxy Environments via ZCS Installer [Recommended Method]

Using New Servers

Source: http://wiki.zimbra.com/wiki/Enabling_Zimbra_Proxy#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 Zimbra Proxy configuration menu would be displayed which would look like this.

Proxy configuration

  1) Status:                                  Enabled                       
  2) Enable POP/IMAP Proxy:                   TRUE                          
  3) IMAP server port:                        7143                          
  4) IMAP server SSL port:                    7993                          
  5) IMAP proxy port:                         143                           
  6) IMAP SSL proxy port:                     993                           
  7) POP server port:                         7110                          
  8) POP server SSL port:                     7995                          
  9) POP proxy port:                          110                           
 10) POP SSL proxy port:                      995                           
 11) Bind password for nginx ldap user:       set                           
 12) Enable HTTP[S] Proxy:                    TRUE                          
 13) Web server HTTP port:                    8080                          
 14) Web server HTTPS port:                   8443                          
 15) HTTP proxy port:                         80                            
 16) HTTPS proxy port:                        443                           
 17) Proxy server mode:                       https          

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

* Needs more details, incomplete right now.

* /opt/zimbra/libexec/zmsetup.pl vs ./install.sh ? --Adam

Adding Zimbra Proxy Services To Existing Non-Proxy Environments via CLI [Advanced Method]

Using New Servers

Using Existing Servers

Source: http://wiki.zimbra.com/wiki/Enabling_Zimbra_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

Start 8.5+ installer (install.sh script)

* /opt/zimbra/libexec/zmsetup.pl vs ./install.sh ? --Adam

Do you wish to upgrade? [Y] y

Install zimbra-memcached [N] y

Install zimbra-proxy [N] y

After install is done, enable web/mail proxy, and set the proxy mode and ports:

  • If localconfig key 'zimbra_require_interprocess_security' is set, Only "https" and "both" are valid modes
/opt/zimbra/libexec/zmproxyconfig -e -w -o -a 8080:80:8443:443 -x <https/both>  -H `zmhostname`
  • Else if 'zimbra_require_interprocess_security' is unset, Only "http" and "both" are valid modes
/opt/zimbra/libexec/zmproxyconfig -e -w -o -a 8080:80:8443:443 -x <http/both>  -H `zmhostname`
  • Set the mail proxy ports
/opt/zimbra/libexec/zmproxyconfig -e -m -o -i 7143:143:7993:993 -p 7110:110:7995:995 -H `zmhostname`

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.

Manually Modifying Zimbra Proxy Services And Related Variables via CLI

Source: http://wiki.zimbra.com/wiki/Enabling_Zimbra_Proxy#Manually_Modifying_Proxy_.26_related_Variables_via_CLI

Simple Command With Defaults

Source: http://wiki.zimbra.com/wiki/Enabling_Zimbra_Proxy#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

Source: http://wiki.zimbra.com/wiki/Enabling_Zimbra_Proxy#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 - The zimbraPublicService variables

Source: http://wiki.zimbra.com/wiki/Enabling_Zimbra_Proxy#Documents_.26_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

Disabling Zimbra Proxy

Completely Disable Proxy In Single ZCS Server Environment

* Note - Recommend /opt/zimbra/libexec/zmsetup.pl as default method to do this? --Adam

Completely Disable Proxy In Multi-Server ZCS Environment

* Note - Recommend /opt/zimbra/libexec/zmsetup.pl as default method to do this? --Adam

Disable POP/IMAP Proxy In Single ZCS Server Environment

Source: http://wiki.zimbra.com/wiki/Ajcody-Proxy-Notes#Need_To_Disable_Pop.2FImap_Proxy_And_Use_POP.2FIMAP_Normally


* Note - Recommend /opt/zimbra/libexec/zmsetup.pl as default method to do this? --Adam


Sometimes, people install/setup proxy services on their single ZCS server and they don't need them. Here's how you would disable the proxy stuff and get imap/pop working over the default ports.

do a zmprov -l gs `zmhostname` | grep -i port

get the ports, then set variables to port 0:

zmprov ms `zmhostname` zimbraImapProxyBindPort 0
zmprov ms `zmhostname` zimbraImapSSLProxyBindPort 0
zmprov ms `zmhostname` zimbraPop3ProxyBindPort 0
zmprov ms `zmhostname` zimbraPop3SSLProxyBindPort 0

then, set the non "Proxy" ports to the desired standard ports

zmprov ms `zmhostname` zimbraImapBindPort 143
zmprov ms `zmhostname` zimbraImapSSLBindPort 993
zmprov ms `zmhostname` zimbraPop3BindPort 110
zmprov ms `zmhostname` zimbraPop3SSLBindPort 995

once complete:

zmprov ms `zmhostname` -zimbraServiceEnabled memcached
zmprov ms `zmhostname` -zimbraServiceEnabled imapproxy

zmproxyctl stop
zmmemcachedctl stop
zmmailboxdctl stop
zmmailboxdctl start 
Jump to: navigation, search