nginx-upload-module - upload_store ディレクティブによって指定されるディレクトリへアップロードされる全てのファイルを格納するリクエストボディをパースします。そしてファイルはボディから取り除かれ、変更されたリクエストがupload_pass ディレクティブによって指定された場所に渡されます。従って、アップロードされたファイルを任意に処理することができます。各ファイルフィールドはupload_set_form_field ディレクティブによって指定されるフィールドのセットによって置換されます。各アップロードされたファイルの内容は $upload_tmp_path
変数で指定されたファイルから読み込むか、単純に最終的な目的地に移動することができます。出力ファイルの削除はディレクティブ upload_cleanupによって制御されます。リクエストがPOST以外のメソッドの場合、モジュールは405 (Method not allowed) を返します。そのようなメソッドのリクエストはerror_page ディレクティブを使って別の場所で処理をすることができます。
解凍した後で、以下のオプションをNGINX ./configureコマンドに追加してください:
--add-module=path/to/nginx_upload_module
構文: | upload_pass <location> |
---|---|
デフォルト: | none |
コンテキスト: | server,location |
リクエストボディを渡すlocationを指定します。ファイル フィールドは取り除かれ、アップロードされたファイルを処理するために必要な情報を含むフィールドによって置き換えられます。
構文: | upload_resumable <on/off> |
---|---|
デフォルト: | off |
コンテキスト: | http,server,location |
レジューム可能なアップロードを有効にします。
構文: | upload_store <directory> [<level 1> [<level 2> ] ... ] |
---|---|
デフォルト: | none |
コンテキスト: | server,location |
出力ファイルが保存されるディレクトリを指定します。ディレクトリはハッシュ化することができます。この場合、全てのディレクトリはNGINXが開始する前に存在していなければなりません。
構文: | upload_state_store <directory> [<level 1> [<level 2> ] ... ] |
---|---|
デフォルト: | none |
コンテキスト: | server,location |
任意レジューム可能なアップロードのための状態ファイルを含むだろうディレクトリを指定します。ディレクトリはハッシュ化することができます。この場合、全てのディレクトリはNGINXが開始する前に存在していなければなりません。
構文: | upload_store_access <mode> |
---|---|
デフォルト: | user:rw |
コンテキスト: | server,location |
出力ファイルを生成するために使われるアクセスモードを指定します。
構文: | upload_set_form_field <name> <value> |
---|---|
デフォルト: | none |
コンテキスト: | server,location |
任意バックエンドに渡されるリクエストボディ内の各アップロードファイルのために生成されるフォームフィールドを指定します。名前と値は以下の特別な変数を含むことができます: * $upload_field_name – 元のファイルフィールドの名前 * $upload_content_type – アップロードされたファイルの内容 * $upload_file_name – DOSおよびUNIX表記の先頭のパス要素が取り去られたアップロードされたファイルの元の名前。つまり、"D:Documents And SettingsMy DcoumentsMy PicturesPicture.jpg" は "Picture.jpg" に変換され、"/etc/passwd" は "passwd" に変換されます。* $upload_tmp_path – 元のファイルの内容が保存されるパス。出力ファイル名は10桁から成り、proxy_temp_path directive と同じアルゴリズムを使って生成されます。これらの変数は元のリクエストボディの一部分が処理されている間のみ有効です。
例えば:
upload_set_form_field $upload_field_name.name "$upload_file_name";
upload_set_form_field $upload_field_name.content_type "$upload_content_type";
upload_set_form_field $upload_field_name.path "$upload_tmp_path";
構文: | upload_aggregate_form_field <name> <value> |
---|---|
デフォルト: | none |
コンテキスト: | server,location |
任意バックエンドに渡されるリクエストボディ内の各アップロードファイルのために生成される、集約属性を含むフォームフィールドを指定します。名前と値は標準のNGINX変数、upload_set_form_fieldディレクティブからの変数、および以下の追加の特別な変数を含むことができます: * $upload_file_md5 – ファイルのMD5チェックサム * $upload_file_md5_uc – ファイルの大文字のMD5チェックサム * $upload_file_sha1 – ファイルのSHA1チェックサム * $upload_file_sha1_uc – ファイルの大文字のSHA1チェックサム * $upload_file_crc32 – ファイルのCRC32の16進値 * $upload_file_size – ファイルのサイズのバイト数 * $upload_file_number – リクエストボディ内のファイルの順番
このディレクティブによって指定されるフィールドの値は、ファイルのアップロードが成功した後で評価されます。したがってこれらの変数は元のリクエストボディの一部分の処理の終了時のみ利用可能です。
例えば:
upload_aggregate_form_field $upload_field_name.md5 "$upload_file_md5";
upload_aggregate_form_field $upload_field_name.size "$upload_file_size";
警告
変数 $upload_file_md5_, $upload_file_md5_uc_, $upload_file_sha1_ および $upload_file_sha1_uc_ はMD5およびSHA1チェックサムを計算するために追加のリソースを使用します。
構文: | upload_pass_form_field <regex> |
---|---|
デフォルト: | none |
コンテキスト: | server,location |
元のリクエストボディからバックエンドに渡されるフィールドの名前の正規表現パターンを指定します。このディレクティブはlocationごとに複数回指定することができます。フィールドは最初のパターンが一致するとすぐにバックエンドに渡されるでしょう。PCREが無い環境では、このディレクティブはバックエンドに渡すためにフィールドの正確な名前を指定します。ディレクティブが省略された場合は、クライアントからバックエンドにどのフィールドも渡されないでしょう。
例えば:
upload_pass_form_field "^submit$|^description$";
PCREが無い環境:
upload_pass_form_field "submit";
upload_pass_form_field "description";
構文: | upload_cleanup <HTTP status/range> [<HTTP status/range ...] |
---|---|
デフォルト: | none |
コンテキスト: | server,location |
Specifies HTTP statuses after generation of which all file successfuly uploaded in current request will be removed. バックエンドあるいはサーバの失敗の後で掃除をするために使われます。なんらかの理由でバックエンドがアップロードされたファイルを必要としない場合は、バックエンドは明示的にerrornousステータスも発信するかも知れません。HTTP ステータスは400-599の間の数字で、前に0が付くことは許されません。ステータスの範囲はダッシュを付けて指定することができます。
例えば:
upload_cleanup 400 404 499 500-505;
構文: | upload__buffer_size <size> |
---|---|
デフォルト: | size of memory page in bytes |
コンテキスト: | server,location |
ファイルデータを集めそれをディスクに書き込むために使われるwriteバッファのバイト数。このディレクティブはメモリ使用量 vs. syscal 率を解決するために使われることを目的としています。
構文: | upload_max_part_header_len <size> |
---|---|
デフォルト: | 512 |
コンテキスト: | server,location |
ヘッダ部分の最大のバイト数を指定します。ヘッダ部分を集めるために使われるバッファのサイズを決定します。
構文: | upload_max_file_size <size> |
---|---|
デフォルト: | none |
コンテキスト: | server,location |
ファイルの最大サイズを指定します。このディレクティブの値よりも大きいファイルは除外されます。指定された制限より長いファイルに遭遇した後でNGINXはリクエストボディを処理し続け、残りのファイルを受け取ろうとするという意味で、このディレクティブは"soft"制限を指定します。"hard" 制限のためには、client_max_body_size ディレクティブが使われなければなりません。このディレクティブでの0は、ファイルサイズの制限が適用されてはいけないことを示します。
構文: | upload_limit_rate <rate> |
---|---|
デフォルト: | 0 |
コンテキスト: | main,server,location |
アップロードの秒間あたりのバイト数の制限を指定します。0は制限が無いことを意味します。
構文: | upload_max_output_body_len <size> |
---|---|
デフォルト: | 100k |
コンテキスト: | main,server,location |
出力ボディの最大長を指定します。これはメモリ内にファイルでは無いフォームフィールドを積み上げることを防ぎます。出力ボディが指定された制限を超える時はいつでもエラー 413 (Request entity too large) が生成されるでしょう。このディレクティブでの0は、出力ボディへの制限が適用されてはならないことを意味します。
構文: | upload_tame_arrays <on/off> |
---|---|
デフォルト: | off |
コンテキスト: | main,server,location |
ファイルフィールド名の四角括弧が取り除かれなければならないかを指定します(PHP配列で必要とされます)。
構文: | upload_pass_args <on/off> |
---|---|
デフォルト: | off |
コンテキスト: | main,server,location |
upload_passで指定される、locationへのクエリ引数の転送を有効にします。名前付きのlocationでは効果がありません。例:
...
location /upload {
upload_pass /internal_upload;
upload_pass_args on;
}
...
location /internal_upload {
...
proxy_pass http://backend;
}
この例では、バックエンドはリクエスト URI "/upload?id=5" を取得します。upload_pass_args が off の場合、バックエンドは "/upload" を取得します。
server {
client_max_body_size 100m;
listen 80;
# Upload form should be submitted to this location
location /upload {
# Pass altered request body to this location
upload_pass @test;
# Store files to this directory
# The directory is hashed, subdirectories 0 1 2 3 4 5 6 7 8 9 should exist
upload_store /tmp 1;
# Allow uploaded files to be read only by user
upload_store_access user:r;
# Set specified fields in request body
upload_set_form_field $upload_field_name.name "$upload_file_name";
upload_set_form_field $upload_field_name.content_type "$upload_content_type";
upload_set_form_field $upload_field_name.path "$upload_tmp_path";
# Inform backend about hash and size of a file
upload_aggregate_form_field "$upload_field_name.md5" "$upload_file_md5";
upload_aggregate_form_field "$upload_field_name.size" "$upload_file_size";
upload_pass_form_field "^submit$|^description$";
upload_cleanup 400 404 499 500-505;
}
# Pass altered request body to a backend
location @test {
proxy_pass http://localhost:8080;
}
}
<html>
<head>
<title>Test upload</title>
</head>
<body>
<h2>Select files to upload</h2>
<form name="upload" method="POST" enctype="multipart/form-data" action="/upload">
<input type="file" name="file1"><br>
<input type="file" name="file2"><br>
<input type="file" name="file3"><br>
<input type="file" name="file4"><br>
<input type="file" name="file5"><br>
<input type="file" name="file6"><br>
<input type="submit" name="submit" value="Upload">
<input type="hidden" name="test" value="value">
</form>
</body>
</html>