nginx配置,nginx 变量

Aug 9, 2021


前言

nginx是常用的高性能反向代理服务,内置了许多变量,本文转载自:

https://www.javatpoint.com/nginx-variables

原文

Variables are the natural part of the programming languages. These are just containers holding various values in imperative languages like Perl, C/C++, Bourne shell, Perl. And values can be strings like “hello world”, numbers like “3.14”, or even complicated things like references to arrays or hash tables in those languages.

For the Nginx configuration language, however, variables can hold only one type of values, i.e. strings. But there is an interesting exception: the 3rd party module ngx_array_var extends Nginx variables to contain arrays, but it is implemented by encoding a C pointer as a binary string value behind the scene.

Variable syntax

Consider that our nginx.conf configuration file which has the following line:

set $a “hello world”;

Here, we assign a value to the variable “$a” through the set configuration directive which is coming from the standard nginx_rewrite module. And here we assign the string value “hello world” to “$a”.

From the above example, we can see that the Nginx variable name takes a dollar sign ($) in front of it. Hence, we can say that whenever we want to add a reference to an nginx variable in the configuration file, we must add a dollar ($) prefix.

Let’s see another simple example,

set $a hello;
set $b “$a, $a”;

From the above example, we can see that variable $a is used to construct the value for the variable $b. So after these two directives complete execution, the value of $a is “hello”, and $b is “hello, hello”. This technique is called “variable interpolation”.

Let’s see the list of variables in Nginx:

Variable Description
$ancient_browser This variable is used to equal the value set by the ancient_browser_value directive, if a browser was identified as ancient.
$arg_name Name of the argument in the request line.
$args List of arguments on the request line.
$binary_remote_addr (ngx_http_core_module) Client address in the form of binary. Length of value is always 4 bytes for IP4 addresses or 16 bytes for IPv6 addresses.
$binary_remote_addr (ngx_stream_core_module) Client address in the form of binary. Length of value is always 4 bytes for IP4 addresses or 16 bytes for IPv6 addresses.
$body_bytes_sent Number of bytes sent to the client, not counts the response header.
$bytes_received Number of bytes received from a client.
$bytes_sent (ngx_http_core_module) Number of bytes sent to a client.
$bytes_sent (ngx_http_log_module) Number of bytes sent to a client.
$bytes_sent (ngx_stream_core_module) Number of bytes sent to a client.
$connection (ngx_http_core_module) connection serial number
$connection (ngx_http_log_module) connection serial number
$connection (ngx_stream_core_module) connection serial number
$connection_requests (ngx_http_core_module) Current number of requests made via connection.
$connection_requests (ngx_http_log_module) Current number of requests made via connection.
$connections_active Same as Active connections value
$connections_reading Same as Reading value
$connections_waiting Same as the Waiting value
$connections_writing Same as the writing value.
$content_length "Content length" request header field.
$content_type "Content type" request header field
$cookie_name The name of cookie
$date_gmt Current time in GMT (Greenwich Mean Time). To set the format, use the config command with timefmt parameter.
$date_local Current time in the local time zone. To set the format, use the config command with timefmt parameter.
$document_root Value of root or alias directive for the current request.
$document_uri It is same as $uri.
$fastcgi_path_info When using the fastcgi_split_path_info directive, the $fastcgi_script_name variable equals the value of the first capture set by the directive. And the value of second capture set by the fastcgi_split_path_info directive. This variable is used to set the PATH_INFO parameter.
$fastcgi_script_name Request URI (Uniform Resource Identifier) or, if a URI ends with a slash, request URI with an index file name configured by the fastcgi_index directive appended to it.
$geoip_area_code (ngx_http_geoip_module) Telephone area code (US only). This variable may contain some information which is outdated since the corresponding database field is deprecated.
$geoip_area_code (ngx_stream_geoip_module) Telephone area code (US only). This variable may contain outdated information since the corresponding database field is deprecated.
$geoip_city (ngx_http_geoip_module) City name, e.g. "Washinton", "Moscow".
$geoip_city (ngx_stream_geoip_module) City name, e.g. "Washinton", "Moscow".
$geoip_city_continent_code (ngx_http_geoip_module) Continent code in two letters. For example, "NA", "EU".
$geoip_city_continent_code (ngx_stream_geoip_module) Continent code in two letters. For example, "NA", "EU".
$geoip_city_country_code (ngx_http_geoip_module) Continent code in two letters. For example, "NA", "EU".
$geoip_city_country_code (ngx_http_geoip_module) Country code in two letters. For example, "RU", "US".
$geoip_city_country_code (ngx_stream_geoip_module) Country code in two letters. For example, "RU", "US".
$geoip_city_country_code3 (ngx_http_geoip_module) Country code in three letters. For example, "RUS", "USA".
$geoip_city_country_code3 (ngx_stream_geoip_module) Country code in three letters. For example, "RUS", "USA".
$geoip_city_country_name (ngx_http_geoip_module) Name of the country. For example, "India", "United States".
$geoip_city_country_name (ngx_stream_geoip_module) Name of the country. For example, "India", "United States".
$geoip_country_code (ngx_http_geoip_module) Country code in two letters. For example, "RU", "US".
$geoip_country_code (ngx_stream_geoip_module) Country code in two letters. For example, "RU", "US".
$geoip_country_code3 (ngx_http_geoip_module) Country code in three letters. For example, "RUS", "USA".
$geoip_country_code3 (ngx_stream_geoip_module) Country code in three letters. For example, "RUS", "USA".
$geoip_country_name (ngx_http_geoip_module) Name of the country. For example, "India", "United States".
$geoip_country_name (ngx_stream_geoip_module) Name of the country. For example, "India", "United States".
$geoip_dma_code (ngx_http_geoip_module) It is the DMA (Designated Market Area) code or metro code in US, according to the geo-targeting in Google AdWords API.
$geoip_dma_code (ngx_stream_geoip_module) It is the DMA (Designated Market Area) code or metro code in US, according to the geo-targeting in Google AdWords API.
$geoip_latitude (ngx_http_geoip_module) Latitude.
$geoip_latitude (ngx_stream_geoip_module) Latitude.
$geoip_longitude (ngx_http_geoip_module) Longitude
$geoip_longitude (ngx_stream_geoip_module) Longitude
$geoip_org (ngx_http_geoip_module) Name of the organization. For example "University of California".
$geoip_org (ngx_stream_geoip_module) Name of the organization. For example "University of California".
$geoip_postal_code (ngx_http_geoip_module) Postal code.
$geoip_postal_code (ngx_stream_geoip_module) Postal code.
$geoip_region (ngx_http_geoip_module) The name of the region (Province, region, state, federal land, territory) for example, for Moscow City, DC.
$geoip_region (ngx_stream_geoip_module) The name of the region (Province, region, state, federal land, territory) for example, for Moscow City, DC.
$geoip_region_name (ngx_http_geoip_module) Country region name ((Province, region, state, federal land, territory), for example "Moscow City", "District of Columbia".
$geoip_region_name (ngx_stream_geoip_module) Country region name ((Province, region, state, federal land, territory), for example "Moscow City", "District of Columbia".
$gzip_ratio It is the achieved compression ratio, computed as the ratio between the original and compressed response sizes.
$host Host name from the request line, host name form the Host request header field, or the server name matching a request.
$hostname (ngx_http_core_module) Host name.
$hostname (ngx_stream_core_module) Host name.
$http2 Negotiated protocol identifier: h2 for HTTP/2 over TLS, h2c for HTTP/2 over clear text TCP, or an empty string otherwise.
$http_name It is the arbitrary request header field: the last part of a variable name is the field name which is converted to lower case with dashes replaced by underscores.
$https If connection operates in SSL mode then it is "on", or an empty string otherwise.
$invalid_referer If the "Referer" request header field value is considered valid, then the string is empty, otherwise 1.
$is_args "?" if a request line has arguments, or an empty string otherwise.
$jwt_claim_name It returns the value of a specified JWT (JSON Web Token) claim.
$jwt_header_name Returns the value of a specified JOSE (JavaScript Object Signing and Encryption) header.
$limit_rate Setting this variable enables response rate limiting.
$memcached_key Defines a key for obtaining response from a memcached server.
$modern_browser Equals the value set by the modern_browser_value directive, if a browser was identified as modern.
$msec (ngx_http_core_module) Current time in seconds with the ms (milliseconds) resolution.
$msec (ngx_http_log_module) Time in seconds with a milliseconds resolution at the time of the log write.
$msec (ngx_stream_core_module) Current time in seconds with the ms (milliseconds) resolution.
$msie Equals 1 if a browser was identified as MSIE (Microsoft Internet Explorer) of any version.
$nginx_version (ngx_http_core_module) Shows the nginx version
$nginx_version (ngx_stream_core_module) Nginx version.
$pid (ngx_http_core_module) PID (Process ID) of the worker process.
$pid (ngx_stream_core_module) PID (Process ID) of the worker process.
$pipe (ngx_http_core_module) "p" if request was pipelined, "." Otherwise.
$pipe (ngx_http_log_module) "p" if request was pipelined, "." Otherwise.
$protocol Protocol used to communicate with the client: UDP or TCP.
$proxy_add_x_forwarded_for the "X-Forwarded-For" client request header field with the $remote_addr variable appended to it, separated by a comma. If the "X-Forwarded-For" field is not present in the client request header, the $proxy_add_x_forwarded_for variable is equal to the $remote_addr variable.
$proxy_host Name and port of the proxied server as specified in the proxy_pass directive.
$proxy_port Port of the proxied server as specified in the proxy_pass directive, or the default port of the protocol.
$proxy_protocol_addr (ngx_http_core_module) Client address from the PROXY protocol header, or an empty string otherwise. The PROXY protocol must be enabled before. This can be done by setting the proxy protocol parameter in the listen directive.
$proxy_protocol_addr (ngx_stream_core_module) Client address from the PROXY protocol header, or an empty string otherwise. The PROXY protocol must be enabled before. This can be done by setting the proxy protocol parameter in the listen directive.
$proxy_protocol_port (ngx_http_core_module) Client address from the PROXY protocol header, or an empty string otherwise. The PROXY protocol must be enabled before. This can be done by setting the proxy protocol parameter in the listen directive.
$proxy_protocol_port (ngx_stream_core_module) Client address from the PROXY protocol header, or an empty string otherwise. The PROXY protocol must be enabled before. This can be done by setting the proxy protocol parameter in the listen directive.
$query_string Same as $args
$realip_remote_addr (ngx_http_realip_module) It is used to keep the original client address.
$realip_remote_addr (ngx_stream_realip_module) It is used to keep the original client address.
$realip_remote_port (ngx_http_realip_module) It is used to keep the original client address.
$realip_remote_port (ngx_stream_realip_module) It is used to keep the original client address.
$realpath_root An absolute path name corresponding to the alias or root directive's value for the current request, with all symbolic links resolved to real paths.
$remote_addr (ngx_http_core_module) Client Address
$remote_addr (ngx_stream_core_module) Client Address
$remote_port (ngx_http_core_module) Client Port
$remote_port (ngx_stream_core_module) Client port
$remote_user User name supplied with the Basic authentication.
$request Full original request line.
$request_body The variable's value is made available in locations processed by the proxy_pass, and scgi_pass directive when the request body was read to a memory_buffer.
$request_body_file Name of a temporary file with the request body.
$request_completion Value is "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_id Unique request identifier generated from 16 random bytes, in hexadecimal.
$request_length (ngx_http_core_module) Request length (request line, request body, and header).
$request_length (ngx_http_log_module) Request length (request line, request body, and header).
$request_method Request method. Usually "GET" or "POST".
$request_time (ngx_http_core_module) Request processing time in seconds with a milliseconds resolution; time elapsed since the first bytes were read from the client.
$request_time (ngx_http_log_module) Request processing time in seconds with a milliseconds resolution; time elapsed between the first bytes were read from the client and the log write after the last bytes were sent to the client.
$request_uri Full original request URI (Uniform Resource Identifier) with arguments.
$scheme Request scheme which may be http or https
$secure_link Shows the status a link check and the value depends on the selected operation mode.
$secure_link_expires The lifetime of a link passed in a request;
$sent_http_name It is the arbitrary response header field; the last part of a variable name is the name of the field converted to lower case with dashes replaced by underscores.
$sent_trailer_name Arbitrary field sent at the end of the response; the last part of a variable name is the name of the field converted to lower case with dashes replaced by underscores.
$server_addr (ngx_http_core_module) Server's address which accepted a request. To compute the value of this variable requires a system call.
$server_addr (ngx_stream_core_module) Server's address which accepted a request. To compute the value of this variable requires a system call.
$server_name Server's name which accepted a request.
$server_port (ngx_http_core_module) Server's port which accepted a request.
$server_port (ngx_stream_core_module) Server's port which accepted a connection.
$server_protocol It is a request protocol, usually HTTP/1.0, HTTP/1.1 or HTTP/2.0.  
$session_log_binary_id Current session ID in the form of binary.
$session_log_id Current session ID.
$session_time Session duration in seconds with a milliseconds resolution.
$slice_range The current slice range in HTTP byte range format. E.g. bytes=0-1048575
$spdy SPDY protocol version for SPDY(pronounced as speedy) connections, or an empty string otherwise.
$spdy_request_priority Request priority for SPDY (pronounced as speedy) connections or an empty string otherwise.
$ssl_cipher (ngx_http_ssl_module) Returns the string of ciphers used for an established SSL (Secure Sockets Layer) connection.
$ssl_cipher (ngx_stream_ssl_module) Returns the string of ciphers used for an established SSL (Secure Sockets Layer) connection.
$ssl_ciphers (ngx_http_ssl_module) It will return the list of ciphers supported by the client. Here, known ciphers are listed by names and unknown are shown in hexadecimal, for example, AES128-SHA:AES256-SHA:0x00ff
$ssl_ciphers (ngx_stream_ssl_module) It will return the list of ciphers supported by the client. Here, known ciphers are listed by names and unknown are shown in hexadecimal, for example, AES128-SHA:AES256-SHA:0x00ff
$ssl_client_cert (ngx_http_ssl_module) It will return the client certificate in the PEM (Privacy Enhanced Mail) for an established SSL connection, with each line except the 1st prepended with the tab character.
$ssl_client_cert (ngx_stream_ssl_module) It will return the client certificate in the PEM (Privacy Enhanced Mail) for an established SSL connection, with each line except the 1st prepended with the tab character.
$ssl_client_escaped_cert It will return the client certificate in the PEM (Privacy Enhanced Mail) for an established SSL connection
$ssl_client_fingerprint (ngx_http_ssl_module) It will return the SHA1 (Secure Hash Algorithm) fingerprint of the client certificate for an established SSL connection.
$ssl_client_fingerprint (ngx_stream_ssl_module) It will return the SHA1 (Secure Hash Algorithm) fingerprint of the client certificate for an established SSL connection.
$ssl_client_i_dn (ngx_http_ssl_module) Returns the "issuer DN" (where DN is Distinguished name) string of the client certificate for an established SSL connection according to RFC 2253.
$ssl_client_i_dn (ngx_stream_ssl_module) Returns the "issuer DN" (where DN is Distinguished name) string of the client certificate for an established SSL connection according to RFC 2253.
$ssl_client_i_dn_legacy Returns the "issuer DN" (where DN is Distinguished name) string of the client certificate for an established SSL connection.
$ssl_client_raw_cert (ngx_http_ssl_module) It will return the client certificate in the PEM (Privacy Enhanced Mail) format for an established SSL connection.
$ssl_client_raw_cert (ngx_stream_ssl_module) It will return the client certificate in the PEM (Privacy Enhanced Mail) format for an established SSL connection.
$ssl_client_s_dn (ngx_http_ssl_module) Returns the "subject DN" (where DN is Distinguished name) string of the client certificate for an established SSL connection according to RFC2253.
$ssl_client_s_dn (ngx_stream_ssl_module) Returns the "subject DN" (where DN is Distinguished name) string of the client certificate for an established SSL connection according to RFC2253.
$ssl_client_s_dn_legacy Returns the "subject DN" (where DN is Distinguished name) string of the client certificate for an established SSL connection.
$ssl_client_serial (ngx_http_ssl_module) It will return the serial number of the client certificate for an established SSL connection.
$ssl_client_serial (ngx_stream_ssl_module) It will return the serial number of the client certificate for an established SSL connection.
$ssl_client_v_end (ngx_http_ssl_module) It will return the end date of the client certificate.
$ssl_client_v_end (ngx_stream_ssl_module) It will return the end date of the client certificate.
$ssl_client_v_remain (ngx_http_ssl_module) It will return the number of days until the client certificate expires.
$ssl_client_v_remain (ngx_stream_ssl_module) It will return the number of days until the client certificate expires.
$ssl_client_v_start (ngx_http_ssl_module) It will return the start date of the client certificate.
$ssl_client_v_start (ngx_stream_ssl_module) It will return the start date of the client certificate.
$ssl_client_verify (ngx_http_ssl_module) It will return the result of client certificate verification: "SUCCESS", "FAILD:reason", and "NONE" if a certificate was not present.
$ssl_client_verify (ngx_stream_ssl_module) It will return the result of client certificate verification: "SUCCESS", "FAILD:reason", and "NONE" if a certificate was not present.
$ssl_curves (ngx_http_ssl_module) Returns the list of curves supported by the client. All known curves are listed by names, and unknown are shown in hexadecimal, for example: 0x001d:prime256v1:secp521r1:secp384r1
$ssl_curves (ngx_stream_ssl_module) Returns the list of curves supported by the client. All known curves are listed by names, and unknown are shown in hexadecimal, for example: 0x001d:prime256v1:secp521r1:secp384r1
$ssl_early_data It will return 1 if TLS 1.3 early data is used and the handshake is not complete otherwise return empty.
$ssl_preread_alpn_protocols It returns the list of protocols advertised by the client through ALPN and the values are separated by commas.
$ssl_preread_protocol The highest SSL (Secure Sockets layer) protocol version supported by the client.
$ssl_preread_server_name Returns the name of the server requested through SNI (Sever Name Indication).
$ssl_protocol (ngx_http_ssl_module) It will return the protocol of an established SSL connection.
$ssl_protocol (ngx_stream_ssl_module) It will return the protocol of an established SSL connection.
$ssl_server_name (ngx_http_ssl_module) Returns the name of the server requested through SNI (Server Name Indication).
$ssl_server_name (ngx_stream_ssl_module) Returns the name of the server requested through SNI (Server Name Indication).
$ssl_session_id (ngx_http_ssl_module) It will return the session identifier of an established SSL connection.
$ssl_session_id (ngx_stream_ssl_module) It will return the session identifier of an established SSL connection.
$ssl_session_reused (ngx_http_ssl_module) Returns "r" if an SSL session was reused or "." Otherwise.
$ssl_session_reused (ngx_stream_ssl_module) Returns "r" if an SSL session was reused or "." Otherwise.
$status (ngx_http_core_module) Response status.
$status (ngx_http_log_module) Response status.
$status (ngx_stream_core_module) Session status, which can be one of the following: 200: Session completed successfully. 400: Data of client could not be parsed. 403: access forbidden. 500: internal server error. 502: bad gateway. 503: service unavailable.
$tcpinfo_rtt Displays the information about the client TCP connection, available on systems that support the TCP_INFO socket option.
$tcpinfo_rttvar Displays the information about the client TCP connection, available on systems that support the TCP_INFO socket option.
$tcpinfo_snd_cwnd Displays the information about the client TCP connection, available on systems that support the TCP_INFO socket option.
$tcpinfo_rcv_space Displays the information about the client TCP connection, available on systems that support the TCP_INFO socket option.
$time_iso8601 (ngx_http_core_module) Shows the Local time in the standard format of ISO 8601.
$time_iso8601 (ngx_http_log_module) Shows the Local time in the standard format of ISO 8601.
$time_iso8601 (ngx_stream_core_module) Shows the Local time in the standard format of ISO 8601.
$time_local (ngx_http_core_module) Shows the Local time in the format of common log
$time_local (ngx_http_log_module) Shows the local time in the format of common log.
$time_local (ngx_stream_core_module) Shows the local time in the format of common log.
$uid_got The name of the cookie and received client identifier.
$uid_reset If the variable is set to a ?non-empty' string means that is not ?0', then the client identifier are reset. The special value log additionally leads to the output of messages about the reset identifiers to the error_log.
$uid_set The name of the cookie and sent the client identifier.
$upstream_addr (ngx_http_upstream_module) It will keep the IP address and port, or the path to the UNIX-domain socket of the upstream server. If several servers were contacted during request processing, then their addresses are separated by commas.
$upstream_addr (ngx_stream_upstream_module) It will keep the IP address and port, or the path to the UNIX-domain socket of the upstream server. If several servers were contacted during request processing, then their addresses are separated by commas.
$upstream_bytes_received (ngx_http_upstream_module) Number of bytes received from an upstream stream server. Values from several connections are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable.
$upstream_bytes_received (ngx_stream_upstream_module) Number of bytes received from an upstream stream server. Values from several connections are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable.
$upstream_bytes_sent (ngx_http_upstream_module) Number of bytes sent to an upstream stream server. Values from several connections are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable.
$upstream_bytes_sent (ngx_stream_upstream_module) Number of bytes sent to an upstream stream server. Values from several connections are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable.
$upstream_cache_status It will keep the status of accessing a response cache. The status can be either "BYPASS", "MISS", "EXPIRED", "STALE", "REVALIDATED", "UPDATING" or "HIT".
$upstream_connect_time (ngx_http_upstream_module) It is used to keep the time spent on establishing a connection with the upstream server (1.9.1); the time is kept in seconds with millisecond resolution. In case of SSL, adds time spent on handshake. Times of several connections are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable.
$upstream_connect_time (ngx_stream_upstream_module) Keeps the time to connect to the upstream server; the time is kept in seconds with milliseconds resolution. Times of several connections are separated by commas (,) like addresses in the $upstream_addr variable.
$upstream_cookie_name Cookie with the defined name sent by the upstream server in the Set-Cookie response header field. Only the cookies from the response of the last server are saved.
$upstream_first_byte_time Time to receive the first byte of data. The time is kept in seconds with millisecond resolution. Times of multiple connections are separated by commas (,) like addresses in the $upstream_addr variable.
$upstream_header_time It is used to keep the time spent on receiving header from the upstream server. Times of multiple connections are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable.
$upstream_http_name Keep the server response header fields.
$upstream_queue_time It is used to keep time the request spent in the upstream queue; the time is kept in seconds with milliseconds resolution. Times of multiple connections are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable.
$upstream_response_length It is used to keep the length of the response obtained from the upstream server. The length is kept in bytes. Lengths of multiple responses are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable.
$upstream_response_time It is used to keep time spent on receiving the response from the upstream server; the time is kept in seconds with milliseconds resolution. Times of several connections are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable.
$upstream_session_time Session duration in seconds with milliseconds resolution. Times of several connections are separated by commas (,) like addresses in the $upstream_addr variable.
$upstream_status It is used to keep the status code of the response obtained from the upstream server. Status codes of the several responses are separated by commas (,) and colons (:) like addresses in the $upstream_addr variable. If the server can't be selected, the variable keeps the 502 (Bad Gateway) status code.
$upstream_trailer_name It is used to keep the field from the end of the response obtained from the upstream server.
$uri Current URI in request, normalized. We can change the value of the $uri during request processing, e.g. when doing internal redirects, or when using index files.