mod_uploader 取扱説明書 (Apache モジュール版用)

mod_uploader: Apache のモジュールとして動作する高速アップローダ

Contents

mod_uploader とは?

mod_uploader は，よくあるアップローダを Apache のモジュールとして実装したものです．以下のような特長があります．

Apache のモジュールとして C++ で記述されているので，Perl や PHP で作られた物に比べて高速．
独自の簡易スクリプト言語によるテンプレート機能があるので，再コンパイル無しで手軽に見た目を変更可能．
アップロード時の進捗状況をリアルタイムに表示可能．

Windows 用 Apache モジュール版も存在します．

動作サンプル

http://acapulco.dyndns.org:8888/up/

動作環境

mod_uploader は，UNIX 系 OS で動作します．詳細を以下に示します．

Apache 2.0 以上（ Debian の場合，apache2，apache2-*-dev， libapr0-dev が必要）
GNU Compiler Collection 3.3 以上，または， Intel C++ Compiler for Linux 9.0 以上
GNU Make 3.8 以上
ImageMagick 6.0 以上（サムネイル画像生成を行わない場合は不要）
ffmpeg 0.4.9 以上（動画のサムネイル画像生成を行わない場合は不要）

開発は， Gentoo Linux kernel 2.6.10 ，GCC 3.3.5 ，Apache 2.0.54 ，ImageMagick 6.1.8.8 ，ffmpeg 0.4.9 で行っています．

ライセンス

The zlib/libpng License （ The zlib/libpng License の翻訳）に従います．

ダウンロード

mod_uploader-1.4.4.tgz

CVS リポジトリ

下記のようにすることで check out できます．（パスワードは空）

$ cvs -d:pserver:anonymous@cvs.sourceforge.jp:/cvsroot/mod-uploader login
$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.jp:/cvsroot/mod-uploader co mod_uploader

また， ViewCVS 経由で参照することもできます．

バグ情報

バグを見つけた場合は，リンク先の「新規レポート」から書き込んでください．

コンパイル方法

GNU Compiler Collection でコンパイルする場合は，

$ ./configure
$ make apache-module

とします． Intel C++ Compiler でコンパイルする場合は，

$ env CC=icc ./configure
$ make apache-module

とします．

configure は次のオプションを受け付けます．エラーがでた場合は， --with-apxs2 ， --with-apctl2 ， --with-aprconf や --enable-iconv-const を試してみてください．

--with-apxs2 = APXS: apxs コマンドのパスを指定します．自動的に検出されない場合に使用して下さい．
--with-apctl2 = APCTL: apachectl コマンドのパスを指定します．自動的に検出されない場合に使用して下さい．
--with-aprconf = APRCONF: apr-config コマンドのパスを指定します．自動的に検出されない場合に使用して下さい．
--with-libtool = LIBTOOL: libtool コマンドのパスを指定します．自動的に検出されない場合に使用して下さい．
--with-march = CPU: 特定の CPU 向けに最適化したい場合に使用します．例えば，Pentium 4 に最適化したい場合は， --with-march = pentium4 とします．
--enable-thumbnail: ファイルのサムネイル画像を生成したい場合に指定してください．
--enable-movie: ffmpeg を使って動画のサムネイル画像を生成したい場合に指定してください． --enable-thumbnail と組み合わせて使用します．
--with-mconf = MCONF: Magick++-config コマンドのパスを指定します．自動的に検出されない場合に使用してください．
--with-writer = TYPE: ファイルを書き出す方法を指定します．basic と mmap が指定可能です． (デフォルト: basic)
--with-ie-name-code = CODE: Internet Explorer に対してファイル名を出力するときの文字コード． (デフォルト: cp932)
--enable-iconv-const iconv の第二引数に const をつけるかどうか．: Mac OSX Tiger や FreeBSD を使用している場合は指定する必要があります．
--disable-rwlock: rwlock の代わりに mutex を使って，スレッド間の同期を行います．Mac OSX Tiger では，(現状) rwlock が使えないので指定する必要があります．

各環境での例

Gentoo Linux

$ ./configure
$ make apache-module

FreeBSD

$ env CPPFLAGS="-I/usr/local/include -L/usr/local/lib" ./configure --enable-iconv-const --with-libtool=/usr/local/bin/libtool15
$ gmake apache-module

Mac OSX Tiger + Fink

$ env CPPFLAGS="-I/sw/include" ./configure --enable-iconv-const --disable-rwlock
$ env MACOSX_DEPLOYMENT_TARGET=10.4 make apache-module

インストール

次のコマンドを実行するだけで OK です．

$ su
# make -f GNUmakefile.apache install

設定

設定は，Apache の設定ファイル（ .htaccess は不可）に，以下のように記述します．（ * 印がついているものは必須）

テンプレートは，tmpl/apache ディレクトリに入っている view.htm ， progress.htm ， download.htm ， thumbnail.htm ， error.htm を利用してください．

<Location アップローダを設置する場所>
    SetHandler              uploader

    Url                     アップローダの URL（RSS の生成に利用）

    FileDirectory           アップロードファイルを保存するディレクトリ *
    ThumbDirectory          サムネイル画像を保存するディレクトリ *
    TmpDirectory            一時ファイルを保存するディレクトリ *

    MaxFileSize             一回にアップロードできるファイルの最大サイズ（KB）
    TotalFileSizeLimit      ファイルの合計サイズの上限値（KB）
    TotalFileNumberLimit    ファイルの個数の上限値
    PerPageItemNumber       1 ページあたりに表示するアイテム数

    ViewTemplateFile        トップページのテンプレートファイル *
  　ProgressTemplateFile    アップロード状況表示画面のテンプレートファイル *
    DownloadTemplateFile    DL pass 入力画面のテンプレートファイル *
    ThumbTemplateFile       サムネイルページのテンプレートファイル *
    ErrorTemplateFile       エラーページのテンプレートファイル *
</Location>

http://foo/up/ に設置する場合の設定例は以下のようになります． /img ， /css や /thumb の Alias は必須ではありません．テンプレートを書き換えたくない場合に指定してみてください．（これはあくまでも例です．ディレクトリやファイルのパスは環境よって違ってきます）

<Location /up>
    SetHandler              uploader

    Url                     "http://foo/up/"

    FileDirectory           "/path/to/mod_uploader/file"
    ThumbDirectory          "/path/to/mod_uploader/thumb"
    TmpDirectory            "/path/to/mod_uploader/tmp"

    MaxFileSize             1024
    TotalFileSizeLimit      10240
    TotalFileNumberLimit    1000
    PerPageItemNumber       20

    ViewTemplateFile        "/path/to/mod_uploader/tmpl/apache/view.htm"
    ProgressTemplateFile    "/path/to/mod_uploader/tmpl/apache/progress.htm"
    DownloadTemplateFile    "/path/to/mod_uploader/tmpl/apache/download.htm"
    ThumbTemplateFile       "/path/to/mod_uploader/tmpl/apache/thumbnail.htm"
    ErrorTemplateFile       "/path/to/mod_uploader/tmpl/apache/error.htm"
</Location>

Alias   /img    "/path/to/mod_uploader/img"
Alias   /css    "/path/to/mod_uploader/css"
Alias   /thumb  "/path/to/mod_uploader/thumb"

注意事項

Apache の動作に不慣れなうちは，ディレクトリやファイルの指定には絶対パスを使用してください．
ディレクトリやファイルの指定には「\」を使わないでください． ( × C:foobarbaz， × C:/foo/bar/baz)
ディレクトリやファイルの指定には空白「」を含めないでください． ( × C:/Documents and Settings/foo/bar/baz)
FileDirectory ， ThumbDirectory ， TmpDirectory の各ディレクトリは， Apache が読み書き実行できるパーミッションに設定されている必要があります．
FileDirectory ， ThumbDirectory には mod_uploader が生成するファイル以外を置かないでください．
<Location> で指定するパスには「~」を含めないでください．
設定によっては，テンプレートを一部書き換えないと正常に表示されません．適宜書き換えてください．

起動

Apache を普通に起動すれば OK です．設置した場所にブラウザでアクセスしてみましょう．

お試し実行

次のコマンドを入力して，http://127.0.0.1:8080/up/ にアクセスすることですることでインストールせずに動作を確認できます．(他のホストからアクセスする場合は， 127.0.0.1 の部分を適当に置き換えてください)

$ su -
# make -f GNUmakefile.apache start

もし， LoadModule 関連のエラーが出た場合は，conf/apache.conf を適宜修正してください．

停止は，次のようにします．

# make -f GNUmakefile.apache stop

トラブル・シューティング

アクセスすると Internal Server Error になってしまう．

mod_uploader を実行するのに必要な環境が整っていない場合に表示されます．

この場合， Apache のエラーログに，「[mod_uploader] Exception: ....」のような出力が出ていると思います．メッセージを参考にしながら設定を見直して見て下さい．

また，メッセージが「Exception: \xc0\xdf\xc4\xea\xcf\xb3\xa4\xec\xa4\xac\xa4\xa2\xa4\xea\xa4\xde\xa4\xb9\xa1\xa5 」のように文字化けしている場合 [1] ，Exception 以降の文字列をコピーして，コンソールで以下のようなコマンドを実行してみてください．日本語のエラーメッセージを読むことができます．

$ perl -e 'print "\xc0\xdf\xc4\xea\xcf\xb3\xa4\xec\xa4\xac\xa4\xa2\xa4\xea\xa4\xde\xa4\xb9\xa1\xa5", "\n"'
設定漏れがあります．

[1]	AP_UNSAFE_ERROR_LOG_UNESCAPED を define して Apache をコンパイルすると，このような文字化けが発生しなくなります．

テンプレートの書式

Comming soon...

パフォーマンス

高速な表示

mod_uploader は，表示を非常に高速に行うことができます．

右に他のアップローダとの速度比較を示します．HTML は，表示を静的な HTML で行うもの，Perl および PHP はそれぞれの言語で作られたアップローダを指しています．測定には ApacheBench を用い，5 並列で 10,000 リクエスト発行した場合の値をプロットしました．

mod_uploader は Perl の約 100 倍，PHP の約 10 倍高速に動作しています．これらの言語を使った場合， mod_perl （ModPerl::Registry）や APC を使用すればある程度速度を改善することが可能です．それでも， mod_uploader には及びません．

また，mod_uploader は，静的な HTML を用いるものと比べてもわずかながら高速に動作します．これは，表示に静的な HTML を用いる場合でも，アップロード処理のためには libphp4.so をロードする必要があるので，そのためのオーバーヘッドがかかっているのが原因と思われます．libphp4.so のロードを無くした場合，HTML の値は 2,800 を超えて最速になります．

省メモリのアップロード

mod_uploader は，巨大なファイルのアップロードにもわずかなメモリしか消費しません．

それに対してアップローダの多くは，アップロードされたデータを一旦全てメモリに入れて処理するため，アップロードにはファイルサイズに比例したサイズのメモリを消費してしまいます．

API ドキュメント

http://acapulco.dyndns.org/mod_uploader/api/

ツール

プログラムの作成にあたってお世話になったツールを紹介します．

Valgrind: メモリの不正な参照や解放し忘れなどをチェックしてくれるツール．デバッグでかなりお世話になりました．

参考文献

プログラムの作成にあたってお世話になった文献を紹介します．

Apacheモジュールプログラミングガイド: Apache のモジュール作成に必要になる事柄を一通り説明した本．痒いところに手が届いているので，手元に置いておくと重宝します．
Advanced Topics in Module Design: Threadsafety and Portability: Apache 2.0 でモジュールを作成するときに必要になってくるテクニックが解説されたパワポ．そんなに長くないので，モジュール書く前にさらっと読んでおきましょう．
Apache API C++ Cookbook: C++ を使って Apache のモジュールを作成する際の注意事項について説明したサイト．
libapr (apache portable runtime) programming tutorial: APR のチュートリアル．サンプルコードおよび，間違いやすい点についての記述が多いので重宝します．
Using libavformat and libavcodec: An Update: libavformat と libavcodec を使って動画からフレーム画像を取り出す方法を解説したページ．丁寧に書かれています．
STL のページ: C++ の標準テンプレートライブラリである STL について簡潔にまとめられたサイト．
RubyExtensionProgrammingGuide: Ruby の拡張ライブラリの書き方を解説したサイト．基本的な事項から少し高度な話題まで非常に良くまとまってます．
Compiler Construction Lecture: コンパイラ作成に関する実践的な内容が簡潔にまとめられたサイト．簡単なインタプリタもどきを作るんだったら，このサイトだけで十分かも．