commit 810f7c545b926a2daf50f311b0879780f1d7760b
Author: J. Ryan Stinnett <jryans(a)gmail.com>
Date: Sun Dec 4 09:55:57 2016 -0600
Clean up formatting of tor.1 man page and HTML doc
Fixes #20885.
---
changes/20885 | 3 +++
doc/tor.1.txt | 77 +++++++++++++++++++++++++++++++----------------------------
2 files changed, 43 insertions(+), 37 deletions(-)
diff --git a/changes/20885 b/changes/20885
new file mode 100644
index 0000000..f1cddda
--- /dev/null
+++ b/changes/20885
@@ -0,0 +1,3 @@
+ o Documentation (formatting):
+ - Clean up formatting of tor.1 man page and HTML doc, where <pre> blocks
+ were incorrectly appearing. Closes ticket 20885.
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index aa3859e..4fd7641 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -1143,6 +1143,7 @@ The following options are useful only for clients (that is, if
authentication" when IsolateSOCKSAuth is disabled, or when this
option is set.
+[[SocksPortFlagsMisc]]::
Flags are processed left to right. If flags conflict, the last flag on the
line is used, and all earlier flags are ignored. No error is issued for
conflicting flags.
@@ -1336,7 +1337,7 @@ The following options are useful only for clients (that is, if
[[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**::
TransProxyType may only be enabled when there is transparent proxy listener
- enabled.
+ enabled. +
+
Set this to "TPROXY" if you wish to be able to use the TPROXY Linux module
to transparently proxy connections that are configured using the TransPort
@@ -1344,19 +1345,19 @@ The following options are useful only for clients (that is, if
for all addresses, even when the TransListenAddress is configured for an
internal address. Detailed information on how to configure the TPROXY
feature can be found in the Linux kernel source tree in the file
- Documentation/networking/tproxy.txt.
+ Documentation/networking/tproxy.txt. +
+
- Set this option to "ipfw" to use the FreeBSD ipfw interface.
+ Set this option to "ipfw" to use the FreeBSD ipfw interface. +
+
On *BSD operating systems when using pf, set this to "pf-divert" to take
advantage of +divert-to+ rules, which do not modify the packets like
+rdr-to+ rules do. Detailed information on how to configure pf to use
+divert-to+ rules can be found in the pf.conf(5) manual page. On OpenBSD,
+divert-to+ is available to use on versions greater than or equal to
- OpenBSD 4.4.
+ OpenBSD 4.4. +
+
Set this to "default", or leave it unconfigured, to use regular IPTables
- on Linux, or to use pf +rdr-to+ rules on *BSD systems.
+ on Linux, or to use pf +rdr-to+ rules on *BSD systems. +
+
(Default: "default".)
@@ -1463,11 +1464,11 @@ The following options are useful only for clients (that is, if
(Example:
Tor2webRendezvousPoints Fastyfasty, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
+
- This feature can only be used if Tor2webMode is also enabled.
+ This feature can only be used if Tor2webMode is also enabled. +
+
ExcludeNodes have higher priority than Tor2webRendezvousPoints,
which means that nodes specified in ExcludeNodes will not be
- picked as RPs.
+ picked as RPs. +
+
If no nodes in Tor2webRendezvousPoints are currently available for
use, Tor will choose a random node when building HS circuits.
@@ -1495,7 +1496,7 @@ The following options are useful only for clients (that is, if
These options override the default behavior of Tor's (**currently
experimental**) path bias detection algorithm. To try to find broken or
misbehaving guard nodes, Tor looks for nodes where more than a certain
- fraction of circuits through that guard fail to get built.
+ fraction of circuits through that guard fail to get built. +
+
The PathBiasCircThreshold option controls how many circuits we need to build
through a guard before we make these checks. The PathBiasNoticeRate,
@@ -1521,14 +1522,14 @@ The following options are useful only for clients (that is, if
[[PathBiasScaleUseThreshold]] **PathBiasScaleUseThreshold** __NUM__::
Similar to the above options, these options override the default behavior
- of Tor's (**currently experimental**) path use bias detection algorithm.
+ of Tor's (**currently experimental**) path use bias detection algorithm. +
+
Where as the path bias parameters govern thresholds for successfully
building circuits, these four path use bias parameters govern thresholds
only for circuit usage. Circuits which receive no stream usage
are not counted by this detection algorithm. A used circuit is considered
successful if it is capable of carrying streams or otherwise receiving
- well-formed responses to RELAY cells.
+ well-formed responses to RELAY cells. +
+
By default, or if a negative value is provided for one of these options,
Tor uses reasonable defaults from the networkstatus consensus document.
@@ -1662,7 +1663,7 @@ is non-zero):
Tells Tor whether to run as an exit relay. If Tor is running as a
non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to
exit according to the ExitPolicy option (or the default ExitPolicy if
- none is specified).
+ none is specified). +
+
If ExitRelay is set to 0, no traffic is allowed to
exit, and the ExitPolicy option is ignored. +
@@ -1740,6 +1741,7 @@ is non-zero):
reject *:6881-6999
accept *:*
+[[ExitPolicyDefault]]::
Since the default exit policy uses accept/reject *, it applies to both
IPv4 and IPv6 addresses.
@@ -1776,7 +1778,7 @@ is non-zero):
that they are in the same \'family', Tor clients will not use them in the
same circuit. (Each server only needs to list the other servers in its
family; it doesn't need to list itself, but it won't hurt.) Do not list
- any bridge relay as it would compromise its concealment.
+ any bridge relay as it would compromise its concealment. +
+
When listing a node, it's better to list it by fingerprint than by
nickname: fingerprints are more reliable.
@@ -1794,26 +1796,27 @@ is non-zero):
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. Set it to 0 to not
- run an ORPort at all. This option can occur more than once. (Default: 0)
-+
+ run an ORPort at all. This option can occur more than once. (Default: 0) +
+ +
Tor recognizes these flags on each ORPort:
- **NoAdvertise**::
+ **NoAdvertise**;;
By default, we bind to a port and tell our users about it. If
NoAdvertise is specified, we don't advertise, but listen anyway. This
can be useful if the port everybody will be connecting to (for
example, one that's opened on our firewall) is somewhere else.
- **NoListen**::
+ **NoListen**;;
By default, we bind to a port and tell our users about it. If
NoListen is specified, we don't bind, but advertise anyway. This
can be useful if something else (for example, a firewall's port
forwarding configuration) is causing connections to reach us.
- **IPv4Only**::
+ **IPv4Only**;;
If the address is absent, or resolves to both an IPv4 and an IPv6
address, only listen to the IPv4 address.
- **IPv6Only**::
+ **IPv6Only**;;
If the address is absent, or resolves to both an IPv4 and an IPv6
address, only listen to the IPv6 address.
-+
+
+[[ORPortFlagsExclusive]]::
For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and
IPv4Only and IPv6Only are mutually exclusive.
@@ -1821,8 +1824,8 @@ is non-zero):
Bind to this IP address to listen for connections from Tor clients and
servers. If you specify a port, bind to this port rather than the one
specified in ORPort. (Default: 0.0.0.0) This directive can be specified
- multiple times to bind to multiple addresses/ports.
-+
+ multiple times to bind to multiple addresses/ports. +
+ +
This option is deprecated; you can get the same behavior with ORPort now
that it supports NoAdvertise and explicit addresses.
@@ -1841,7 +1844,7 @@ is non-zero):
[[PublishServerDescriptor]] **PublishServerDescriptor** **0**|**1**|**v3**|**bridge**,**...**::
This option specifies which descriptors Tor will publish when acting as
a relay. You can
- choose multiple arguments, separated by commas.
+ choose multiple arguments, separated by commas. +
+
If this option is set to 0, Tor will not publish its
descriptors to any directories. (This is useful if you're testing
@@ -2096,16 +2099,16 @@ if DirPort is non-zero):
If this option is nonzero, advertise the directory service on this port.
Set it to "auto" to have Tor pick a port for you. This option can occur
more than once, but only one advertised DirPort is supported: all
- but one DirPort must have the **NoAdvertise** flag set. (Default: 0)
-+
+ but one DirPort must have the **NoAdvertise** flag set. (Default: 0) +
+ +
The same flags are supported here as are supported by ORPort.
[[DirListenAddress]] **DirListenAddress** __IP__[:__PORT__]::
Bind the directory service to this address. If you specify a port, bind to
this port rather than the one specified in DirPort. (Default: 0.0.0.0)
This directive can be specified multiple times to bind to multiple
- addresses/ports.
-+
+ addresses/ports. +
+ +
This option is deprecated; you can get the same behavior with DirPort now
that it supports NoAdvertise and explicit addresses.
@@ -2200,7 +2203,7 @@ on the public Tor network.
[[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__::
Authoritative directories only. A set of address patterns for servers that
will be listed as bad exits in any network status document this authority
- publishes, if **AuthDirListBadExits** is set.
+ publishes, if **AuthDirListBadExits** is set. +
+
(The address pattern syntax here and in the options below
is the same as for exit policies, except that you don't need to say
@@ -2418,16 +2421,16 @@ The following options are used to configure a hidden service.
Single Onion Service. One-hop circuits make Single Onion servers easily
locatable, but clients remain location-anonymous. However, the fact that a
client is accessing a Single Onion rather than a Hidden Service may be
- statistically distinguishable.
-
+ statistically distinguishable. +
+ +
**WARNING:** Once a hidden service directory has been used by a tor
instance in HiddenServiceSingleHopMode, it can **NEVER** be used again for
a hidden service. It is best practice to create a new hidden service
directory, key, and address for each new Single Onion Service and Hidden
Service. It is not possible to run Single Onion Services and Hidden
Services from the same tor instance: they should be run on different
- servers with different IP addresses.
-
+ servers with different IP addresses. +
+ +
HiddenServiceSingleHopMode requires HiddenServiceNonAnonymousMode to be set
to 1. Since a Single Onion service is non-anonymous, you can not configure
a SOCKSPort on a tor instance that is running in
@@ -2585,7 +2588,7 @@ The following options are used for running a testing Tor network.
A list of identity fingerprints, country codes, and
address patterns of nodes to vote Exit for regardless of their
uptime, bandwidth, or exit policy. See the **ExcludeNodes**
- option for more information on how to specify nodes.
+ option for more information on how to specify nodes. +
+
In order for this option to have any effect, **TestingTorNetwork**
has to be set. See the **ExcludeNodes** option for more
@@ -2594,7 +2597,7 @@ The following options are used for running a testing Tor network.
[[TestingDirAuthVoteExitIsStrict]] **TestingDirAuthVoteExitIsStrict** **0**|**1** ::
If True (1), a node will never receive the Exit flag unless it is specified
in the **TestingDirAuthVoteExit** list, regardless of its uptime, bandwidth,
- or exit policy.
+ or exit policy. +
+
In order for this option to have any effect, **TestingTorNetwork**
has to be set.
@@ -2603,14 +2606,14 @@ The following options are used for running a testing Tor network.
A list of identity fingerprints and country codes and
address patterns of nodes to vote Guard for regardless of their
uptime and bandwidth. See the **ExcludeNodes** option for more
- information on how to specify nodes.
+ information on how to specify nodes. +
+
In order for this option to have any effect, **TestingTorNetwork**
has to be set.
[[TestingDirAuthVoteGuardIsStrict]] **TestingDirAuthVoteGuardIsStrict** **0**|**1** ::
If True (1), a node will never receive the Guard flag unless it is specified
- in the **TestingDirAuthVoteGuard** list, regardless of its uptime and bandwidth.
+ in the **TestingDirAuthVoteGuard** list, regardless of its uptime and bandwidth. +
+
In order for this option to have any effect, **TestingTorNetwork**
has to be set.
@@ -2619,14 +2622,14 @@ The following options are used for running a testing Tor network.
A list of identity fingerprints and country codes and
address patterns of nodes to vote HSDir for regardless of their
uptime and DirPort. See the **ExcludeNodes** option for more
- information on how to specify nodes.
+ information on how to specify nodes. +
+
In order for this option to have any effect, **TestingTorNetwork**
must be set.
[[TestingDirAuthVoteHSDirIsStrict]] **TestingDirAuthVoteHSDirIsStrict** **0**|**1** ::
If True (1), a node will never receive the HSDir flag unless it is specified
- in the **TestingDirAuthVoteHSDir** list, regardless of its uptime and DirPort.
+ in the **TestingDirAuthVoteHSDir** list, regardless of its uptime and DirPort. +
+
In order for this option to have any effect, **TestingTorNetwork**
has to be set.
