1 files changed, 106 insertions, 0 deletions
diff --git a/ucgi/user-cgi.text b/ucgi/user-cgi.text
new file mode 100644
index 0000000..464686b
--- /dev/null
+++ b/ucgi/user-cgi.text
@@ -0,0 +1,106 @@
+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/.