NGINX Configuration Structure

Revision as of 17:02, 10 September 2014 by Ajcody (talk | contribs) (/opt/zimbra/conf/nginx.conf)

Admin Article

Article Information

This article applies to the following ZCS versions.

ZCS 8.5 Article ZCS 8.5ZCS 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
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.main.template

/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
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.memcache.template

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.mail
Description: This file contains the common configuration for NGINX Mail Proxy. The directives referenced here are usually common across both, POP and IMAP. 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

/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 NGINX IMAP Proxy
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.mail.imap.default.template

/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 NGINX IMAP SSL Proxy
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.mail.imaps.default.template

/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 NGINX POP3 Proxy
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.template.pop3.default.template

/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 NGINX POP3 SSL Proxy
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.mail.pop3s.default.template

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


  • /opt/zimbra/conf/nginx/includes/nginx.conf.web
Description: This file contains the common configuration for NGINX Web Proxy. The directives here apply for both, 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

/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 NGINX HTTP Proxy
Template: /opt/zimbra/conf/nginx/templates/nginx.conf.web.http.default.template

/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