NGINX Configuration Structure

Admin Article

Article Information

This article applies to the following ZCS versions.

ZCS 8.5 Article ZCS 8.5 ZCS 8.0 Article ZCS 8.0



Nginx Configuration Overview

Zimbra NGINX Proxy has a hierarchical configuration structure. Top level configuration files include other functionality-specific configuration files. The main configuration file is /opt/zimbra/conf/nginx.conf, and this includes other configuration files as per the hierarchy below. Each configuration file usually defines and/or references one or more directives. For a complete list of NGINX Proxy Configuration Directives, please refer to NGINX Configuration Directive Reference

Each NGINX configuration file is generated from a corresponding template file. A template file looks exactly the same as its corresponding configuration file, with the difference that the template file contains keywords which are expanded by the Proxy Config Generator, and the configuration file is produced as a result

Understanding The Zimbra Proxy Config Rewrite


zmproxyconfgen , zmproxyconfig and zmproxyctl

One changes the proxy environment variables with either zmproxyconfig or zmprov . After you make your changes, zmproxyctl restart is ran, which will restart the proxy service and invoke zmproxyconfgen in the background. The zmproxyconfgen 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.

To change multiple LDAP attributes related to the proxy at once (i.e any of the zimbraReverseProxy* attrs) instead of using zmprov command to change each attribute individually, /opt/zimbra/libexec/zmproxyconfig can be used. The usage for this script see Ajcody-Proxy-Guide-Rewrite-Project#zmproxyconfig

You will have to restart the proxy after modifying your proxy server with zmproxyconfig by running 'zmproxyctl restart' .

  • Note: zmproxyconfig is no longer required to enable the proxy if you are doing a fresh installation of ZCS with proxy. The installer already runs this and the proxy is enabled for imap/pop/https access by default. Although it is needed while trying to deploy proxy in existing non-proxy environments when using the existing servers. Kindly refer http://wiki.zimbra.com/wiki/Enabling_Zimbra_Proxy#Using_existing_servers

zmconfigd

* More details needed.

Updates to the Nginx configuration files are also done via the zmconfigd processes on your proxy and mailstore nodes.

Config Files And Config Templates


Source: http://wiki.zimbra.com/wiki/Zimbra_Proxy_Guide#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. 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)

Nginx Configuration 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.zmlookup
    |_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail
       |_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imap.default
       |_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imaps.default
       |_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3.default
       |_ /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3s.default
    |_ /opt/zimbra/conf/nginx/includes/nginx.conf.web
       |_ /opt/zimbra/conf/nginx/includes/nginx.conf.web.http.default
       |_ /opt/zimbra/conf/nginx/includes/nginx.conf.web.https.default
       |_ /opt/zimbra/conf/nginx/includes/nginx.conf.web.admin.default  
       |_ /opt/zimbra/conf/nginx/includes/nginx.conf.web.sso.default

Description Of The Nginx Configuration Files

/opt/zimbra/conf/nginx.conf


  • /opt/zimbra/conf/nginx.conf
Description:
This is the main top-level Nginx configuration file. It defines the working directory for Nginx worker processes (/opt/zimbra), and includes the main, memcache, mail, and web configuration files. When Nginx Proxy starts, it reads this configuration file first
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.template
Includes:
/opt/zimbra/conf/nginx/includes/nginx.conf.main
/opt/zimbra/conf/nginx/includes/nginx.conf.memcache
/opt/zimbra/conf/nginx/includes/nginx.conf.zmlookup
/opt/zimbra/conf/nginx/includes/nginx.conf.mail
/opt/zimbra/conf/nginx/includes/nginx.conf.web

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.main
Description:
This file contains the directives that control the basic Nginx functionality. Defines global parameters for all Nginx worker processes.
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.main.template
Includes:
None

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.memcache
Description:
This file contains the memcache configuration for Nginx. It defines all the memcache servers that are used by Nginx Proxy, and the various cache timeout related settings for cache fetch/store. Common for mail and web.
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.memcache.template
Includes:
None

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.mail
Description:
This file contains the common configuration for Mail [POP3[S] And IMAP[S]]. The directives referenced here are usually common across both, POP3[S] and IMAP[S]. Significantly, this file defines the route lookup handlers used by Nginx to discover the mail routes.
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.mail.template
Includes:
/opt/zimbra/conf/nginx/includes/nginx.conf.mail.imap.default
/opt/zimbra/conf/nginx/includes/nginx.conf.mail.imaps.default
/opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3.default
/opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3s.default

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imap.default
Description:
This file defines the server block for IMAP.
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.mail.imap.default.template
Includes:
None

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.mail.imaps.default
Description:
This file defines the server block for IMAPS.
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.mail.imaps.default.template
Includes:
None

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3.default
Description:
This file defines the server block for POP3.
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.template.pop3.default.template
Includes:
None

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.mail.pop3s.default
Description:
This file defines the server block for POP3S.
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.mail.pop3s.default.template
Includes:
None

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.web
Description:
This file contains the common configuration for Web Proxy [HTTP and HTTPS]. The directives here apply HTTP as well as HTTPS. This file also defines the route lookup handlers used by NGINX to discover the web routes.
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.web.template
Includes:
/opt/zimbra/conf/nginx/includes/nginx.conf.web.http.default
/opt/zimbra/conf/nginx/includes/nginx.conf.web.https.default
/opt/zimbra/conf/nginx/includes/nginx.conf.web.sso.default
/opt/zimbra/conf/nginx/includes/nginx.conf.web.admin.default

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.web.http.default
Description:
This file defines the server block for HTTP.
Template:
/opt/zimbra/conf/nginx/templates/nginx.conf.web.http.default.template
Includes:
None

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.web.https.default
Description: This file defines the server block for NGINX HTTP SSL Proxy
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.web.https.default.template

/opt/zimbra/conf/nginx/includes/nginx.conf.web.sso.default


  • /opt/zimbra/conf/nginx/includes/nginx.conf.web.sso.default
Description: This file defines the server block for NGINX HTTP SSO Proxy
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.web.sso.default.template

/opt/zimbra/conf/nginx/includes/nginx.conf.web.admin.default


  • /opt/zimbra/conf/nginx/includes/nginx.conf.web.admin.default
Description: This file defines the server block for NGINX Admin Proxy
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.web.admin.default.template


Verified Against: ZCS 8.0 and later Date Created: 6/5/2014
Article ID: https://wiki.zimbra.com/index.php?title=NGINX_Configuration_Structure Date Modified: 2014-09-10



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