[hcoop/zz_old/debian/suphp.git] / doc / apache / INSTALL

===========================
== suPHP Apache module   ==
===========================

Installation
------------

1. Introduction

The suPHP Apache module together with suPHP itself provides an easy way to
run PHP scripts with different users on the same server.

It provides security, because the PHP scripts are not run with the rights of
the webserver's user.
In addition to that you probably won't have to use PHP's "safe mode", which
applies many restrictions on the scripts.

Please be sure to have read the README file in this directory and both the
README and the INSTALL file in the main directory of the suPHP distribution.


2. The simple facts

In this part, I'll give the most important information for people who know
how to compile the Apache Server with additional modules.
If you aren't familiar with doing this, you'll find a step-by-step guide in
the third part of this manual.

mod_suphp only consists of one file, called "mod_suphp.c".
If the suphp binary is not in the default path (/usr/sbin/suphp) you'll have
to modify the corresponding line in mod_suphp.c before adding it to your
Apache sources with the "configure" script of Apache.
 
The easiest way to install mod_suphp is to compile it as a dynamically
loadable module (DSO). If your Apache was compiled with DSO support and
"apxs" is either in your path or you specified the path to it when running
"configure", mod_suphp will automatically be compiled when doing "make" and
installed to your Apache server (when doing "make install").

Information on how to configure mod_suphp can be found in the "CONFIG" file
in this directory.

Please note that mod_suphp was developped for Apache 1.3.2x and Apache
2.0.x. It might not work with other version.

suPHP was developped for Linux, perhaps it'll also work with some other
*NIX-systems. I have heard that there is a suPHP port for FreeBSD, however
as I do not have running FreeBSD on any system at the moment I cannot test
which modifications have to be made to the current version to run it on
suPHP. If you know, tell me and a will try to modify the GNU autoconf
scripts to make decisions automatically.

If you have tested it with another system and it works, please tell me.


3. Step-by-step guide

If you have already running Apache with mod_so (DSO-support), mod_suphp
should have been installed to your Apache server automatically.

It it is not working look for the two lines
 LoadModule suphp_module       /usr/lib/httpd/mod_suphp.so
and
 AddModule mod_suphp.c
in your "httpd.conf".

Sometimes "apxs" adds this lines at the wrong locations. In this case you
will have to move them to the appropriate position (see the Apache
documentation for details).

To compile Apache from scratch with mod_suphp (statically) proceed with the 
following steps:

If necessary change the path to the suPHP executable in "mod_suphp.c".

Get the Apache sources from http://www.apache.org and unpack them.
Now go into the newly created directory. And run "./configure --help" which
will output some really useful information about the configure-script.

Now run the configure script with the parameters that match your needs but
add the option "--add-module=/path/to/mod_suphp.c".

This will copy mod_suphp.c to the Apache sources and activate it.

Now you can "make" Apache and install it using "make install".

Please note that suPHP will probably not work if you also compile in mod_php.

To use suPHP to parse PHP-Files add a line like

AddType application/x-httpd-php .php

to your Apache configuration and to activate mod_suphp for the appropriate
VHosts.

You can turn mod_suphp on by adding the line

suPHP_Engine on

to your global Apache-configuration.
This will activate mod_suphp for all VirtualHosts.

Please note that you have to specify at least one suPHP_AddHandler
directive, because mod_suphp by default handles no mime-type.

Example:

suPHP_AddHandler application/x-httpd-php

If you are using "paranoid" or "force" mode, you have to specify
at least one suPHP_UserGroup directive.

Information about additional options can be found in the "CONFIG"-Readme.

4. Additional information

Please note, that running mod_suphp and mod_php concurrently can be 
*VERY DANGEROUS* and should be avoided. The same applies to CGI 
scripts which are run with webserver privileges.

suPHP should only be used if you are using no CGI scripts or if all CGI
scripts are run using suExec.


===================================
(c)2002-2007 by Sebastian Marsching
<sebastian@marsching.com>
Please see LICENSE for
additional information
Commit	Line	Data
623e7ab4	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