www-cgi/: Document customisable environment filters

This feature was documented in the commit message, but not in the
tree.

Introduce a straight copy of the commit message from
 f7b4be5a "www-cgi/: Allow customization of the environment filters."

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

1 files changed, 23 insertions, 0 deletions

diff --git a/www-cgi/README.custom-env-filter b/www-cgi/README.custom-env-filter
new file mode 100644
index 0000000..245d071
--- /dev/null
+++ b/www-cgi/README.custom-env-filter
@@ -0,0 +1,23 @@
+www-cgi/: Allow customization of the environment filters.
+    
+Sites can now configure `ucgi's environment filters, and end users can
+configure `ucgitarget's filters.
+
+By default, `ucgi' will look in `/etc/userv/ucgi.env-filter', but if
+`UCGI_ENV_FILTER' is set in its environment, it will look there
+instead.  The filter may contain wildcards and so on.
+
+By default, `ucgitarget' looks in `.userv/ucgitarget.env-filter', or
+`/etc/userv/ucgitarget.env-filter', if the former doesn't exist; but if
+passed a `-e FILTER' option on its command line, it will look in the
+file FILTER instead.  This filter may /not/ contain wildcards.
+
+In both cases, if an explicitly named filter file can't be found then
+the program fails; if the default filter files can't be found then they
+fall back to built-in lists.
+
+The reason for the asymmetry in interfaces is: it's hard to pass
+command-line options to CGI scripts from webservers, but pretty easy to
+set environment variables; whereas it's hard to pass environment
+variables to a service program in a Userv configuration file, but easy
+to pass command-line arguments.