FAQ

Page Discussion History

HttpRewriteModuleJa

インストール | モジュール | アドオン | 設定 | コミュニティ | その他の情報源

Contents

概要

This module makes it possible to change URI using regular expressions (PCRE), and to redirect and select configuration depending on variables.

If the directives of this module are given at the server level, then they are carried out before the location of the request is determined. If in that selected location there are further rewrite directives, then they also are carried out. If the URI changed as a result of the execution of directives inside location, then location is again determined for the new URI.

This cycle can be repeated up to 10 times, after which Nginx returns a 500 error.

ディレクティブ

break

Syntax: break
Default:
Context: server
location
if
Reference:break


現在のルールの処理を完了します。現在のロケーションブロックの処理は継続されますが、rewriteディレクティブの処理はこれ以上行われません。

設定例:

if ($slow) {
  limit_rate  10k;
  break;
}

if

Syntax: if ( condition ) { ... }
Default:
Context: server
location
Reference:if


注意: if を使う前に、the if is evil page を熟読し、try_files の利用を検討してください。

Checks the truth of a condition. If the condition evaluates to true, then the code indicated in the curly braces is carried out and the request is processed in accordance with the configuration within the following block. The configuration inside the ifdirective is inherited from the previous level.

The condition can be:

  • the name of a variable; false values are: empty string ("", or any string starting with "0";
  • a comparison of a variable using the = and != operators;
  • pattern matching with regular expressions:
    • ~ performs a case-sensitive match
    • ~* performs a case-insensitive match (firefox matches FireFox)
    • !~ and !~* mean the opposite, "doesn't match"
  • checking for the existence of a file using the -f or !-f operators;
  • checking for the existence of a directory using -d or !-d;
  • checking for the existence of a file, directory or symbolic link using -e or !-e;
  • checking whether a file is executable using -x or !-x.

Parts of the regular expressions can be in parentheses, whose value can then later be accessed in the $1 to $9 variables. See Extracting matches.

設定例:

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;
}
 
if ($args ~ post=140){
  rewrite ^ http://example.com/ permanent;
}

The value of the built-in variable $invalid_referer is given by the directive valid_referers.

return

Syntax: return code [ text ]
return code URL
return URL
Default:
Context: server
location
if
Reference:return


このディレクティブは、ルールの実行を切り上げ、ステータスコードをクライアントに返却します。リターンコードとしては、0-999 の範囲の任意の数値を利用することが可能です。なお、非標準のコード 444 を利用することで、ヘッダを送信せずにコネクションをクローズすることができます。

rewrite

Syntax: rewrite regex replacement [ flag ]
Default:
Context: server
location
if
Reference:rewrite


このディレクティブは、URI を正規表現と置換文字列によって変換します。ディレクティブは、設定ファイルに記述された順に実行されます。

フラグにより、rewrite ディレクティブの実行を中断することも可能です。

置換後の文字列が、http:// から始まる場合、クライアントはリダイレクトされ、後続の rewrite ディレクティブは実行されません。

フラグは、次のいずれかを指定することができます:

  • last - 現在の rewrite ディレクティブの実行を完了させ、restarts the process (including rewriting) with a search for a match on the URI from all available locations.
  • break - 現在の rewrite ディレクティブの実行を完了させ、 and non-rewrite processing continues within the current location block only.
  • redirect - コード 302 により、一時的なリダイレクトを返却します。これは置換された行が http://から始まる場合に用いられます。
  • permanent - コード 301 により、恒久的なリダイレクトを返却します。

- Note that outside location blocks, last and break are effectively the same.

設定例:

rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  last;
rewrite  ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   last;
return   403;

これらのディレクティブを /download/ ロケーション内に配置した場合は、"last" フラグを "break" に置き換える必要があります。 otherwise Nginx will hit the 10 cycle limit and return error 500:

location /download/ {
  rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break;
  rewrite  ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   break;
  return   403;
}

If in the line of replacement arguments are indicated, then the rest of the request arguments are appended to them. To avoid having them appended, place a question mark as the last character:

  rewrite  ^/users/(.*)$  /show?user=$1?  last;

Note: for curly braces( { and } ), as they are used both in regexes and for block control, to avoid conflicts, regexes with curly braces are to be enclosed with double quotes (or single quotes). For example, to rewrite URLs like:

/photos/123456

to:

/path/to/photos/12/1234/123456.png

use the following (note the quotes enclosing the regex):

rewrite  "/photos/([0-9]{2})([0-9]{2})([0-9]{2})" /path/to/photos/$1/$1$2/$1$2$3.png;

If you specify a ? at the end of a rewrite then Nginx will drop the original $args (arguments). When using $request_uri or $uri&$args you should specify the ? at the end of the rewrite to avoid Nginx doubling the query string.

Example using $request_uri in a rewrite from www.example.com to example.com

server {
   server_name www.example.com;
   rewrite ^ http://example.com$request_uri? permanent;
}

Also rewrite operates only on path, not parameters. To rewrite a URL with parameters to another URL, use this instead:

if ($args ~ post=100){
  rewrite ^ http://example.com/new-address.html? permanent;
}

Note that the $args variable is not decoded, unlike URIs during location matching.

Also note that named subexpressions (?<name>) should be used when accessing variables from a map using regular expressions (patterns begininng with ~) because the map runs on demand and will override $1 (even when named subexpressions are used in the map).

rewrite_log

syntax: rewrite_log on | off

default: rewrite_log off

context: http, server, if-in-server, location, if-in-location

variables: no


When enabled, outputs information about rewrites to the error log at notice level.

set

Syntax: set variable value
Default:
Context: server
location
if
Reference:set


Directive establishes value for the variable indicated. As the value it is possible to use a text, variables and their combination.

You can use set to define a new variable. Note that you can't set the value of a $http_xxx header variable.

uninitialized_variable_warn

Syntax: uninitialized_variable_warn on | off
Default: on
Context: http
server
location
if
Reference:uninitialized_variable_warn


Enables or disables logging of warnings about noninitialized variables.

Internal implementation

Internally, the rewrite directives are compiled at the time the configuration file is loaded into internal codes, usable during the request by the interpreter.

This interpreter is a simple stack virtual machine. For example, the directive:

location /download/ {
  if ($forbidden) {
    return   403;
  }
  if ($slow) {
    limit_rate  10k;
  }
  rewrite  ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break;
}

will be compiled into this sequence:

  variable $forbidden
  checking to zero
  recovery 403
  completion of entire code
  variable $slow
  checking to zero
  checkings of regular expression
  copying "/"
  copying $1
  copying "/mp3/"
  copying $2
  copying ".mp3"
  completion of regular expression
  completion of entire sequence

Note that there is no code for directive limit_rate, since it does not refer to module ngx_http_rewrite_module. The "if" block exists in the same part of the configuration as the "location" directive.

If $slow is true, then what's inside the "if" block is evaluated, and in this configuration limit_rate it is equal to 10k.

Directive:

  rewrite  ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break;

It is possible to reduce the sequence, if in the regular expression we include the first slash inside the parentheses:

  rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break;

then the sequence will appear like this:

  checking regular expression
  copying $1
  copying "/mp3/"
  copying $2
  copying ".mp3"
  completion of regular expression
  completion of entire code

References

Original Documentation

PCRE Man Page in Plain Text


RegexOne» Learn regular expressions with simple, interactive examples.

RegexPal — a JavaScript regular expression tester