Understanding the Nginx Configuration File Structure and Configuration Contexts | Digit... - 0 views
-
discussing the basic structure of an Nginx configuration file along with some guidelines on how to design your files
-
/etc/nginx/nginx.conf
-
In Nginx parlance, the areas that these brackets define are called "contexts" because they contain configuration details that are separated according to their area of concern
- ...50 more annotations...
-
contexts can be layered within one another
-
if a directive is valid in multiple nested scopes, a declaration in a broader context will be passed on to any child contexts as default values.
-
The children contexts can override these values at will
-
Nginx will error out on reading a configuration file with directives that are declared in the wrong context.
-
The most general context is the "main" or "global" context
-
Any directive that exist entirely outside of these blocks is said to inhabit the "main" context
-
The main context represents the broadest environment for Nginx configuration.
-
The "events" context is contained within the "main" context. It is used to set global options that affect how Nginx handles connections at a general level.
-
Nginx uses an event-based connection processing model, so the directives defined within this context determine how worker processes should handle connections.
-
the connection processing method is automatically selected based on the most efficient choice that the platform has available
-
a worker will only take a single connection at a time
-
When configuring Nginx as a web server or reverse proxy, the "http" context will hold the majority of the configuration.
-
The http context is a sibling of the events context, so they should be listed side-by-side, rather than nested
-
fine-tune the TCP keep alive settings (keepalive_disable, keepalive_requests, and keepalive_timeout)
-
The "server" context is declared within the "http" context.
-
multiple declarations
-
each instance defines a specific virtual server to handle client requests
-
Each client request will be handled according to the configuration defined in a single server context, so Nginx must decide which server context is most appropriate based on details of the request.
-
listen: The ip address / port combination that this server block is designed to respond to.
-
server_name: This directive is the other component used to select a server block for processing.
-
"Host" header
-
configure files to try to respond to requests (try_files)
-
issue redirects and rewrites (return and rewrite)
-
set arbitrary variables (set)
-
Location contexts share many relational qualities with server contexts
-
multiple location contexts can be defined, each location is used to handle a certain type of client request, and each location is selected by virtue of matching the location definition against the client request through a selection algorithm
-
Location blocks live within server contexts and, unlike server blocks, can be nested inside one another.
-
While server contexts are selected based on the requested IP address/port combination and the host name in the "Host" header, location blocks further divide up the request handling within a server block by looking at the request URI
-
The request URI is the portion of the request that comes after the domain name or IP address/port combination.
-
New directives at this level allow you to reach locations outside of the document root (alias), mark the location as only internally accessible (internal), and proxy to other servers or locations (using http, fastcgi, scgi, and uwsgi proxying).
-
These can then be used to do A/B testing by providing different content to different hosts.
-
configures Perl handlers for the location they appear in
-
set the value of a variable depending on the value of another variable
-
used to map MIME types to the file extensions that should be associated with them.
-
this context defines a named pool of servers that Nginx can then proxy requests to
-
The upstream context should be placed within the http context, outside of any specific server contexts.
-
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.
-
function as a high performance mail proxy server
-
The mail context is defined within the "main" or "global" context (outside of the http context).
-
Nginx has the ability to redirect authentication requests to an external authentication server
-
the if directive in Nginx will execute the instructions contained if a given test returns "true".
-
Since Nginx will test conditions of a request with many other purpose-made directives, if should not be used for most forms of conditional execution.
-
The limit_except context is used to restrict the use of certain HTTP methods within a location context.
-
The result of the above example is that any client can use the GET and HEAD verbs, but only clients coming from the 192.168.1.1/24 subnet are allowed to use other methods.
-
Many directives are valid in more than one context
-
it is usually best to declare directives in the highest context to which they are applicable, and overriding them in lower contexts as necessary.
-
Declaring at higher levels provides you with a sane default
-
Nginx already engages in a well-documented selection algorithm for things like selecting server blocks and location blocks.
-
instead of relying on rewrites to get a user supplied request into the format that you would like to work with, you should try to set up two blocks for the request, one of which represents the desired method, and the other that catches messy requests and redirects (and possibly rewrites) them to your correct block.
-
incorrect requests can get by with a redirect rather than a rewrite, which should execute with lower overhead.