# README for mod_uploader

(言語: | | )

Contents

- mod_uploader とは?
- 機能比較
- 動作サンプル
- 動作環境
  - 各環境で必要になる主なパッケージ
    - CentOS
    - Debian
    - FedoraCore
    - FreeBSD
    - Gentoo Linux
    - Ubuntu Linux
- ライセンス
- ダウンロード
- CVS リポジトリ
- 変更履歴
- コンパイル方法
  - 各環境での例
    - CentOS, FedoraCore, Gentoo Linux, Ubuntu Linux
    - FreeBSD
    - Mac OSX Tiger + Fink
  - トラブルシューティング
    - /usr/bin/ld: cannot find -lxxx
- インストール
- 設定
  - 注意事項
- 起動
  - トラブルシューティング
    - Apache が起動しなくなった
    - 進捗情報が常に Server Busy となる
    - ダウンロードカウンタがリセットされた
- お試し実行
- 高度な設定
  - アップロードの記録
- パフォーマンス
  - 高速な表示
  - 省メモリのアップロード
- テスト結果
- API ドキュメント
- ツール
- 寄付
- 参考文献

# mod_uploader とは?

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

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

# 機能比較

他のアップローダとの機能比較を下記に示します．

# 動作サンプル

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

# 動作環境

mod_uploader は，UNIX 系 OS で動作します．( Windows 版はこちら)

- Apache 2.0 以上
- GNU Compiler Collection 3.3 以上，または， Intel C++ Compiler for Linux 9.1 以上
- GNU Make 3.8 以上
- GNU Libtool 1.5 以上
- ImageMagick 6.0 以上

開発は， Gentoo Linux Kernel 2.6.20 ，GCC 3.4.5 ，Apache 2.0.58 ，ImageMagick 6.3.3 で行っています．

## 各環境で必要になる主なパッケージ

### CentOS

- gcc-c++
- make
- libtool
- httpd-devel
- ImageMagick-c++-devel

### Debian

- libtool
- apache2-mpm-prefork
- apache2-prefork-dev
- libmagick++6-dev

### FedoraCore

- gcc-c++
- make
- libtool
- httpd-devel
- ImageMagick-c++-devel
- freetype-devel
- fontconfig-devel

### FreeBSD

- www/apache20 or www/apache22
- graphics/ImageMagick

### Gentoo Linux

- gcc
- make
- libtool
- apache
- imagemagick

### Ubuntu Linux

- g++
- apache2-mpm-prefork
- apache2-prefork-dev
- libmagick++9-dev

# ライセンス

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

# ダウンロード

- mod_uploader-2.5.0.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 checkout -P mod_uploader

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

# 変更履歴

ChangeLog

# コンパイル方法

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

    $ ./configure
    $ make apache-module

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

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

とします．

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

--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-empty-comment
  空のコメントを受け付ける場合に指定してください．
--enable-empty-password
  空のパスワードによる削除を受け付ける場合に指定してください．
--enable-thumbnail
  ファイルのサムネイル画像を生成したい場合に指定してください．
--enable-numname = NAME
  ダウンロード時のファイル名を NAMEファイル番号.拡張子 のように，ファ イル番号を使用したものにします．
--with-mconf = MCONF
  Magick++-config コマンドのパスを指定します．自動的に検出されない場 合に使用してください．

## 各環境での例

### CentOS, FedoraCore, Gentoo Linux, Ubuntu Linux

    $ ./configure
    $ make apache-module

### FreeBSD

    $ ./configure
    $ gmake apache-module

### Mac OSX Tiger + Fink

    $ ./configure
    $ env MACOSX_DEPLOYMENT_TARGET=10.4 make apache-module

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

### /usr/bin/ld: cannot find -lxxx

必要なライブラリがインストールされていないのが原因です．cannot find -l xxx というエラーの場合，lib xxx がインストールされていません．通常， これらのライブラリは，パッケージ管理システムが依存関係に基づいて自動的 にインストールされるものですが，何らかの事情によりうまくインストールさ れなかった場合このエラーが発生します．

ライブラリを手動でインストールすることでエラーを解決できます．例えば cannot find -lgs というエラーの場合，Ghostscript をインストールします． CentOS/FedoraCore の場合，下記のようにします．

    $ su
    # yum install ghostscript

# インストール

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

    $ su
    # make -f GNUmakefile.apache install

# 設定

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

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

        UploaderBaseUrl                アップローダの URL *

        UploaderDataDirectory          データを保存するフォルダ *
        UploaderFileDirectory          ファイルを保存するフォルダ *
        UploaderThumbDirectory         サムネイルを保存するフォルダ *
        UploaderTempDirectory          一時ファイルを保存するフォルダ *

        UploaderTotalFileSizeLimit     ファイルサイズの合計の上限 (KB)
        UploaderTotalFileNumberLimit   ファイルの個数の上限
        UploaderFileSizeLimit          一回にアップロードできるファイルの最大サイズ (KB)
        UploaderPerPageItemNumber      1 ページあたりに表示するアイテム数

        UploaderIndexViewTemplate      トップページのテンプレート *
        UploaderProgressViewTemplate   アップロード進捗ページのテンプレート *
        UploaderDownloadViewTemplate   ダウンロードページのテンプレート *
        UploaderThumbnailViewTemplate  サムネイルページのテンプレート *
        UploaderAdminViewTemplate      管理ページのテンプレート *
        UploaderErrorViewTemplate      エラーページのテンプレート *
    </Location>
    <Location アップローダを設置する場所/admin>
        Order                   Deny,Allow
        Deny                    From All
        Allow                   From 127.0.0.1
    </Location>

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

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

    <Location /up>
        SetHandler                     uploader

        UploaderBaseUrl                "http://foo/up"
        UploaderDataDirectory          "/path/to/mod_uploader/test/data"
        UploaderFileDirectory          "/path/to/mod_uploader/test/file"
        UploaderThumbDirectory         "/path/to/mod_uploader/test/thumb"
        UploaderTempDirectory          "/path/to/mod_uploader/test/temp"

        UploaderTotalFileSizeLimit     10485760
        UploaderTotalFileNumberLimit   200
        UploaderFileSizeLimit          1048576
        UploaderPerPageItemNumber      30

        UploaderIndexViewTemplate      "/path/to/mod_uploader/tmpl/index.htm"
        UploaderProgressViewTemplate   "/path/to/mod_uploader/tmpl/progress.htm"
        UploaderDownloadViewTemplate   "/path/to/mod_uploader/tmpl/download.htm"
        UploaderThumbnailViewTemplate  "/path/to/mod_uploader/tmpl/thumbnail.htm"
        UploaderAdminViewTemplate      "/path/to/mod_uploader/tmpl/admin.htm"
        UploaderErrorViewTemplate      "/path/to/mod_uploader/tmpl/error.htm"
    </Location>

    <Location /up/admin>
        Order                   Deny,Allow
        Deny                    From All
        Allow                   From 127.0.0.1
    </Location>

    Alias /up_img                  "/path/to/mod_uploader/img"
    Alias /up_css                  "/path/to/mod_uploader/css"
    Alias /up_js                   "/path/to/mod_uploader/js"

## 注意事項

- Apache の動作に不慣れなうちは，ディレクトリやファイルの指定には絶対パ スを使用してください．
- FileDirectory ， ThumbDirectory ， TempDirectory の各ディレクト リは， Apache が読み書き実行できるパーミッションに設定されている必要 があります．
- FileDirectory ， ThumbDirectory には mod_uploader が生成するファ イル以外を置かないでください．
- <Location> で指定するパスには「~」を含めないでください．
- <Loadtion> で設定した mod_uploader の設置場所と同じパスにディレクト リやファイルを置かないでください．例えば，DocumentRoot が /var/www で，`/up` に mod_uploader を設置する場合，`/var/www/up` というディレ クトリが存在するとエラーになります．
- 設定によっては，テンプレートを一部書き換えないと正常に表示されません． 適宜書き換えてください．

# 起動

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

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

### Apache が起動しなくなった

Apache のエラーログにエラー内容が出力されているので，内容を確認して設定 を見直してください．

### 進捗情報が常に Server Busy となる

UploaderBaseUrl と違うアドレスでアップローダにアクセスした場合に発生し ます．例えば，UploaderBaseUrl では http://localhost/up と指定している のに，ブラウザでは http://127.0.0.1/up にアクセスしている場合がこれに 該当します．

UploaderBaseUrl で指定したアドレスでアクセスしてください．

### ダウンロードカウンタがリセットされた

mod_uploader は，高速動作のため，ダウンロードカウンタのカウントアップを メモリ上でのみ行っており，Apache の終了時にデータをファイルに書き出すよ うになっています．そのため，Apache が正常に終了しなかった場合，ファイル への書き出しが行われずダウンロードカウンタが以前の状態にリセットされて しまいます．

# お試し実行

次のコマンドを入力して，http://localhost:8080/up/ にアクセスすることで することでインストールせずに動作を確認できます．

他のホストからアクセスする場合は， localhost の部分を適当に置き換えて ください．

    $ su -
    # make -f GNUmakefile.apache start

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

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

    # make -f GNUmakefile.apache stop

# 高度な設定

## アップロードの記録

mod_uploader はファイルのアップロード時に環境変数 uploader_upload を 定義するので，以下の様な設定を追加することで投稿者の IP アドレスをログ に記録する事が出来ます．

    LogFormat "%t HOST: %h ID: %{uploader_item_id}e AGENT: %{User-agent}i" uploader
    CustomLog log/apache.upload_log uploader env=uploader_upload

uploader_item_id は，ファイルの ID に展開されます．その他の書式について は， mod_log_config のドキュメント を参照 してください．

なお，ファイルのダウンロード時と削除時にも，環境変数 uploader_download ， uploader_remove を定義するので，同様の方法でロ グをとることが可能です．

# パフォーマンス

## 高速な表示

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

# 寄付

PayPal 経由での寄付を受け付けています．mod_uploader が気に入った場合は よろしくお願いします．いただいたお金は開発のための書籍購入などにあてさ せていただきます．

# 参考文献

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

The Apache Modules Book: Application Development With Apache
  Apache 2.x のモジュール作成に必要になるのモジュール作成に必要にな る事柄を一通り説明した本．トップダウンで全体を眺めた後，ボトムアップ で詳しい説明がされているので非常に理解しやすいです．
Apacheモジュール プログラミングガイド
  Apache 1.x のモジュール作成に必要になる事柄を一通り説明した本．痒 いところに手が届いているので，手元に置いておくと重宝します．
Secure Coding in C And C++
  C/C++ でプログラムを作るときにセキュリティホールが発生してしまう原理と その対策について詳しく説明した本です．丁寧に書かれているので内容を しっかりと理解することができます．
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
  コンパイラ作成に関する実践的な内容が簡潔にまとめられたサイト．簡単な インタプリタもどきを作るんだったら，このサイトだけで十分かも．