a33962ba |
1 | Users can arrange to have CGI scripts run by the webserver. |
2 | This is achieved using userv (see |
9a7d9296 |
3 | <URL:http://www.chiark.greenend.org.uk/~ian/userv/>). |
4 | |
5 | Before you write such scripts you should be aware of the security |
a33962ba |
6 | issues involved. |
9a7d9296 |
7 | |
a33962ba |
8 | Paths in the http space of the form |
9a7d9296 |
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, |
a33962ba |
14 | http://www.example.com/ucgi/~ijackson/spong/foo?bar=baz |
9a7d9296 |
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 | |
a33962ba |
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. |
9a7d9296 |
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 |
a33962ba |
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 |
9a7d9296 |
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 |
a33962ba |
58 | argument unparsing everywhere (and don't do it if you don't know what |
59 | I mean by argument unparsing). |
9a7d9296 |
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 | |
a33962ba |
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 | |
711a0748 |
88 | Copyright (C) 1998-1999,2003 Ian Jackson |
a33962ba |
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. |
9a7d9296 |
103 | |
a33962ba |
104 | $Id$ |