| 1 | Users can arrange to have CGI scripts run by the webserver. |
| 2 | This is achieved using userv (see |
| 3 | <URL:http://www.chiark.greenend.org.uk/~ian/userv/>). |
| 4 | |
| 5 | Before you write such scripts you should be aware of the security |
| 6 | issues involved. |
| 7 | |
| 8 | Paths in the http space of the form |
| 9 | /ucgi/~<username>/<path-to-script>/<extra-stuff>... |
| 10 | will be taken to refer to the CGI script |
| 11 | ~<username>/public-cgi/<path-to-script> |
| 12 | and /<extra-stuff> will be used as the PATH_INFO (as is |
| 13 | conventional). For example, |
| 14 | http://www.example.com/ucgi/~ijackson/spong/foo?bar=baz |
| 15 | will run ~ijackson/public-cgi/spong with PATH_INFO set to `/foo' and |
| 16 | QUERY_STRING set to `bar=baz'. |
| 17 | |
| 18 | You can debug your scripts by using |
| 19 | /ucgi-debug/~<username>/<path-to-script>... |
| 20 | which will return a text/plain document consisting of the standard |
| 21 | output and standard error of your script and a line at the bottom with |
| 22 | the high and low bytes of the script's exit status. |
| 23 | |
| 24 | Also, /usr/local/lib/user-cgi/cgi/check is a script which will dump |
| 25 | its arguments and environment as a text/plain output file. This can |
| 26 | be used to see what input your CGI program ought to expect. |
| 27 | |
| 28 | The default configuration does not enable userv's `set-environment' |
| 29 | feature, so the environment your scripts in will be rather minimal. |
| 30 | You can change this it if you want by saying something like |
| 31 | if glob service www-cgi |
| 32 | set-environment |
| 33 | fi |
| 34 | in your ~/.userv/rc file. This will cause your scripts to be run by a |
| 35 | shell which has sourced your ~/.environment file, if it exists. See |
| 36 | the userv documentation for details, and look in /etc/environment. |
| 37 | |
| 38 | CGI programs will be run in your account. They will be able to access |
| 39 | files exactly as if you had run them yourself directly. Their PATH |
| 40 | and other similar variables will be set correctly (see below) and can |
| 41 | and should be trusted. |
| 42 | |
| 43 | However, their arguments, input and webserver-provided environment |
| 44 | variables (the full list is in ucgicommon.c) will have come from the |
| 45 | client WWW browser and are highly untrustworthy. This means you must |
| 46 | be very careful when writing such programs. Beware particularly of |
| 47 | * buffer overruns in C |
| 48 | * trusting data not to have metacharacters. |
| 49 | You should generally not pass client-provided data to |
| 50 | - eval (Perl or shell) |
| 51 | - system (Perl or C) and exec (Perl) |
| 52 | - open (Perl) and popen (C) |
| 53 | - anything similar. |
| 54 | |
| 55 | Safely using untrusted client-provided data in shell scripts is very |
| 56 | difficult. I would recommend against programming CGI scripts in |
| 57 | shell. If you must, make sure you use appropriate quoting and |
| 58 | argument unparsing everywhere (and don't do it if you don't know what |
| 59 | I mean by argument unparsing). |
| 60 | |
| 61 | The invocation of user-provided CGI scripts is achieved by using userv |
| 62 | to invoke the `www-cgi' service. The webserver-provided environment |
| 63 | variables will be passed as userv parameters using |
| 64 | -DE_<variable>=<value>. The E_PATH_INFO parameter contains the |
| 65 | portion of the path beyond the username. |
| 66 | |
| 67 | The default configuration (/etc/userv/system.default) arranges for |
| 68 | www-cgi to run /usr/local/lib/user-cgi/target, which removes the |
| 69 | USERV_E_ from the start of the webserver-provided environment |
| 70 | variables and adjusts some of them for the script's actual location |
| 71 | and the calls the actual script. `target' takes one parameter, the |
| 72 | location of the user's public CGI directory relative to their home |
| 73 | directory (`public-cgi' in the default configuration). It must be a |
| 74 | relative path. |
| 75 | |
| 76 | You can run your own scripts from the command line by saying |
| 77 | userv -DE_PATH_INFO=/<script>[/<path-info>] \ |
| 78 | -DE_QUERY_STRING=<query> --spoof-user www - www-cgi \ |
| 79 | [<arg-for-isindex-query>] |
| 80 | |
| 81 | CGI programs' path components may not be empty, may not start with a |
| 82 | full stop `.', and may not end with a hash `#' or tilde `~'. |
| 83 | |
| 84 | It is important that the webserver removes /../ components from the |
| 85 | PATH_INFO - if it doesn't there is a security hole. |
| 86 | |
| 87 | |
| 88 | Copyright (C) 1998-1999,2003 Ian Jackson |
| 89 | |
| 90 | This is free software; you can redistribute it and/or modify it |
| 91 | under the terms of the GNU General Public License as published by |
| 92 | the Free Software Foundation; either version 2 of the License, or |
| 93 | (at your option) any later version. |
| 94 | |
| 95 | This program is distributed in the hope that it will be useful, but |
| 96 | WITHOUT ANY WARRANTY; without even the implied warranty of |
| 97 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 98 | General Public License for more details. |
| 99 | |
| 100 | You should have received a copy of the GNU General Public License |
| 101 | along with userv-utils; if not, write to the Free Software |
| 102 | Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
| 103 | |
| 104 | $Id$ |