
                     ======================================
                         mod_upload installation notes 
                        version 0.4 releases 2017-11-06
                     ======================================

                       Emmanuel Dreyfus <manu@netbsd.org>


 Table of contents:  
 1 Why mod_upload
 2 Building and installing mod_upload
 3 Apache configuration
 4 Sample configuration
 5 bugs
 6 License

Run this command to regenerate a table of contents:
 sed '/^.====/{g;p;};h;d' README


 1 Why mod_upload
 ================

This module can be used to manage file uploads in Apache standalone,
or it can be used as a PHP helper (see UploadCompatPHP option).

The module provides a performance improvement over PHP native
mechanism when it comes to network filesystems. When writint to 
a remote filesystem, latency will kill performance if write block
size is too small. mod_upload can set the write block size using
the UploadBlockSize option.


 2 Building and installing mod_upload
 ====================================

Just run usual configure && make && make install

Configure options:
 --with-apxs       Path to Apache apxs
 --with-php_config Path to PHP php-config

php-config is required to suppor the UploadCompatPHP option

 3 Apache configuration
 ======================

Here are mod_upload configuration directives

UploadEnable      Enable upload filter (on, off)

UploadDir         Set upload directory
                  Uploaded files will be saved there

UploadPrefix      Set upload form field prefix for files
                  PHP will see usual $_FILES data in $_POST['prefix'] 

UploadCommit      Set upload commit mode (on, off, force)
                  off: the file is uploaded with temporary name
                  on: after upload the file is moved to requested name
                  force: same as on but overwrites existing file

UploadFormSize    Provide hint number of form fields
                  This is a hint only

UploadBlockSize   Set file write block size in bytes
                  Big block size are good for network filesystems

UploadTimeout     Set file write timeout in seconds

UploadCompatPHP   Let PHP's is_uploaded_file() and move_uploaded_file()
                  accept the files, and generates $_FILES


 4 Sample configuration
 ======================

/etc/httpd/httpd.conf
  LoadModule upload_module      lib/httpd/mod_upload.so

  <Location /upload>
   MellonEnable Off
   Require all granted
   SecRuleEngine  Off
   UploadEnable On
   UploadCompatPHP On
   UploadCommit Off
   UploadBlockSize 1000000
   UploadDir /htdocs/upload
  </Location>


 5 bugs
 ======

- mod_security will bug on CRS 200004 "Multipart parser detected a possible 
  unmatched boundary"
- mod_security content inspection will kill performances will big files. 
  SecRuleEngine Off is advised
- Apache LimitRequestBody default is 1GB since apache-2.4.53.-, it was 
  0 (inifinite) before. Increase the value to upload files bigger than
  1GB.

 6 License
 =========

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.
 
   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
   


