Enabling Zimbra Proxy and memcached: Difference between revisions

No edit summary
Line 1: Line 1:
{{Article Infobox|{{admin}}||{{ZCS 8.0}}|}}
{{Article Infobox|{{admin}}||{{ZCS 8.0}}|}}


== ZCS Versions ==
== Recommended Way To Deploy Proxy In Existing Non-Proxy Environments ==
This document is applicable to ZCS 8.0+.  
=== 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.


== Multi-node ==
Proxy configuration
=== 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


==== Preparing Proxy Hosts ====
  1) Status:                                  Enabled                     
Log into each proxy server hosts and run as user ''zimbra''
  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         


* Enable (-e) IMAP/POP3 mail (-m) and HTTP (-w) in both HTTP and HTTPS (-x) mode for host (-H) returned by the zmhostname command
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.
/opt/zimbra/libexec/zmproxyconfig -m -w -e -x both -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.


or
=== 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)
Do you wish to upgrade? [Y] y
Install zimbra-memcached [N] y
Install zimbra-proxy [N] y
After install is done, enable web proxy, and set the proxy ports:


* Enable IMAP/POP3 proxy only without HTTP
./libexec/zmproxyconfig -e -w -o -a 8080:80:8443:443 -x https  -H `zmhostname`
/opt/zimbra/libexec/zmproxyconfig -m -e -H `zmhostname`


or
./libexec/zmproxyconfig -e -m -o -i 7143:143:7993:993 -p 7110:110:7995:995 -H `zmhostname`


* Enable HTTP proxy only without IMAP/POP3 in both mode
zmcontrol restart
/opt/zimbra/libexec/zmproxyconfig -w -e -x both -H `zmhostname`


Note: the zmproxyconfig command can be run more than once with the (-e) flag to enable proxy services. It is common, for example, to enable HTTP proxy after having used proxy for IMAP/POP3 services.
== Manually Modifying Proxy & related Variables via CLI ==
 
=== Simple Command With Defaults ===
==== Preparing Mailbox Server Hosts ====
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
Log into each mailbox server host and run as user ''zimbra''
/opt/zimbra/libexec/zmproxyconfig -m -w -e -H `zmhostname`
 
'''** STOP **''' here if the simple commands are used.
 
----


=== HTTP ===
=== Protocol Requirements Including HTTPS Redirect ===
When using ''zmproxyconfig'' to enable HTTP proxy, ''-w'' is used to indicate web proxy and ''-a'' is used to specify a colon separated list of web ports in format '''HTTP-STORE:HTTP-PROXY:HTTPS-STORE:HTTPS-PROXY'''. Note these port designations only specify listener ports for the server specified with ''-H'', therefore, use a value of "0" (disabled) to avoid port conflict errors.
 
==== Preparing Proxy Hosts ====
Enable the proxy host to listen on ports 80 and 443. Login to each host running zimbra-proxy and run
/opt/zimbra/libexec/zmproxyconfig -w -e -a 0:80:0:443 -x both -H `zmhostname`
 
HTTP-PROXY and HTTPS-PROXY ports are set to indicate listener ports for the HTTP proxy host. HTTP-STORE and HTTPS-STORE designations are 0 (disabled) since they apply only to mailbox server configurations and this is a proxy only host.
 
==== Preparing Mailstore Hosts ====
Login to each host running zimbra-mailbox and run
/opt/zimbra/libexec/zmproxyconfig -w -e -a 8080:0:8443:0 -H `zmhostname`
 
HTTP-STORE and HTTPS-STORE ports of 8080 and 8443 are set to indicate listener ports for the mailbox server host. HTTP-PROXY and HTTPS-PROXY designations are 0 (disabled) since they apply only to proxy server configurations and this is a mailbox only host.
 
Alternatively, mailbox servers can listen on ports 80 and 443 without conflict to the proxy or other service. Just specify the desired listener ports with zmproxyinit's -a flag
/opt/zimbra/libexec/zmproxyconfig -w -e -a 80:0:443:0 -H `zmhostname`
 
==== 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.
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.


Line 70: Line 68:
  zmprov ms proxy.server.name zimbraReverseProxyMailMode mixed
  zmprov ms proxy.server.name zimbraReverseProxyMailMode mixed


=== IMAP/POP3 ===
=== 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.
====Preparing Proxy Hosts ====
* IMAP
/opt/zimbra/libexec/zmproxyconfig -m -e -i 0:143:0:993 -H `zmhostname`
 
* POP3
/opt/zimbra/libexec/zmproxyconfig -m -e -p 0:110:0:995 -H `zmhostname`


* POP3 and IMAP in a single command
Set zimbraPublicServiceHostname to the value of the host that will be used in the URL for access to the HTTP proxy.
  /opt/zimbra/libexec/zmproxyconfig -m -e -p 110:0:995:0 -i 143:0:993:0 -H `zmhostname`
* 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


==== Preparing Mailstore Hosts ====
* This command sets ''mail.domaina.com'' as the public hostname to be used for access to ''domaina.com'' domain:
* IMAP
  zmprov md domaina.com zimbraPublicServiceHostname mail.domaina.com
  /opt/zimbra/libexec/zmproxyconfig -m -e -i 7143:143:7993:993 -H `zmhostname`


* POP3
* Set zimbraPublicServiceProtocol to ''http'' or ''https'' depending on the protocol requirements for HTTP proxy:
  /opt/zimbra/libexec/zmproxyconfig -m -e -p 7110:110:7995:995 -H `zmhostname`
  zmprov md domaina.com zimbraPublicServiceProtocol https


* POP3 and IMAP in a single command
* 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):
  /opt/zimbra/libexec/zmproxyconfig -m -e -p 110:0:995:0 -i 143:0:993:0 -H `zmhostname`
  zmprov md domaina.com zimbraPublicServicePort 443


== Troubleshooting ==
== Troubleshooting ==

Revision as of 22:05, 28 July 2014

Admin Article

Article Information

This article applies to the following ZCS versions.

ZCS 8.0 Article ZCS 8.0


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.

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

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)

Do you wish to upgrade? [Y] y

Install zimbra-memcached [N] y Install zimbra-proxy [N] y

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

./libexec/zmproxyconfig -e -w -o -a 8080:80:8443:443 -x https -H `zmhostname`

./libexec/zmproxyconfig -e -m -o -i 7143:143:7993:993 -p 7110:110:7995:995 -H `zmhostname`

zmcontrol restart

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

grep zm_lookup_handlers /opt/zimbra/conf/nginx/includes/nginx.conf.zmlookup

If a non-mailbox server is listed, set the zimbraReverseProxyLookupTarget server configuration attribute to FALSE for that server.

zmprov ms `zmhostname` zimbraReverseProxyLookupTarget FALSE

Additionally, zimbraReverseProxyLookupTarget is a server inherited attribute from the global configuration, so check if zimbraReverseProxyLookupTarget has been incorrectly designated in global config.

zmprov gcf zimbraReverseProxyLookupTarget
Verified Against: Date Created: 6/05/2014
Article ID: https://wiki.zimbra.com/index.php?title=Enabling_Zimbra_Proxy_and_memcached Date Modified: 2014-07-28



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search