mod_uploader

[ mod_uploader とは? | 動作サンプル | 動作環境 | ライセンス | ダウンロード | CVS リポジトリ | バグ情報 | コンパイル方法 | インストール | 設定 | 起動 | お試し実行 | トラブル・シューティング | テンプレートの書式 | パフォーマンス | API ドキュメント | ツール | 参考文献 ]

# mod_uploader とは?

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

- Apache のモジュールとして C++ で記述されているので，Perl や PHP で 作られた物に比べて高速．
- 独自の簡易スクリプト言語によるテンプレート機能があるので，再コンパ イル無しで手軽に見た目を変更可能．
- メモリを圧迫せずに巨大なファイルのアップロードが可能．

# 動作サンプル

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

# 動作環境

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

## UNIX 系 OS

- Apache 2.0 以上 (Debian の場合，apache2， apache2-*-dev，libapr0-dev が必要です)
- GCC 3.3 以上 または Intel C++ Compiler for Linux 9.0 以上
- GNU Make 3.8 以上
- ImageMagick 6.0 以上 (サムネイル生成機能を使わない場合は不要)

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

## Windows

- Apache 2.0 以上 [インストール手順]
- ImageMagick DLL 版 6.0 以上 (サムネイル生成機能を使わない場合は不要) [インストール手順]
- Visual C++ .NET 2003 以上 (コンパイルしない場合は不要)
- Cygwin 版 GNU Make 3.8 以上(コンパイルしない場合は不要)

# ライセンス

The zlib/libpng License (翻訳) に従います．

# ダウンロード

- mod_uploader-1.2.0.tgz
- mod_uploader.so-1.2.0.zip (Apache 2.0.54 for Windows 用バイナリ，サムネイル機能あり)

# 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

GCC でコンパイルする場合は，

    $ ./configure
    $ make

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

    $ CC=icc ./configure
    $ make

とします．

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
  指定すると，ThumbDirectory で指定したディレクトリにサムネイル画像を 生成するようになります．
--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 や FreeBSD を使 用している場合は指定する必要があります．
--disable-rwlock
  rwlock の代わりに mutex を使って，スレッド間の同期を行います．Mac OSX Tiger では，(現状) rwlock が使えないので指定する必要があります．

## Windows

まず，UNIX 系 OS で configure します．

    $ ./configure

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

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

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

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

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

# インストール

## UNIX 系 OS

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

    $ su
    # make 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 の設定ファイル(.htaccess は不可)に，以下のように記述 します．(* 印がついているものは必須) テンプレートは，tmpl ディレクトリに入っている 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 に設置する場合の設定例は以下のようになります．/css や /thumb の Alias は必須ではありません．テンプレートを書き換えたくない 場合に指定してみてください．(これはあくまでも例です．ディレクトリや ファイルのパスは環境よって違ってきます)

    <Location /up>
        SetHandler              uploader

        Url                     "http://acapulco.dyndns.org/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/view.htm"
        ProgressTemplateFile    "Z:/prog/Apache/Uploader/tmpl/progress.htm"
        DownloadTemplateFile    "Z:/prog/Apache/Uploader/tmpl/download.htm"
        ThumbTemplateFile       "Z:/prog/Apache/Uploader/tmpl/thumbnail.htm"
        ErrorTemplateFile       "Z:/prog/Apache/Uploader/tmpl/error.htm"
    </Location>

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

## ImageMagick の設定

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

## 注意事項

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

# 起動

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

# お試し実行

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

    $ su
    # make start

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

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

    # make 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 」のように文字化けしている場合，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"'
    設定漏れがあります．

## icc でコンパイルすると，エラー画面が出ずに Internal Server Error になってしまう．

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

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