Links
- Browse sources (trac)
- Articles
- See page 4 of How to set up a safe and secure Web server: Safety and Security
- Has some additional nginx settings.
- See page 4 of How to set up a safe and secure Web server: Safety and Security
- calomel.org: Secure configs
- Very detailed guide. to read
- agentzh's Tutorials
- Command Line
- Modules
- ngx_http_core_module
- alias, default_type, disable_symlinks, error_page, etag, http, if_modified_since, ignore_invalid_headers, internal, keepalive_requests, limit_except, limit_rate, lingering_close, listen, location, log_subrequest, merge_slashes, msie_padding, port_in_redirect, recursive_error_pages, reset_timedout_connection, resolver, root, satisfy, send_timeout, sendfile, sendfile_max_chunk, server, server_name, server_name_in_redirect, server_tokens, try_files, types, underscores_in_headers,
- Embedded Variables
- uwsgi
- Secure Link
- Google Perftools
- FLV
- SSL
- Stub Status: View server statistics
- ngx_http_autoindex_module
- ngx_fancyindex (github)
- ngx_http_rewrite_module
- ngx_set_misc
- ngx_http_core_module
- Configuration
- Nginx Primer
- Core directives
- Phases
- Pitfalls
- Fyi, the add_header
directive only adds the specified field to a
response header provided that the response code
equals
200
,201
,204
,206
,301
,302
,303
,304
, or307
. Use the more_set_headers directive instead.
- Fyi, the add_header
directive only adds the specified field to a
response header provided that the response code
equals
- The configuration file is an inheriting-hierarchy.
- There are 3 hierarchies / blocks.
- http » server » location
- The server typically refers / deals with virtual host type stuff.
- The location typically deals with URI stuff.
- There are two special locations.
- An event block and
- the root (which the event block and the http block reside in.)
- These contain only a minor amount of directives.
map
directive- root
- alias
- error_page
- try_files
- internal
- server {...}
- location
- Named locations,
@name
, are special.- They are intended only to process internally redirected requests and are not used during normal processing.
- They are passed query parameters.
- Regular locations work without query params.
- Only one location block will be run.
- Use
=
as first parameter to indicate an exact match – this is faster. - Use
^~
to indicate a prefix string match, that if matched, terminates further searching.- Otherwise, the string match is used only if not other regex match wins.
- Use
~
to indicate regex matching and~*
to indicate case inseneitive regex matching. - Comparison are always made against decoded URIs.
- To match "/images/%20/test" you must use "/images/ /test".
- Named locations,
- Rewrites
- They are internal by default.
- This means that they won’t change the URI the browser sees.
- If you specify the “redirect” or “permanent”
rewrite flag or if you rewrite to an absolute
URL including the
http://
part, then it becomes an external redirect.
- proxy_redirect
- WebSocket proxying
- Examples
- Full Example 1
- Full Example 2
- Python via UWSGI
- Reverse Proxy with caching
- Reverse Proxy | nginx admin-guide
- Passing request headers: By default, NGINX
redefines two header fields in proxied
requests, “Host” and “Connection”, and
eliminates the header fields whose values
are empty strings. “Host” is set to the
$proxy_host variable, and “Connection” is
set to close.
- To prevent a header field from being passed to the proxied server, set it to an empty string.
- Buffering: By default, proxy_buffering
is set to
on
.- If you're worried about nginx resources,
set it to
off
. If you want nginx to take the load off of your backends, especially with slow clients, then set it toon
.
- If you're worried about nginx resources,
set it to
- Passing request headers: By default, NGINX
redefines two header fields in proxied
requests, “Host” and “Connection”, and
eliminates the header fields whose values
are empty strings. “Host” is set to the
$proxy_host variable, and “Connection” is
set to close.
- limit_rate
- Optimizing Nginx
- Debug nginx
- FAQ
- Cookbook
- Stream of data with nginx
- Set
uwsgi_buffering off;
if your app is generating a stream of data.
- Set
- github repo of sample configs: h5bp/server-configs-nginx
- Performance / Best Practices
Nginx directive execution order
- post-read (e.g. ngx_realip module)
- server-rewrite (e.g. set, ngx_rewrite in server section)
- find-config (can't register custom handlers)
- matches
location
directives. - Note: This means that if you use a module in a
location directive, then those module directives can
only affect the following phases. So, for example,
if you use
ngx_realip
in a server directive, its post-read handler will do the right thing and set$remote_addr
correctly. However, if you don't specify it in a server directive but in a location directive, then the first chance that it can get it is therewrite
phase. Sinceset
happens in the rewrite phase and the realip module can't be sure if it runs before or after the set, it instead runs in thepreaccess
phase for consistency/predictability.
- matches
- rewrite (e.g. set and ngx_rewrite in the location directive.)
- post-rewrite (can't register custom handlers)
ngx_rewrite
in the rewrite phase only set's up the config to perform the redirect. The actual redirect happens in this phase where nginx takes the final result of the rewrite phase and jumps to the find-config if needed.
- preaccess (e.g. ngx_limit_req and ngx_limit_zone)
- access
- post-access (can't register custom handlers)
- runs the satisfy directive.
- try-files
- content
- log
Embedded Variables
Name | Description |
---|---|
$arg_ name |
argument _name_ in the request line |
$args |
arguments in the request line |
$binary_remote_addr |
client address in a binary form, value’s length is always 4 bytes |
$body_bytes_sent |
number of bytes sent to a client, not counting the response header; this variable is compatible with the “%B ” parameter of the mod_log_config Apache module |
$bytes_sent |
number of bytes sent to a client (1.3.8, 1.2.5) |
$connection |
connection serial number (1.3.8, 1.2.5) |
$connection_requests |
current number of requests made through a connection (1.3.8, 1.2.5) |
$content_length |
“Content-Length” request header field |
$content_type |
“Content-Type” request header field |
$cookie_ name |
the _name_ cookie |
$document_root |
root or alias directive’s value for the current request |
$document_uri |
same as $uri |
$host |
in this order of precedence: host name from the request line, or host name from the “Host” request header field, or the server name matching a request |
$hostname |
host name |
$http_ name |
arbitrary request header field; the last part of a variable name is the field name converted to lower case with dashes replaced by underscores |
$https |
“on ” if connection operates in SSL mode, or an empty string otherwise |
$is_args |
“? ” if a request line has arguments, or an empty string otherwise |
$limit_rate |
setting this variable enables response rate limiting; see limit_rate |
$msec |
current time in seconds with the milliseconds resolution (1.3.9, 1.2.6) |
$nginx_version |
nginx version |
$pid |
PID of the worker process |
$pipe |
“p ” if request was pipelined, “. ” otherwise (1.3.12, 1.2.7) |
$proxy_protocol_addr |
client address from the PROXY protocol header, or an empty string otherwise (1.5.12). The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the listendirective. |
$query_string |
same as $args |
$realpath_root |
an absolute pathname corresponding to the root or alias directive’s value for the current request, with all symbolic links resolved to real paths |
$remote_addr |
client address |
$remote_port |
client port |
$remote_user |
user name supplied with the Basic authentication |
$request |
full original request line |
$request_body |
request body. The variable’s value is made available in locations processed by the proxy_pass and fastcgi_passdirectives. |
$request_body_file |
name of a temporary file with the request body. At the end of processing, the file needs to be removed. To always write the request body to a file,client_body_in_file_only needs to be enabled. When the name of a temporary file is passed in a proxied request or in a request to a FastCGI server, passing the request body should be disabled by theproxy_pass_request_body off and fastcgi_pass_request_body off directives, respectively. |
$request_completion |
“OK ” if a request has completed, or an empty string otherwise |
$request_filename |
file path for the current request, based on the root or alias directives, and the request URI |
$request_length |
request length (including request line, header, and request body) (1.3.12, 1.2.7) |
$request_method |
request method, usually “GET ” or “POST ” |
$request_time |
request processing time in seconds with a milliseconds resolution (1.3.9, 1.2.6); time elapsed since the first bytes were read from the client |
$request_uri |
full original request URI (with arguments) |
$scheme |
request scheme, “http ” or “https ” |
$sent_http_``_name_ |
arbitrary response header field; the last part of a variable name is the field name converted to lower case with dashes replaced by underscores |
$server_addr |
an address of the server which accepted a request. Computing a value of this variable usually requires one system call. To avoid a system call, the listendirectives must specify addresses and use the bind parameter. |
$server_name |
name of the server which accepted a request |
$server_port |
port of the server which accepted a request |
$server_protocol |
request protocol, usually “HTTP/1.0 ” or “HTTP/1.1 ” |
$status |
response status (1.3.2, 1.2.2) |
$tcpinfo_rtt ,$tcpinfo_rttvar ,$tcpinfo_snd_cwnd ,$tcpinfo_rcv_space |
information about the client TCP connection; available on systems that support the TCP_INFO socket option |
$time_iso8601 |
local time in the ISO 8601 standard format (1.3.12, 1.2.7) |
$time_local |
local time in the Common Log Format (1.3.12, 1.2.7) |
$uri |
current URI in request, normalized The value of $uri may change during request processing, e.g. when doing internal redirects, or when using index files. |