HttpCoreModuleJa

インストール | モジュール |  アドオン |  設定 |  コミュニティ |  その他の情報源 nginx.org のドキュメント の翻訳です.

Wiki の英語バージョン は、若干記述が古いため、本家のドキュメントを直接翻訳しています.

= 概要 =

Nginx の HTTP プロセスのコア機能をコントロールします.

= ディレクティブ =

aio


FreeBSD および Linux の非同期 I/O (AIO) 機能の有効化、無効化を行います.

FreeBSD において、AIO は FreeBSD 4.3 以降で利用できます. AIO は次のようにしてカーネルに静的にリンクするか:

options VFS_AIO

もしくはローダブルモジュールとして動的にロードします:

kldload aio

FreeBSD 5 および 6 において、AIO を静的に有効にするか、カーネルのブート時に動的に有効にした場合、ネットワークサブシステム全体が、パフォーマンス低下を引き起こすジャイアントロックを使用するようになります. この制限は、2009 年の FreeBSD 6.4-STABLE および FreeBSD 7 において取り除かれました. なお、FreeBSD 5.3 以降では、ネットワークサブシステムに対するジャイアントロックの問題なしに AIO を有効にできるようになっていますが、これには AIO モジュールをカーネルのブート後にロードする必要があります. この場合、/var/log/messages に次のようなメッセージが出力されますが、これらは無視して構いません.

WARNING: Network stack Giant-free, but aio requires Giant. Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0

AIO を動作させるためには、 sendfile を無効にする必要があります.

location /video { sendfile    off: aio         on; output_buffers 1 64k; }

FreeBSD 5.2.1 および Nginx 0.8.12 以降では、AIO を  用にあらかじめロードされたデータに対して使用できます:

location /video { sendfile    on; tcp_nopush  on; aio         sendfile; } 上記の設定では、 が   フラグ付きで呼び出されます. そのため、これはディスク I/O をブロックせず、データがメモリにないときには、それを報告します. 引き続き、nginx は 1 バイトの読み取りにより非同期のデータロードを開始します. FreeBSD のカーネルは、ファイルの先頭 128K バイトをメモリにロードしますが、以降のデータのロードは 16K のチャンク単位で行われます. これは read_ahead ディレクティブの使用によりチューニングすることができます.

Linux の場合、AIO はカーネル 2.6.22 以降で利用できます. 加えて、AIO には directio が必須であり、これを用いなかった場合、読み取りがブロックされます:

location /video/ { aio           on; directio      512; output_buffers 1 128k; }

Linux の場合、 directio は512 バイト境界 (XFS の場合は 4K) にアラインメントされたブロックの読み取りにのみ使用できます. アラインメントされていないファイル終端の読み取りは、ブロッキングモードで行われます. 同じことがバイト範囲のリクエストや、ファイルの先頭以外から行われる FLV のリクエストに付いても言えます. アラインメントされていないデータをファイルの先頭から末尾まで行う場合はブロッキングされます. sendfile を明示的に無効にする必要はありません. これは、 directio を使用する際、自動的に無効化されます.

alias


指定された location の置換を定義します. 例えば、次のような設定の場合:

location /i/ { alias /data/w3/images/; }

へのリクエストについては  ファイルがレスポンスとして返却されます.

path の値には、 および   以外の任意の変数を含めることができます.

が location 内で正規表現を用いて指定された場合、この正規表現はキャプチャを含む必要があり、 はこれらのキャプチャを参照する必要があります (0.7.40). 次に例を示します:

location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { alias /data/w3/images/$1; }

location が ディレクティブの値の最後の部分に合致する場合:

location /images/ { alias /data/w3/images/; }

root ディレクティブを使用することが推奨されます:

location /images/ { root /data/w3; }

chunked_transfer_encoding


HTTP/1.1 におけるチャンク化された転送エンコーディングの有効化、無効化を制御します (0.7.66 以上). これは、チャンク化されたエンコーディングのサポートがうまくいかないソフトウェアを使用する際に有効です. ただし、標準では、このサポートは必須です.

client_body_buffer_size


クライアントからのリクエストボディを読み取る際のバッファサイズを指定します. リクエストボディがこのバッファよりも大きい時は、リクエストボディ全体、もしくは一部が 一時ファイル に書きこまれます. デフォルトのサイズはページサイズの 2 倍で、x86、その他の 32 ビットプラットフォーム、x86-64 では 8K、その他の 64 ビットプラットフォームでは 16K です.

client_body_in_file_only


このディレクティブにより nginx がクライアントからのリクエストボディを一時ディスクファイルに常に保存するようになります. これは、たとえボディのサイズが 0 であっても行われます.

このディレクティブが有効の場合、リクエスト完了時にファイルは削除されないので注意してください.

このディレクティブはデバッグと埋め込み Perl モジュールの  で利用できます.

client_body_in_single_buffer


このディレクティブ (0.7.58以上) は単一のクライアントリクエストバッファにボディ全体を保持するかどうかを指定します. コピー処理を削減するために変数 $request_body を使用するときには、このディレクティブの有効化が推奨されます.

リクエストボディが単一バッファ (client_body_buffer_size を参照) で保持できない場合、ボディはディスクに書きこまれます.

client_body_temp_path
シンタックス: client_body_temp_path dir-path [ level1 [ level2 [ level3 ]    

デフォルト: client_body_temp

コンテキスト: http, server, location

このディレクティブはリクエストのボディとともに一時ファイルをを保存するためのディレクトリを指定します.

にてサブディレクトリの階層を三階層まで設定可能です.

例

client_body_temp_path /spool/nginx/client_temp 1 2; ディレクトリ構造は次のようになります:

/spool/nginx/client_temp/7/45/00000123457

client_body_timeout
シンタックス: client_body_timeout time

デフォルト: 60

コンテキスト: http, server, location

このディレクティブはクライアントからのボディリクエストの読み出しタイムアウトを設定します.

このタイムアウトは一度のリードステップでボディが得られないときのみ設定されます. もしこの時間後にクライアントが何も送信しなければ nginx は "Request time out" (408) のエラーを返します.

client_header_buffer_size


このディレクティブは、クライアントからのリクエストヘッダ用のヘッダバッファサイズを設定します.

大半のリクエストについては、1K のバッファサイズで充分なはずです.

しかしながら、リクエストヘッダに大きなクッキーがあったり、WAP クライアントからのリクエストがあったりする場合は、ヘッダが 1K に収まらない場合があります. その場合、リクエストヘッダがこのバッファに完全には収まらないので nginx はより大きなバッファを割り当てます. その際のバッファのサイズは large_client_hedaer_buffers で設定します.

client_header_timeout
シンタックス: client_header_timeout time

デフォルト: 60

コンテキスト: http, server

クライアントのリクエストのタイトル読み出しのタイムアウトを設定します.

このタイムアウトは一度のリードステップでヘッダーが得られないときのみ設定されます. もしこの時間後にクライアントが何も送信しなければ nginx は "Request time out" (408) のエラーを返します.

client_max_body_size
シンタックス: client_max_body_size size

デフォルト: client_max_body_size 1m

コンテキスト: http, server, location

このディレクティブはクライアントリクエストの受信ボディサイズの最大値を設定します. これはリクエストのヘッダーにある  の行で指示されています.

もしサイズが設定値より大きいとクライアントには "Request Entity Too Large" (413) エラーが送られます.

ブラウザはこのエラーを正しく表示する方法を知らないことに留意してください.

default_type
シンタックス: default_type MIME-type

デフォルト: default_type text/plain

コンテキスト: http, server, location

標準 MIME マップが何も指定されていないファイルに使われるデフォルト MIME タイプを指定します.

typesも参照してください.

directio


このディレクティブで指定したサイズより大きいファイルを読み取る際に O_DIRECT (FreeBSD, Linux)、F_NOCACHE (Mac OS X) フラグや directio 関数 (Solaris) が有効になります. このディレクティブは sendfile の利用を無効にします. 大きなファイルに便利かもしれません: directio 4m;

directio_alignment


error_page


このディレクティブはエラーが発生したときに表示される URI を指定します.

例: error_page  404          /404.html; error_page  502 503 504  /50x.html; error_page  403          http://example.com/forbidden.html; error_page  404          = @fetch; さらに、アンサーコードを別のものに変更することも可能です. 例えば:

error_page 404 =200 /.empty.gif;

もしプロキシサーバや FastCGI サーバによって誤ったアンサーが処理されてこのサーバが別のアンサーコード、例えば 200、302、401、404 を返すことがある場合、返されるコードを発行することができます:

error_page  404  =  /404.php;

リダイレクションの間に URI を変更する必要がない場合、エラーページの処理を名前をつけた location にリダイレクトさせることができます:

location / (   error_page 404 = @fallback; )

location @fallback (   proxy_pass http://backend; )

etag


静的なリソースに対して自動的に生成される "ETag" レスポンスヘッダフィールドの有効化、無効化を制御します.

if_modified_since
シンタックス: if_modified_since [off|exact|before]

デフォルト: if_modified_since exact

コンテキスト: http, server, location

このディレクティブ (0.7.24) はファイル修正時刻とリクエストヘッダー "If-Modified-Since" の時刻の比較方法を定義します:
 * off — "If-Modified-Since" リクエストヘッダーをチェックしない (0.7.34);
 * exact — 完全一致;
 * before — ファイル修正時刻は "If-Modified-Since" リクエストヘッダーの時刻より前でなくてはならない

internal
シンタックス: internal

デフォルト: no

コンテキスト: location

internal が、location のマッチがいわゆる "internal(内部)" のリクエストのみ使われるのかどうかを示します.

外部のリクエストに大してはエラー "Not found" (404) を返します.

内部リクエストは次のものです:
 * error_pageでの指示によるリダイレクトされたリクエスト
 * "ngx_http_ssi_module" モジュールのコマンド include virtual によって作成されたサブリクエスト
 * "ngx_http_rewrite_module" モジュールの rewrite 指示によって変更されたリクエスト

クライアントがエラーページを直接取得するのを防ぐ例です: error_page 404 /404.html; location /404.html { internal; }

keepalive_timeout
シンタックス: keepalive_timeout [ time ] 

デフォルト: keepalive_timeout 75

コンテキスト: http, server, location

最初のパラメータはクライアントとのキープアライブ接続のタイムアウトを指定します. サーバはこの時間後に接続を閉じます.

二番目の任意のパラメータはレスポンスのヘッダー  の   値を指定します. このヘッダーによりブラウザによっては接続を閉じさせることができ、サーバが閉じる必要はなくなります. このパラメータなしでは nginx は  ヘッダーを送りません (とはいえ、これは接続を "キープアライブ" させておくものではありません).

このパラメータはそれぞれ異なります.

ブラウザが  ヘッダーをどのように扱うかについて:


 * MSIE と Opera は "Keep-Alive: timeout=" ヘッダーを無視します.
 * MSIE は接続を約 60-65 秒間保ち、その後 TCP RST を送信します.
 * Opera は長時間接続を保ちます.
 * Mozilla は N プラス約 1-10 秒間接続を保ちます.
 * Konqueror は約 N 秒間接続を保ちます.

keepalive_requests
シンタックス: keepalive_requests n

デフォルト: keepalive_requests 100

コンテキスト: http, server, location

キープアライブ接続越しにリクエストできる数.

large_client_header_buffers


クライアントリクエストから大きなヘッダを読み取るためのバッファの最大数と最大サイズを指定します.

リクエスト行は単一のバッファサイズ以下である必要があります. クライアントがそれより大きいヘッダを送信してきた場合、nginx は「Request URI too large」 (414) エラーを返却します.

リクエストの最長ヘッダ行も、単一のバッファサイズ以下である必要があります. それを超えた場合、クライアントには「Bad request」 (400) エラーが返却されます.

バッファは必要に応じて分割されます.

デフォルトでは、単一のバッファサイズは 8192 バイトですが、以前の nginx では単一のページサイズと同等で、プラットフォームにより 4K もしくは 8K でした. 実行中リクエストの終了時に、コネクションのステータスがキープアライブに遷移した際、これらのバッファは解放されます.

limit_except


ロケーション内で利用可能なHTTPメソッドを制限します. このメソッドのパラメータは、 から一つ以上を選択します. メソッドを許可すると メソッドも許可したことになるので注意してください. その他のメソッドの制御については、 ngx_http_access_module と ngx_http_auth_basic_module モジュールのディレクティブが使えます.

limit_except GET { allow 192.168.1.0/32; deny  all; }

上記の例では、 および 以外のメソッドは利用できません.

limit_rate
シンタックス: limit_rate speed

デフォルト: no

コンテキスト: http, server, location, if in location

このディレクティブはクライアントへの返信伝送速度を指定します. 速度は秒あたりのバイト数で指定します. 制限が有効なのはひとつの接続だけです. つまり、もしクライアントが２つの接続を開いている場合、トータルの速度はこの制限設定の２倍以上になります.

何かの条件をもとにしてサーバレベルでクライアントの速度を制限する必要がある場合は、このディレクティブは当てはまりません. 代わりに、以下のように $limit_rate の変数に値を指定して制限を設定してください:

server { if ($slow) { set $limit_rate 4k; } }

また、  ヘッダー (XSendfile) を設定することにより   レスポンス (HttpProxyModule) によって返される個々のレスポンスのレートをコントロールすることもできます. これは  ヘッダー無しで可能です.

limit_rate_after
シンタックス: limit_rate_after time

デフォルト: limit_rate_after 1m

コンテキスト: http, server, location, if in location

このディレクティブは最初の部分が送信された後でのみ、スピードを制限します.

limit_rate_after 1m; limit_rate 100k;

lingering_close


nginx がクライアントからのコネクションをどのようにクローズするかを制御します.

デフォルト値の on を指定すると、nginx はコネクションを完全にクローズする前に、クライアントから追加のデータがあると判断されると、そのデータを待ち受けて処理を行います、

always を指定すると、nginx は無条件にクライアントからの追加のデータを待ち受けて処理を行います.

off を指定すると、nginx はデータを待ち受けずに、コネクションを直ちにクローズします. これはプロトコル上問題を発生させますので、通常用いるべきではありません.

lingering_time


lingering_close が有効になっている場合、このディレクティブは nginx がクライアントからの追加のデータを処理（読み取ったうえで破棄）する最長時間を指定します. この時間を過ぎるとコネクションは、追加のデータの有無に関わらずクローズされます.

lingering_timeout
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/lingering_timeout.txt" />

lingering_close が有効になっている場合、このディレクティブはクライアントからの追加のデータの到着を待ち受ける時間を指定します. データがこの時間内に到着しなかった場合、コネクションはクローズされます. それ以外の場合、データは読み取られた上で破棄され、nginx は再度追加のデータの到着を待ち受けます. この「待ち受け-読み取り-破棄」サイクルは、lingering_time ディレクティブで指定された時間を超えて繰り返されることはありません.

listen
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/listen.txt" />

listen ディレクティブは、server {...} ブロックが accept するアドレスとポートを設定します. これはアドレスだけ、ポートだけの指定や、アドレスの代わりにサーバ名での指定が可能です.

listen 127.0.0.1:8000; listen 127.0.0.1; listen 8000; listen *:8000; listen localhost:8000;

IPv6 アドレスは  で指定します.

listen [::]:8000; listen [fe80::1];

In Linux by default any IPv6 TCP socket also accepts IPv4 traffic using the IPv4 to IPv6 mapped address format, i.e., ::ffff:<IPv4 adddress in dotted decimal notation>. E.g., maps the IPv4 address 192.168.0.27 to an IPv6 address.

When you enable the address [::]:80, binding port 80 using IPv6, in the listen directive, in Linux, by default, the IPv4 port 80 is also enabled. Meaning that nginx listens for both IPv4 and IPv6 incoming traffic. Therefore if you erroneously specify also a IPv4 address you'll get an already bind address error when reloading nginx configuration.

In Linux the separation of the IPv6 and IPv4 stacks is controlled through the runtime parameter: which has the value 0 by default.

IPv4 と IPv6 で別々のソケットを用いたい場合は、 を用いてこのパラメータを 1 に設定する必要があります.

Note that any nginx instance that was running before you made the change will continue to accept IPv4 traffic. Therefore you should edit your nginx configuration to reflect the new setup for IPv6 and IPv4 packet handling and do a restart.

If on the other hand you launched another server instance (vhost) and you expect it to also handle IPv4 traffic by using only, for example: listen [::]:80; the binding of the IPv4 address will fail. The correct way to to this is by using the "ipv6only=on" option in the IPv6 listen directive and also specifying a IPv4 listen directive in the respective server block.

This re-editing of the configuration must be done after you changed your kernel runtime parameter. This is the most generic situation in that case (separation of IPv6 and IPv4 sockets): listen [::]:80 ipv6only=on; # listen for IPv6 only traffic on IPv6 sockets listen 80; # listen also for IPv4 traffic on "regular" IPv4 sockets

In FreeBSD the default is separate IPv4 and IPv6 sockets. Therefore "listen [::]:80" only binds port 80 for listening to IPv6 traffic. It's always necessary to specify also IPv4 listen directives if you wish to also handle IPv4 traffic.

It's possible to specify only IPv6 addresses in the listen directive. Using the "default_server ipv6only=on" option. Specific IPv6 addresses can be used with a IPv6 only default directive. Other server directives can also specifiy listen directives with IPv4 addresses. The uniqueness of the IPv6 handling concerns only the same server {...} block. listen [2a02:750:5::123]:80; listen [::]:80 default_server ipv6only=on;

アドレスのみが指定された場合、nginx がデフォルトでバインドするポートは 80 です.

ディレクティブに default_server パラメータが指定された場合、server {...} で囲まれたブロックは、その address:port ペアに対するデフォルトサーバとして機能します. これはネームベースの仮想ホストを利用しており、いずれの server_name ディレクティブにも合致しないホスト名に対して動作するデフォルトサーバを定義しておきたい場合に有用です. default_server パラメータが指定されていなかった場合は、 ペアごとに、先頭の server ブロックがデフォルトサーバとして機能します. default_server パラメータは 0.8.21 以降で実装され、これにより default パラメータが廃止予定となっています.

ディレクティブには、ほかにも  や   システムコールに固有のいくつかのパラメータを指定可能です. These parameters must follow the  parameter.

backlog=num -- is assigned parameter backlog in call. By default backlog equals -1.

rcvbuf=size -- assigned to the parameter  for the listening socket.

sndbuf=size -- assigned to the parameter  for the listening socket.

accept_filter=filter -- accept-filter の名前


 * . FreeBSD のみ動作し、 と   という 2 種類のフィルタを用いることが可能です.  On the signal -HUP accept-filter it is possible to change only in the quite last versions FreeBSD: 6.0, 5.4-STABLE and 4.11-STABLE.

deferred -- indicates to use that postponed accept(2) on Linux with


 * . the aid of option.

bind -- indicates that it is necessary to make  separately


 * . for this pair of address:port. The fact is that if are described several directives listen with the identical port, but by different addresses and one of the directives listen listens to on all addresses for this port (*:port), then nginx will make bind(2) only to *:port. It is necessary to consider that in this case for determining the address, on which the connections arrive, is done the system call getsockname. But if are used parameters backlog, rcvbuf, sndbuf, accept_filter or deferred, then it is always done separately for this pair of address:port bind(2).

ssl -- parameter (0.7.14) not related to listen(2) and bind(2) syscalls


 * . but instead specifies that connections accepted on this port should work in SSL mode. This allows to specify compact configurations for servers working with both HTTP and HTTPS. For example:

listen 80; listen 443 default_server ssl;

これらのパラメータの設定例を以下に示します: listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

0.8.21 以降の nginx では、UNIX ドメインソケットを listen することも可能です: listen unix:/tmp/nginx1.sock;

location
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/location.txt" />

This directive allows different configurations depending on the URI. It can be configured using both literal strings and regular expressions. To use regular expressions, you must use a prefix:
 * 1)  "~" for case sensitive matching
 * 2)  "~*" for case insensitive matching

あるクエリに対して、どの location が合致するかを確認する際には、リテラル文字列が最初にチェックされます. リテラル文字列は、クエリの先頭部分とマッチされ、最長一致になります. その後正規表現が設定ファイルで指定された順にチェックされ、いずれかの正規表現にマッチした時点でチェックは終了します. 正規表現にマッチしなかった場合は、リテラル文字列のチェック結果が用いられます.

For case insensitive operating systems, like Mac OS X or Windows with Cygwin, literal string matching is done in a case insensitive way (0.7.7). However, comparison is limited to single-byte locale's only.

正規表現にはキャプチャを含めることができます (0.7.40). これは他のディレクティブで用いることができます.

"^~" 修飾子を用いることで、リテラル文字列に対するマッチング後の正規表現によるチェックを無効にすることもできます. 最長一致のリテラル文字列にこの修飾子が指定されていた場合、正規表現によるチェックは行われません.

By using the "=" prefix we define the exact match between request URI and location. When matched search stops immediately. 一例をあげると、"/" に対するリクエストは頻繁に発生しますが、"location = /" を用いることで、最初の比較の時点でチェックが終了するので、リクエストの処理が若干ですがスピードアップします.

On exact match with literal location without "=" or "^~" prefixes search is also immediately terminated.

To summarize, the order in which directives are checked is as follows:


 * 1)  Directives with the "=" prefix that match the query exactly. If found, searching stops.
 * 2)  All remaining directives with conventional strings. If this match used the "^~" prefix, searching stops.
 * 3)  Regular expressions, in the order they are defined in the configuration file.
 * 4)  If #3 yielded a match, that result is used. Otherwise, the match from #2 is used.

It is important to know that nginx does the comparison against decoded URIs. For example, if you wish to match "/images/%20/test", then you must use "/images/ /test" to determine the location.

Example:

location = / { # matches the query / only. [ configuration A ] } location / { # matches any query, since all queries begin with /, but regular # expressions and any longer conventional blocks will be # matched first. [ configuration B ] } location ^~ /images/ { # matches any query beginning with /images/ and halts searching, # so regular expressions will not be checked. [ configuration C ] } location ~* \.(gif|jpg|jpeg)$ { # matches any request ending in gif, jpg, or jpeg. However, all # requests to the /images/ directory will be handled by # Configuration C.     [ configuration D ] }

Example requests:


 * / -> configuration A
 * /documents/document.html -> configuration B
 * /images/1.gif -> configuration C
 * /documents/1.jpg -> configuration D

Note that you could define these 4 configurations in any order and the results would remain the same. While nested locations are allowed by the configuration file parser, their use is discouraged and may produce unexpected results.

The prefix "@" specifies a named location. Such locations are not used during normal processing of requests, they are intended only to process internally redirected requests (see error_page, try_files).

log_not_found
syntax: log_not_found [on|off]

default: log_not_found on

context: http, server, location

The directive enables or disables messages in error_log about files not found on disk.

log_subrequest
syntax: log_subrequest [on|off]

default: log_subrequest off

context: http, server, location

The directive enables or disables messages in access_log about sub-requests such as rewrite rules and/or SSI requests.

msie_padding
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/msie_padding.txt" />

このディレクティブは、MSIE ブラウザおよび Chrome (nginx 0.8.25以上) に対する msie_padding 機能の有効化、無効化を制御します. When this is enabled, nginx will pad the size of the response body to a minimum of 512 bytes for responses with a status code above or equal to 400.

The padding prevents the activation of "friendly" HTTP error pages in MSIE and Chrome, so as to not hide/mask the more-informative error pages from the server.

msie_refresh
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/msie_refresh.txt" />

This directive allows or forbids issuing a  instead of doing a   for MSIE.

open_file_cache
syntax: open_file_cache max = N [inactive = time] | off 

default: open_file_cache off

context: http, server, location

The directive sets the cache activity on. These information can be stored:
 * Open file descriptors, information with their size and modification time;
 * Information about the existence of directories;
 * Error information when searches for a file - no file, do not have rights to read, etc. See also open_file_cache_errors

Options directive:


 * - specifies the maximum number of entries in the cache. When the cache overflows, the least recently used(LRU) items will be removed;
 * - specifies the time when the cached item is removed, if it has not been downloaded during that time, the default is 60 seconds;
 * - prohibits the cache activity.

Example: open_file_cache max=1000 inactive=20s; open_file_cache_valid   30s; open_file_cache_min_uses 2; open_file_cache_errors  on;

open_file_cache_errors
syntax: open_file_cache_errors on | off 

default: open_file_cache_errors off

context: http, server, location

The directive specifies to cache errors or not when searching a file.

open_file_cache_min_uses
syntax: open_file_cache_min_uses number

default: open_file_cache_min_uses 1

context: http, server, location

The directive defines the minimum use number of a file within the time specified in the directive parameter inactive in open_file_cache. ?If use more than the number, the file descriptor will remain open in the cache.

open_file_cache_valid
syntax: open_file_cache_valid time

default: open_file_cache_valid 60

context: http, server, location

The directive specifies the time when need to check the validity of the information about the item in open_file_cache.

optimize_server_names
syntax: optimize_server_names [ on|off ] 

default: optimize_server_names on

context: http, server

Directive activates or deactivates optimization of host name checks for name-based virtual servers.

In particular, the check influences the name of the host used in redirects. If optimization is on, and all name-based servers listening on one address:port pair have identical configuration, then names are not checked during request execution and redirects use first server name.

If redirect must use host name passed by the client, then the optimization must be turned off.

Note: this directive is deprecated in nginx 0.7.x, use server_name_in_redirect instead.

port_in_redirect
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/port_in_redirect.txt" />

nginx がリダイレクトを処理する際に、ポート指定を継承するか否かを制御します.

が off の場合、Nginx はリクエストがリダイレクトされた際に、URL 内のポート指定を継承しません.

post_action
syntax: post_action [ uri|off ] 

default: post_action off

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

Defines a URI to sub-request upon completion of current request.

location /protected_files { internal;

proxy_pass http://127.0.0.2; post_action /protected_done; }

location /protected_done { internal; fastcgi_pass 127.0.0.1:9000; }
 * 1) Send the post_action request to a FastCGI backend for logging.

recursive_error_pages
syntax: recursive_error_pages [on|off] 

default: recursive_error_pages off

context: http, server, location

enables or disables following a chain of  directives.

request_pool_size
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/request_pool_size.txt" />

このディレクティブはリクエストごとのメモリ割り当てに用いられます. プール (pool) は小規模なメモリ割り当てに用いられます. ブロックがプールサイズやページサイズにより大きい場合は、プール外で割り当てが行われます. プール内で小規模なメモリ割り当てを行うためのメモリが不足している場合は、新しく同じサイズのメモリブロックがプール用に割り当てられます. このディレクティブの設定による影響は微小です（ http://markmail.org/message/b2kmrluscevimpba を参照）

reset_timedout_connection
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/reset_timedout_connection.txt" />

タイムアウトしたコネクションのリセットを有効にするかどうかを制御します. リセットを行う際には、ソケットのクローズ前に SO_LINGER オプションが timeout 値 0 に設定されます. これにより、ソケットがクローズされるとクライアントに TCP_RST が送信され、ソケットが使っていたメモリが解放されます. これにより、既にクローズされたソケットが FIN_WAIT1 ステータスのまま残り、バッファが長期間占有されることが避けられます.

このディレクティブの設定に関わらず、キープアライブコネクションのタイムアウトの際は通常通りにクローズされる点に留意してください.

resolver
syntax: resolver address

default: no

context: http, server, location

Directive defines DNS server address, e.g.

resolver 127.0.0.1;

resolver_timeout
syntax: resolver_timeout time

default: 30s

context: http, server, location

Directive defines timeout for name resolution, e.g.

resolver_timeout 5s;

root
syntax: root path

default: root html

context: http, server, location, if in location

root specifies the document root for the requests. For example, with this configuration

location /i/ { root /spool/w3; } A request for "/i/top.gif" will return the file "/spool/w3/i/top.gif". You can use variables in the argument.

note: Keep in mind that the root will still append the directory to the request so that a request for "/i/top.gif" will not look in "/spool/w3/top.gif" like might happen in an Apache-like alias configuration where the location match itself is dropped. Use the  directive to achieve the Apache-like functionality.

satisfy
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/satisfy.txt" />

コンテキスト内で Access module と Auth Basic module の両方が定義されていた場合のアクセスポリシを定義します.
 * all - コンテキスト内では Access *および* Auth Basic ディレクティブの両方でアクセスが許可される必要がある
 * any - コンテキスト内では Access *または* Auth Basic ディレクティブのいずれかでアクセスが許可される必要がある

location / { satisfy any; allow 192.168.1.0/32; deny all; auth_basic "closed site"; auth_basic_user_file conf/htpasswd; }

satisfy_any
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/satisfy_any.txt" />

deprecated: 0.6.25 -- satisfy ディレクティブを代わりに用いること

send_lowat
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/send_lowat.txt" />

0 以外の値を設定した場合、nginx は kqueue メソッドの NOTE_LOWAT フラグもしくはソケットオプションの SO_SNDLOWAT を用いて、クライアントのソケットに対する send 処理の回数を、指定された size を用いて最小にしようと試みます.

このディレクティブは Linux, Solaris, Windows では無視されます.

send_timeout
syntax: send_timeout the time

default: send_timeout 60

context: http, server, location

Directive assigns response timeout to client. Timeout is established not on entire transfer of answer, but only between two operations of reading, if after this time client will take nothing, then nginx is shutting down the connection.

sendfile
syntax: sendfile [ on|off ] 

default: sendfile off

context: http, server, location

Directive activate or deactivate the usage of.

server
syntax: server {...}

default: no

context: http

Directive assigns configuration for the virtual server.

There is no separation of IP and name-based (the  header of the request) servers.

Instead, the directive  is used to describe all addresses and ports on which incoming connections can occur, and in directive   indicate all names of the server.

server_name
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/server_name.txt" />

このディレクティブは、以下の 2 つの動作を行います:


 * 受信した HTTP リクエストの  ヘッダと、Nginx 設定ファイルで定義された server { ... } の比較を行い、最初に合致するブロックを選択します. これにより、仮想サーバ が定義されます. サーバ名は次の順で処理されます:


 * 1) 完全に固定の名前
 * 2) 先頭にワイルドカードが付加された名前 — *.example.com
 * 3) 後方にワイルドカードが付加された名前 — www.example.*
 * 4) 正規表現で指定された名前
 * 合致するものがなかった場合、設定ファイル内の server { ... } ブロックが、次の順に基づいて選択されます:


 * 1)   ディレクティブが合致したサーバブロックで、  が指定されているもの
 * 2)   ディレクティブが合致した (暗黙的な を含む) 最初のサーバブロック


 * server_name_in_redirect が設定されている場合、HTTP リダイレクトで用いるサーバ名を設定します.

設定例:

server { server_name  example.com  www.example.com; }

先頭の名前は、サーバの基本名です. デフォルトでは、マシンのホスト名が利用されます.

"*" を用いることで、名前の先頭もしくは末尾を置き換えることも可能です:

server { server_name  example.com  *.example.com  www.example.*; }

上記の例の最初の 2 つ (example.com and *.example.com) は、次のように 1 つで表現することもできます:

server { server_name .example.com; }

名前の先頭にチルダ "~" を付加することで、サーバ名に正規表現を用いることも可能です:

server { server_name  www.example.com   ~^www\d+\.example\.com$; }

nginx 0.7.12 以降では、"Host" ヘッダのないリクエストに対応するため、空のサーバ名もサポートされています. ただし、大半のブラウザは、常に Host ヘッダを送信します. IP アドレスでのアクセスの場合は、Host ヘッダにも IP アドレスが含まれます. すべてのリクエストに対応したい場合は、listen ディレクティブの default_server フラグを参照してください.

server { server_name ""; }

nginx 0.8.25 以降では、server_name として名前付きキャプチャも利用できます:

server { server_name  ~^(www\.)?(? .+)$; root /sites/$domain; }

以下はキャプチャを複数用いた例です: server { server_name  ~^(? .+?)\.(? .+)$; root /sites/$domain/$subdomain; }

古いバージョンの PCRE によっては、以下のような文法になります. 問題が発生したら、試してみてください:

server { server_name  ~^(www\.)?(?P .+)$; root /sites/$domain; }

nginx 0.9.4 以降では $hostname を server_name の引数として指定することができます: server { server_name $hostname; }

server_name_in_redirect
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/server_name_in_redirect.txt" />

が on の場合、nginx はリダイレクトの際に server_name の最初の値を利用します. が off の場合、nginx はリクエストされた  ヘッダを利用します.

Note: for Location headers coming from an upstream proxy (via proxy_pass for example) this may not be the only directive you need. In fact, it seems to be ignored a lot of the time. If you are seeing the upstream's server name come through and not be rewritten, you will need to use proxy_redirect to rewrite the upstream's provided hostname to what you want. Something like  - you will want to rewrite it to a / relative path.

server_names_hash_max_size
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/server_names_hash_max_size.txt" />

The maximum size of the server name hash tables. For more detail see the description of tuning the hash tables in Nginx Optimizations.

server_names_hash_bucket_size
syntax: server_names_hash_bucket_size number

default: server_names_hash_bucket_size 32/64/128

context: http

Directive assigns the size of basket in the hash-tables of the names of servers. This value by default depends on the size of the line of processor cache. For more detail see the description of tuning the hash tables in Nginx Optimizations.

server_tokens
syntax: server_tokens on|off

default: server_tokens on

context: http, server, location

Whether to send the Nginx version number in error pages and  header.

tcp_nodelay
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/tcp_nodelay.txt" />

このディレクティブは、ソケットオプション  の有効化、無効化を制御します. コネクション内でのみ有効です.

ソケットオプション  についての詳細は、こちらを参照してください.

tcp_nopush
syntax: tcp_nopush [on|off] 

default: tcp_nopush off

context: http, server, location

This directive permits or forbids the use of the socket options  on FreeBSD or   on Linux. This option is only available when using.

Setting this option causes nginx to attempt to send it's HTTP response headers in one packet on Linux and FreeBSD 4.x

You can read more about the  and   socket options here.

try_files
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_core_module/try_files.txt" />

ファイルの存在を順に確認し、最初に確認できたファイルを返却します. のように末尾にスラッシュのついたパスはディレクトリを示します. ファイルが確認できなかった場合は、末尾に指定したパラメータに対して内部リダイレクトが行われます. 末尾のパラメータはフォールバック用の URI で、必ず 存在している必要があります. 存在していない場合は内部エラーが発生します. Unlike rewrite, $args are not automatically preserved if the fallback is not a named location. args を保持する必要がある場合は、次のように明示的に実施する必要があります:

try_files $uri $uri/ /index.php?q=$uri&$args;

Example use in proxying Mongrel: try_files /system/maintenance.html $uri $uri/index.html $uri.html @mongrel;

location @mongrel { proxy_pass http://mongrel; }

Note that you can specify an HTTP status code as the last argument to  since Nginx version 0.7.51. Here's an example: location / { try_files $uri $uri/ /error.php?c=404 =404; } When all other attempts to serve the content corresponding to the request fail issue a.

Example of use with Drupal / FastCGI: try_files $uri $uri/ @drupal;
 * 1) for drupal 6:

try_files $uri $uri/ /index.php?q=$uri&$args;
 * 1) for drupal 7:

location @drupal { rewrite ^ /index.php?q=$uri last; # for drupal 6 }
 * 1) only needed for Drupal 6 (or if you absolutely need a named location)

location ~ \.php$ { fastcgi_pass 127.0.0.1:8888; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; # if not already defined in the fastcgi_params file # any other specific fastcgi_params }

In this example, the directive try_files $uri $uri/ @drupal;

Is basically the same as this: location / { error_page    404 = @drupal; log_not_found off; }

Or this: if (!-e $request_filename) { rewrite ^ /index.php?q=$uri last; }

is basically a replacement for the typical mod_rewrite style file/directory existence check. It is supposed to be more efficient than using  - see IfIsEvil

Examples of use with Wordpress and Joomla (typical "Front controller pattern" packages) try_files $uri $uri/ /index.php?q=$uri&$args;
 * 1) wordpress (without WP Super Cache) - example 1

try_files $uri $uri/ /index.php;
 * 1) wordpress (without WP Super Cache) - example 2 (it doesn't REALLY need the "q" parameter)

try_files $uri $uri/ /index.php?q=$uri&$args;
 * 1) joomla

location ~ \.php$ { fastcgi_pass 127.0.0.1:8888; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; # if not already defined in the fastcgi_params file # any other specific fastcgi_params }

WP Super Cache requires a bunch of static file checks. Those are not shown here.

types
syntax: types {...}

context: http, server, location

Directive assigns the correspondence of expansion and MIME-types of answers. To one MIME- type can correspond several expansions. By default it is used these correspondences:

types { text/html   html; image/gif   gif; image/jpeg  jpg; } The sufficiently complete table of mappings is included and is located in the file.

So that for that determined location's for all answers would reveal MIME- type, it is possible to use the following:

location /download/ { types        { } default_type application/octet-stream; }

underscores_in_headers
syntax: underscores_in_headers on|off

default: off

context: http, server

Allows or disallows underscores in headers.

variables_hash_bucket_size
Assigns the key bucket size for the variables hash table.

variables_hash_max_size
The maximum size of the variables hash table. For more detail see the description of tuning the hash tables in Nginx Optimizations.

= Variables = The core module supports built-in variables, whose names correspond with the names of variables in Apache.

First of all, there are variables which represent header lines in the client request, for example,,  , and so forth. Note that because these correspond to what the client actually sends, they are not guaranteed to exist and their meaning is defined elsewhere (e.g. in relevant standards).

Furthermore, there are other variables:

$arg_PARAMETER
This variable contains the value of the  request variable PARAMETER if present in the query string

$args
This variable is the  parameters in request line, e.g.  ;

$binary_remote_addr
The address of the client in binary form;

$body_bytes_sent
The amount of bytes sent as part of the body of the response. Is accurate even when connections are aborted or interrupted.

$content_length
This variable is equal to line  in the header of request;

$content_type
This variable is equal to line  in the header of request;

$cookie_COOKIE
The value of the cookie COOKIE;

$document_root
This variable is equal to the value of directive root for the current request;

$document_uri
The same as $uri.

$host
This variable is equal to line  in the header of request or name of the server processing the request if the   header is not available.

This variable may have a different value from  when the   input header is absent or has an empty value.

$hostname
Set to the machine's hostname as returned by gethostname

$http_HEADER
The value of the HTTP request header HEADER when converted to lowercase and with 'dashes' converted to 'underscores', e.g. $http_user_agent, $http_referer...;

$is_args
Evaluates to "?" if $args is set, "" otherwise.

$limit_rate
This variable allows limiting the connection rate.

$nginx_version
The version of Nginx that the server is currently running;

$query_string
The same as $args.

$remote_addr
The address of the client.

$remote_port
The port of the client;

$remote_user
This variable is equal to the name of user, authenticated by the Auth Basic Module;

$request_filename
This variable is equal to path to the file for the current request, formed from directives root or alias and URI request;

$request_body
This variable(0.7.58+) contains the body of the request. The significance of this variable appears in locations with directives proxy_pass or fastcgi_pass.

$request_body_file
Client request body temporary filename;

$request_completion
Set to "OK" if request was completed successfully. Empty if request was not completed or if request was not the last part of a series of range requests.

$request_method
This variable is equal to the method of request, usually  or.

Before and including 0.8.20, this variable always evaluates to the method name of the main request, not the current request if the current request is a subrequest.

$request_uri
This variable is equal to the *original* request URI as received from the client including the args. It cannot be modified. Look at $uri for the post-rewrite/altered URI. Does not include host name. Example: "/foo/bar.php?arg=baz"

$scheme
The HTTP scheme (i.e. http, https). Evaluated only on demand, for example: rewrite ^  $scheme://example.com$uri  redirect;

$server_addr
Equal to the server address. As a rule, for obtaining the value of this variable is done one system call. In order to avoid system call, it is necessary to indicate addresses in directives listen and to use parameter.

$server_name
The name of the server.

$server_port
This variable is equal to the port of the server, to which the request arrived;

$server_protocol
This variable is equal to the protocol of request, usually this  or.

$uri
This variable is equal to current URI in the request (without arguments, those are in $args.) It can differ from $request_uri which is what is sent by the browser. Examples of how it can be modified are internal redirects, or with the use of index. Does not include host name. Example: "/foo/bar.html"

= References = Original Documentation


 * English
 * Russian
 * German
 * Italian
 * French
 * Polish
 * 简体中文文档
 * Spanish
 * Korean
 * Tiếng Việt
 * Brazilian Portuguese
 * 日本語