Found in chiark:/info

diff --git a/www-cgi/user-cgi.text b/www-cgi/user-cgi.text
new file mode 100644 (file)
index 0000000..88676ea
--- /dev/null
+++ b/www-cgi/user-cgi.text
@@ -0,0 +1,96 @@
+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