www-cgi/user-cgi.text

   1 Users can now arrange to have CGI scripts run by chiark's webserver.
   2 This is achieved using userv (see /info/new 183, /usr/doc/userv and
   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.  Please read /info/cgi-security.text !
   7
   8 Note that public-cgi programs (and their source code) should be world
   9 readable, and in any case by creating them you give me implicit
  10 permission to read its contents, using my system privilege if
  11 necessary, without notifying you.  See cgi-security.text for full
  12 details of the policy.
  13
  14 Paths in chiark's http space of the form
  15   /ucgi/~<username>/<path-to-script>/<extra-stuff>...
  16 will be taken to refer to the CGI script
  17   ~<username>/public-cgi/<path-to-script>
  18 and /<extra-stuff> will be used as the PATH_INFO (as is
  19 conventional).  For example,
  20   http://www.chiark.greenend.org.uk/ucgi/~ijackson/spong/foo?bar=baz
  21 will run ~ijackson/public-cgi/spong with PATH_INFO set to `/foo' and
  22 QUERY_STRING set to `bar=baz'.
  23
  24 You can debug your scripts by using
  25  /ucgi-debug/~<username>/<path-to-script>...
  26 which will return a text/plain document consisting of the standard
  27 output and standard error of your script and a line at the bottom with
  28 the high and low bytes of the script's exit status.
  29
  30 Also both of
  31  http://www.chiark.greenend.org.uk/ucgicgi/check
  32  http://www.chiark.greenend.org.uk/ucgi/~ijackson/check
  33 are scripts which will dump their arguments and environment as a
  34 text/plain output file.  This can be used to see what input your CGI
  35 program ought to expect.
  36
  37 The default configuration does not enable userv's `set-environment'
  38 feature, so the environment your scripts in will be rather minimal.
  39 You can change this it if you want by saying something like
  40   if glob service www-cgi
  41           set-environment
  42   fi
  43 in your ~/.userv/rc file.  This will cause your scripts to be run by a
  44 shell which has sourced your ~/.environment file, if it exists.  See
  45 the userv documentation for details, and look in /etc/environment.
  46
  47 CGI programs will be run in your account.  They will be able to access
  48 files exactly as if you had run them yourself directly.  Their PATH
  49 and other similar variables will be set correctly (see below) and can
  50 and should be trusted.
  51
  52 However, their arguments, input and webserver-provided environment
  53 variables (the full list is in /usr/local/src/davenant/ucgicommon.c)
  54 will have come from the client WWW browser and are highly
  55 untrustworthy.  This means you must be very careful when writing such
  56 programs.  Beware particularly of
  57   * buffer overruns in C
  58   * trusting data not to have metacharacters.
  59     You should generally not pass client-provided data to
  60     - eval (Perl or shell)
  61     - system (Perl or C) and exec (Perl)
  62     - open (Perl) and popen (C)
  63     - anything similar.
  64
  65 Safely using untrusted client-provided data in shell scripts is very
  66 difficult.  I would recommend against programming CGI scripts in
  67 shell.  If you must, make sure you use appropriate quoting and
  68 argument unparsing everywhere.
  69
  70 The invocation of user-provided CGI scripts is achieved by using userv
  71 to invoke the `www-cgi' service.  The webserver-provided environment
  72 variables will be passed as userv parameters using
  73 -DE_<variable>=<value>.  The E_PATH_INFO parameter contains the
  74 portion of the path beyond the username.
  75
  76 The default configuration (/etc/userv/system.default) arranges for
  77 www-cgi to run /usr/local/lib/user-cgi/target, which removes the
  78 USERV_E_ from the start of the webserver-provided environment
  79 variables and adjusts some of them for the script's actual location
  80 and the calls the actual script.  `target' takes one parameter, the
  81 location of the user's public CGI directory relative to their home
  82 directory (`public-cgi' in the default configuration).  It must be a
  83 relative path.
  84
  85 You can run your own scripts from the command line by saying
  86   userv -DE_PATH_INFO=/<script>[/<path-info>]                 \
  87         -DE_QUERY_STRING=<query> --spoof-user www - www-cgi   \
  88         [<arg-for-isindex-query>]
  89
  90 CGI programs' path components may not be empty, may not start with a
  91 full stop `.', and may not end with a hash `#' or tilde `~'.
  92
  93 Please report problems to webmaster@chiark or sysadmin@chiark.
  94 Comments on userv should go to userv-maint@chiark.greenend.org.uk.
  95
  96  - Ian Jackson 14.07.1998