Ajcody-Proxy-Notes: Difference between revisions

Line 8: Line 8:


Please see [[Ajcody-Proxy-Notes]]
Please see [[Ajcody-Proxy-Notes]]
===UPDATE PLEASE SEE THIS FIRST===
Our Administration Guide now has everything you should need to setup your proxy server.
Please see:
* http://www.zimbra.com/docs/ne/latest/administration_guide/ZimbraProxy.7.1.html


===My Own Proxy How-To For Setup===
===My Own Proxy How-To For Setup===

Revision as of 15:06, 5 December 2008

Attention.png - This article is NOT official Zimbra documentation. It is a user contribution and may include unsupported customizations, references, suggestions, or information.

A Proxy On You!

Actual Proxy Notes Homepage

Please see Ajcody-Proxy-Notes

UPDATE PLEASE SEE THIS FIRST

Our Administration Guide now has everything you should need to setup your proxy server.

Please see:

My Own Proxy How-To For Setup

The official documents, in my opinion, don't make any sense or give enough guidance on how to setup proxy.

Note: We are working on improving the official documentation. I haven't seen the document yet for the 5.0.11 release, but I've been told it will have many improvements. See - http://bugzilla.zimbra.com/show_bug.cgi?id=32551

Here's my attempt at writing something better in the meantime.

High Level Overview

One Package

First, there's only ONE package or rpm in the installer for "proxy".

Where Does It Get Installed?

It can be installed with any of your Zimbra servers (a complete ZCS install, ZCS MTA, ZCS LDAP, ZCS Mailstore) or on its own server. ( Reference )

Other proxy documentation might give the impression it needs to go onto a zimbra server that is running some other function - mta, ldap, or mailstore.

Three Components To The Package

This package, can be broken down into THREE components.

Ngnix

Ngnix is a high performance IMAP/POP3 proxy server which handles all incoming POP/IMAP requests. In addition to this, it is also able to reverse proxy HTTP requests to the right backend (mailstore) server. This helps to hide the hostnames of the backend mailbox servers from end users. The steps involved in this lookup are described in more detail under the Flow_Process_For_Proxy_Target_Lookups below.

Memcached

Memcached is a high performance, distributed memory object caching system (an open source distributed in-memory hashtable). Route information is cached for further use in order to increase performance.

Memcache does not have authentication and security features so the servers should have a firewall set up appropriately. The default port is 11211 and is controlled by zimbraMemcacheBindPort conf setting in zimbraserver.

Note: Memcached will be split into its own service in the future. Meaning, for example, that you'll be able to configure a server to solely perform this function of providing the cache results. This will give more flexibility in managing performance issues, as related to the proxy environment. Rather than the same server having to share cpu/memory resources with nginx. It will also allow you to configure your different servers running nginx to quiry against a "shared" cached table of memcached. Currently, each nginx will have unique results in their memcached tables.

What is being cached, are the prior results of pop and imap lookups of users and their corresponding mailbox server they should be routed to. The process is described below in Flow_Process_For_Proxy_Target_Lookups.

Zimbra Proxy Route Lookup Handler

Zimbra Proxy Route Lookup Handler is a servlet located on the ZCS mailbox servers. This servlet handles queries for the user account route information (the server and port number where the user account resides). This is more about a difference in functionality when the proxy package is being used rather than a "new" software package being installed. The functionality difference is coming from the "software" related to nginx and memcached. The process is described in more detail in Flow_Process_For_Proxy_Target_Lookups.

NOTE - Again, don't let the reference to "mailbox server" confuse you. The mailbox servers don't need the proxy package installed on them directly to see this effect. The proxy server (whatever one you install it on, will make configuration changes global to handle this function. The referenced servlet is already on a base mailbox server install. This is referring to how the proxy package components will or can interact with that pre-existing servlet on the mailbox server.
Flow Process For Proxy Target Lookups

Here's the flow of the process for pop and imap lookups:

  1. Nginx will query the LOCAL memcached service first to see if the lookup result has a cached result. [FYI - Memcache runs over port 11211]
    • Note: when memcached is allowed to run on another server besides the one where nginx is at, you'll need to account for this port 11211 access between the servers. For now, it's all occurring locally to the server. If you can't access this memcache process, confirm you don't have any firewall/port level blocking occur for the local machine communicating over port 11211.
  2. If the initial lookups by nginx against the LOCAL memcached service have no results, nginx will then proceed to query against the "Zimbra Proxy Route Lookup Handler" services.
    • By default, all mailbox servers participate in this lookup process via the "Zimbra Proxy Route Lookup Handler".
      • This "where" to lookup is determined by the zimbraReverseProxyLookupTarget server attribute on servers running the mailbox service.
    • The lookups are performed in a round-robin fashion across configured mailbox servers.
    • Now that there is a successful lookup, the results are then cached in LOCAL memcached service and future lookups will bypass the "Zimbra Proxy Route Lookup Handler" steps for that specific lookup.
      • Meaning, the lookups will solely operate between nginx and LOCAL memcached service and no longer involve the "Zimbra Proxy Route Lookup Handler"/mailbox stores.

Here's the flow of the process for reverse proxy http lookups:

  1. Nginx will query against the "Zimbra Proxy Route Lookup Handler" services.
    • By default, all mailbox servers participate in this lookup process via the "Zimbra Proxy Route Lookup Handler".
      • This "where" to lookup is determined by the zimbraReverseProxyLookupTarget server attribute on servers running the mailbox service.
    • The lookups are performed in a round-robin fashion across configured mailbox servers.
    • Ngninx will perform this lookup for every http request, it does not involve the memcached server for cache results.
Three Functions That Can Be Done With Proxy Package

There are THREE functions or options within Zimbra that relate to "proxy".

IMAP - POP Proxy

IMAP/POP Proxy is about the use of an IMAP/POP proxy server routes users of these services to the Zimbra mailbox server on which their mailbox resides.

For example, proxying allows users to enter imap.example.com as their IMAP server. The proxy running on imap.example.com inspects their IMAP traffic, does a lookup to determine which backend mailbox server a user’s mailbox lives on (mbs1.example.com, for example), and transparently proxies the connection from user’s IMAP client to the correct mailbox server.

Flow Of The Login Process: When an IMAP or POP3 client logs in through the proxy, the following takes place:

  1. The proxy analyzes the login sequence
  2. Extracts the user name of the user trying to login
  3. Does a HTTP lookup on a mailbox server to find out which server the mailbox of the user attempting to login lives on
    • This lookup service runs on mailbox servers on port 7072, and this port on mailbox servers should be available from all proxy servers.
      • Which mailbox servers participate in this lookup is determined by the zimbraReverseProxyLookupTarget server attribute on servers running the mailbox service.
        • By default all mailbox servers participate in this lookup.
      • Lookup is performed round-robin across configured mailbox servers.
      • The result of the login name to mailbox server lookup are cached in memcached (an open source distributed in-memory hashtable).
        • The memcached process is run alongside all IMAP/POP proxy services (nginx). Meaning wherever the proxy package was install and is configured to run.
  4. Also see Flow_Process_For_Proxy_Target_Lookups, if you have not.

Port Changes For IMAP/POP Proxying: When the proxy server is configured, the service ports on backend Zimbra mailbox server are changed to alternate ports. The proxy now services the standard ports for these protocols. This change is applied even if the proxy services are run on their own independent hosts, in order to distinguish and avoid confusion between the services.

  1. Here's the changes that will be made on the mailbox servers and what ports will now be handled by the proxy server(s).
    • Note: If you have any other services running on these ports, turn them off.
      • Standard Ports now server or handled by Proxy server(s)
        • IMAP proxy port 143
        • IMAP SSL proxy port 993
        • POP proxy port 110
        • POP proxy port 995
      • Mailbox Servers will now work on these alternate ports
        • IMAP port 7072
        • IMAP SSL port 7143
        • POP port 7110
        • POP SSL port 7995
        • Route Lookup Handler (new port) 7072
        • This was described above in regards to the "Flow Of The Login Process".
Reverse HTTP Proxy
  1. Reverse HTTP Proxy
    • Using an nginx-based reverse proxy for HTTP helps to hide names of backend mailbox servers from end users. For example, users can always use their web browser to visit the proxy server at http://mail.example.com. The connection from users whose mailbox lives on mbs1. example.com will be proxied to mbs1.example.com by the proxy running on the mail.example.com server. In addition to the ZCS web interface, clients such as REST and CalDAV clients, Zimbra Connector for Outlook and Zimbra Mobile Sync devices are also supported by the proxy.
      • HTTP reverse proxy routes requests as follows:
        1. If the request has an auth token cookie (ZM_AUTH_TOKEN), the request is routed to the backend mailbox server of the authenticated user.
        2. If the requesting URL can be examined to determine the user name, then the request is routed to the backend mailbox server of the user in the URL. REST, Ca lDAV, and Zimbra Mobile Sync are supported through this mechanism.
        3. If the above methods do not work, the IP hash method is used to load balance the requests across the backend mailbox servers which are able to handle the request or do any necessary internal proxying.
Virtual Hosting
  1. Virtual Hosting
    • You can configure multiple virtual hostnames to host more than one domain name on a server. When you create a virtual host, users can log in without have to specify the domain name as part of their user name. Virtual hosts are configured from the administration console Domains>Virtual Hosts tab. The virtual host requires a valid DNS configuration with an A record. When users log in, they enter the virtual host name in the browser. For example, https://mail.example.com. When the Zimbra logon screen displays, users enter only their user name and password. The authentication request searches for a domain with that virtual host name. When the virtual host is found, the authentication is completed against that domain.
    • Exception. It would be possible to do the functions of Virtual Hosting without installing the zimbra proxy package. Using jetty directly for example. Our recommendation is to use the zimbra proxy package to achieve this though.
      • Example, you have a single ZCS setup and your going to host multiple domains. [This is only true with a single ZCS mailbox setup. ] You want your users of those domains to use the "domainname" throughout all client configurations and interactions with the mailserver. So the pop/imap/http url's use the mail domain they are in, rather than the physical hostname+domainname of the ZCS server.
        • You would configure in the /etc/hosts and/or DNS to resolve the domainname targets that the user will be using to point to the physical ip address of the ZCS server.
        • You would then in the admin web console of ZCS, setup the domains under the "Domain Virtual Hosts" section. And confirm the "default domain login" is properly setup for the users/domain users.
        • NOTE - Before Proceeding With Proxy Package Install If this is all your needing, you can avoid doing all the other "stuff" in regards to zimbra proxy. You don't need to install the zimbra proxy package and can avoid this layer of complexity.

Proxy References

NGINX Open-Source Project Homepage

Proxy documentation BUG/RFE's:

From Install Guide':

From Wiki:

zmproxyinit Help Output [Oct 16, 2008 - From 5.0.9 I believe]:

[zimbra@mail2 libexec]$ ./zmproxyinit 
Usage: ./zmproxyinit [-h] [-o] [-m] [-w] [-d [-r] [-s] [-a w1:w2:w3:w4] [-i p1:p2:p3:p4] [-p p1:p2:p3:p4] [-x mailmode]] 
[-e [-a w1:w2:w3:w4] [-i p1:p2:p3:p4] [-p p1:p2:p3:p4] [-x mailmode]] [-f] -H hostname
        -h: display this help message
        -H: Hostname of server on which enable/disable proxy functionality.
        -a: Colon separated list of Web ports to use. Format: HTTP-STORE:HTTP-PROXY:HTTPS-STORE:HTTPS-PROXY (Ex: 8080:80:
8443:443)
        -d: disable proxy
        -e: enable proxy
        -f: Full reset on memcached port and search queries and POP/IMAP throttling.
        -i: Colon separated list of IMAP ports to use. Format: IMAP-STORE:IMAP-PROXY:IMAPS-STORE:IMAPS-PROXY (Ex: 7143:14
3:7993:993)
        -m: Toggle mail proxy portions
        -o: Override enabled checks
        -p: Colon separated list of POP ports to use. Format: POP-STORE:POP-PROXY:POPS-STORE:POPS-PROXY (Ex: 7110:110:799
5:995)
        -r: Disable reverse proxy lookup target for store server.  Only valid with -d.  Be sure that you intend for all p
roxy function for the server to be disabled
        -s: Set cleartext to FALSE (secure mode) on disable
        -w: Toggle Web proxy portions
        -x: zimbraMailMode to use on disable (Default: http)
hostname is the value of the zimbra_server_hostname LC key for the server being modified.
Required options are -f by itself, or -f with -d or -e.
Note that -d or -e require one or both of -m and -w.
Note that -i or -p require -m.
Note that -a requires -w.
Note that -x requires -w and -d for store.
Note that -x requires -w for proxy.
The following are the defaults for -a, -i, -p, and -x if they are not supplied as options.
-a default on enable: 8080:80:8443:443
-a default on disable: 80:0:443:0
-i default on enable: 7143:143:7993:993
-i default on disable: 143:7143:993:7993
-p default on enable: 7110:110:7995:995
-p default on disable: 110:7110:995:7995
-x default on store disable: http
-x default on proxy enable/disable: http

What's Wrong?

Did you check in /opt/zimbra/log/nginx.log ?

Notable Proxy Bugs

Unresolved At This Time (Sept 25, 2008)

Unsorted

  • "ZCS Mailbox Server Proxy"
    • See: http://bugzilla.zimbra.com/show_bug.cgi?id=9469
    • From release notes, "HTTP proxy is supported (Beta). This includes REST sharing, Caldav, and Zimbra mobile. For Zimbra Mobile, ZCS redirect/forwards to the correct host. (Bug 9469)"
      • Please note, that ZCS HTTP Proxy (http reverse proxy) is Beta, first released in 5.0.6.
    • Though, as of 5.0.8,""For activesync connection to go thru the proxy, they'll have to configure reversed proxy. However, there're already a few known bugs about sharing broken with reversed proxy enabled. They're better off waiting for 5.0.9 than to try to configure reversed proxy now."
  • "need to support multi-server (proxy) for mobile clients"

Resolved In 5.0.9

Those That Are Sort Of Client Side Impacting
Configuration / Initial Setup Issues

Resolved in 5.0.7

Resolved in 5.0.6

Public Service Hostname

Resolved in 5.0.5

  • Nginx: http proxy does not work with REST
    • Note, this isn't "completely" resolved, as you'll notice by other targeted bugs with 5.0.5+ releases.
    • See: Nginx: http proxy does not work with REST
Jump to: navigation, search