doc/apache/INSTALL

   1 ===========================
   2 == suPHP Apache module   ==
   3 ===========================
   4
   5 Installation
   6 ------------
   7
   8 1. Introduction
   9
  10 The suPHP Apache module together with suPHP itself provides an easy way to
  11 run PHP scripts with different users on the same server.
  12
  13 It provides security, because the PHP scripts are not run with the rights of
  14 the webserver's user.
  15 In addition to that you probably won't have to use PHP's "safe mode", which
  16 applies many restrictions on the scripts.
  17
  18 Please be sure to have read the README file in this directory and both the
  19 README and the INSTALL file in the main directory of the suPHP distribution.
  20
  21
  22 2. The simple facts
  23
  24 In this part, I'll give the most important information for people who know
  25 how to compile the Apache Server with additional modules.
  26 If you aren't familiar with doing this, you'll find a step-by-step guide in
  27 the third part of this manual.
  28
  29 mod_suphp only consists of one file, called "mod_suphp.c".
  30 If the suphp binary is not in the default path (/usr/sbin/suphp) you'll have
  31 to modify the corresponding line in mod_suphp.c before adding it to your
  32 Apache sources with the "configure" script of Apache.
  33
  34 The easiest way to install mod_suphp is to compile it as a dynamically
  35 loadable module (DSO). If your Apache was compiled with DSO support and
  36 "apxs" is either in your path or you specified the path to it when running
  37 "configure", mod_suphp will automatically be compiled when doing "make" and
  38 installed to your Apache server (when doing "make install").
  39
  40 Information on how to configure mod_suphp can be found in the "CONFIG" file
  41 in this directory.
  42
  43 Please note that mod_suphp was developped for Apache 1.3.2x and Apache
  44 2.0.x. It might not work with other version.
  45
  46 suPHP was developped for Linux, perhaps it'll also work with some other
  47 *NIX-systems. I have heard that there is a suPHP port for FreeBSD, however
  48 as I do not have running FreeBSD on any system at the moment I cannot test
  49 which modifications have to be made to the current version to run it on
  50 suPHP. If you know, tell me and a will try to modify the GNU autoconf
  51 scripts to make decisions automatically.
  52
  53 If you have tested it with another system and it works, please tell me.
  54
  55
  56 3. Step-by-step guide
  57
  58 If you have already running Apache with mod_so (DSO-support), mod_suphp
  59 should have been installed to your Apache server automatically.
  60
  61 It it is not working look for the two lines
  62  LoadModule suphp_module       /usr/lib/httpd/mod_suphp.so
  63 and
  64  AddModule mod_suphp.c
  65 in your "httpd.conf".
  66
  67 Sometimes "apxs" adds this lines at the wrong locations. In this case you
  68 will have to move them to the appropriate position (see the Apache
  69 documentation for details).
  70
  71 To compile Apache from scratch with mod_suphp (statically) proceed with the
  72 following steps:
  73
  74 If necessary change the path to the suPHP executable in "mod_suphp.c".
  75
  76 Get the Apache sources from http://www.apache.org and unpack them.
  77 Now go into the newly created directory. And run "./configure --help" which
  78 will output some really useful information about the configure-script.
  79
  80 Now run the configure script with the parameters that match your needs but
  81 add the option "--add-module=/path/to/mod_suphp.c".
  82
  83 This will copy mod_suphp.c to the Apache sources and activate it.
  84
  85 Now you can "make" Apache and install it using "make install".
  86
  87 Please note that suPHP will probably not work if you also compile in mod_php.
  88
  89 To use suPHP to parse PHP-Files add a line like
  90
  91 AddType application/x-httpd-php .php
  92
  93 to your Apache configuration and to activate mod_suphp for the appropriate
  94 VHosts.
  95
  96 You can turn mod_suphp on by adding the line
  97
  98 suPHP_Engine on
  99
 100 to your global Apache-configuration.
 101 This will activate mod_suphp for all VirtualHosts.
 102
 103 Please note that you have to specify at least one suPHP_AddHandler
 104 directive, because mod_suphp by default handles no mime-type.
 105
 106 Example:
 107
 108 suPHP_AddHandler application/x-httpd-php
 109
 110 If you are using "paranoid" or "force" mode, you have to specify
 111 at least one suPHP_UserGroup directive.
 112
 113 Information about additional options can be found in the "CONFIG"-Readme.
 114
 115 4. Additional information
 116
 117 Please note, that running mod_suphp and mod_php concurrently can be
 118 *VERY DANGEROUS* and should be avoided. The same applies to CGI
 119 scripts which are run with webserver privileges.
 120
 121 suPHP should only be used if you are using no CGI scripts or if all CGI
 122 scripts are run using suExec.
 123
 124
 125 ===================================
 126 (c)2002-2007 by Sebastian Marsching
 127 <sebastian@marsching.com>
 128 Please see LICENSE for
 129 additional information