NGINX Configuration Tips

NGINX Configuration Tips+

   KB 2590        Last updated on 2015-07-12  




0.00
(0 votes)

Many configuration parameters of NGINX can be customized. This page provides tips to take care of the most usual ways to customize NGINX configuration.

View/Modify Route Lookup Handlers (garpu)

The command zmprov garpu (get all reverse proxy urls) gives a list of all the route lookup handlers used by NGINX for mail/web route discovery.

zmprov garpu will list all the servers for which zimbraReverseProxyLookupTarget is TRUE.

Therefore, to add a server to the route lookup handler list, execute the command:

zmprov ms <server> zimbraReverseProxyLookupTarget TRUE

To remove a server from the route lookup handler list, execute the command:

zmprov ms <server> zimbraReverseProxyLookupTarget FALSE

NOTE: Only add servers running the mailbox service to the route lookup handler list. This is because the URL used by NGINX is of the form http://<server>:7072/service/extension/nginx-lookup - and this URL is handled by jetty.

Set up Virtual Hosting (Domain Completion) for Mail

For accounts authenticating without domain, NGINX internally suffixes @domain to the login name, by first looking up an existing domain by the IP address of the proxy interface where the connection came in. If no such domain is found, then NGINX falls back to the default domain name specified by the config attribute zimbraDefaultDomainName.

The IP to domain mapping is done based on the zimbraVirtualIPAddress attribute of the domain.

To set up virtualhosting for multiple domains, then follow these steps:

  • For each domain, identify a set of proxy IP addresses that should be reverse mapped to this domain. Then, for each of these IP addresses, execute the command
zmprov md <domain> +zimbraVirtualIPAddress 1.2.3.4
zmprov md <domain> +zimbraVirtualIPAddress 5.6.7.8
  • The above step will ensure that if a mail user logs in on Proxy IP 1.2.3.4, or on IP address 5.6.7.8, then @<domain> will automatically be suffixed to the login name

NOTE The IP-to-domain mapping is a many-to-one relationship. That means, one domain can map to multiple IP addresses, but one IP address can only map to a single domain. Therefore, to set up domain completion for multiple domains, at least one separate IP address must be allocated for each domain, and the NGINX Proxy server(s) must accept connections on each of these IP addresses.

In case of a single domain that needs to be appended to each unqualified login name, the global config attribute zimbraDefaultDomainName to the required domain name

zmprov mcf zimbraDefaultDomainName <defaultdomain>

Bad/Invalid command when proxying to external POP/IMAP servers

NGINX issues the XOIP command to the upstream POP3 server, and the ID command to the upstream IMAP server, before logging in to upstream. This is for auditing purposes so that the client's IP address is known to the upstream server. The global config attributes zimbraReverseProxySendPop3Xoip and zimbraReverseProxySendImapId control this aspect.

However, some external IMAP servers may not implement the ID command, and some external POP3 servers may not implement the XOIP command.

To turn off sending the XOIP command, set zimbraReverseProxySendPop3Xoip to false. To turn off sending the IMAP command, set zimbraReverseProxySendImapId to false.

zmprov mcf zimbraReverseProxySendPop3Xoip FALSE
zmprov mcf zimbraReverseProxySendImapId FALSE

AUTH GSSAPI

NGINX supports enablement of the SASL GSSAPI Authentication Mechanism for POP and IMAP through the zimbraReverseProxyPop3SaslGssapiEnabled and zimbraReverseProxyImapSaslGssapiEnabled attributes respectively.

Set them to true to enable GSSAPI Authentication for NGINX

zmprov ms <server> zimbraReverseProxyPop3SaslGssapiEnabled TRUE
zmprov ms <server> zimbraReverseProxyImapSaslGssapiEnabled TRUE

Set these attributes to FALSE to disable GSSAPI Authentication.

AUTH PLAIN

NGINX supports enablement of the SASL PLAIN Authentication Mechanism (RFC 4616) for POP and IMAP through the zimbraReverseProxyPop3SaslPlainEnabled and zimbraReverseProxyImapSaslPlainEnabled attributes respectively.

Set them to true to enable PLAIN Authentication for NGINX

zmprov ms <server> zimbraReverseProxyPop3SaslPlainEnabled TRUE
zmprov ms <server> zimbraReverseProxyImapSaslPlainEnabled TRUE

Set them to false to disable PLAIN Authentication for NGINX

zmprov ms <server> zimbraReverseProxyPop3SaslPlainEnabled FALSE
zmprov ms <server> zimbraReverseProxyImapSaslPlainEnabled FALSE

Allow/Disallow Clear-Text Logins

To configure NGINX to allow/disallow cleartext logins on non SSL/TLS connections, use the zimbraReverseProxyPop3StartTlsMode and zimbraReverseProxyImapStartTlsMode attributes.

To allow clear-text logins for POP and IMAP (respectively) over non-SSL/TLS connections, run these commands

zmprov ms <server> zimbraReverseProxyPop3StartTlsMode on
zmprov ms <server> zimbraReverseProxyImapStartTlsMode on

To disallow clear-text logins for POP and IMAP (respectively) over non-SSL/TLS connections, run these commands

zmprov ms <server> zimbraReverseProxyPop3StartTlsMode only
zmprov ms <server> zimbraReverseProxyImapStartTlsMode only


Verified Against: ZCS 5.0.x Date Created: 9/10/2008
Article ID: https://wiki.zimbra.com/index.php?title=NGINX_Configuration_Tips Date Modified: 2015-07-12



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