Creating NGINX Plus Configuration Files

NGINX Plus is similar to other services in that it has a text-based configuration file written in a particular format. By default the file is named nginx.conf and placed in the /etc/nginx directory. (For the open source NGINX product, the location depends on the package system used to install NGINX and the operating system. It is typically one of /usr/local/nginx/conf, /etc/nginx, or /usr/local/etc/nginx.)

The configuration file consists of directives and their parameters. Simple (single-line) directives each end with a semicolon. Other directives act as “containers” that group together related directives, enclosing them in curly braces ( {} ). Here are some examples of simple directives.

user             nobody;
error_log        logs/error.log notice;
worker_processes 1;

To make the configuration easier to maintain, we recommend that you split it into a set of feature-specific files stored in the /etc/nginx/conf.d directory and use the include directive in the main nginx.conf file to reference the contents of the feature-specific files.

include conf.d/http;
include conf.d/stream;
include conf.d/exchange-enhanced;

A few top-level directives, referred to as contexts, group together the directives that apply to different traffic types:

  • events – General connection processing
  • http – HTTP traffic
  • mail – Mail traffic
  • stream – TCP traffic

Directives placed outside of these contexts are said to be in the main context.

In each of the traffic-handling contexts, you include one or more server contexts to define virtual servers that control the processing of requests. The directives you can include within a server context vary depending on the traffic type.

For HTTP traffic (the http context), each server directive controls the processing of requests for resources at particular domains or IP addresses. One or more location contexts in a server context define how to process specific sets of URIs.

For mail and TCP traffic (the mail and stream contexts) the server directives each control the processing of traffic arriving at a particular TCP port or UNIX socket.

The following configuration illustrates the use of contexts.

user nobody; # a directive in the 'main' context

events {
    # configuration of connection processing

http {

    # Configuration specific to HTTP and affecting all virtual servers

    server {
        # configuration of HTTP virtual server 1

        location /one {
            # configuration for processing URIs with '/one'

        location /two {
            # configuration for processing URIs with '/two'

    server {
        # configuration of HTTP virtual server 2

stream {
    # Configuration specific to TCP and affecting all virtual servers

    server {
        # configuration of TCP virtual server 1 

For most directives, a context that is defined inside another context (a child context) inherits the values of directives included at the parent level. To override a value inherited from the parent, include the directive in the child context. For more information on context inheritence, see the documentation for the proxy_set_header directive.

For changes to the configuration file to take effect, NGINX Plus must reload the file. You can either restart the nginx process or send the reload signal to upgrade the configuration without interrupting the processing of current requests.


Download a 30 day free trial and see what you've been missing.


Got a question for the NGINX team?

< back


Sign up for beta

We'll be in touch with you about our NGINX Controller beta.