X-Git-Url: https://git.distorted.org.uk/~mdw/userv-utils/blobdiff_plain/186ea161e7d144dd8e3791f174a7173e2f399346..5e217877d0d85c56c881da5c8a11fd253c11fe0a:/ucgi/user-cgi.text
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
+).
+
+Before you write such scripts you should be aware of the security
+issues involved.
+
+Paths in the http space of the form
+ /ucgi/~//...
+will be taken to refer to the CGI script
+ ~/public-cgi/
+and / 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/~/...
+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_=. 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=/