"(Socks|Control|etc)Port auto" now tells Tor to open an arbitrary port

This is the major part of the implementation for trac issue 3076.

1 files changed, 23 insertions, 14 deletions

diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index fb4b3f9bf3..e48342e165 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -145,13 +145,15 @@ Other options can be specified either on the command-line (--option
     all sockets will be set to this limit. Must be a value between 2048 and
     262144, in 1024 byte increments. Default of 8192 is recommended.
 
-**ControlPort** __Port__::
+**ControlPort** __PORT__|**auto**::
     If set, Tor will accept connections on this port and allow those
     connections to control the Tor process using the Tor Control Protocol
     (described in control-spec.txt). Note: unless you also specify one of
-    **HashedControlPassword** or **CookieAuthentication**, setting this option will
+    **HashedControlPassword** or **CookieAuthentication**, setting this
+    option will
     cause Tor to allow any process on the local host to control it. This
     option is required for many Tor controllers; most use the value of 9051.
+    Set it to "auto" to have Tor pick a port for you. (Default: 0).
 
 **ControlListenAddress** __IP__[:__PORT__]::
     Bind the controller listener to this address. If you specify a port, bind
@@ -647,10 +649,11 @@ The following options are useful only for clients (that is, if
     the same circuit. Currently, two addresses are "too close" if they lie in
     the same /16 range. (Default: 1)
 
-**SocksPort** __PORT__::
+**SocksPort** __PORT__|**auto**::
     Advertise this port to listen for connections from Socks-speaking
     applications. Set this to 0 if you don't want to allow application
-    connections. (Default: 9050)
+    connections via SOCKS. Set it to "auto" to have Tor pick a port for
+    you. (Default: 9050)
 
 **SocksListenAddress** __IP__[:__PORT__]::
     Bind to this address to listen for connections from Socks-speaking
@@ -759,23 +762,25 @@ The following options are useful only for clients (that is, if
     operating as a relay, and it will never use the public key step if it
     doesn't yet know the onion key of the first hop. (Default: 1)
 
-**TransPort** __PORT__::
+**TransPort** __PORT__|**auto**::
     If non-zero, enables transparent proxy support on __PORT__ (by convention,
     9040). Requires OS support for transparent proxies, such as BSDs' pf or
     Linux's IPTables. If you're planning to use Tor as a transparent proxy for
     a network, you'll want to examine and change VirtualAddrNetwork from the
     default setting. You'll also want to set the TransListenAddress option for
-    the network you'd like to proxy. (Default: 0).
+    the network you'd like to proxy.  Set it to "auto" to have Tor pick a
+    port for you.  (Default: 0).
 
 **TransListenAddress** __IP__[:__PORT__]::
     Bind to this address to listen for transparent proxy connections. (Default:
     127.0.0.1). This is useful for exporting a transparent proxy server to an
     entire network.
 
-**NATDPort** __PORT__::
+**NATDPort** __PORT__|**auto**::
     Allow old versions of ipfw (as included in old versions of FreeBSD, etc.)
     to send connections through Tor using the NATD protocol. This option is
-    only for people who cannot use TransPort.
+    only for people who cannot use TransPort.  Set it to "auto" to have Tor
+    pick a port for you. (Default: 0)
 
 **NATDListenAddress** __IP__[:__PORT__]::
     Bind to this address to listen for NATD connections. (Default: 127.0.0.1).
@@ -791,9 +796,10 @@ The following options are useful only for clients (that is, if
     A comma-separated list of suffixes to use with **AutomapHostsOnResolve**.
     The "." suffix is equivalent to "all addresses." (Default: .exit,.onion).
 
-**DNSPort** __PORT__::
+**DNSPort** __PORT__|**auto**::
     If non-zero, Tor listens for UDP DNS requests on this port and resolves
-    them anonymously. (Default: 0).
+    them anonymously.  Set it to "auto" to have Tor pick a port for
+    you. (Default: 0).
 
 **DNSListenAddress** __IP__[:__PORT__]::
     Bind to this address to listen for DNS connections. (Default: 127.0.0.1).
@@ -945,8 +951,10 @@ is non-zero):
 **NumCPUs** __num__::
     How many processes to use at once for decrypting onionskins. (Default: 1)
 
-**ORPort** __PORT__::
-    Advertise this port to listen for connections from Tor clients and servers.
+**ORPort** __PORT__|**auto**::
+    Advertise this port to listen for connections from Tor clients and
+    servers.  This option is required to be a Tor server.
+    Set it to "auto" to have Tor pick a port for you. (Default: 0).
 
 **ORListenAddress** __IP__[:__PORT__]::
     Bind to this IP address to listen for connections from Tor clients and
@@ -1158,8 +1166,9 @@ if DirPort is non-zero):
     Minimum uptime of a v2 hidden service directory to be accepted as such by
     authoritative directories. (Default: 24 hours)
 
-**DirPort** __PORT__::
-    Advertise the directory service on this port.
+**DirPort** __PORT__|**auto**::
+    If this option is nonzero, advertise the directory service on this port.
+    Set it to "auto" to have Tor pick a port for you.  (Default: 0)
 
 **DirListenAddress** __IP__[:__PORT__]::
     Bind the directory service to this address. If you specify a port, bind to