README for mod_uploader

mod_uploader: file upload application works as Apache module

Contents

What is mod_uploader

mod_uploader is a file upload application works as Apache module. The following features are provided:

Screenshot of progress report

Preparing system

mod_uploader works on Unix-like systems such as Linux, FreeBSD, and Max OSX. (Windows Windows edition is here)

mod_uploader is developed under Gentoo Linux Kernel 2.6.20 , GCC 3.4.5 , Apache 2.0.58, and ImageMagick 6.3.3.

Package requirement

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

License

mod_uploader is distributed under the terms of The zlib/libpng License.

Download

GitHub

Building

If you use GNU Compiler Collection, use the following commands:

$ ./configure
$ make

If you use Intel C++ Compiler, use the following commands:

$ env CC=icc ./configure
$ make

Configure options

If configure is failed, try --with-apxs , --with-apctl2, or --with-aprconf option.

--with-apxs = APXS
Specify the path to apxs command.
--with-apctl2 = APCTL
Specify the path to apachectl command.
--with-aprconf = APRCONF
Specify the path to apr-config command.
--with-libtool = LIBTOOL
Specify the path to libtool command.
--with-march = CPU
If you want to optimize code for particular CPU, specify this option. For example, if you want to optimize for Pentium 4, specify --with-march=pentium4.
--enable-empty-comment
If you want to accept file with empty comment, specify this option.
--enable-empty-password
If you want to accept empty password to remove files, specify this option.
--enable-thumbnail
If you want to make thumbnail of image files, specify this option.
--with-mconf = MCONF
Specify the path to Magick++-config command.

Command examples

FreeBSD

$ ./configure
$ gmake

Mac OSX Tiger + Fink

$ ./configure
$ env MACOSX_DEPLOYMENT_TARGET=10.4 make

Installation

$ su
# make -f GNUmakefile.apache install

Setting

Add the following setting to the apache configuration file (.htaccess is not permitted).

<Location "Place where uploader is set up (URL path, not file system path)">
    SetHandler                     uploader

    UploaderDataDirectory          Path of the direcory where meta data is saved
    UploaderFileDirectory          Path of the direcory where file is saved
    UploaderThumbDirectory         Path of the direcory where thumbnail image is saved
    UploaderTempDirectory          Path of the direcory where temporary file is saved

    UploaderTotalFileSizeLimit     Limit of total file size (KB)
    UploaderTotalFileNumberLimit   Limit of number of files
    UploaderFileSizeLimit          Limit of size per file (KB)
    UploaderPerPageItemNumber      Number of files showed in one page

    UploaderIndexViewTemplate      Template of top page (use index.htm)
    UploaderInfoViewTemplate       Template of info page (use info.htm)
    UploaderProgressViewTemplate   Template of progress reporting page (use progress.htm)
    UploaderDownloadViewTemplate   Template of download page (use download.htm)
    UploaderThumbnailViewTemplate  Template of thumbnail page (use thumbnail.htm)
    UploaderAdminViewTemplate      Template of administration page (use admin.htm)
    UploaderErrorViewTemplate      Template of error page (use error.htm)
</Location>
<Location "Place where uploader is set up (URL path, not file system path)"/admin>
    Order                   Deny,Allow
    Deny                    From All
    Allow                   From 127.0.0.1
</Location>

UploaderBaseUrl             The URL of uploader

Please use index.htm, info.htm, progress.htm, download.htm, thumbnail.htm, admin.htm, and error.htm that exists in the tmpl/en directory as template file.

For example, if you want to set up mod_uploader at http://foo/up/, use the following setting. Alias of /up_img, /up_css, and /up_js is not indispensable. If you do not want to edit template file, use those aliases.

<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/en/index.htm"
    UploaderInfoViewTemplate       "/path/to/mod_uploader/tmpl/en/info.htm"
    UploaderProgressViewTemplate   "/path/to/mod_uploader/tmpl/en/progress.htm"
    UploaderDownloadViewTemplate   "/path/to/mod_uploader/tmpl/en/download.htm"
    UploaderThumbnailViewTemplate  "/path/to/mod_uploader/tmpl/en/thumbnail.htm"
    UploaderAdminViewTemplate      "/path/to/mod_uploader/tmpl/en/admin.htm"
    UploaderErrorViewTemplate      "/path/to/mod_uploader/tmpl/en/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"

Notes

  • Absolute path is recommended to specify directory and file, if you are not accustomed to Apache setting.

  • It is necessary to set each directory of FileDirectory, ThumbDirectory, and TempDirectory to the permission that Apache can read and write.

  • Please do not put any files on FileDirectory and ThumbDirectory excluding those that mod_uploader generates.

  • You can not include "~" in the path specified for <Location>.

  • Do not make directory or file at the path specified by <Loadtion>, where mod_uploader is set up.

    For example, if DocumentRoot is /var/www and sets up mod_uploader at /up, directory must not exist at /var/www/up.

  • According to the setting, it is not normally displayed. Please modify templates properly.

Run

Star Apache as usual. Access the address you set up mod_uploader.

Troubleshooting

Apache did not start

Please check error log of Apache. The error messages you see may be self-explanatory enough to enable you to diagnose and fix the problem.

Progress report is always Server Busy

This problem occurs, if you access mod_uploader through an address different from UploaderBaseUrl. For example, UploaderBaseUrl is set to http://localhost/up and you access http://127.0.0.1/up.

Please access mod_uploader through the address specified for UploaderBaseUrl.

Download counter was reset

mod_uploader manages download counts on memory for high-speed operation, and when Apache is stopped, those data is written file.

Therefore, if Apache does not stop normally, download counter is reset.

Run without installation

You can run mod_uploader without installation. Use the following command, and access http://localhost:8080/up/.

If you access from other computer, modify the part of localhost properly.

$ su -
# make -f GNUmakefile.apache start

If error related to LoadModule occured, please correct conf/en/apache.conf properly. To stop mod_uploader, use the following command:

# make -f GNUmakefile.apache stop

Tests

Resut of tests

API Document

http://green-rabbit.sakura.ne.jp/mod_uploader/api/

Reference

The Apache Modules Book Secure Coding in C And C++