Ajcody-Proxy-Config-Txt
- This is archive documentation, which means it is not supported or valid for recent versions of Zimbra Collaboration.
Configuring Zimbra NGINX POP/IMAP/HTTP Proxy Text Notes
[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}