Rename www-cgi to ucgi (in nearly all places)

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

Users can arrange to have CGI scripts run by the webserver.
This is achieved using userv (see
<URL:http://www.chiark.greenend.org.uk/~ian/userv/>).

Before you write such scripts you should be aware of the security
issues involved.

Paths in the 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.example.com/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, /usr/local/lib/user-cgi/cgi/check is a script which will dump
its 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 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 (and don't do it if you don't know what
I mean by argument unparsing).

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 `~'.

It is important that the webserver removes /../ components from the
PATH_INFO - if it doesn't there is a security hole.


userv-utils are
Copyright 1996-2013 Ian Jackson <ijackson@chiark.greenend.org.uk>
Copyright 1998 David Damerell <damerell@chiark.greenend.org.uk>
Copyright 1999,2003
   Chancellor Masters and Scholars of the University of Cambridge
Copyright 2010 Tony Finch <fanf@dotat.at>

All the utilities here are free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with userv-utils; if not, see http://www.gnu.org/licenses/.