+ + + + +server +location +if + + +Stops processing the current set of +ngx_http_rewrite_module directives. + + + +Example: + +if ($slow) { + limit_rate 10k; + break; +} + + + + + + + +(condition) + +server +location + + +The specified condition is evaluated. +If true, the directives of this module specified inside the braces are +executed, and a request is assigned the configuration inside the +if directive. +Configurations inside the if directives are +inherited from the previous configuration level. + + + +A condition may be any of the following: + + + +a variable name; false if the value of a variable is an empty string +or any string starting with “0”; + + + +comparing a variable with a string using the +“=” and “!=” operators; + + + +matching a variable against a regular expression using the +“~” (for case-sensitive matching) and +“~*” (for case-insensitive matching) operators. +Regular expressions can contain captures that are made available for +later reuse in the $1..$9 variables. +Negative operators “!~” and “!~*” +are also available. +If a regular expression includes the characters “}” +or “;”, the whole expressions should be enclosed +in single or double quotes. + + + +checking a file existence with the “-f” and +“!-f” operators; + + + +checking a directory existence with the “-d” and +“!-d” operators; + + + +checking a file, directory, or symbolic link existence with the +“-e” and “!-e” operators; + + + +checking for an executable file with operators “-x” +and “!-x” operators. + + + + + + +Examples: + +if ($http_user_agent ~ MSIE) { + rewrite ^(.*)$ /msie/$1 break; +} + +if ($http_cookie ~* "id=([^;]+)(?:;|$)") { + set $id $1; +} + +if ($request_method = POST) { + return 405; +} + +if ($slow) { + limit_rate 10k; +} + +if ($invalid_referer) { + return 403; +} + + +A value of the embedded variable $invalid_referer is set by the + directive. + + + + + + + +code + +server +location +if + + +Stops processing and returns the specified code to a client. +The following codes can be returned: 204, 400, +402 — 406, 408, 410, 411, 413, 416 и 500 — 504. +In addition, the non-standard code 444 closes a connection without sending +a response header. + + + + + + + + regex + replacement + [flag] + +server +location +if + + +If the specified regular expression matches a URI, the URI is changed +as specified in the replacement string. +The rewrite directives are executed sequentially +in order of their appearance in the configuration file. +Flags make it possible to terminate further processing of directives. +If a replacement string starts with “http://” +or “https://”, the processing stops and a +redirect is returned to a client. + + + +An optional flag parameter can be one of: + + +last + +stops processing the current set of +ngx_http_rewrite_module directives +followed by a search for a new location matching the changed URI; + + +break + +stops processing the current set of +ngx_http_rewrite_module directives; + + +redirect + +returns a temporary redirect with the code 302; +used if a replacement string does not start with +“http://” or “https://”; + + +permanent + +returns a permanent redirect with the code 301. + + + + + + +Example: + +server { + ... + rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; + rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; + return 403; + ... +} + + + + +But if these directives are put inside the “/download/” +location, the last flag should be replaced by +break, otherwise nginx will make 10 cycles and +return the error 500: + +location /download/ { + rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; + rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break; + return 403; +} + + + + +If a replacement string includes the new request arguments, +the previous request arguments are appended after them. +If this is undesired, putting a question mark at the end of a replacement +string avoids having them appended, for example: + +rewrite ^/users/(.*)$ /show?user=$1? last; + + + + +If a regular expression includes the characters “}” +or “;”, the whole expressions should be enclosed +in single or double quotes. + + + + + + +variable value + +server +location +if + + +Sets a value for the specified variable. +A value can contain text, variables, and their combination. + + + + + + +on | off +on +http +server +location +if + + +Controls whether warnings about uninitialized variables are logged. + + + + +

+ + +The ngx_http_rewrite_module module directives +are compiled during the configuration stage into internal instructions +that are interpreted during request processing. +An interpreter is a simple virtual stack machine. + + + +For example, the directives + +location /download/ { + if ($forbidden) { + return 403; + } + + if ($slow) { + limit_rate 10k; + } + + rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; +} + +will be translated into these instructions: + +variable $forbidden +check against zero + return 403 + end of code +variable $slow +check against zero +match of regular expression +copy "/" +copy $1 +copy "/mp3/" +copy $2 +copy ".mp3" +end of regular expression +end of code + + + + +Note that there are no instructions for the + +directive above as it is unrelated to the +ngx_http_rewrite_module module. +A separate configuration is created for the block. +If the condition holds true, a request is assigned this configuration +where limit_rate equals to 10k. + + + +The directive + +rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; + +can be made smaller by one instruction if the first slash in the regular expression +is put inside the parentheses: + +rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; + +The corresponding instructions will then look like this: + +match of regular expression +copy $1 +copy "/mp3/" +copy $2 +copy ".mp3" +end of regular expression +end of code + + + +