SOCKS: move from Experimental to mainline

3 files changed, 91 insertions, 38 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 8b2bb4dab..677b4ef50 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -23729,6 +23729,14 @@ Alternatively, if the value of &%size_addition%& is set negative, it disables
 the use of the SIZE option altogether.
 
 
+.new
+.option socks_proxy smtp string&!! unset
+.cindex proxy SOCKS
+This option enables use of SOCKS proxies for connections made by the
+transport.  For details see &<<SECTproxySOCKS>>&.
+.wen
+
+
 .option tls_certificate smtp string&!! unset
 .cindex "TLS" "client certificate, location of"
 .cindex "certificate" "client, location of"
@@ -38008,6 +38016,83 @@ for more information of what they mean.
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
+.chapter "Proxies" "CHAPproxies" &&&
+         "Proxy support"
+.cindex "proxy support"
+.cindex "proxy" "access via"
+
+.new
+A proxy is an intermediate system through which communication is passed.
+Proxies may provide a security, availability or load-distribution function.
+
+.section "Outbound proxies" SECTproxySOCKS
+.cindex proxy outbound
+.cindex proxy "client side"
+.cindex proxy SOCKS
+.cindex SOCKS proxy
+Exim has support for sending outbound SMTP via a proxy
+using a protocol called SOCKS5 (defined by RFC1928).
+The support can be removed by defining DISABLE_SOCKS=yes in Local/Makefile.
+
+Use of a proxy is enabled by setting the &%socks_proxy%& on an smtp transport.
+The option value is expanded and should then be a list
+(colon-separated by default) of proxy specifiers.
+Each proxy specifier is a list
+(space-separated by default) where the initial element
+is an IP address and any subsequent elements are options.
+
+Options are a string <name>=<value>. 
+The list of options is in the following table:
+.display
+&`auth   `& authentication method
+&`name   `& authentication username
+&`pass   `& authentication password
+&`port   `& tcp port
+&`tmo    `& connection timeout
+&`pri    `& priority
+&`weight `& selection bias
+.endd
+
+More details on each of these options follows:
+
+.ilist
+.cindex authentication "to proxy"
+.cindex proxy authentication
+&%auth%&: Either &"none"& (default) or &"name"&.
+Using &"name"& selects username/password authentication per RFC 1929
+for access to the proxy.
+Default is &"none"&.
+.next
+&%name%&: sets the username for the &"name"& authentication method.
+Default is empty.
+.next
+&%pass%&: sets the password for the &"name"& authentication method.
+Default is empty.
+.next
+&%port%&: the TCP port number to use for the connection to the proxy.
+Default is 1080.
+.next
+&%tmo%&: sets a connection timeout in seconds for this proxy.
+Default is 5.
+.next
+&%pri%&: specifies a priority for the proxy within the list,
+higher values being tried first.
+The default priority is 1.
+.next
+&%weight%&: specifies a selection bias.
+Within a priority set servers are queried in a random fashion,
+weighted by this value.
+The default value for selection bias is 1.
+.endlist
+
+Proxies from the list are tried according to their priority
+and weight settings until one responds.  The timeout for the
+overall connection applies to the set of proxied attempts.
+.wen
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
 .chapter "Adding new drivers or lookup types" "CHID13" &&&
          "Adding drivers or lookups"
 .cindex "adding drivers"
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index 20623997f..e78f49cf4 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -112,6 +112,9 @@ JH/21 Bug 1720: Add support for priority groups and weighted-random proxy
 JH/22 Bugs 963, 1721: Fix some corner cases in message body canonicalisation
       for DKIM processing.
 
+JH/23 Move SOCKS5 support from Experimental to mainline.  It can be left out
+      from a build by defining DISABLE_SOCKS.
+
 
 Exim version 4.86
 -----------------
diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 18a5fd917..f0f1035ea 100644
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -880,6 +880,9 @@ following will be forced:
 
 No other use is made of the result string.
 
+If transport proxying is used, the remote IP/port during a
+tcp:connect event will be that of the proxy.
+
 
 Known issues:
 - the tls:cert event is only called for the cert chain elements
@@ -1115,44 +1118,6 @@ QUIT
 
 
 
-SOCKS
-------------------------------------------------------------
-Support for proxying outbound SMTP via a Socks 5 proxy
-(RFC 1928) is included if Exim is compiled with
-EXPERIMENTAL_SOCKS defined.
-
-If an smtp transport has a nonempty socks_proxy option
-defined, this is active.  The option is expanded and
-should be a list (colon-separated by default) of
-proxy specifiers.  Each proxy specifier is a list
-(space-separated by default) where the initial element
-is an IP address and any subsequent elements are options.
-
-Options are a string <name>=<value>.
-These options are currently defined:
-- "auth", with possible values "none" and "name".
-  Using "name" selects username/password authentication
-  per RFC 1929. Default is "none".
-- "name" sets the authentication username. Default is empty.
-- "pass" sets the authentication password. Default is empty.
-- "port" sets the tcp port number for the proxy. Default is 1080.
-- "tmo" sets a connection timeout in seconds for this proxy. Default is 5.
-- "pri" specifies a priority for the server within the list, higher
-  values being tried first. The default priority is 1.
-- "weight" specifies a selection bias. Within a priority set servers
-  are queried in a random fashion, weighted by this value. The default
-  value for selection bias is 1.
-
-Proxies from the list are tried according to their priority
-and weight settings until one responds.  The timeout for the
-overall connection applies to the set of proxied attempts.
-
-If events are used, the remote IP/port during a
-tcp:connect event will be that of the proxy.
-
-
-
-
 DANE
 ------------------------------------------------------------
 DNS-based Authentication of Named Entities, as applied