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:

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,

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:

VariableDescription
$ancient_browserThis variable is used to equal the value set by the ancient_browser_value directive, if a browser was identified as ancient.
$arg_nameName of the argument in the request line.
$argsList 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_sentNumber of bytes sent to the client, not counts the response header.
$bytes_receivedNumber 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_activeSame as Active connections value
$connections_readingSame as Reading value
$connections_waitingSame as the Waiting value
$connections_writingSame as the writing value.
$content_length"Content length" request header field.
$content_type"Content type" request header field
$cookie_nameThe name of cookie
$date_gmtCurrent time in GMT (Greenwich Mean Time). To set the format, use the config command with timefmt parameter.
$date_localCurrent time in the local time zone. To set the format, use the config command with timefmt parameter.
$document_rootValue of root or alias directive for the current request.
$document_uriIt is same as $uri.
$fastcgi_path_infoWhen 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_nameRequest 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_ratioIt is the achieved compression ratio, computed as the ratio between the original and compressed response sizes.
$hostHost 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.
$http2Negotiated protocol identifier: h2 for HTTP/2 over TLS, h2c for HTTP/2 over clear text TCP, or an empty string otherwise.
$http_nameIt 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.
$httpsIf connection operates in SSL mode then it is "on", or an empty string otherwise.
$invalid_refererIf 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_nameIt returns the value of a specified JWT (JSON Web Token) claim.
$jwt_header_nameReturns the value of a specified JOSE (JavaScript Object Signing and Encryption) header.
$limit_rateSetting this variable enables response rate limiting.
$memcached_keyDefines a key for obtaining response from a memcached server.
$modern_browserEquals 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.
$msieEquals 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.
$protocolProtocol used to communicate with the client: UDP or TCP.
$proxy_add_x_forwarded_forthe "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_hostName and port of the proxied server as specified in the proxy_pass directive.
$proxy_portPort 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_stringSame 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_rootAn 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_userUser name supplied with the Basic authentication.
$requestFull original request line.
$request_bodyThe 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_fileName of a temporary file with the request body.
$request_completionValue is "OK" if a request has completed, or an empty string otherwise.
$request_filenameFile path for the current request, based on the root or alias directives, and the request URI.
$request_idUnique 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_methodRequest 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_uriFull original request URI (Uniform Resource Identifier) with arguments.
$schemeRequest scheme which may be http or https
$secure_linkShows the status a link check and the value depends on the selected operation mode.
$secure_link_expiresThe lifetime of a link passed in a request;
$sent_http_nameIt 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_nameArbitrary 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_nameServer'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_protocolIt is a request protocol, usually HTTP/1.0, HTTP/1.1 or HTTP/2.0.  
$session_log_binary_idCurrent session ID in the form of binary.
$session_log_idCurrent session ID.
$session_timeSession duration in seconds with a milliseconds resolution.
$slice_rangeThe current slice range in HTTP byte range format. E.g. bytes=0-1048575
$spdySPDY protocol version for SPDY(pronounced as speedy) connections, or an empty string otherwise.
$spdy_request_priorityRequest 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_certIt 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_legacyReturns 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_legacyReturns 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_dataIt will return 1 if TLS 1.3 early data is used and the handshake is not complete otherwise return empty.
$ssl_preread_alpn_protocolsIt returns the list of protocols advertised by the client through ALPN and the values are separated by commas.
$ssl_preread_protocolThe highest SSL (Secure Sockets layer) protocol version supported by the client.
$ssl_preread_server_nameReturns 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_rttDisplays the information about the client TCP connection, available on systems that support the TCP_INFO socket option.
$tcpinfo_rttvarDisplays the information about the client TCP connection, available on systems that support the TCP_INFO socket option.
$tcpinfo_snd_cwndDisplays the information about the client TCP connection, available on systems that support the TCP_INFO socket option.
$tcpinfo_rcv_spaceDisplays 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_gotThe name of the cookie and received client identifier.
$uid_resetIf 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_setThe 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_statusIt 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_nameCookie 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_timeTime 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_timeIt 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_nameKeep the server response header fields.
$upstream_queue_timeIt 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_lengthIt 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_timeIt 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_timeSession duration in seconds with milliseconds resolution. Times of several connections are separated by commas (,) like addresses in the $upstream_addr variable.
$upstream_statusIt 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_nameIt is used to keep the field from the end of the response obtained from the upstream server.
$uriCurrent 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.





Latest Courses