ucgi/user-cgi.text

   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 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.
  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
 106 along with userv-utils; if not, see http://www.gnu.org/licenses/.