Headers More

Name

ngx_headers_more - "追加"だけでなく、入力と出力ヘッダを設定および消去します！

注意

このモジュールはNGIXのソースと一緒に配布されません。 インストレーションの説明を見てください。

バージョン

このドキュメントは2014年1月10日にリリースされたheaders-more-nginx-module v0.25 を説明します。

概要

# サーバ出力ヘッダを設定
more_set_headers 'Server: my-server';

# set and clear output headers
location /bar {
    more_set_headers 'X-MyHeader: blah' 'X-MyHeader2: foo';
    more_set_headers -t 'text/plain text/css' 'Content-Type: text/foo';
    more_set_headers -s '400 404 500 503' -s 413 'Foo: Bar';
    more_clear_headers 'Content-Type';

    # proxy_pass/memcached_pass/あるいはその他の設定がここにきます...
}

# 出力ヘッダを設定
location /type {
    more_set_headers 'Content-Type: text/plain';
    # ...
}

# 入力ヘッダを設定
location /foo {
    set $my_host 'my dog';
    more_set_input_headers 'Host: $my_host';
    more_set_input_headers -t 'text/plain' 'X-Foo: bah';

    # これで、$host と $http_host は新しい値を持ちます...
    # ...
}

# 既に存在している場合は入力ヘッダ X-Foo *だけ*を置き換えます
more_set_input_headers -r 'X-Foo: howdy';

説明

このモジュールは指定した入力あるいは出力ヘッダの追加、設定、あるいは消去をすることができます。

Content-Type, Content-Lengthおよび Serverのような"組み込みヘッダ"を再設定あるいは消去するユーティリティを提供するため、これは標準のheaders モジュールの拡張バージョンです。

more_set_headers と more_clear_headers ディレクティブを使って出力ヘッダを修正する間に、-s オプションを使って任意のHTTPステータスコード条件と、-t オプションを使って任意のコンテントタイプ条件を指定することもできます。例えば:

more_set_headers -s 404 -t 'text/html' 'X-Foo: Bar';

入力ヘッダも変更することができます。例えば:

location /foo {
    more_set_input_headers 'Host: foo' 'User-Agent: faked';
    # now $host, $http_host, $user_agent, and
    #   $http_user_agent all have their new values.
}

-sは使えませんが、オプション-tもmore_set_input_headers と more_clear_input_headers ディレクティブ(リクエストヘッダフィルタリングのために)の中で使うことができます。

標準のheaders モジュールと異なり、このモジュールのディレクティブはデフォルトで4xx と 5xxを含む全てのステータスコードに適用されます。

ディレクティブ

more_set_headers

構文:more_set_headers [-t <content-type list>]... [-s <status-code list>]... <new-header>...
デフォルト:none
コンテキスト:http, server, location, location if
Phase:output-header-filter

応答ステータスが-s オプションで指定されたコードと一致し、かつ応答コンテントタイプが-tオプションで指定されたタイプと一致する場合に、(もしあれば)置き換えあるいは(なければ)追加します。

-s あるいは -t のどちらかが指定されないあるいは空のリスト値を持たない場合は、一致は必要ではありません。したがって、以下のディレクティブは全ての ステータスコードおよび 全ての コンテントタイプについてServer出力ヘッダを独自の値に設定します。

more_set_headers    "Server: my_server";

同じ名前を持つ既存の応答ヘッダは常に上書きされます。ヘッダを逐次的に追加したい場合は、代わりに標準のadd_header ディレクティブを使います。

一つのディレクティブは複数の出力ヘッダを設定/追加することができます。例えば、

more_set_headers 'Foo: bar' 'Baz: bah';

一つのディレクティブの中で複数のオプションの存在が許されます。それらの値は一つに結合されるでしょう。例えば

more_set_headers -s 404 -s '500 503' 'Foo: bar';

は以下と等価です

more_set_headers -s '404 500 503' 'Foo: bar';

新しいヘッダは以下の形式の一つでなければなりません:

  1. 名前: 値
  2. 名前:
  3. 名前

最後の２つはヘッダ名の値を効果的に消去します。

NGINX 変数はヘッダ値の中で存在することができます。例えば:

set $my_var "dog";
more_set_headers "Server: $my_var";

しかし、パフォーマンスの考慮のために変数はヘッダのキー内で動作しないでしょう。

一つのlocationの中で複数の set/clear ヘッダディレクティブの存在が許されます。そしてそれらは順番に実行されます。

上位レベルのスコープ(つまり httpブロックあるいはサーバブロック)から継承されたディレクティブは、locationブロック内のディレクティブの前に実行されます。

more_set_headers はlocation のifブロック内で使うことができますが、serverの中のifブロックでは使え無いことに注意してください。

?  # This is NOT allowed!
?  server {
?      if ($args ~ 'download') {
?          more_set_headers 'Foo: Bar';
?      }
?      ...
?  }

Behind the scene, use of this directive and its friend more_clear_headers will (lazily) register an ouput header filter that modifies r->headers_out the way you specify.

more_clear_headers

構文:more_clear_headers [-t <content-type list>]... [-s <status-code list>]... <new-header>...
デフォルト:none
コンテキスト:http, server, location, location if
Phase:output-header-filter

指定された出力ヘッダを消去します。

実際、

more_clear_headers -s 404 -t 'text/plain' Foo Baz;

厳密に以下と等価です

more_set_headers -s 404 -t 'text/plain' "Foo: " "Baz: ";

あるいは

more_set_headers -s 404 -t 'text/plain' Foo Baz

参照

詳細は more_set_headers を見てください。

ヘッダ名パターンを指定するためにワイルドカード *も使うことができます。例えば、以下のディレクティブは“X-Hidden-”から始まる どのような出力ヘッダも効果的に消去します:

more_clear_headers 'X-Hidden-*';

* ワイルドカード サポートはv0.09で初めて導入されました。

more_set_input_headers

構文:more_set_input_headers [-r] [-t <content-type list>]... <new-header>...
デフォルト:none
コンテキスト:http, server, location, location if
Phase:rewrite tail

入力ヘッダ(あるいはリクエストヘッダ)上で作用し、-tオプションのみをサポートすることを除いては、、more_set_headersにとても良く似ています。

このディレクティブ内で-t オプションを使うことは、応答ヘッダでは無く、Content-Type リクエストヘッダによってフィルターすることを意味することに注意してください。

Behind the scene, use of this directive and its friend more_clear_input_headers will (lazily) register a rewrite phase handler that modifies r->headers_in the way you specify. 常にrewriteの最後に実行されるため、標準のrewrite モジュールの後で実行され、サブリクエストの中でも同じく動作します。

-r オプションが指定された場合、ヘッダはそれらが既に存在する場合のみ置き換えられるでしょう。

more_clear_input_headers

構文:more_clear_input_headers [-t <content-type list>]... <new-header>...
デフォルト:none
コンテキスト:http, server, location, location if
Phase:rewrite tail

指定された入力ヘッダを消去します。

実際、

more_clear_input_headers -s 404 -t 'text/plain' Foo Baz;

厳密に以下と等価です

more_set_input_headers -s 404 -t 'text/plain' "Foo: " "Baz: ";

あるいは

more_set_input_headers -s 404 -t 'text/plain' Foo Baz

参照

詳細はmore_set_input_headersを見てください。

制限

  • 標準の headersモジュールと異なり、このモジュールは自動的にExpires, Cache-Control および Last-Modified ヘッダ間の制限を処理します。You have to get them right yourself or use the headers module together with this module.
  • Connection応答ヘッダはNGINXコアの標準のngx_http_header_filter_moduleによって生成されるため、このモジュールを使ってConnection 応答ヘッダを削除することはできません。出力ヘッダフィルタは常にこのモジュールのフィルタの 後で実行します。Connection ヘッダを削除する実際の唯一の方法は、NGINXコアにパッチを当てることです。これはsrc/http/ngx_http_header_filter_module.cファイル内のC関数ngx_http_header_filter を編集します。

インストール

例えば、バージョン1.7.7 (NGINX互換性を見てください)のNGINXのソースコードをnginx.orgからダウンロードし、このモジュールを使ってソースをビルドします:

wget 'http://nginx.org/download/nginx-1.7.7.tar.gz'
tar -xzvf nginx-1.7.7.tar.gz
cd nginx-1.7.7/

# Here we assume you would install you nginx under /opt/nginx/.
./configure --prefix=/opt/nginx \
    --add-module=/path/to/headers-more-nginx-module

make
make install

headers-more-nginx-module ファイルリストからこのモジュールのリリースtarballの最新バージョンをダウンロードします。

また、このモジュールはngx_openresty bundleの中に含まれていてデフォルトで有効です。

互換性

NGINXの以下のバージョンがこのモジュールで動作するはずです:

  • 1.7.x (最後のテスト: 1.7.7)
  • 1.6.x (最後のテスト: 1.6.2)
  • 1.5.x (最後のテスト: 1.5.8)
  • 1.4.x (最後のテスト: 1.4.4)
  • 1.3.x (最後のテスト: 1.3.7)
  • 1.2.x (最後のテスト: 1.2.9)
  • 1.1.x (最後のテスト: 1.1.5)
  • 1.0.x (最後のテスト: 1.0.11)
  • 0.9.x (最後のテスト: 0.9.4)
  • 0.8.x (最後のテスト: 0.8.54)
  • 0.7.x >= 0.7.44 (最後のテスト: 0.7.68)

0.6.x および 0.5.x のようなNGINXの以前のバージョンは動作しないでしょう。

0.7.44以上のNGINXの特定のバージョンでこのモジュールが動作しないことを見つけたらバグの報告を考えてみてください。

コミュニティ

英語のメーリングリスト

openresty-en メーリングリストは英語を話す人のためのものです。

中国語のメーリングリスト

openresty メーリングリストは中国語を話す人のためのものです。

バグとパッチ

バグレポート、欲しいもののリスト、あるいはパッチを下記でサブミットしてください

  1. GitHub Issue Tracker上でチケットを作成
  2. あるいは、OpenResty communityにポスト。

ソースリポジトリ

GitHub上のopenresty/headers-more-nginx-moduleで利用可能です。

変更

このモジュールの各リリースの変更は、ngx_openresty バンドルのchange logsから取得することができます:

http://openresty.org/#Changes

テストスィート

このモジュールはPerl駆動テストスィートが付いています。test cases も declarative です。Perl世界の Test::Nginx モジュールに感謝します。

アナタの側でそれを実行するには:

$ PATH=/path/to/your/nginx-with-headers-more-module:$PATH prove -r t

valgrindのmemcheckを使ってテストスィートを実行するには、以下のコマンドを使ってください:

$ export PATH=/path/to/your/nginx-with-headers-more-module:$PATH
$ TEST_NGINX_USE_VALGRIND=1 prove -r t

NGINXサーバ バイナリを変更した場合はテストスィートを実行する前に全てのNGINXプロセスを終了する必要があります。

単一のNGINX サーバ (デフォルトでは localhost:1984) は全てのテストスクリプト(.t ファイル)に渡って使用されるため、proveユーティリティを起動する時に-jNを指定することで並行してテストスィートを実行することは意味がありません。

テストスィートの幾つかの部分はNGINXをビルドする時にモジュールproxy, rewrite および echo を有効にする必要があります。

TODO

  • 新しいヘッダのキーでの変数をサポートします。

Getting involved

authorにパッチをサブミット、あるいはGitHub上のsource repositoryに少しコミットするように依頼することをとても歓迎します。

著者

このwikiページもauthor自身によって整備されており、同様に誰でもこのページを改善することは奨励されています。