Other Contexts

The contexts below were separated out either because they depend on more optional modules, they are used only in certain circumstances, or they are used for functionality that most people will not be using.

Some of these contexts are:

• split_clients: This context is configured to split the clients that the server receives into categories by labeling them with variables based on a percentage. These can then be used to do A/B testing by providing different content to different hosts.
• perl / perl_set: These contexts configures Perl handlers for the location they appear in. This will only be used for processing with Perl.
• map: This context is used to set the value of a variable depending on the value of another variable. It provides a mapping of one variable’s values to determine what the second variable should be set to.
• geo: Like the above context, this context is used to specify a mapping. However, this mapping is specifically used to categorize client IP addresses. It sets the value of a variable depending on the connecting IP address.
• types: This context is again used for mapping. This context is used to map MIME types to the file extensions that should be associated with them. This is usually provided with Nginx through a file that is sourced into the main nginx.conf config file.
• charset_map: This is another example of a mapping context. This context is used to map a conversion table from one character set to another. In the context header, both sets are listed and in the body, the mapping takes place.

The Upstream Context

The upstream context is used to define and configure “upstream” servers. This context defines a named pool of servers that Nginx can then proxy requests to. This context will likely be used when you are configuring proxies of various types.

The upstream context should be placed within the http context, outside of any specific server contexts. The general form looks something like this:

# main context
http {
    # http context
    upstream upstream_name {
        # upstream context
        server proxy_server1;
        server proxy_server2;
        . . .
    }
    server {
        # server context
    }
}

The upstream context can then be referenced by name within server or location blocks to pass requests of a certain type to the pool of servers that have been defined. The upstream will then use an algorithm (round-robin by default) to determine which specific server to hand the request to. This context gives our Nginx the ability to do some load balancing when proxying requests.

The Mail Context

Although Nginx is most often used as a web or reverse proxy server, it can also function as a high performance mail proxy server. The mail context is defined within the “main” or “global” context (outside of the http context).

The main function of the mail context is to provide an area for configuring a mail proxying solution on the server. Nginx has the ability to redirect authentication requests to an external authentication server. It can then provide access to POP3 and IMAP mail servers for serving the actual mail data. The mail context can also be configured to connect to an SMTP Relayhost if desired.

# main context
events {
    # events context
}
mail {
    # mail context
}

The If context

The “if” context can be established to provide conditional processing of directives defined within. The if directive in Nginx will execute the instructions contained if a given test returns true.

The problem with using if directive is that the Nginx processing order can very often lead to unexpected results and the only directives that are considered reliably safe to use inside of these contexts are the return and rewrite directives.

Most often, an if will be used to determine whether a rewrite or return is needed:

# main context
http {
    # http context
    server {
        # server context
        location location_match {
            # location context
            if (test_condition) {
                # if context
            }
        }
    }
}

The Limit_except Context

The limit_except context is used to restrict the use of certain HTTP methods within a location context.

If only certain clients should have access to POST content, but everyone should have the ability to read content, you can use a limit_except block to define this requirement:

. . .
# server or location context
location /restricted-write {
    # location context
    limit_except GET HEAD {
        # limit_except context
        allow 192.168.1.1/24;
        deny all;
    }
}

This will apply the directives inside the context when encountering any HTTP methods except those listed in the context header. As a result only clients from 192.168.1.1./24 subnet are allowed to use GET and HEAD methods.