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

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

Contents

mod_uploader とは?

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

lighttpd プラグイン版CGI 版 も存在し ます.

動作サンプル

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

動作環境

mod_uploader は,UNIX 系 OS 及び Windows で動作します.詳細を以下に示し ます.

UNIX 系 OS

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

Windows

ライセンス

The zlib/libpng LicenseThe zlib/libpng License の翻訳 )に従いま す.

ダウンロード

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 経由で参照 することもできます.

バグ情報

バグ情報

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

コンパイル方法

UNIX 系 OS

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 TigerFreeBSD を使用している場合は指定する必要があり ます.
--disable-rwlock
rwlock の代わりに mutex を使って,スレッド間の同期を行います.Mac OSX Tiger では,(現状) rwlock が使えないので指定する必要があります.

各環境での例

Gentoo Linux

$ ./configure
$ make apache-module

FreeBSD

$ ./configure --enable-iconv-const --with-libtool=/usr/local/bin/libtool15
$ gmake apache-module

Mac OSX Tiger

$ ./configure --enable-iconv-const --disable-rwlock
$ env MACOSX_DEPLOYMENT_TARGET=10.4 make apache-module

Windows

まず,UNIX 系 OS で configure します.

$ ./configure

次に,ディレクトリを丸ごと Windows にコピーし,src/GNUmakefile.apache.win32 の 次の部分を, Apache をインストールしたディレクトリおよび ImageMagick をインストールしたディレクトリに書き換えます.

APACHERDIR  := C:/Server/Apache2
MAGICKDIR   := C:/Application/Image/Edit/ImageMagick

以上が完了したら,src/GNUmakefile.apache.win32 を使って make します.

> cd src
> vsvars32.bat
> make -f GNUmakefile.apache.win32

vsvars32.bat は,コマンドラインから Visual C++ .NET を使うための環 境設定を行うスクリプトです. Visual C++ .NET をインストールしたディ レクトリ以下の Common7/Tools にあります.

インストール

UNIX 系 OS

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

$ su
# make -f GNUmakefile.apache install

Windows

コンパイル or ダウンロードした mod_uploader.so を Apache をインストー ルしたディレクトリ以下にある modules ディレクトリにコピーし, Apache の設定ファイル (httpd.conf) に

LoadModule uploader_module modules/mod_uploader.so

を追加します.

次に,環境変数 APR_ICONV_PATH に,Apache をインストールしたディレク トリ以下にある bin/iconv ディレクトリへのパスを指定します.これが正 常に行われていないと,「文字コードの変換を行うコンバータが存在しませ ん.」というエラーが発生します.

設定

Apache の設定

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

テンプレートは,tmpl/apache ディレクトリに入っている view.htmprogress.htmdownload.htmthumbnail.htmerror.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           "Z:/prog/Apache/Uploader/file"
    ThumbDirectory          "Z:/prog/Apache/Uploader/thumb"
    TmpDirectory            "Z:/prog/Apache/Uploader/tmp"

    MaxFileSize             1024
    TotalFileSizeLimit      10240
    TotalFileNumberLimit    1000
    PerPageItemNumber       20

    ViewTemplateFile        "Z:/prog/Apache/Uploader/tmpl/apache/view.htm"
    ProgressTemplateFile    "Z:/prog/Apache/Uploader/tmpl/apache/progress.htm"
    DownloadTemplateFile    "Z:/prog/Apache/Uploader/tmpl/apache/download.htm"
    ThumbTemplateFile       "Z:/prog/Apache/Uploader/tmpl/apache/thumbnail.htm"
    ErrorTemplateFile       "Z:/prog/Apache/Uploader/tmpl/apache/error.htm"
</Location>

Alias   /img    "Z:/prog/Apache/Uploader/img"
Alias   /css    "Z:/prog/Apache/Uploader/css"
Alias   /thumb  "Z:/prog/Apache/Uploader/thumb"

ImageMagick の設定

Windows でサムネイル作成機能を使う場合,環境変数 PATH に, ImageMagick をインストールしたディレクトリ(CORE_RL_*.dll があるディ レクトリ)が含まれていることを確認してください.

注意事項

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

起動

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

お試し実行

UNIX 系 OS の場合,次のコマンドを入力して,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 してコンパイルした場合, このような文字化けは発生しません.

Intel C++ Compiler でコンパイルすると,Internal Server Error になってしまう.

下記のように, LD_PRELOAD に libunwind.so.5 を指定しながら Apache を起動したら症状が改善する場合,ICC のインストール方法に問題があります. もう一度設定を見直してください.

$ env LD_PRELOAD=/opt/intel_cc_81/lib/libunwind.so.5 "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モジュール プログラミングガイド
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
コンパイラ作成に関する実践的な内容が簡潔にまとめられたサイト.簡単な インタプリタもどきを作るんだったら,このサイトだけで十分かも.