Fix permissions to make git-buildpackage shut up
[hcoop/zz_old/debian/suphp.git] / doc / INSTALL
CommitLineData
623e7ab4 1===========================
2== suPHP ==
3===========================
4
5Installation
6------------
7
81. Introduction
9
10The suPHP Apache module together with suPHP itself provides an easy way to
11run PHP scripts with different users on the same server.
12
13It provides security, because the PHP scripts are not run with the rights of
14the webserver's user.
15In addition to that you probably won't have to use PHP's "safe mode", which
16applies many restrictions on the scripts.
17
18Please note that the suPHP binary has to be installed setuid-root to work,
19so a security bug in suPHP probably will allow atackers to run commands with
20root privileges. Although I currently don't know any bug in suPHP I can't
21guarantee that there aren't any.
22
232. Installation
24
25Run ./configure with the appropriate paramters for your system.
26
27On most systems a
28 ./configure --prefix=/usr
29will suffice.
30
31The configure script can take the familar GNU autoconf arguments plus the
32following suPHP specific ones:
33
34--disable-checkpath: With this compile time option suPHP does not check,
35 whether a script (or a symink to it)is inside the
36 DOCUMENT_ROOT. You may want to activate this option
37 if you are working with "Alias"-directives.
38
39--disable-checkuid: You may specify this option to make suPHP work with
40 scripts whose UIDs are not listed in /etc/passwd.
41
42--disable-checkgid: You may specify this option to make suPHP work with
43 scripts whose GIDs are not listed in /etc/group.
44
45--with-apxs=FILE: Path to "apxs" of your Apache installation. If not
46 specified, configure will look for apxs in your PATH.
47 Without apxs the Apache module mod_suphp will not be
48 built. It will not be built either, if your Apache has
49 been compiled without DSO support. Please make sure you
50 specify the right path to apxs, because suPHP will use
51 apxs to check whether to build mod_suphp for Apache 1
52 or Apache 2.
53
54--with-min-uid=UID: The minium UID that suPHP will allow PHP to run scripts
55 with (defaults to 100).
56
57--with-min-gid=GID: The minium GID that suPHP will allow PHP to run scripts
58 with (defaults to 100).
59
60--with-apache-user=USERNAME:
61 Username (not UID) Apache is running as (defaults to
62 wwwrun).
63
64--with-logfile=FILE Path to the suPHP logfile (defaults to
65 /var/log/httpd/suphp_log).
66
67--with-setid-mode=MODE:
68 MODE has to be one of:
69 "owner": Run scripts with owner UID/GID
70 "force": Run scripts with UID/GID specified in Apache
71 configuration
72 "paranoid": Run scripts with owner UID/GID but also check
73 if they match the UID/GID specified in the
74 Apache configuration
75 The default is "paranoid" mode.
76 You should *NEVER* use "force" mode as it is very
77 dangerous.
78 While "owner" mode is not as dangerous as "force" mode
79 its use is disadvised and "paranoid" mode should be
80 preferred.
81
82Now compile suPHP using "make" and if no error occured install it using
83"make install". Be sure to be root, when you try to install it.
84
85If your Apache is running with DSO support and "apxs" was found during the
86build process, you are done. Otherwise you have to rebuilt your Apache
87server with "mod_suphp.c" included. If you used another prefix during the
88suPHP build than "/usr", you have to modify "mod_suphp.c" to set the path to
89the suPHP executable (which you can find in $exec_prefix/sbin/suphp).
90
91Details on how to compile your Apache webserver with mod_suphp can be found
92in apache/INSTALL.
93
94Now, you have to modify your "httpd.conf" to activate suPHP for specific
95VHosts. See apache/CONFIG for details on this.
96
97Please note that in order to make suPHP work, you have to specify at least
98one handler in the suPHP configuration file. Read CONFIG for additonal
99information about how to configure suPHP.
100
101===================================
102(c)2002-2008 by Sebastian Marsching
103<sebastian@marsching.com>
104Please see LICENSE for
105additional information