Commit | Line | Data |
---|---|---|
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 | ||
9028e234 IJ |
88 | userv-utils are |
89 | Copyright 1996-2013 Ian Jackson <ijackson@chiark.greenend.org.uk> | |
90 | Copyright 1998 David Damerell <damerell@chiark.greenend.org.uk> | |
91 | Copyright 1999,2003 | |
92 | Chancellor Masters and Scholars of the University of Cambridge | |
93 | Copyright 2010 Tony Finch <fanf@dotat.at> | |
94 | ||
95 | All the utilities here are free software; you can redistribute it and/or | |
96 | modify it under the terms of the GNU General Public License as published by | |
97 | the Free Software Foundation; either version 3 of the License, or (at your | |
98 | option) any later version. | |
a33962ba | 99 | |
100 | This program is distributed in the hope that it will be useful, but | |
101 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
102 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
103 | General Public License for more details. | |
104 | ||
105 | You should have received a copy of the GNU General Public License | |
9028e234 | 106 | along with userv-utils; if not, see http://www.gnu.org/licenses/. |