Configuring Zimbra NGINX POP/IMAP/HTTP Proxy Text Notes

Back To Main Proxy Page


    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 

    (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 

    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/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

    (III) Description of Config Files

    * /opt/zimbra/conf/nginx.conf

        Core NGINX configuration file read by NGINX Proxy


        ${core.workdir}         : NGINX working directory


    * /opt/zimbra/conf/nginx/includes/nginx.conf.main

        Defines global parameters for all NGINX worker processes


        ${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


    * /opt/zimbra/conf/nginx/includes/nginx.conf.memcache

        Defines memcache configuration, common for mail and web


        ${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


    * /opt/zimbra/conf/nginx/includes/nginx.conf.mail

        Defines the common mail configuration common to IMAP and POP3


        ${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)
                                : 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
                                : 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)
                                : Enables AUTH PLAIN support for IMAP
                                : Enables AUTH GSSAPI support for IMAP
                                : Enables AUTH PLAIN support for POP3
                                : 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
                                : 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


    * /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imap

        Defines the server block for IMAP 


        ${mail.imap.port}       : IMAP server port
        ${mail.imap.tls}        : TLS Mode for IMAP (on|off|only)


    * /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imaps

        Defines the server block for IMAPS


        ${mail.imaps.port}      : IMAPS server port


    * /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3

        Defines the server block for POP3


        ${mail.pop3.port}       : POP3 server port
        ${mail.pop3.tls}        : POP3 TLS Mode for POP3 (on|off|only)


    * /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3s

        Defines the server block for POP3S


        ${mail.pop3s.port}      : POP3S server port


    * /opt/zimbra/conf/nginx/includes/nginx.conf.web

        Defines the common web configuration common to HTTP and HTTPS


        ${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


    * /opt/zimbra/conf/nginx/includes/nginx.conf.web.http

        Defines the server block for HTTP


        ${web.http.port}        : HTTP server port
        ${web.http.maxbody}     : Maximum allowed size for client request

        (<M> is mail mode, and can be one of http|https|both|redirect|mixed)

    * /opt/zimbra/conf/nginx/includes/nginx.conf.web.https

        Defines the server block for HTTPS


        ${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

        (<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>

        There are 5 mail modes, and there exists one config file for each 
        mail mode for HTTP as well as separate ones for HTTPS




    (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}

Jump to: navigation, search