Document SOCKS_CONF environment variable.

svn path=/branches/BRANCH_6-3/; revision=5054

3 files changed, 38 insertions, 14 deletions

diff --git a/NEWS b/NEWS
index 28703ed2..de7064b7 100644
--- a/NEWS
+++ b/NEWS
@@ -57,7 +57,8 @@ fetchmail 6.3.8 (not yet released):
 # DOCUMENTATION:
 * Extend --mda documentation, discourage use of qmail-inject.
   Based on a patch by Rob MacGregor.
-* Document SOCKS is not run-time configurable. Patch by Rob MacGregor.
+* Document SOCKS configuration facility (SOCKS_CONF environment variable).
+  Thanks to Jochen Hayek, Michael Shuldman and Rob MacGregor.
 * Use envelope option in multidrop example. Patch by Rob MacGregor.
 * Document expected Received: line format when parsing for envelope addressees.
 * Stripped option documentation from sample.rcfile, since this is bound to go
diff --git a/fetchmail-FAQ.html b/fetchmail-FAQ.html
index 17168554..034a4111 100644
--- a/fetchmail-FAQ.html
+++ b/fetchmail-FAQ.html
@@ -1971,15 +1971,23 @@ sites.)</p>
 methods</h1>
 <h2><a id="K1" name="K1">K1. How can I use fetchmail with SOCKS?</a></h2>
 
-<p>Giuseppe Guerini added a --with-socks option that supports
-linking with socks library. If you specify the value of this option
-as "yes", the configure script will try to find the Rconnect
+<p>Giuseppe Guerini added a <kbd>--with-socks</kbd> compile-time option
+that supports linking with socks library. If you specify the value of
+this option as "yes", the configure script will try to find the Rconnect
 library and set the makefile up to link it. You can also specify a
 directory containing the Rconnect library.</p>
 
-<p>Alan Schmitt has added a similar --with-socks5 option that may
+<p>Alan Schmitt has added a similar <kbd>--with-socks5</kbd> option that may
 work better if you have a recent version of the SOCKS library.</p>
 
+<p>In either case, fetchmail has no direct configuration hooks, but you
+can specify which socks configuration file the library should read by
+means of the <tt>SOCKS_CONF</tt> environment variable. In order to
+bypass the SOCKS proxy altogether, you could run (adding your usual
+options to the end of this line):</p>
+
+<pre>env SOCKS_CONF=/dev/null fetchmail</pre>
+
 <h2><a id="K2" name="K2">K2. How can I use fetchmail with IPv6 and
 IPsec?</a></h2>
 
diff --git a/fetchmail.man b/fetchmail.man
index 3739724a..429628fa 100644
--- a/fetchmail.man
+++ b/fetchmail.man
@@ -2461,14 +2461,21 @@ you can declare 'no dns' to suppress DNS lookups entirely and
 \fIonly\fR match against the aka list.
 
 .SH SOCKS
-Support for socks4/5 is a 
-.B compile time 
-configuration option.  Once
-compiled in fetchmail will always use the socks libraries and
-configuration on your system.  There are no configuration
-options internal to fetchmail to control this behaviour, and the socks 
-and socks5 libraries provide no documented interfaces that fetchmail 
-could use to achieve run-time configurability.
+Support for socks4/5 is a \fBcompile time\fP configuration option. Once
+compiled in, fetchmail will always use the socks libraries and
+configuration on your system, there are no run-time switches in
+fetchmail - but you can still configure SOCKS: you can specify which
+SOCKS configuration file is used in the \fBSOCKS_CONF\fP environment
+variable.
+
+For instance, if you wanted to bypass the SOCKS proxy altogether and
+have fetchmail connect directly, you could just pass
+SOCKS_CONF=/dev/null in the environment, for example (add your usual
+command line options - if any - to the end of this line):
+
+.nf
+env SOCKS_CONF=/dev/null fetchmail
+.fi
 
 .SH EXIT CODES
 To facilitate the use of
@@ -2569,6 +2576,7 @@ lock file to help prevent concurrent runs (root mode, Linux systems).
 lock file to help prevent concurrent runs (root mode, systems without /var/run).
 
 .SH ENVIRONMENT
+.B FETCHMAILUSER:
 If the FETCHMAILUSER variable is set, it is used as the name of the
 calling user (default local name) for purposes such as mailing error
 notifications.  Otherwise, if either the LOGNAME or USER variable is
@@ -2578,6 +2586,7 @@ then that name is used as the default local name.  Otherwise
 session ID (this elaborate logic is designed to handle the case of
 multiple names per userid gracefully).
 
+.B FETCHMAILHOME:
 If the environment variable FETCHMAILHOME is set to a valid and
 existing directory name, fetchmail will read $FETCHMAILHOME/fetchmailrc
 (the dot is missing in this case), $FETCHMAILHOME/.fetchids and
@@ -2585,10 +2594,16 @@ $FETCHMAILHOME/.fetchmail.pid rather than from the user's home
 directory.  The .netrc file is always looked for in the the invoking
 user's home directory regardless of FETCHMAILHOME's setting.
 
+.B HOME_ETC:
 If the HOME_ETC variable is set, fetchmail will read
 $HOME_ETC/.fetchmailrc instead of ~/.fetchmailrc.
 
-If HOME_ETC and FETCHMAILHOME are set, HOME_ETC will be ignored.
+If HOME_ETC and FETCHMAILHOME are both set, HOME_ETC will be ignored.
+
+.B SOCKS_CONF:
+(only if SOCKS support is compiled in) this variable is used by the
+socks library to find out which configuration file it should read. Set
+this to /dev/null to bypass the SOCKS proxy.
 
 .SH SIGNALS
 If a