| 1 | =========================== |
| 2 | == suPHP == |
| 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 note that the suPHP binary has to be installed setuid-root to work, |
| 19 | so a security bug in suPHP probably will allow atackers to run commands with |
| 20 | root privileges. Although I currently don't know any bug in suPHP I can't |
| 21 | guarantee that there aren't any. |
| 22 | |
| 23 | 2. Installation |
| 24 | |
| 25 | Run ./configure with the appropriate paramters for your system. |
| 26 | |
| 27 | On most systems a |
| 28 | ./configure --prefix=/usr |
| 29 | will suffice. |
| 30 | |
| 31 | The configure script can take the familar GNU autoconf arguments plus the |
| 32 | following 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 | |
| 82 | Now 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 | |
| 85 | If your Apache is running with DSO support and "apxs" was found during the |
| 86 | build process, you are done. Otherwise you have to rebuilt your Apache |
| 87 | server with "mod_suphp.c" included. If you used another prefix during the |
| 88 | suPHP build than "/usr", you have to modify "mod_suphp.c" to set the path to |
| 89 | the suPHP executable (which you can find in $exec_prefix/sbin/suphp). |
| 90 | |
| 91 | Details on how to compile your Apache webserver with mod_suphp can be found |
| 92 | in apache/INSTALL. |
| 93 | |
| 94 | Now, you have to modify your "httpd.conf" to activate suPHP for specific |
| 95 | VHosts. See apache/CONFIG for details on this. |
| 96 | |
| 97 | Please note that in order to make suPHP work, you have to specify at least |
| 98 | one handler in the suPHP configuration file. Read CONFIG for additonal |
| 99 | information about how to configure suPHP. |
| 100 | |
| 101 | =================================== |
| 102 | (c)2002-2008 by Sebastian Marsching |
| 103 | <sebastian@marsching.com> |
| 104 | Please see LICENSE for |
| 105 | additional information |