Found in chiark:/info

[userv-utils] / www-cgi / user-cgi.text

Users can now arrange to have CGI scripts run by chiark's webserver.
This is achieved using userv (see /info/new 183, /usr/doc/userv and
<URL:http://www.chiark.greenend.org.uk/~ian/userv/>).

Before you write such scripts you should be aware of the security
issues involved.  Please read /info/cgi-security.text !

Note that public-cgi programs (and their source code) should be world
readable, and in any case by creating them you give me implicit
permission to read its contents, using my system privilege if
necessary, without notifying you.  See cgi-security.text for full
details of the policy.

Paths in chiark's http space of the form
  /ucgi/~<username>/<path-to-script>/<extra-stuff>...
will be taken to refer to the CGI script
  ~<username>/public-cgi/<path-to-script>
and /<extra-stuff> will be used as the PATH_INFO (as is
conventional).  For example,
  http://www.chiark.greenend.org.uk/ucgi/~ijackson/spong/foo?bar=baz
will run ~ijackson/public-cgi/spong with PATH_INFO set to `/foo' and
QUERY_STRING set to `bar=baz'.

You can debug your scripts by using
 /ucgi-debug/~<username>/<path-to-script>...
which will return a text/plain document consisting of the standard
output and standard error of your script and a line at the bottom with
the high and low bytes of the script's exit status.

Also both of
 http://www.chiark.greenend.org.uk/ucgicgi/check
 http://www.chiark.greenend.org.uk/ucgi/~ijackson/check
are scripts which will dump their arguments and environment as a
text/plain output file.  This can be used to see what input your CGI
program ought to expect.

The default configuration does not enable userv's `set-environment'
feature, so the environment your scripts in will be rather minimal.
You can change this it if you want by saying something like
  if glob service www-cgi
          set-environment
  fi
in your ~/.userv/rc file.  This will cause your scripts to be run by a
shell which has sourced your ~/.environment file, if it exists.  See
the userv documentation for details, and look in /etc/environment.

CGI programs will be run in your account.  They will be able to access
files exactly as if you had run them yourself directly.  Their PATH
and other similar variables will be set correctly (see below) and can
and should be trusted.

However, their arguments, input and webserver-provided environment
variables (the full list is in /usr/local/src/davenant/ucgicommon.c)
will have come from the client WWW browser and are highly
untrustworthy.  This means you must be very careful when writing such
programs.  Beware particularly of
  * buffer overruns in C
  * trusting data not to have metacharacters.
    You should generally not pass client-provided data to
    - eval (Perl or shell)
    - system (Perl or C) and exec (Perl)
    - open (Perl) and popen (C)
    - anything similar.

Safely using untrusted client-provided data in shell scripts is very
difficult.  I would recommend against programming CGI scripts in
shell.  If you must, make sure you use appropriate quoting and
argument unparsing everywhere.

The invocation of user-provided CGI scripts is achieved by using userv
to invoke the `www-cgi' service.  The webserver-provided environment
variables will be passed as userv parameters using
-DE_<variable>=<value>.  The E_PATH_INFO parameter contains the
portion of the path beyond the username.

The default configuration (/etc/userv/system.default) arranges for
www-cgi to run /usr/local/lib/user-cgi/target, which removes the
USERV_E_ from the start of the webserver-provided environment
variables and adjusts some of them for the script's actual location
and the calls the actual script.  `target' takes one parameter, the
location of the user's public CGI directory relative to their home
directory (`public-cgi' in the default configuration).  It must be a
relative path.

You can run your own scripts from the command line by saying
  userv -DE_PATH_INFO=/<script>[/<path-info>]                 \
        -DE_QUERY_STRING=<query> --spoof-user www - www-cgi   \
        [<arg-for-isindex-query>]

CGI programs' path components may not be empty, may not start with a
full stop `.', and may not end with a hash `#' or tilde `~'.

Please report problems to webmaster@chiark or sysadmin@chiark.
Comments on userv should go to userv-maint@chiark.greenend.org.uk.

 - Ian Jackson 14.07.1998