Configuring Zimbra NGINX POP/IMAP/HTTP Proxy Text Notes
Back To Main Proxy Page
[CONFIGURING ZIMBRA NGINX POP/IMAP/HTTP PROXY]
Zimbra NGINX POP/IMAP/HTTP proxy configuration is generated by the
zmproxyconfgen config generation script. This script reads in the proxy
configuration template files, and generates the NGINX config files after
performing keyword substitution on the template files with values from the
LDAP configuration.
zmproxyconfgen is usually never invoked directly -- it is invoked
automatically by zmproxyctl
The following sections describe the structure of the NGINX Proxy
Configuration
(I) Config Files and Config Templates
-------------------------------------
To simplify configuration, the NGINX configuration files have been split
up into different config files based on functionality
The main, top-level configuration file is /opt/zimbra/conf/nginx.conf, and
this file includes the main config, memcache config, mail config, and web
config files
The mail config in turn includes the configuration for imap, imaps, pop3
and pop3s
The web config includes the configuration for http and https. Each of the
http and https configs include exactly one sub-configuration which depends
on the mail mode, which can be one of http,https,both,redirect,mixed
The template files follow exactly the same inclusion hierarchy, and each
configuration file has a corresponding template file from which it is
generated
Each template file resides in /opt/zimbra/conf/nginx/templates/
Each corresponding config file resides in /opt/zimbra/conf/nginx/includes/
(excluding top-level config file which is /opt/zimbra/conf/nginx/nginx.conf)
The next section describes the configuration inclusion hierarchy
(II) Config File Hierarchy
--------------------------
The symbol |_ indicates that a file is included by the one above it
Increasing levels of indentation indicate lower levels of config files
/opt/zimbra/conf/nginx.conf
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.main
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.memcache
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imap
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imaps
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3s
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.web
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.web.http
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.web.http.mode-<M>
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.web.https
|_ /opt/zimbra/conf/nginx/includes/nginx.conf.web.https.mode-<M>
... where <M> is the mail mode, and can be one of
http|https|both|redirect|mixed
(III) Description of Config Files
---------------------------------
* /opt/zimbra/conf/nginx.conf
Description:
Core NGINX configuration file read by NGINX Proxy
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.template
Keywords:
${core.workdir} : NGINX working directory
Includes:
/opt/zimbra/conf/nginx/includes/nginx.conf.main
/opt/zimbra/conf/nginx/includes/nginx.conf.memcache
/opt/zimbra/conf/nginx/includes/nginx.conf.mail
/opt/zimbra/conf/nginx/includes/nginx.conf.web
* /opt/zimbra/conf/nginx/includes/nginx.conf.main
Description:
Defines global parameters for all NGINX worker processes
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.main.template
Keywords:
${main.user} : User Name of worker process
${main.group} : Group Name of worker process
${main.workers} : Number of worker processes
${main.pidfile} : NGINX PID file
${main.logfile} : Error Log file
${main.loglevel} : Error Log level
${main.connections} : Number of connections that each worker
: process is allowed to handle
${main.krb5keytab} : Location of Kerberos Keytab file used for
: GSSAPI authentication
Includes:
None
* /opt/zimbra/conf/nginx/includes/nginx.conf.memcache
Description:
Defines memcache configuration, common for mail and web
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.memcache.template
Keywords:
${memcache.:servers} : List of available memcache servers/ports
${memcache.timeout} : The time that NGINX will wait for a cache
: result before treating it as a cache miss
${memcache.reconnect} : The time after which NGINX will attempt to
: re-connect to a memcache server which has
: gone down
${memcache.ttl} : The time interval that an entry will spend
: in memcache before being automatically
: evicted by memcache
${memcache.unqual} : (deprecated) Whether mail routes should be
: stored without user-name qualification
: The value is always considered false
Includes:
None
* /opt/zimbra/conf/nginx/includes/nginx.conf.mail
Description:
Defines the common mail configuration common to IMAP and POP3
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.mail.template
Keywords:
${mail.timeout} : Idle timeout between mail client and proxy
${mail.passerrors} : Whether to pass backend errors to client
${mail.:auth_http} : The list of route lookup handlers
${mail.pop3capa} : NGINX POP3 capabilities
${mail.imapcapa} : NGINX IMAP capabilities
${mail.imapid} : Response given by NGINX to the IMAP ID command
: (RFC 2971)
${mail.dpasswd} : Password for zmnginx user (GSSAPI auth)
${mail.defaultrealm} : Default Kerberos Realm (GSSAPI auth)
${mail.sasl_host_from_ip}
: Whether to look up service principal by
: incoming interface address (GSSAPI auth)
${mail.saslapp} : NGINX SASL authentication application name
: (GSSAPI auth)
${mail.ipmax} : IP throttle counter
${mail.ipttl} : TTL for IP throttle counter
${mail.iprej} : IP throttle rejection message
${mail.usermax} : User throttle counter
${mail.userttl} : TTL for User throttle counter
${mail.userrej} : User throttle rejection message
${mail.upstream.pop3xoip}
: Whether to send XOIP to POP3 upstream before
: logging in (Audit)
${mail.upstream.imapid} : Whether to send ID command to IMAP upstream
: before logging in (Audit)
${mail.imap.authplain.enabled}
: Enables AUTH PLAIN support for IMAP
${mail.imap.authgssapi.enabled}
: Enables AUTH GSSAPI support for IMAP
${mail.pop3.authplain.enabled}
: Enables AUTH PLAIN support for POP3
${mail.pop3.authgssapi.enabled}
: Enables AUTH GSSAPI support for POP3
${mail.imap.literalauth}: Enables upstream IMAP auth using literals
${mail.auth_wait} : Time delay before which NGINX will reject
: an invalid login attempt
${mail.ssl.preferserverciphers}
: Requires protocols SSLv3 and TLSv1 server
: ciphers be preferred over client's ciphers.
${mail.ssl.cert} : Path to server certificate (IMAPS+POP3S)
${mail.ssl.key} : Path to server certificate key (IMAPS+POP3S)
${mail.ssl.ciphers} : Permitted ciphers
Includes:
/opt/zimbra/conf/nginx/includes/nginx.conf.mail.imap
/opt/zimbra/conf/nginx/includes/nginx.conf.mail.imaps
/opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3
/opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3s
* /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imap
Description:
Defines the server block for IMAP
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.mail.imap.template
Keywords:
${mail.imap.port} : IMAP server port
${mail.imap.tls} : TLS Mode for IMAP (on|off|only)
Includes:
None
* /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imaps
Description:
Defines the server block for IMAPS
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.mail.imaps.template
Keywords:
${mail.imaps.port} : IMAPS server port
Includes:
None
* /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3
Description:
Defines the server block for POP3
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.mail.pop3.template
Keywords:
${mail.pop3.port} : POP3 server port
${mail.pop3.tls} : POP3 TLS Mode for POP3 (on|off|only)
Includes:
None
* /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3s
Description:
Defines the server block for POP3S
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.mail.pop3s.template
Keywords:
${mail.pop3s.port} : POP3S server port
Includes:
None
* /opt/zimbra/conf/nginx/includes/nginx.conf.web
Description:
Defines the common web configuration common to HTTP and HTTPS
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.web.template
Keywords:
${web.upstream.name} : Symbolic name of upstream server cluster
${web.upstream.:servers}: List of upstream HTTP servers
${web.:routehandlers} : List of route handlers
${web.routetimeout} : Route lookup timeout
Includes:
/opt/zimbra/conf/nginx/includes/nginx.conf.web.http
/opt/zimbra/conf/nginx/includes/nginx.conf.web.https
* /opt/zimbra/conf/nginx/includes/nginx.conf.web.http
Description:
Defines the server block for HTTP
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.web.http.template
Keywords:
${web.http.port} : HTTP server port
${web.http.maxbody} : Maximum allowed size for client request
Includes:
/opt/zimbra/conf/nginx/includes/nginx.conf.web.http.mode-<M>
(<M> is mail mode, and can be one of http|https|both|redirect|mixed)
* /opt/zimbra/conf/nginx/includes/nginx.conf.web.https
Description:
Defines the server block for HTTPS
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.web.http.template
Keywords:
${web.https.port} : HTTPS server port
${web.https.maxbody} : Maximum allowed size for client request
${web.ssl.cert} : Path to server certificate
${web.ssl.key} : Path to server certificate key
Includes:
/opt/zimbra/conf/nginx/includes/nginx.conf.web.https.mode-<M>
(<M> is mail mode, and can be one of http|https|both|redirect|mixed)
* /opt/zimbra/conf/nginx/includes/nginx.conf.web.http(s).mode-<M>
Description:
There are 5 mail modes, and there exists one config file for each
mail mode for HTTP as well as separate ones for HTTPS
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.web.http(s).mode-<M>.template
Keywords:
None
Includes:
None
(IV) Customizing the proxy configuration
----------------------------------------
A few LDAP attributes (and some localconfig values) affect some of the
variable definitions in the Proxy Configuration Files. The config generation
script (zmproxyconfgen) is responsible for reading these LDAP attributes
and performing the textual substitution in the template files.
The following is the list of LDAP attributes (and localconfig values) that
govern the NGINX configuration keywords. The list includes the attribute
name, its type, how to get, how to set, which NGINX keyword it overrides,
and its default value.
To customize the NGINX configuration, modify these attributes, and
generate the proxy configuration by running the command
$ /opt/zimbra/libexec/zmmtaconfig imapproxy
If the nginx keyword that you wish to customize does not appear in the
list below, then the template file should be directly modified on disk
(/opt/zimbra/conf/nginx/templates/*), and the corresponding keyword, say,
${k}, should be replaced by the desired value.
Also make sure that the customized template files are backed up, because
upgrades will overwrite any modifications made to the template files
For example, the NGINX log level keyword ${main.loglevel} is not overridden
by any LDAP configuration. Therefore, if debug log level is desired, then
the template file nginx.conf.main.template must be edited, and the line:
error_log ${main.logfile} ${main.loglevel};
must be replaced by
error_log ${main.logfile} debug;
(See http://wiki.codemongers.com/ for a complete reference of NGINX
configuration directives)
* krb5_keytab
Name : krb5_keytab
Type : localconfig
Get: : zmlocalconfig -x krb5_keytab
Set: : zmlocalconfig -e krb5_keytab=<value>
Default: : /opt/zimbra/conf/krb5.keytab
Overrides : ${main.krb5keytab}
* ldap_nginx_password
Name : ldap_nginx_password
Type : localconfig
Get : zmlocalconfig -x -s ldap_nginx_password
Set : zmlocalconfig -e ldap_nginx_password=<value>
Default : zmnginx
Overrides : ${mail.dpasswd}
* zimbraReverseProxyIPLoginLimit
Name : zimbraReverseProxyIPLoginLimit
Type : LDAP (globalConfig)
Get : zmprov gcf zimbraReverseProxyIPLoginLimit
Set : zmprov mcf zimbraReverseProxyIPLoginLimit <value>
Default : 0
Overrides : ${mail.ipmax}
* zimbraReverseProxyIPLoginLimitTime
Name : zimbraReverseProxyIPLoginLimitTime
Type : LDAP (globalConfig)
Get : zmprov gcf zimbraReverseProxyIPLoginLimitTime
Set : zmprov mcf zimbraReverseProxyIPLoginLimitTime \
: <value>
Default : 3600 (seconds)
Overrides : ${mail.ipttl}
* zimbraReverseProxyUserLoginLimit
Name : zimbraReverseProxyUserLoginLimit
Type : LDAP (globalConfig)
Get : zmprov gcf zimbraReverseProxyUserLoginLimit
Set : zmprov mcf zimbraReverseProxyUserLoginLimit \
: <value>
Default : 0
Overrides : ${mail.usermax}
* zimbraReverseProxyUserLoginLimitTime
Name : zimbraReverseProxyUserLoginLimitTime
Type : LDAP (globalConfig)
Get : zmprov gcf zimbraReverseProxyUserLoginLimitTime
Set : zmprov mcf zimbraReverseProxyUserLoginLimitTime \
: <value>
Default : 3600 (seconds)
Overrides : ${mail.userttl}
* zimbraReverseProxySendPop3Xoip
Name : zimbraReverseProxySendPop3Xoip
Type : LDAP (globalConfig)
Get : zmprov gcf zimbraReverseProxySendPop3Xoip
Set : zmprov mcf zimbraReverseProxySendPop3Xoip <value>
Default : TRUE
Overrides : mail.upstream.pop3xoip
* zimbraReverseProxySendImapId
Name : zimbraReverseProxySendImapId
Type : LDAP (globalConfig)
Get : zmprov gcf zimbraReverseProxySendImapId
Set : zmprov mcf zimbraReverseProxySendImapId <value>
Default : TRUE
Overrides : mail.upstream.imapid
* zimbraReverseProxyImapSaslGssapiEnabled
Name : zimbraReverseProxyImapSaslGssapiEnabled
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraReverseProxyImapSaslGssapiEnabled
Get(server) : zmprov gs <server> \
: zimbraReverseProxyImapSaslGssapiEnabled
Set(global) : zmprov mcf \
: zimbraReverseProxyImapSaslGssapiEnabled <value>
Set(server) : zmprov ms <server> \
: zimbraReverseProxyImapSaslGssapiEnabled <value>
Default : FALSE
Overrides : mail.imap.authgssapi.enabled
* zimbraReverseProxyPop3SaslGssapiEnabled
Name : zimbraReverseProxyPop3SaslGssapiEnabled
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraReverseProxyPop3SaslGssapiEnabled
Get(server) : zmprov gs <server> \
: zimbraReverseProxyPop3SaslGssapiEnabled
Set(global) : zmprov mcf \
: zimbraReverseProxyPop3SaslGssapiEnabled <value>
Set(server) : zmprov ms <server> \
: zimbraReverseProxyPop3SaslGssapiEnabled <value>
Default : FALSE
Overrides : mail.pop3.authgssapi.enabled
* zimbraReverseProxyDefaultRealm
Name : zimbraReverseProxyDefaultRealm
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraReverseProxyDefaultRealm
Get(server) : zmprov gs <server> zimbraReverseProxyDefaultRealm
Set(global) : zmprov mcf zimbraReverseProxyDefaultRealm <value>
Set(server) : zmprov ms <server> \
: zimbraReverseProxyDefaultRealm <value>
Default : EXAMPLE.COM
Overrides : ${mail.defaultrealm}
* zimbraReverseProxySSLCiphers
Name : zimbraReverseProxySSLCiphers
Type : LDAP (globalConfig)
Get : zmprov gcf zimbraReverseProxySSLCiphers
Set : zmprov mcf zimbraReverseProxySSLCiphers <value>
Default : !SSLv2:!MD5:HIGH
Overrides : ${mail.ssl.ciphers}
* zimbraReverseProxyMailEnabled
Name : zimbraReverseProxyMailEnabled
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraReverseProxyMailEnabled
Get(server) : zmprov gs <server> zimbraReverseProxyMailEnabled
Set(global) : zmprov mcf zimbraReverseProxyMailEnabled <value>
Set(server) : zmprov ms <server> \
: zimbraReverseProxyMailEnabled <value>
Default : TRUE
Overrides : ${mail.enabled}
* zimbraReverseProxyHttpEnabled
Name : zimbraReverseProxyHttpEnabled
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraReverseProxyHttpEnabled
Get(server) : zmprov gs <server> zimbraReverseProxyHttpEnabled
Set(global) : zmprov mcf zimbraReverseProxyHttpEnabled <value>
Set(server) : zmprov ms <server> \
: zimbraReverseProxyHttpEnabled <value>
Default : FALSE
Overrides : ${web.enabled}
* zimbraPop3ProxyBindPort
Name : zimbraPop3ProxyBindPort
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraPop3ProxyBindPort
Get(server) : zmprov gs <server> zimbraPop3ProxyBindPort
Set(global) : zmprov mcf zimbraPop3ProxyBindPort <value>
Set(server) : zmprov ms <server> zimbraPop3ProxyBindPort <value>
Default : 110
Overrides : ${mail.pop3.port}
* zimbraPop3SSLProxyBindPort
Name : zimbraPop3SSLProxyBindPort
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraPop3SSLProxyBindPort
Get(server) : zmprov gs <server> zimbraPop3SSLProxyBindPort
Set(global) : zmprov mcf zimbraPop3SSLProxyBindPort <value>
Set(server) : zmprov ms <server> \
: zimbraPop3SSLProxyBindPort <value>
Default : 995
Overrides : ${mail.pop3s.port}
* zimbraImapProxyBindPort
Name : zimbraImapProxyBindPort
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraImapProxyBindPort
Get(server) : zmprov gs <server> zimbraImapProxyBindPort
Set(global) : zmprov mcf zimbraImapProxyBindPort <value>
Set(server) : zmprov ms <server> zimbraImapProxyBindPort <value>
Default : 143
Overrides : ${mail.imap.port}
* zimbraImapSSLProxyBindPort
Name : zimbraImapSSLProxyBindPort
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraImapSSLProxyBindPort
Get(server) : zmprov gs <server> zimbraImapSSLProxyBindPort
Set(global) : zmprov mcf zimbraImapSSLProxyBindPort <value>
Set(server) : zmprov ms <server> \
: zimbraImapSSLProxyBindPort <value>
Default : 993
Overrides : ${mail.imaps.port}
* zimbraReverseProxyImapStartTlsMode
Name : zimbraReverseProxyImapStartTlsMode
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraReverseProxyImapStartTlsMode
Get(server) : zmprov gs <server> \
: zimbraReverseProxyImapStartTlsMode
Set(global) : zmprov mcf zimbraReverseProxyImapStartTlsMode \
: <value>
Set(server) : zmprov ms <server> \
: zimbraReverseProxyImapStartTlsMode <value>
Default : only
Overrides : ${mail.imap.tls}
* zimbraReverseProxyPop3StartTlsMode
Name : zimbraReverseProxyPop3StartTlsMode
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraReverseProxyPop3StartTlsMode
Get(server) : zmprov gs <server> \
: zimbraReverseProxyPop3StartTlsMode
Set(global) : zmprov mcf zimbraReverseProxyPop3StartTlsMode \
: <value>
Set(server) : zmprov ms <server> \
: zimbraReverseProxyPop3StartTlsMode <value>
Default : only
Overrides : ${mail.pop3.tls}
* zimbraFileUploadMaxSize
Name : zimbraFileUploadMaxSize
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraFileUploadMaxSize
Get(server) : zmprov gs <server> zimbraFileUploadMaxSize
Set(global) : zmprov mcf zimbraFileUploadMaxSize <value>
Set(server) : zmprov ms <server> zimbraFileUploadMaxSize <value>
Default : 10485760
Overrides : ${web.uploadmax}
* zimbraMailProxyPort
Name : zimbraMailProxyPort
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraMailProxyPort
Get(server) : zmprov gs <server> zimbraMailProxyPort
Set(global) : zmprov mcf zimbraMailProxyPort <value>
Set(server) : zmprov ms <server> zimbraMailProxyPort <value>
Default : 0
Overrides : ${web.http.port}
* zimbraMailSSLProxyPort
Name : zimbraMailSSLProxyPort
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraMailSSLProxyPort
Get(server) : zmprov gs <server> zimbraMailSSLProxyPort
Set(global) : zmprov mcf zimbraMailSSLProxyPort <value>
Set(server) : zmprov ms <server> zimbraMailSSLProxyPort <value>
Default : 0
Overrides : ${web.https.port}
* zimbraMailPort
Name : zimbraMailPort
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraMailPort
Get(server) : zmprov gs <server> zimbraMailPort
Set(global) : zmprov mcf zimbraMailPort <value>
Set(server) : zmprov ms <server> zimbraMailPort <value>
Default : 0
Overrides : ${web.http.uport}
* zimbraReverseProxyMailMode
Name : zimbraReverseProxyMailMode
Type : LDAP (globalConfig,server)
Get(global) : zmprov gcf zimbraReverseProxyMailMode
Get(server) : zmprov gs <server> zimbraReverseProxyMailMode
Set(global) : zmprov mcf zimbraReverseProxyMailMode <value>
Set(server) : zmprov ms <server> \
: zimbraReverseProxyMailMode <value>
Default : both
Overrides : ${web.mailmode}