mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-12-05 01:53:32 +01:00
a6f2d2091b
HiddenServiceDirGroupReadable has no effect in Windows
2444 lines
127 KiB
Plaintext
2444 lines
127 KiB
Plaintext
// Copyright (c) The Tor Project, Inc.
|
|
// See LICENSE for licensing information
|
|
// This is an asciidoc file used to generate the manpage/html reference.
|
|
// Learn asciidoc on http://www.methods.co.nz/asciidoc/userguide.html
|
|
:man source: Tor
|
|
:man manual: Tor Manual
|
|
TOR(1)
|
|
======
|
|
|
|
NAME
|
|
----
|
|
tor - The second-generation onion router
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
**tor** [__OPTION__ __value__]...
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
Tor is a connection-oriented anonymizing communication
|
|
service. Users choose a source-routed path through a set of nodes, and
|
|
negotiate a "virtual circuit" through the network, in which each node
|
|
knows its predecessor and successor, but no others. Traffic flowing down
|
|
the circuit is unwrapped by a symmetric key at each node, which reveals
|
|
the downstream node. +
|
|
|
|
Basically, Tor provides a distributed network of servers or relays ("onion routers").
|
|
Users bounce their TCP streams -- web traffic, ftp, ssh, etc. -- around the
|
|
network, and recipients, observers, and even the relays themselves have
|
|
difficulty tracking the source of the stream.
|
|
|
|
By default, **tor** will only act as a client only. To help the network
|
|
by providing bandwidth as a relay, change the **ORPort** configuration
|
|
option -- see below. Please also consult the documentation on the Tor
|
|
Project's website.
|
|
|
|
COMMAND-LINE OPTIONS
|
|
--------------------
|
|
[[opt-h]] **-h**, **-help**::
|
|
Display a short help message and exit.
|
|
|
|
[[opt-f]] **-f** __FILE__::
|
|
Specify a new configuration file to contain further Tor configuration
|
|
options. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not
|
|
found)
|
|
|
|
[[opt-allow-missing-torrc]] **--allow-missing-torrc**::
|
|
Do not require that configuration file specified by **-f** exist if
|
|
default torrc can be accessed.
|
|
|
|
[[opt-defaults-torrc]] **--defaults-torrc** __FILE__::
|
|
Specify a file in which to find default values for Tor options. The
|
|
contents of this file are overridden by those in the regular
|
|
configuration file, and by those on the command line. (Default:
|
|
@CONFDIR@/torrc-defaults.)
|
|
|
|
[[opt-ignore-missing-torrc]] **--ignore-missing-torrc**::
|
|
Specifies that Tor should treat a missing torrc file as though it
|
|
were empty. Ordinarily, Tor does this for missing default torrc files,
|
|
but not for those specified on the command line.
|
|
|
|
[[opt-hash-password]] **--hash-password** __PASSWORD__::
|
|
Generates a hashed password for control port access.
|
|
|
|
[[opt-list-fingerprint]] **--list-fingerprint**::
|
|
Generate your keys and output your nickname and fingerprint.
|
|
|
|
[[opt-verify-config]] **--verify-config**::
|
|
Verify the configuration file is valid.
|
|
|
|
[[opt-serviceinstall]] **--service install** [**--options** __command-line options__]::
|
|
Install an instance of Tor as a Windows service, with the provided
|
|
command-line options. Current instructions can be found at
|
|
https://trac.torproject.org/projects/tor/wiki/doc/TorFAQ#HowdoIrunmyTorrelayasanNTservice
|
|
|
|
[[opt-service]] **--service** **remove**|**start**|**stop**::
|
|
Remove, start, or stop a configured Tor Windows service.
|
|
|
|
[[opt-nt-service]] **--nt-service**::
|
|
Used internally to implement a Windows service.
|
|
|
|
[[opt-list-torrc-options]] **--list-torrc-options**::
|
|
List all valid options.
|
|
|
|
[[opt-version]] **--version**::
|
|
Display Tor version and exit.
|
|
|
|
[[opt-quiet]] **--quiet**|**--hush**::
|
|
Override the default console log. By default, Tor starts out logging
|
|
messages at level "notice" and higher to the console. It stops doing so
|
|
after it parses its configuration, if the configuration tells it to log
|
|
anywhere else. You can override this behavior with the **--hush** option,
|
|
which tells Tor to only send warnings and errors to the console, or with
|
|
the **--quiet** option, which tells Tor not to log to the console at all.
|
|
|
|
Other options can be specified on the command-line in the format "--option
|
|
value", in the format "option value", or in a configuration file. For
|
|
instance, you can tell Tor to start listening for SOCKS connections on port
|
|
9999 by passing --SOCKSPort 9999 or SOCKSPort 9999 to it on the command line,
|
|
or by putting "SOCKSPort 9999" in the configuration file. You will need to
|
|
quote options with spaces in them: if you want Tor to log all debugging
|
|
messages to debug.log, you will probably need to say --Log 'debug file
|
|
debug.log'.
|
|
|
|
Options on the command line override those in configuration files. See the
|
|
next section for more information.
|
|
|
|
THE CONFIGURATION FILE FORMAT
|
|
-----------------------------
|
|
|
|
All configuration options in a configuration are written on a single line by
|
|
default. They take the form of an option name and a value, or an option name
|
|
and a quoted value (option value or option "value"). Anything after a #
|
|
character is treated as a comment. Options are
|
|
case-insensitive. C-style escaped characters are allowed inside quoted
|
|
values. To split one configuration entry into multiple lines, use a single
|
|
backslash character (\) before the end of the line. Comments can be used in
|
|
such multiline entries, but they must start at the beginning of a line.
|
|
|
|
By default, an option on the command line overrides an option found in the
|
|
configuration file, and an option in a configuration file overrides one in
|
|
the defaults file.
|
|
|
|
This rule is simple for options that take a single value, but it can become
|
|
complicated for options that are allowed to occur more than once: if you
|
|
specify four SOCKSPorts in your configuration file, and one more SOCKSPort on
|
|
the command line, the option on the command line will replace __all__ of the
|
|
SOCKSPorts in the configuration file. If this isn't what you want, prefix
|
|
the option name with a plus sign, and it will be appended to the previous set
|
|
of options instead.
|
|
|
|
Alternatively, you might want to remove every instance of an option in the
|
|
configuration file, and not replace it at all: you might want to say on the
|
|
command line that you want no SOCKSPorts at all. To do that, prefix the
|
|
option name with a forward slash.
|
|
|
|
GENERAL OPTIONS
|
|
---------------
|
|
|
|
[[BandwidthRate]] **BandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
A token bucket limits the average incoming bandwidth usage on this node to
|
|
the specified number of bytes per second, and the average outgoing
|
|
bandwidth usage to that same value. If you want to run a relay in the
|
|
public network, this needs to be _at the very least_ 30 KBytes (that is,
|
|
30720 bytes). (Default: 1 GByte) +
|
|
+
|
|
With this option, and in other options that take arguments in bytes,
|
|
KBytes, and so on, other formats are also supported. Notably, "KBytes" can
|
|
also be written as "kilobytes" or "kb"; "MBytes" can be written as
|
|
"megabytes" or "MB"; "kbits" can be written as "kilobits"; and so forth.
|
|
Tor also accepts "byte" and "bit" in the singular.
|
|
The prefixes "tera" and "T" are also recognized.
|
|
If no units are given, we default to bytes.
|
|
To avoid confusion, we recommend writing "bytes" or "bits" explicitly,
|
|
since it's easy to forget that "B" means bytes, not bits.
|
|
|
|
[[BandwidthBurst]] **BandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
Limit the maximum token bucket size (also known as the burst) to the given
|
|
number of bytes in each direction. (Default: 1 GByte)
|
|
|
|
[[MaxAdvertisedBandwidth]] **MaxAdvertisedBandwidth** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
If set, we will not advertise more than this amount of bandwidth for our
|
|
BandwidthRate. Server operators who want to reduce the number of clients
|
|
who ask to build circuits through them (since this is proportional to
|
|
advertised bandwidth rate) can thus reduce the CPU demands on their server
|
|
without impacting network performance.
|
|
|
|
[[RelayBandwidthRate]] **RelayBandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
If not 0, a separate token bucket limits the average incoming bandwidth
|
|
usage for \_relayed traffic_ on this node to the specified number of bytes
|
|
per second, and the average outgoing bandwidth usage to that same value.
|
|
Relayed traffic currently is calculated to include answers to directory
|
|
requests, but that may change in future versions. (Default: 0)
|
|
|
|
[[RelayBandwidthBurst]] **RelayBandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
If not 0, limit the maximum token bucket size (also known as the burst) for
|
|
\_relayed traffic_ to the given number of bytes in each direction.
|
|
(Default: 0)
|
|
|
|
[[PerConnBWRate]] **PerConnBWRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
If set, do separate rate limiting for each connection from a non-relay.
|
|
You should never need to change this value, since a network-wide value is
|
|
published in the consensus and your relay will use that value. (Default: 0)
|
|
|
|
[[PerConnBWBurst]] **PerConnBWBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
If set, do separate rate limiting for each connection from a non-relay.
|
|
You should never need to change this value, since a network-wide value is
|
|
published in the consensus and your relay will use that value. (Default: 0)
|
|
|
|
[[ClientTransportPlugin]] **ClientTransportPlugin** __transport__ socks4|socks5 __IP__:__PORT__::
|
|
**ClientTransportPlugin** __transport__ exec __path-to-binary__ [options]::
|
|
In its first form, when set along with a corresponding Bridge line, the Tor
|
|
client forwards its traffic to a SOCKS-speaking proxy on "IP:PORT". It's the
|
|
duty of that proxy to properly forward the traffic to the bridge. +
|
|
+
|
|
In its second form, when set along with a corresponding Bridge line, the Tor
|
|
client launches the pluggable transport proxy executable in
|
|
__path-to-binary__ using __options__ as its command-line options, and
|
|
forwards its traffic to it. It's the duty of that proxy to properly forward
|
|
the traffic to the bridge.
|
|
|
|
[[ServerTransportPlugin]] **ServerTransportPlugin** __transport__ exec __path-to-binary__ [options]::
|
|
The Tor relay launches the pluggable transport proxy in __path-to-binary__
|
|
using __options__ as its command-line options, and expects to receive
|
|
proxied client traffic from it.
|
|
|
|
[[ServerTransportListenAddr]] **ServerTransportListenAddr** __transport__ __IP__:__PORT__::
|
|
When this option is set, Tor will suggest __IP__:__PORT__ as the
|
|
listening address of any pluggable transport proxy that tries to
|
|
launch __transport__.
|
|
|
|
[[ServerTransportOptions]] **ServerTransportOptions** __transport__ __k=v__ __k=v__ ...::
|
|
When this option is set, Tor will pass the __k=v__ parameters to
|
|
any pluggable transport proxy that tries to launch __transport__. +
|
|
(Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd cache=/var/lib/tor/cache)
|
|
|
|
[[ExtORPort]] **ExtORPort** \['address':]__port__|**auto**
|
|
Open this port to listen for Extended ORPort connections from your
|
|
pluggable transports.
|
|
|
|
[[ExtORPortCookieAuthFile]] **ExtORPortCookieAuthFile** __Path__::
|
|
If set, this option overrides the default location and file name
|
|
for the Extended ORPort's cookie file -- the cookie file is needed
|
|
for pluggable transports to communicate through the Extended ORPort.
|
|
|
|
[[ExtORPortCookieAuthFileGroupReadable]] **ExtORPortCookieAuthFileGroupReadable** **0**|**1**::
|
|
If this option is set to 0, don't allow the filesystem group to read the
|
|
Extended OR Port cookie file. If the option is set to 1, make the cookie
|
|
file readable by the default GID. [Making the file readable by other
|
|
groups is not yet implemented; let us know if you need this for some
|
|
reason.] (Default: 0)
|
|
|
|
[[ConnLimit]] **ConnLimit** __NUM__::
|
|
The minimum number of file descriptors that must be available to the Tor
|
|
process before it will start. Tor will ask the OS for as many file
|
|
descriptors as the OS will allow (you can find this by "ulimit -H -n").
|
|
If this number is less than ConnLimit, then Tor will refuse to start. +
|
|
+
|
|
You probably don't need to adjust this. It has no effect on Windows
|
|
since that platform lacks getrlimit(). (Default: 1000)
|
|
|
|
[[DisableNetwork]] **DisableNetwork** **0**|**1**::
|
|
When this option is set, we don't listen for or accept any connections
|
|
other than controller connections, and we close (and don't reattempt)
|
|
any outbound
|
|
connections. Controllers sometimes use this option to avoid using
|
|
the network until Tor is fully configured. (Default: 0)
|
|
|
|
[[ConstrainedSockets]] **ConstrainedSockets** **0**|**1**::
|
|
If set, Tor will tell the kernel to attempt to shrink the buffers for all
|
|
sockets to the size specified in **ConstrainedSockSize**. This is useful for
|
|
virtual servers and other environments where system level TCP buffers may
|
|
be limited. If you're on a virtual server, and you encounter the "Error
|
|
creating network socket: No buffer space available" message, you are
|
|
likely experiencing this problem. +
|
|
+
|
|
The preferred solution is to have the admin increase the buffer pool for
|
|
the host itself via /proc/sys/net/ipv4/tcp_mem or equivalent facility;
|
|
this configuration option is a second-resort. +
|
|
+
|
|
The DirPort option should also not be used if TCP buffers are scarce. The
|
|
cached directory requests consume additional sockets which exacerbates
|
|
the problem. +
|
|
+
|
|
You should **not** enable this feature unless you encounter the "no buffer
|
|
space available" issue. Reducing the TCP buffers affects window size for
|
|
the TCP stream and will reduce throughput in proportion to round trip
|
|
time on long paths. (Default: 0)
|
|
|
|
[[ConstrainedSockSize]] **ConstrainedSockSize** __N__ **bytes**|**KBytes**::
|
|
When **ConstrainedSockets** is enabled the receive and transmit buffers for
|
|
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]] **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 or
|
|
more of **HashedControlPassword** or **CookieAuthentication**,
|
|
setting this option will cause Tor to allow any process on the local
|
|
host to control it. (Setting both authentication methods means either
|
|
method is sufficient to authenticate to Tor.) 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]] **ControlListenAddress** __IP__[:__PORT__]::
|
|
Bind the controller listener to this address. If you specify a port, bind
|
|
to this port rather than the one specified in ControlPort. We strongly
|
|
recommend that you leave this alone unless you know what you're doing,
|
|
since giving attackers access to your control listener is really
|
|
dangerous. This directive can be specified multiple
|
|
times to bind to multiple addresses/ports. (Default: 127.0.0.1)
|
|
|
|
[[ControlSocket]] **ControlSocket** __Path__::
|
|
Like ControlPort, but listens on a Unix domain socket, rather than a TCP
|
|
socket. (Unix and Unix-like systems only.)
|
|
|
|
[[ControlSocketsGroupWritable]] **ControlSocketsGroupWritable** **0**|**1**::
|
|
If this option is set to 0, don't allow the filesystem group to read and
|
|
write unix sockets (e.g. ControlSocket). If the option is set to 1, make
|
|
the control socket readable and writable by the default GID. (Default: 0)
|
|
|
|
[[HashedControlPassword]] **HashedControlPassword** __hashed_password__::
|
|
Allow connections on the control port if they present
|
|
the password whose one-way hash is __hashed_password__. You
|
|
can compute the hash of a password by running "tor --hash-password
|
|
__password__". You can provide several acceptable passwords by using more
|
|
than one HashedControlPassword line.
|
|
|
|
[[CookieAuthentication]] **CookieAuthentication** **0**|**1**::
|
|
If this option is set to 1, allow connections on the control port
|
|
when the connecting process knows the contents of a file named
|
|
"control_auth_cookie", which Tor will create in its data directory. This
|
|
authentication method should only be used on systems with good filesystem
|
|
security. (Default: 0)
|
|
|
|
[[CookieAuthFile]] **CookieAuthFile** __Path__::
|
|
If set, this option overrides the default location and file name
|
|
for Tor's cookie file. (See CookieAuthentication above.)
|
|
|
|
[[CookieAuthFileGroupReadable]] **CookieAuthFileGroupReadable** **0**|**1**::
|
|
If this option is set to 0, don't allow the filesystem group to read the
|
|
cookie file. If the option is set to 1, make the cookie file readable by
|
|
the default GID. [Making the file readable by other groups is not yet
|
|
implemented; let us know if you need this for some reason.] (Default: 0)
|
|
|
|
[[ControlPortWriteToFile]] **ControlPortWriteToFile** __Path__::
|
|
If set, Tor writes the address and port of any control port it opens to
|
|
this address. Usable by controllers to learn the actual control port
|
|
when ControlPort is set to "auto".
|
|
|
|
[[ControlPortFileGroupReadable]] **ControlPortFileGroupReadable** **0**|**1**::
|
|
If this option is set to 0, don't allow the filesystem group to read the
|
|
control port file. If the option is set to 1, make the control port
|
|
file readable by the default GID. (Default: 0)
|
|
|
|
[[DataDirectory]] **DataDirectory** __DIR__::
|
|
Store working data in DIR (Default: @LOCALSTATEDIR@/lib/tor)
|
|
|
|
[[FallbackDir]] **FallbackDir** __address__:__port__ orport=__port__ id=__fingerprint__ [weight=__num__]::
|
|
When we're unable to connect to any directory cache for directory info
|
|
(usually because we don't know about any yet) we try a FallbackDir.
|
|
By default, the directory authorities are also FallbackDirs.
|
|
|
|
[[DirAuthority]] **DirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__::
|
|
Use a nonstandard authoritative directory server at the provided address
|
|
and port, with the specified key fingerprint. This option can be repeated
|
|
many times, for multiple authoritative directory servers. Flags are
|
|
separated by spaces, and determine what kind of an authority this directory
|
|
is. By default, an authority is not authoritative for any directory style
|
|
or version unless an appropriate flag is given.
|
|
Tor will use this authority as a bridge authoritative directory if the
|
|
"bridge" flag is set. If a flag "orport=**port**" is given, Tor will use the
|
|
given port when opening encrypted tunnels to the dirserver. If a flag
|
|
"weight=**num**" is given, then the directory server is chosen randomly
|
|
with probability proportional to that weight (default 1.0). Lastly, if a
|
|
flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority
|
|
whose v3 long-term signing key has the fingerprint **fp**. +
|
|
+
|
|
If no **DirAuthority** line is given, Tor will use the default directory
|
|
authorities. NOTE: this option is intended for setting up a private Tor
|
|
network with its own directory authorities. If you use it, you will be
|
|
distinguishable from other users, because you won't believe the same
|
|
authorities they do.
|
|
|
|
[[DirAuthorityFallbackRate]] **DirAuthorityFallbackRate** __NUM__::
|
|
When configured to use both directory authorities and fallback
|
|
directories, the directory authorities also work as fallbacks. They are
|
|
chosen with their regular weights, multiplied by this number, which
|
|
should be 1.0 or less. (Default: 1.0)
|
|
|
|
[[DynamicDHGroups]] **DynamicDHGroups** **0**|**1**::
|
|
If this option is set to 1, when running as a server, generate our
|
|
own Diffie-Hellman group instead of using the one from Apache's mod_ssl.
|
|
This option may help circumvent censorship based on static
|
|
Diffie-Hellman parameters. (Default: 0)
|
|
|
|
[[AlternateDirAuthority]] **AlternateDirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ +
|
|
|
|
[[AlternateBridgeAuthority]] **AlternateBridgeAuthority** [__nickname__] [**flags**] __address__:__port__ __ fingerprint__::
|
|
These options behave as DirAuthority, but they replace fewer of the
|
|
default directory authorities. Using
|
|
AlternateDirAuthority replaces the default Tor directory authorities, but
|
|
leaves the default bridge authorities in
|
|
place. Similarly,
|
|
AlternateBridgeAuthority replaces the default bridge authority,
|
|
but leaves the directory authorities alone.
|
|
|
|
[[DisableAllSwap]] **DisableAllSwap** **0**|**1**::
|
|
If set to 1, Tor will attempt to lock all current and future memory pages,
|
|
so that memory cannot be paged out. Windows, OS X and Solaris are currently
|
|
not supported. We believe that this feature works on modern Gnu/Linux
|
|
distributions, and that it should work on *BSD systems (untested). This
|
|
option requires that you start your Tor as root, and you should use the
|
|
**User** option to properly reduce Tor's privileges. (Default: 0)
|
|
|
|
[[DisableDebuggerAttachment]] **DisableDebuggerAttachment** **0**|**1**::
|
|
If set to 1, Tor will attempt to prevent basic debugging attachment attempts
|
|
by other processes. This may also keep Tor from generating core files if
|
|
it crashes. It has no impact for users who wish to attach if they
|
|
have CAP_SYS_PTRACE or if they are root. We believe that this feature
|
|
works on modern Gnu/Linux distributions, and that it may also work on *BSD
|
|
systems (untested). Some modern Gnu/Linux systems such as Ubuntu have the
|
|
kernel.yama.ptrace_scope sysctl and by default enable it as an attempt to
|
|
limit the PTRACE scope for all user processes by default. This feature will
|
|
attempt to limit the PTRACE scope for Tor specifically - it will not attempt
|
|
to alter the system wide ptrace scope as it may not even exist. If you wish
|
|
to attach to Tor with a debugger such as gdb or strace you will want to set
|
|
this to 0 for the duration of your debugging. Normal users should leave it
|
|
on. Disabling this option while Tor is running is prohibited. (Default: 1)
|
|
|
|
[[FetchDirInfoEarly]] **FetchDirInfoEarly** **0**|**1**::
|
|
If set to 1, Tor will always fetch directory information like other
|
|
directory caches, even if you don't meet the normal criteria for fetching
|
|
early. Normal users should leave it off. (Default: 0)
|
|
|
|
[[FetchDirInfoExtraEarly]] **FetchDirInfoExtraEarly** **0**|**1**::
|
|
If set to 1, Tor will fetch directory information before other directory
|
|
caches. It will attempt to download directory information closer to the
|
|
start of the consensus period. Normal users should leave it off.
|
|
(Default: 0)
|
|
|
|
[[FetchHidServDescriptors]] **FetchHidServDescriptors** **0**|**1**::
|
|
If set to 0, Tor will never fetch any hidden service descriptors from the
|
|
rendezvous directories. This option is only useful if you're using a Tor
|
|
controller that handles hidden service fetches for you. (Default: 1)
|
|
|
|
[[FetchServerDescriptors]] **FetchServerDescriptors** **0**|**1**::
|
|
If set to 0, Tor will never fetch any network status summaries or server
|
|
descriptors from the directory servers. This option is only useful if
|
|
you're using a Tor controller that handles directory fetches for you.
|
|
(Default: 1)
|
|
|
|
[[FetchUselessDescriptors]] **FetchUselessDescriptors** **0**|**1**::
|
|
If set to 1, Tor will fetch every non-obsolete descriptor from the
|
|
authorities that it hears about. Otherwise, it will avoid fetching useless
|
|
descriptors, for example for routers that are not running. This option is
|
|
useful if you're using the contributed "exitlist" script to enumerate Tor
|
|
nodes that exit to certain addresses. (Default: 0)
|
|
|
|
[[HTTPProxy]] **HTTPProxy** __host__[:__port__]::
|
|
Tor will make all its directory requests through this host:port (or host:80
|
|
if port is not specified), rather than connecting directly to any directory
|
|
servers.
|
|
|
|
[[HTTPProxyAuthenticator]] **HTTPProxyAuthenticator** __username:password__::
|
|
If defined, Tor will use this username:password for Basic HTTP proxy
|
|
authentication, as in RFC 2617. This is currently the only form of HTTP
|
|
proxy authentication that Tor supports; feel free to submit a patch if you
|
|
want it to support others.
|
|
|
|
[[HTTPSProxy]] **HTTPSProxy** __host__[:__port__]::
|
|
Tor will make all its OR (SSL) connections through this host:port (or
|
|
host:443 if port is not specified), via HTTP CONNECT rather than connecting
|
|
directly to servers. You may want to set **FascistFirewall** to restrict
|
|
the set of ports you might try to connect to, if your HTTPS proxy only
|
|
allows connecting to certain ports.
|
|
|
|
[[HTTPSProxyAuthenticator]] **HTTPSProxyAuthenticator** __username:password__::
|
|
If defined, Tor will use this username:password for Basic HTTPS proxy
|
|
authentication, as in RFC 2617. This is currently the only form of HTTPS
|
|
proxy authentication that Tor supports; feel free to submit a patch if you
|
|
want it to support others.
|
|
|
|
[[Sandbox]] **Sandbox** **0**|**1**::
|
|
If set to 1, Tor will run securely through the use of a syscall sandbox.
|
|
Otherwise the sandbox will be disabled. The option is currently an
|
|
experimental feature. (Default: 0)
|
|
|
|
[[Socks4Proxy]] **Socks4Proxy** __host__[:__port__]::
|
|
Tor will make all OR connections through the SOCKS 4 proxy at host:port
|
|
(or host:1080 if port is not specified).
|
|
|
|
[[Socks5Proxy]] **Socks5Proxy** __host__[:__port__]::
|
|
Tor will make all OR connections through the SOCKS 5 proxy at host:port
|
|
(or host:1080 if port is not specified).
|
|
|
|
[[Socks5ProxyUsername]] **Socks5ProxyUsername** __username__ +
|
|
|
|
[[Socks5ProxyPassword]] **Socks5ProxyPassword** __password__::
|
|
If defined, authenticate to the SOCKS 5 server using username and password
|
|
in accordance to RFC 1929. Both username and password must be between 1 and
|
|
255 characters.
|
|
|
|
[[KeepalivePeriod]] **KeepalivePeriod** __NUM__::
|
|
To keep firewalls from expiring connections, send a padding keepalive cell
|
|
every NUM seconds on open connections that are in use. If the connection
|
|
has no open circuits, it will instead be closed after NUM seconds of
|
|
idleness. (Default: 5 minutes)
|
|
|
|
[[Log]] **Log** __minSeverity__[-__maxSeverity__] **stderr**|**stdout**|**syslog**::
|
|
Send all messages between __minSeverity__ and __maxSeverity__ to the standard
|
|
output stream, the standard error stream, or to the system log. (The
|
|
"syslog" value is only supported on Unix.) Recognized severity levels are
|
|
debug, info, notice, warn, and err. We advise using "notice" in most cases,
|
|
since anything more verbose may provide sensitive information to an
|
|
attacker who obtains the logs. If only one severity level is given, all
|
|
messages of that level or higher will be sent to the listed destination.
|
|
|
|
[[Log2]] **Log** __minSeverity__[-__maxSeverity__] **file** __FILENAME__::
|
|
As above, but send log messages to the listed filename. The
|
|
"Log" option may appear more than once in a configuration file.
|
|
Messages are sent to all the logs that match their severity
|
|
level.
|
|
|
|
[[Log3]] **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **file** __FILENAME__ +
|
|
|
|
[[Log4]] **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **stderr**|**stdout**|**syslog**::
|
|
As above, but select messages by range of log severity __and__ by a
|
|
set of "logging domains". Each logging domain corresponds to an area of
|
|
functionality inside Tor. You can specify any number of severity ranges
|
|
for a single log statement, each of them prefixed by a comma-separated
|
|
list of logging domains. You can prefix a domain with $$~$$ to indicate
|
|
negation, and use * to indicate "all domains". If you specify a severity
|
|
range without a list of domains, it matches all domains. +
|
|
+
|
|
This is an advanced feature which is most useful for debugging one or two
|
|
of Tor's subsystems at a time. +
|
|
+
|
|
The currently recognized domains are: general, crypto, net, config, fs,
|
|
protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge,
|
|
acct, hist, and handshake. Domain names are case-insensitive. +
|
|
+
|
|
For example, "`Log [handshake]debug [~net,~mm]info notice stdout`" sends
|
|
to stdout: all handshake messages of any severity, all info-and-higher
|
|
messages from domains other than networking and memory management, and all
|
|
messages of severity notice or higher.
|
|
|
|
[[LogMessageDomains]] **LogMessageDomains** **0**|**1**::
|
|
If 1, Tor includes message domains with each log message. Every log
|
|
message currently has at least one domain; most currently have exactly
|
|
one. This doesn't affect controller log messages. (Default: 0)
|
|
|
|
[[OutboundBindAddress]] **OutboundBindAddress** __IP__::
|
|
Make all outbound connections originate from the IP address specified. This
|
|
is only useful when you have multiple network interfaces, and you want all
|
|
of Tor's outgoing connections to use a single one. This option may
|
|
be used twice, once with an IPv4 address and once with an IPv6 address.
|
|
This setting will be ignored for connections to the loopback addresses
|
|
(127.0.0.0/8 and ::1).
|
|
|
|
[[PidFile]] **PidFile** __FILE__::
|
|
On startup, write our PID to FILE. On clean shutdown, remove
|
|
FILE.
|
|
|
|
[[ProtocolWarnings]] **ProtocolWarnings** **0**|**1**::
|
|
If 1, Tor will log with severity \'warn' various cases of other parties not
|
|
following the Tor specification. Otherwise, they are logged with severity
|
|
\'info'. (Default: 0)
|
|
|
|
[[PredictedPortsRelevanceTime]] **PredictedPortsRelevanceTime** __NUM__::
|
|
Set how long, after the client has mad an anonymized connection to a
|
|
given port, we will try to make sure that we build circuits to
|
|
exits that support that port. The maximum value for this option is 1
|
|
hour. (Default: 1 hour)
|
|
|
|
[[RunAsDaemon]] **RunAsDaemon** **0**|**1**::
|
|
If 1, Tor forks and daemonizes to the background. This option has no effect
|
|
on Windows; instead you should use the --service command-line option.
|
|
(Default: 0)
|
|
|
|
[[LogTimeGranularity]] **LogTimeGranularity** __NUM__::
|
|
Set the resolution of timestamps in Tor's logs to NUM milliseconds.
|
|
NUM must be positive and either a divisor or a multiple of 1 second.
|
|
Note that this option only controls the granularity written by Tor to
|
|
a file or console log. Tor does not (for example) "batch up" log
|
|
messages to affect times logged by a controller, times attached to
|
|
syslog messages, or the mtime fields on log files. (Default: 1 second)
|
|
|
|
[[TruncateLogFile]] **TruncateLogFile** **0**|**1**::
|
|
If 1, Tor will overwrite logs at startup and in response to a HUP signal,
|
|
instead of appending to them. (Default: 0)
|
|
|
|
[[SafeLogging]] **SafeLogging** **0**|**1**|**relay**::
|
|
Tor can scrub potentially sensitive strings from log messages (e.g.
|
|
addresses) by replacing them with the string [scrubbed]. This way logs can
|
|
still be useful, but they don't leave behind personally identifying
|
|
information about what sites a user might have visited. +
|
|
+
|
|
If this option is set to 0, Tor will not perform any scrubbing, if it is
|
|
set to 1, all potentially sensitive strings are replaced. If it is set to
|
|
relay, all log messages generated when acting as a relay are sanitized, but
|
|
all messages generated when acting as a client are not. (Default: 1)
|
|
|
|
[[User]] **User** __UID__::
|
|
On startup, setuid to this user and setgid to their primary group.
|
|
|
|
[[HardwareAccel]] **HardwareAccel** **0**|**1**::
|
|
If non-zero, try to use built-in (static) crypto hardware acceleration when
|
|
available. (Default: 0)
|
|
|
|
[[AccelName]] **AccelName** __NAME__::
|
|
When using OpenSSL hardware crypto acceleration attempt to load the dynamic
|
|
engine of this name. This must be used for any dynamic hardware engine.
|
|
Names can be verified with the openssl engine command.
|
|
|
|
[[AccelDir]] **AccelDir** __DIR__::
|
|
Specify this option if using dynamic hardware acceleration and the engine
|
|
implementation library resides somewhere other than the OpenSSL default.
|
|
|
|
[[AvoidDiskWrites]] **AvoidDiskWrites** **0**|**1**::
|
|
If non-zero, try to write to disk less frequently than we would otherwise.
|
|
This is useful when running on flash memory or other media that support
|
|
only a limited number of writes. (Default: 0)
|
|
|
|
[[CircuitPriorityHalflife]] **CircuitPriorityHalflife** __NUM1__::
|
|
If this value is set, we override the default algorithm for choosing which
|
|
circuit's cell to deliver or relay next. When the value is 0, we
|
|
round-robin between the active circuits on a connection, delivering one
|
|
cell from each in turn. When the value is positive, we prefer delivering
|
|
cells from whichever connection has the lowest weighted cell count, where
|
|
cells are weighted exponentially according to the supplied
|
|
CircuitPriorityHalflife value (in seconds). If this option is not set at
|
|
all, we use the behavior recommended in the current consensus
|
|
networkstatus. This is an advanced option; you generally shouldn't have
|
|
to mess with it. (Default: not set)
|
|
|
|
[[DisableIOCP]] **DisableIOCP** **0**|**1**::
|
|
If Tor was built to use the Libevent's "bufferevents" networking code
|
|
and you're running on Windows, setting this option to 1 will tell Libevent
|
|
not to use the Windows IOCP networking API. (Default: 1)
|
|
|
|
[[UserspaceIOCPBuffers]] **UserspaceIOCPBuffers** **0**|**1**::
|
|
If IOCP is enabled (see DisableIOCP above), setting this option to 1
|
|
will tell Tor to disable kernel-space TCP buffers, in order to avoid
|
|
needless copy operations and try not to run out of non-paged RAM.
|
|
This feature is experimental; don't use it yet unless you're eager to
|
|
help tracking down bugs. (Default: 0)
|
|
|
|
[[UseFilteringSSLBufferevents]] **UseFilteringSSLBufferevents** **0**|**1**::
|
|
Tells Tor to do its SSL communication using a chain of
|
|
bufferevents: one for SSL and one for networking. This option has no
|
|
effect if bufferevents are disabled (in which case it can't turn on), or
|
|
if IOCP bufferevents are enabled (in which case it can't turn off). This
|
|
option is useful for debugging only; most users shouldn't touch it.
|
|
(Default: 0)
|
|
|
|
[[CountPrivateBandwidth]] **CountPrivateBandwidth** **0**|**1**::
|
|
If this option is set, then Tor's rate-limiting applies not only to
|
|
remote connections, but also to connections to private addresses like
|
|
127.0.0.1 or 10.0.0.1. This is mostly useful for debugging
|
|
rate-limiting. (Default: 0)
|
|
|
|
CLIENT OPTIONS
|
|
--------------
|
|
|
|
The following options are useful only for clients (that is, if
|
|
**SocksPort**, **TransPort**, **DNSPort**, or **NATDPort** is non-zero):
|
|
|
|
[[AllowInvalidNodes]] **AllowInvalidNodes** **entry**|**exit**|**middle**|**introduction**|**rendezvous**|**...**::
|
|
If some Tor servers are obviously not working right, the directory
|
|
authorities can manually mark them as invalid, meaning that it's not
|
|
recommended you use them for entry or exit positions in your circuits. You
|
|
can opt to use them in some circuit positions, though. The default is
|
|
"middle,rendezvous", and other choices are not advised.
|
|
|
|
[[ExcludeSingleHopRelays]] **ExcludeSingleHopRelays** **0**|**1**::
|
|
This option controls whether circuits built by Tor will include relays with
|
|
the AllowSingleHopExits flag set to true. If ExcludeSingleHopRelays is set
|
|
to 0, these relays will be included. Note that these relays might be at
|
|
higher risk of being seized or observed, so they are not normally
|
|
included. Also note that relatively few clients turn off this option,
|
|
so using these relays might make your client stand out.
|
|
(Default: 1)
|
|
|
|
[[Bridge]] **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]::
|
|
When set along with UseBridges, instructs Tor to use the relay at
|
|
"IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint"
|
|
is provided (using the same format as for DirAuthority), we will verify that
|
|
the relay running at that location has the right fingerprint. We also use
|
|
fingerprint to look up the bridge descriptor at the bridge authority, if
|
|
it's provided and if UpdateBridgesFromAuthority is set too. +
|
|
+
|
|
If "transport" is provided, and matches to a ClientTransportPlugin
|
|
line, we use that pluggable transports proxy to transfer data to
|
|
the bridge.
|
|
|
|
[[LearnCircuitBuildTimeout]] **LearnCircuitBuildTimeout** **0**|**1**::
|
|
If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1)
|
|
|
|
[[CircuitBuildTimeout]] **CircuitBuildTimeout** __NUM__::
|
|
|
|
Try for at most NUM seconds when building circuits. If the circuit isn't
|
|
open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this
|
|
value serves as the initial value to use before a timeout is learned. If
|
|
LearnCircuitBuildTimeout is 0, this value is the only value used.
|
|
(Default: 60 seconds)
|
|
|
|
[[CircuitIdleTimeout]] **CircuitIdleTimeout** __NUM__::
|
|
If we have kept a clean (never used) circuit around for NUM seconds, then
|
|
close it. This way when the Tor client is entirely idle, it can expire all
|
|
of its circuits, and then expire its TLS connections. Also, if we end up
|
|
making a circuit that is not useful for exiting any of the requests we're
|
|
receiving, it won't forever take up a slot in the circuit list. (Default: 1
|
|
hour)
|
|
|
|
[[CircuitStreamTimeout]] **CircuitStreamTimeout** __NUM__::
|
|
If non-zero, this option overrides our internal timeout schedule for how
|
|
many seconds until we detach a stream from a circuit and try a new circuit.
|
|
If your network is particularly slow, you might want to set this to a
|
|
number like 60. (Default: 0)
|
|
|
|
[[ClientOnly]] **ClientOnly** **0**|**1**::
|
|
If set to 1, Tor will not run as a relay or serve
|
|
directory requests, even if the ORPort, ExtORPort, or DirPort options are
|
|
set. (This config option is
|
|
mostly unnecessary: we added it back when we were considering having
|
|
Tor clients auto-promote themselves to being relays if they were stable
|
|
and fast enough. The current behavior is simply that Tor is a client
|
|
unless ORPort, ExtORPort, or DirPort are configured.) (Default: 0)
|
|
|
|
[[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__::
|
|
A list of identity fingerprints, nicknames, country codes and address
|
|
patterns of nodes to avoid when building a circuit.
|
|
(Example:
|
|
ExcludeNodes SlowServer, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
|
|
+
|
|
By default, this option is treated as a preference that Tor is allowed
|
|
to override in order to keep working.
|
|
For example, if you try to connect to a hidden service,
|
|
but you have excluded all of the hidden service's introduction points,
|
|
Tor will connect to one of them anyway. If you do not want this
|
|
behavior, set the StrictNodes option (documented below). +
|
|
+
|
|
Note also that if you are a relay, this (and the other node selection
|
|
options below) only affects your own circuits that Tor builds for you.
|
|
Clients can still build circuits through you to any node. Controllers
|
|
can tell Tor to build circuits through any node. +
|
|
+
|
|
Country codes are case-insensitive. The code "\{??}" refers to nodes whose
|
|
country can't be identified. No country code, including \{??}, works if
|
|
no GeoIPFile can be loaded. See also the GeoIPExcludeUnknown option below.
|
|
|
|
|
|
[[ExcludeExitNodes]] **ExcludeExitNodes** __node__,__node__,__...__::
|
|
A list of identity fingerprints, nicknames, country codes and address
|
|
patterns of nodes to never use when picking an exit node---that is, a
|
|
node that delivers traffic for you outside the Tor network. Note that any
|
|
node listed in ExcludeNodes is automatically considered to be part of this
|
|
list too. See also the caveats on the "ExitNodes" option below.
|
|
|
|
[[GeoIPExcludeUnknown]] **GeoIPExcludeUnknown** **0**|**1**|**auto**::
|
|
If this option is set to 'auto', then whenever any country code is set in
|
|
ExcludeNodes or ExcludeExitNodes, all nodes with unknown country (\{??} and
|
|
possibly \{A1}) are treated as excluded as well. If this option is set to
|
|
'1', then all unknown countries are treated as excluded in ExcludeNodes
|
|
and ExcludeExitNodes. This option has no effect when a GeoIP file isn't
|
|
configured or can't be found. (Default: auto)
|
|
|
|
[[ExitNodes]] **ExitNodes** __node__,__node__,__...__::
|
|
A list of identity fingerprints, nicknames, country codes and address
|
|
patterns of nodes to use as exit node---that is, a
|
|
node that delivers traffic for you outside the Tor network. +
|
|
+
|
|
Note that if you list too few nodes here, or if you exclude too many exit
|
|
nodes with ExcludeExitNodes, you can degrade functionality. For example,
|
|
if none of the exits you list allows traffic on port 80 or 443, you won't
|
|
be able to browse the web. +
|
|
+
|
|
Note also that not every circuit is used to deliver traffic outside of
|
|
the Tor network. It is normal to see non-exit circuits (such as those
|
|
used to connect to hidden services, those that do directory fetches,
|
|
those used for relay reachability self-tests, and so on) that end
|
|
at a non-exit node. To
|
|
keep a node from being used entirely, see ExcludeNodes and StrictNodes. +
|
|
+
|
|
The ExcludeNodes option overrides this option: any node listed in both
|
|
ExitNodes and ExcludeNodes is treated as excluded. +
|
|
+
|
|
The .exit address notation, if enabled via AllowDotExit, overrides
|
|
this option.
|
|
|
|
[[EntryNodes]] **EntryNodes** __node__,__node__,__...__::
|
|
A list of identity fingerprints, nicknames, and country codes of nodes
|
|
to use for the first hop in your normal circuits.
|
|
Normal circuits include all
|
|
circuits except for direct connections to directory servers. The Bridge
|
|
option overrides this option; if you have configured bridges and
|
|
UseBridges is 1, the Bridges are used as your entry nodes. +
|
|
+
|
|
The ExcludeNodes option overrides this option: any node listed in both
|
|
EntryNodes and ExcludeNodes is treated as excluded.
|
|
|
|
[[StrictNodes]] **StrictNodes** **0**|**1**::
|
|
If StrictNodes is set to 1, Tor will treat the ExcludeNodes option as a
|
|
requirement to follow for all the circuits you generate, even if doing so
|
|
will break functionality for you. If StrictNodes is set to 0, Tor will
|
|
still try to avoid nodes in the ExcludeNodes list, but it will err on the
|
|
side of avoiding unexpected errors. Specifically, StrictNodes 0 tells
|
|
Tor that it is okay to use an excluded node when it is *necessary* to
|
|
perform relay reachability self-tests, connect to
|
|
a hidden service, provide a hidden service to a client, fulfill a .exit
|
|
request, upload directory information, or download directory information.
|
|
(Default: 0)
|
|
|
|
[[FascistFirewall]] **FascistFirewall** **0**|**1**::
|
|
If 1, Tor will only create outgoing connections to ORs running on ports
|
|
that your firewall allows (defaults to 80 and 443; see **FirewallPorts**).
|
|
This will allow you to run Tor as a client behind a firewall with
|
|
restrictive policies, but will not allow you to run as a server behind such
|
|
a firewall. If you prefer more fine-grained control, use
|
|
ReachableAddresses instead.
|
|
|
|
[[FirewallPorts]] **FirewallPorts** __PORTS__::
|
|
A list of ports that your firewall allows you to connect to. Only used when
|
|
**FascistFirewall** is set. This option is deprecated; use ReachableAddresses
|
|
instead. (Default: 80, 443)
|
|
|
|
[[ReachableAddresses]] **ReachableAddresses** __ADDR__[/__MASK__][:__PORT__]...::
|
|
A comma-separated list of IP addresses and ports that your firewall allows
|
|
you to connect to. The format is as for the addresses in ExitPolicy, except
|
|
that "accept" is understood unless "reject" is explicitly provided. For
|
|
example, \'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept
|
|
\*:80' means that your firewall allows connections to everything inside net
|
|
99, rejects port 80 connections to net 18, and accepts connections to port
|
|
80 otherwise. (Default: \'accept \*:*'.)
|
|
|
|
[[ReachableDirAddresses]] **ReachableDirAddresses** __ADDR__[/__MASK__][:__PORT__]...::
|
|
Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
|
|
these restrictions when fetching directory information, using standard HTTP
|
|
GET requests. If not set explicitly then the value of
|
|
**ReachableAddresses** is used. If **HTTPProxy** is set then these
|
|
connections will go through that proxy.
|
|
|
|
[[ReachableORAddresses]] **ReachableORAddresses** __ADDR__[/__MASK__][:__PORT__]...::
|
|
Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
|
|
these restrictions when connecting to Onion Routers, using TLS/SSL. If not
|
|
set explicitly then the value of **ReachableAddresses** is used. If
|
|
**HTTPSProxy** is set then these connections will go through that proxy. +
|
|
+
|
|
The separation between **ReachableORAddresses** and
|
|
**ReachableDirAddresses** is only interesting when you are connecting
|
|
through proxies (see **HTTPProxy** and **HTTPSProxy**). Most proxies limit
|
|
TLS connections (which Tor uses to connect to Onion Routers) to port 443,
|
|
and some limit HTTP GET requests (which Tor uses for fetching directory
|
|
information) to port 80.
|
|
|
|
[[HidServAuth]] **HidServAuth** __onion-address__ __auth-cookie__ [__service-name__]::
|
|
Client authorization for a hidden service. Valid onion addresses contain 16
|
|
characters in a-z2-7 plus ".onion", and valid auth cookies contain 22
|
|
characters in A-Za-z0-9+/. The service name is only used for internal
|
|
purposes, e.g., for Tor controllers. This option may be used multiple times
|
|
for different hidden services. If a hidden service uses authorization and
|
|
this option is not set, the hidden service is not accessible. Hidden
|
|
services can be configured to require authorization using the
|
|
**HiddenServiceAuthorizeClient** option.
|
|
|
|
[[CloseHSClientCircuitsImmediatelyOnTimeout]] **CloseHSClientCircuitsImmediatelyOnTimeout** **0**|**1**::
|
|
If 1, Tor will close unfinished hidden service client circuits
|
|
which have not moved closer to connecting to their destination
|
|
hidden service when their internal state has not changed for the
|
|
duration of the current circuit-build timeout. Otherwise, such
|
|
circuits will be left open, in the hope that they will finish
|
|
connecting to their destination hidden services. In either case,
|
|
another set of introduction and rendezvous circuits for the same
|
|
destination hidden service will be launched. (Default: 0)
|
|
|
|
[[CloseHSServiceRendCircuitsImmediatelyOnTimeout]] **CloseHSServiceRendCircuitsImmediatelyOnTimeout** **0**|**1**::
|
|
If 1, Tor will close unfinished hidden-service-side rendezvous
|
|
circuits after the current circuit-build timeout. Otherwise, such
|
|
circuits will be left open, in the hope that they will finish
|
|
connecting to their destinations. In either case, another
|
|
rendezvous circuit for the same destination client will be
|
|
launched. (Default: 0)
|
|
|
|
[[LongLivedPorts]] **LongLivedPorts** __PORTS__::
|
|
A list of ports for services that tend to have long-running connections
|
|
(e.g. chat and interactive shells). Circuits for streams that use these
|
|
ports will contain only high-uptime nodes, to reduce the chance that a node
|
|
will go down before the stream is finished. Note that the list is also
|
|
honored for circuits (both client and service side) involving hidden
|
|
services whose virtual port is in this list. (Default: 21, 22, 706,
|
|
1863, 5050, 5190, 5222, 5223, 6523, 6667, 6697, 8300)
|
|
|
|
[[MapAddress]] **MapAddress** __address__ __newaddress__::
|
|
When a request for address arrives to Tor, it will transform to newaddress
|
|
before processing it. For example, if you always want connections to
|
|
www.example.com to exit via __torserver__ (where __torserver__ is the
|
|
nickname of the server), use "MapAddress www.example.com
|
|
www.example.com.torserver.exit". If the value is prefixed with a
|
|
"\*.", matches an entire domain. For example, if you
|
|
always want connections to example.com and any if its subdomains
|
|
to exit via
|
|
__torserver__ (where __torserver__ is the nickname of the server), use
|
|
"MapAddress \*.example.com \*.example.com.torserver.exit". (Note the
|
|
leading "*." in each part of the directive.) You can also redirect all
|
|
subdomains of a domain to a single address. For example, "MapAddress
|
|
*.example.com www.example.com". +
|
|
+
|
|
NOTES:
|
|
|
|
1. When evaluating MapAddress expressions Tor stops when it hits the most
|
|
recently added expression that matches the requested address. So if you
|
|
have the following in your torrc, www.torproject.org will map to 1.1.1.1:
|
|
|
|
MapAddress www.torproject.org 2.2.2.2
|
|
MapAddress www.torproject.org 1.1.1.1
|
|
|
|
2. Tor evaluates the MapAddress configuration until it finds no matches. So
|
|
if you have the following in your torrc, www.torproject.org will map to
|
|
2.2.2.2:
|
|
|
|
MapAddress 1.1.1.1 2.2.2.2
|
|
MapAddress www.torproject.org 1.1.1.1
|
|
|
|
3. The following MapAddress expression is invalid (and will be
|
|
ignored) because you cannot map from a specific address to a wildcard
|
|
address:
|
|
|
|
MapAddress www.torproject.org *.torproject.org.torserver.exit
|
|
|
|
4. Using a wildcard to match only part of a string (as in *ample.com) is
|
|
also invalid.
|
|
|
|
[[NewCircuitPeriod]] **NewCircuitPeriod** __NUM__::
|
|
Every NUM seconds consider whether to build a new circuit. (Default: 30
|
|
seconds)
|
|
|
|
[[MaxCircuitDirtiness]] **MaxCircuitDirtiness** __NUM__::
|
|
Feel free to reuse a circuit that was first used at most NUM seconds ago,
|
|
but never attach a new stream to a circuit that is too old. For hidden
|
|
services, this applies to the __last__ time a circuit was used, not the
|
|
first. (Default: 10 minutes)
|
|
|
|
[[MaxClientCircuitsPending]] **MaxClientCircuitsPending** __NUM__::
|
|
Do not allow more than NUM circuits to be pending at a time for handling
|
|
client streams. A circuit is pending if we have begun constructing it,
|
|
but it has not yet been completely constructed. (Default: 32)
|
|
|
|
[[NodeFamily]] **NodeFamily** __node__,__node__,__...__::
|
|
The Tor servers, defined by their identity fingerprints or nicknames,
|
|
constitute a "family" of similar or co-administered servers, so never use
|
|
any two of them in the same circuit. Defining a NodeFamily is only needed
|
|
when a server doesn't list the family itself (with MyFamily). This option
|
|
can be used multiple times. In addition to nodes, you can also list
|
|
IP address and ranges and country codes in {curly braces}.
|
|
|
|
[[EnforceDistinctSubnets]] **EnforceDistinctSubnets** **0**|**1**::
|
|
If 1, Tor will not put two servers whose IP addresses are "too close" on
|
|
the same circuit. Currently, two addresses are "too close" if they lie in
|
|
the same /16 range. (Default: 1)
|
|
|
|
[[SOCKSPort]] **SOCKSPort** \['address':]__port__|**auto** [_flags_] [_isolation flags_]::
|
|
Open this port to listen for connections from SOCKS-speaking
|
|
applications. Set this to 0 if you don't want to allow application
|
|
connections via SOCKS. Set it to "auto" to have Tor pick a port for
|
|
you. This directive can be specified multiple times to bind
|
|
to multiple addresses/ports. (Default: 9050) +
|
|
+
|
|
The _isolation flags_ arguments give Tor rules for which streams
|
|
received on this SOCKSPort are allowed to share circuits with one
|
|
another. Recognized isolation flags are:
|
|
**IsolateClientAddr**;;
|
|
Don't share circuits with streams from a different
|
|
client address. (On by default and strongly recommended;
|
|
you can disable it with **NoIsolateClientAddr**.)
|
|
**IsolateSOCKSAuth**;;
|
|
Don't share circuits with streams for which different
|
|
SOCKS authentication was provided. (On by default;
|
|
you can disable it with **NoIsolateSOCKSAuth**.)
|
|
**IsolateClientProtocol**;;
|
|
Don't share circuits with streams using a different protocol.
|
|
(SOCKS 4, SOCKS 5, TransPort connections, NATDPort connections,
|
|
and DNSPort requests are all considered to be different protocols.)
|
|
**IsolateDestPort**;;
|
|
Don't share circuits with streams targetting a different
|
|
destination port.
|
|
**IsolateDestAddr**;;
|
|
Don't share circuits with streams targetting a different
|
|
destination address.
|
|
**SessionGroup=**__INT__;;
|
|
If no other isolation rules would prevent it, allow streams
|
|
on this port to share circuits with streams from every other
|
|
port with the same session group. (By default, streams received
|
|
on different SOCKSPorts, TransPorts, etc are always isolated from one
|
|
another. This option overrides that behavior.)
|
|
|
|
[[OtherSOCKSPortFlags]]::
|
|
Other recognized __flags__ for a SOCKSPort are:
|
|
**NoIPv4Traffic**;;
|
|
Tell exits to not connect to IPv4 addresses in response to SOCKS
|
|
requests on this connection.
|
|
**IPv6Traffic**;;
|
|
Tell exits to allow IPv6 addresses in response to SOCKS requests on
|
|
this connection, so long as SOCKS5 is in use. (SOCKS4 can't handle
|
|
IPv6.)
|
|
**PreferIPv6**;;
|
|
Tells exits that, if a host has both an IPv4 and an IPv6 address,
|
|
we would prefer to connect to it via IPv6. (IPv4 is the default.) +
|
|
+
|
|
NOTE: Although this option allows you to specify an IP address
|
|
other than localhost, you should do so only with extreme caution.
|
|
The SOCKS protocol is unencrypted and (as we use it)
|
|
unauthenticated, so exposing it in this way could leak your
|
|
information to anybody watching your network, and allow anybody
|
|
to use your computer as an open proxy. +
|
|
+
|
|
**CacheIPv4DNS**;;
|
|
Tells the client to remember IPv4 DNS answers we receive from exit
|
|
nodes via this connection. (On by default.)
|
|
**CacheIPv6DNS**;;
|
|
Tells the client to remember IPv6 DNS answers we receive from exit
|
|
nodes via this connection.
|
|
**CacheDNS**;;
|
|
Tells the client to remember all DNS answers we receive from exit
|
|
nodes via this connection.
|
|
**UseIPv4Cache**;;
|
|
Tells the client to use any cached IPv4 DNS answers we have when making
|
|
requests via this connection. (NOTE: This option, along UseIPv6Cache
|
|
and UseDNSCache, can harm your anonymity, and probably
|
|
won't help performance as much as you might expect. Use with care!)
|
|
**UseIPv6Cache**;;
|
|
Tells the client to use any cached IPv6 DNS answers we have when making
|
|
requests via this connection.
|
|
**UseDNSCache**;;
|
|
Tells the client to use any cached DNS answers we have when making
|
|
requests via this connection.
|
|
**PreferIPv6Automap**;;
|
|
When serving a hostname lookup request on this port that
|
|
should get automapped (according to AutomapHostsOnResove),
|
|
if we could return either an IPv4 or an IPv6 answer, prefer
|
|
an IPv6 answer. (On by default.)
|
|
**PreferSOCKSNoAuth**;;
|
|
Ordinarily, when an application offers both "username/password
|
|
authentication" and "no authentication" to Tor via SOCKS5, Tor
|
|
selects username/password authentication so that IsolateSOCKSAuth can
|
|
work. This can confuse some applications, if they offer a
|
|
username/password combination then get confused when asked for
|
|
one. You can disable this behavior, so that Tor will select "No
|
|
authentication" when IsolateSOCKSAuth is disabled, or when this
|
|
option is set.
|
|
|
|
[[SOCKSListenAddress]] **SOCKSListenAddress** __IP__[:__PORT__]::
|
|
Bind to this address to listen for connections from Socks-speaking
|
|
applications. (Default: 127.0.0.1) You can also specify a port (e.g.
|
|
192.168.0.1:9100). This directive can be specified multiple times to bind
|
|
to multiple addresses/ports. (DEPRECATED: As of 0.2.3.x-alpha, you can
|
|
now use multiple SOCKSPort entries, and provide addresses for SOCKSPort
|
|
entries, so SOCKSListenAddress no longer has a purpose. For backward
|
|
compatibility, SOCKSListenAddress is only allowed when SOCKSPort is just
|
|
a port number.)
|
|
|
|
[[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__::
|
|
Set an entrance policy for this server, to limit who can connect to the
|
|
SocksPort and DNSPort ports. The policies have the same form as exit
|
|
policies below, except that port specifiers are ignored. Any address
|
|
not matched by some entry in the policy is accepted.
|
|
|
|
[[SocksTimeout]] **SocksTimeout** __NUM__::
|
|
Let a socks connection wait NUM seconds handshaking, and NUM seconds
|
|
unattached waiting for an appropriate circuit, before we fail it. (Default:
|
|
2 minutes)
|
|
|
|
[[TokenBucketRefillInterval]] **TokenBucketRefillInterval** __NUM__ [**msec**|**second**]::
|
|
Set the refill interval of Tor's token bucket to NUM milliseconds.
|
|
NUM must be between 1 and 1000, inclusive. Note that the configured
|
|
bandwidth limits are still expressed in bytes per second: this
|
|
option only affects the frequency with which Tor checks to see whether
|
|
previously exhausted connections may read again. (Default: 100 msec)
|
|
|
|
[[TrackHostExits]] **TrackHostExits** __host__,__.domain__,__...__::
|
|
For each value in the comma separated list, Tor will track recent
|
|
connections to hosts that match this value and attempt to reuse the same
|
|
exit node for each. If the value is prepended with a \'.\', it is treated as
|
|
matching an entire domain. If one of the values is just a \'.', it means
|
|
match everything. This option is useful if you frequently connect to sites
|
|
that will expire all your authentication cookies (i.e. log you out) if
|
|
your IP address changes. Note that this option does have the disadvantage
|
|
of making it more clear that a given history is associated with a single
|
|
user. However, most people who would wish to observe this will observe it
|
|
through cookies or other protocol-specific means anyhow.
|
|
|
|
[[TrackHostExitsExpire]] **TrackHostExitsExpire** __NUM__::
|
|
Since exit servers go up and down, it is desirable to expire the
|
|
association between host and exit server after NUM seconds. The default is
|
|
1800 seconds (30 minutes).
|
|
|
|
[[UpdateBridgesFromAuthority]] **UpdateBridgesFromAuthority** **0**|**1**::
|
|
When set (along with UseBridges), Tor will try to fetch bridge descriptors
|
|
from the configured bridge authorities when feasible. It will fall back to
|
|
a direct request if the authority responds with a 404. (Default: 0)
|
|
|
|
[[UseBridges]] **UseBridges** **0**|**1**::
|
|
When set, Tor will fetch descriptors for each bridge listed in the "Bridge"
|
|
config lines, and use these relays as both entry guards and directory
|
|
guards. (Default: 0)
|
|
|
|
[[UseEntryGuards]] **UseEntryGuards** **0**|**1**::
|
|
If this option is set to 1, we pick a few long-term entry servers, and try
|
|
to stick with them. This is desirable because constantly changing servers
|
|
increases the odds that an adversary who owns some servers will observe a
|
|
fraction of your paths. (Default: 1)
|
|
|
|
[[UseEntryGuardsAsDirGuards]] **UseEntryGuardsAsDirGuards** **0**|**1**::
|
|
If this option is set to 1, and UseEntryGuards is also set to 1,
|
|
we try to use our entry guards as directory
|
|
guards, and failing that, pick more nodes to act as our directory guards.
|
|
This helps prevent an adversary from enumerating clients. It's only
|
|
available for clients (non-relay, non-bridge) that aren't configured to
|
|
download any non-default directory material. It doesn't currently
|
|
do anything when we lack a live consensus. (Default: 1)
|
|
|
|
[[NumEntryGuards]] **NumEntryGuards** __NUM__::
|
|
If UseEntryGuards is set to 1, we will try to pick a total of NUM routers
|
|
as long-term entries for our circuits. If NUM is 0, we try to learn
|
|
the number from the NumEntryGuards consensus parameter, and default
|
|
to 3 if the consensus parameter isn't set. (Default: 0)
|
|
|
|
[[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__::
|
|
If UseEntryGuardsAsDirectoryGuards is enabled, we try to make sure we
|
|
have at least NUM routers to use as directory guards. If this option
|
|
is set to 0, use the value from the NumDirectoryGuards consensus
|
|
parameter, falling back to the value from NumEntryGuards if the
|
|
consensus parameter is 0 or isn't set. (Default: 0)
|
|
|
|
[[GuardLifetime]] **GuardLifetime** __N__ **days**|**weeks**|**months**::
|
|
If nonzero, and UseEntryGuards is set, minimum time to keep a guard before
|
|
picking a new one. If zero, we use the GuardLifetime parameter from the
|
|
consensus directory. No value here may be less than 1 month or greater
|
|
than 5 years; out-of-range values are clamped. (Default: 0)
|
|
|
|
[[SafeSocks]] **SafeSocks** **0**|**1**::
|
|
When this option is enabled, Tor will reject application connections that
|
|
use unsafe variants of the socks protocol -- ones that only provide an IP
|
|
address, meaning the application is doing a DNS resolve first.
|
|
Specifically, these are socks4 and socks5 when not doing remote DNS.
|
|
(Default: 0)
|
|
|
|
[[TestSocks]] **TestSocks** **0**|**1**::
|
|
When this option is enabled, Tor will make a notice-level log entry for
|
|
each connection to the Socks port indicating whether the request used a
|
|
safe socks protocol or an unsafe one (see above entry on SafeSocks). This
|
|
helps to determine whether an application using Tor is possibly leaking
|
|
DNS requests. (Default: 0)
|
|
|
|
[[WarnUnsafeSocks]] **WarnUnsafeSocks** **0**|**1**::
|
|
When this option is enabled, Tor will warn whenever a request is
|
|
received that only contains an IP address instead of a hostname. Allowing
|
|
applications to do DNS resolves themselves is usually a bad idea and
|
|
can leak your location to attackers. (Default: 1)
|
|
|
|
[[VirtualAddrNetworkIPv4]] **VirtualAddrNetworkIPv4** __Address__/__bits__ +
|
|
|
|
[[VirtualAddrNetworkIPv6]] **VirtualAddrNetworkIPv6** [__Address__]/__bits__::
|
|
When Tor needs to assign a virtual (unused) address because of a MAPADDRESS
|
|
command from the controller or the AutomapHostsOnResolve feature, Tor
|
|
picks an unassigned address from this range. (Defaults:
|
|
127.192.0.0/10 and [FE80::]/10 respectively.) +
|
|
+
|
|
When providing proxy server service to a network of computers using a tool
|
|
like dns-proxy-tor, change the IPv4 network to "10.192.0.0/10" or
|
|
"172.16.0.0/12" and change the IPv6 network to "[FC00]/7".
|
|
The default **VirtualAddrNetwork** address ranges on a
|
|
properly configured machine will route to the loopback or link-local
|
|
interface. For
|
|
local use, no change to the default VirtualAddrNetwork setting is needed.
|
|
|
|
[[AllowNonRFC953Hostnames]] **AllowNonRFC953Hostnames** **0**|**1**::
|
|
When this option is disabled, Tor blocks hostnames containing illegal
|
|
characters (like @ and :) rather than sending them to an exit node to be
|
|
resolved. This helps trap accidental attempts to resolve URLs and so on.
|
|
(Default: 0)
|
|
|
|
[[AllowDotExit]] **AllowDotExit** **0**|**1**::
|
|
If enabled, we convert "www.google.com.foo.exit" addresses on the
|
|
SocksPort/TransPort/NATDPort into "www.google.com" addresses that exit from
|
|
the node "foo". Disabled by default since attacking websites and exit
|
|
relays can use it to manipulate your path selection. (Default: 0)
|
|
|
|
[[FastFirstHopPK]] **FastFirstHopPK** **0**|**1**|**auto**::
|
|
When this option is disabled, Tor uses the public key step for the first
|
|
hop of creating circuits. Skipping it is generally safe since we have
|
|
already used TLS to authenticate the relay and to establish forward-secure
|
|
keys. Turning this option off makes circuit building a little
|
|
slower. Setting this option to "auto" takes advice from the authorities
|
|
in the latest consensus about whether to use this feature. +
|
|
+
|
|
Note that Tor will always use the public key step for the first hop if it's
|
|
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: auto)
|
|
|
|
[[TransPort]] **TransPort** \['address':]__port__|**auto** [_isolation flags_]::
|
|
Open this port to listen for transparent proxy connections. Set this to
|
|
0 if you don't want to allow transparent proxy connections. Set the port
|
|
to "auto" to have Tor pick a port for you. This directive can be
|
|
specified multiple times to bind to multiple addresses/ports. See
|
|
SOCKSPort for an explanation of isolation flags. +
|
|
+
|
|
TransPort 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)
|
|
|
|
[[TransListenAddress]] **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. (DEPRECATED: As of 0.2.3.x-alpha, you can
|
|
now use multiple TransPort entries, and provide addresses for TransPort
|
|
entries, so TransListenAddress no longer has a purpose. For backward
|
|
compatibility, TransListenAddress is only allowed when TransPort is just
|
|
a port number.)
|
|
|
|
[[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**::
|
|
TransProxyType may only be enabled when there is transparent proxy listener
|
|
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
|
|
option. This setting lets the listener on the TransPort accept connections
|
|
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.
|
|
+
|
|
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.
|
|
+
|
|
Set this to "default", or leave it unconfigured, to use regular IPTables
|
|
on Linux, or to use pf +rdr-to+ rules on *BSD systems.
|
|
+
|
|
(Default: "default".)
|
|
|
|
[[NATDPort]] **NATDPort** \['address':]__port__|**auto** [_isolation flags_]::
|
|
Open this port to listen for connections from old versions of ipfw (as
|
|
included in old versions of FreeBSD, etc) using the NATD protocol.
|
|
Use 0 if you don't want to allow NATD connections. Set the port
|
|
to "auto" to have Tor pick a port for you. This directive can be
|
|
specified multiple times to bind to multiple addresses/ports. See
|
|
SOCKSPort for an explanation of isolation flags. +
|
|
+
|
|
This option is only for people who cannot use TransPort. (Default: 0)
|
|
|
|
[[NATDListenAddress]] **NATDListenAddress** __IP__[:__PORT__]::
|
|
Bind to this address to listen for NATD connections. (DEPRECATED: As of
|
|
0.2.3.x-alpha, you can now use multiple NATDPort entries, and provide
|
|
addresses for NATDPort entries, so NATDListenAddress no longer has a
|
|
purpose. For backward compatibility, NATDListenAddress is only allowed
|
|
when NATDPort is just a port number.)
|
|
|
|
[[AutomapHostsOnResolve]] **AutomapHostsOnResolve** **0**|**1**::
|
|
When this option is enabled, and we get a request to resolve an address
|
|
that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an
|
|
unused virtual address to that address, and return the new virtual address.
|
|
This is handy for making ".onion" addresses work with applications that
|
|
resolve an address and then connect to it. (Default: 0)
|
|
|
|
[[AutomapHostsSuffixes]] **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__::
|
|
A comma-separated list of suffixes to use with **AutomapHostsOnResolve**.
|
|
The "." suffix is equivalent to "all addresses." (Default: .exit,.onion).
|
|
|
|
[[DNSPort]] **DNSPort** \['address':]__port__|**auto** [_isolation flags_]::
|
|
If non-zero, open this port to listen for UDP DNS requests, and resolve
|
|
them anonymously. This port only handles A, AAAA, and PTR requests---it
|
|
doesn't handle arbitrary DNS request types. Set the port to "auto" to
|
|
have Tor pick a port for
|
|
you. This directive can be specified multiple times to bind to multiple
|
|
addresses/ports. See SOCKSPort for an explanation of isolation
|
|
flags. (Default: 0)
|
|
|
|
[[DNSListenAddress]] **DNSListenAddress** __IP__[:__PORT__]::
|
|
Bind to this address to listen for DNS connections. (DEPRECATED: As of
|
|
0.2.3.x-alpha, you can now use multiple DNSPort entries, and provide
|
|
addresses for DNSPort entries, so DNSListenAddress no longer has a
|
|
purpose. For backward compatibility, DNSListenAddress is only allowed
|
|
when DNSPort is just a port number.)
|
|
|
|
[[ClientDNSRejectInternalAddresses]] **ClientDNSRejectInternalAddresses** **0**|**1**::
|
|
If true, Tor does not believe any anonymously retrieved DNS answer that
|
|
tells it that an address resolves to an internal address (like 127.0.0.1 or
|
|
192.168.0.1). This option prevents certain browser-based attacks; don't
|
|
turn it off unless you know what you're doing. (Default: 1)
|
|
|
|
[[ClientRejectInternalAddresses]] **ClientRejectInternalAddresses** **0**|**1**::
|
|
If true, Tor does not try to fulfill requests to connect to an internal
|
|
address (like 127.0.0.1 or 192.168.0.1) __unless a exit node is
|
|
specifically requested__ (for example, via a .exit hostname, or a
|
|
controller request). (Default: 1)
|
|
|
|
[[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**::
|
|
If true, Tor downloads and caches "extra-info" documents. These documents
|
|
contain information about servers other than the information in their
|
|
regular router descriptors. Tor does not use this information for anything
|
|
itself; to save bandwidth, leave this option turned off. (Default: 0)
|
|
|
|
[[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__::
|
|
Tells Tor to issue a warnings whenever the user tries to make an anonymous
|
|
connection to one of these ports. This option is designed to alert users
|
|
to services that risk sending passwords in the clear. (Default:
|
|
23,109,110,143)
|
|
|
|
[[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__::
|
|
Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor
|
|
will instead refuse to make the connection. (Default: None)
|
|
|
|
[[AllowSingleHopCircuits]] **AllowSingleHopCircuits** **0**|**1**::
|
|
When this option is set, the attached Tor controller can use relays
|
|
that have the **AllowSingleHopExits** option turned on to build
|
|
one-hop Tor connections. (Default: 0)
|
|
|
|
[[OptimisticData]] **OptimisticData** **0**|**1**|**auto**::
|
|
When this option is set, and Tor is using an exit node that supports
|
|
the feature, it will try optimistically to send data to the exit node
|
|
without waiting for the exit node to report whether the connection
|
|
succeeded. This can save a round-trip time for protocols like HTTP
|
|
where the client talks first. If OptimisticData is set to **auto**,
|
|
Tor will look at the UseOptimisticData parameter in the networkstatus.
|
|
(Default: auto)
|
|
|
|
[[Tor2webMode]] **Tor2webMode** **0**|**1**::
|
|
When this option is set, Tor connects to hidden services
|
|
**non-anonymously**. This option also disables client connections to
|
|
non-hidden-service hostnames through Tor. It **must only** be used when
|
|
running a tor2web Hidden Service web proxy.
|
|
To enable this option the compile time flag --enable-tor2webmode must be
|
|
specified. (Default: 0)
|
|
|
|
[[UseMicrodescriptors]] **UseMicrodescriptors** **0**|**1**|**auto**::
|
|
Microdescriptors are a smaller version of the information that Tor needs
|
|
in order to build its circuits. Using microdescriptors makes Tor clients
|
|
download less directory information, thus saving bandwidth. Directory
|
|
caches need to fetch regular descriptors and microdescriptors, so this
|
|
option doesn't save any bandwidth for them. If this option is set to
|
|
"auto" (recommended) then it is on for all clients that do not set
|
|
FetchUselessDescriptors. (Default: auto)
|
|
|
|
[[UseNTorHandshake]] **UseNTorHandshake** **0**|**1**|**auto**::
|
|
The "ntor" circuit-creation handshake is faster and (we think) more
|
|
secure than the original ("TAP") circuit handshake, but starting to use
|
|
it too early might make your client stand out. If this option is 0, your
|
|
Tor client won't use the ntor handshake. If it's 1, your Tor client
|
|
will use the ntor handshake to extend circuits through servers that
|
|
support it. If this option is "auto", then your client
|
|
will use the ntor handshake once enough directory authorities recommend
|
|
it. (Default: 1)
|
|
|
|
[[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ +
|
|
|
|
[[PathBiasNoticeRate]] **PathBiasNoticeRate** __NUM__ +
|
|
|
|
[[PathBiasWarnRate]] **PathBiasWarnRate** __NUM__ +
|
|
|
|
[[PathBiasExtremeRate]] **PathBiasExtremeRate** __NUM__ +
|
|
|
|
[[PathBiasDropGuards]] **PathBiasDropGuards** __NUM__ +
|
|
|
|
[[PathBiasScaleThreshold]] **PathBiasScaleThreshold** __NUM__::
|
|
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.
|
|
+
|
|
The PathBiasCircThreshold option controls how many circuits we need to build
|
|
through a guard before we make these checks. The PathBiasNoticeRate,
|
|
PathBiasWarnRate and PathBiasExtremeRate options control what fraction of
|
|
circuits must succeed through a guard so we won't write log messages.
|
|
If less than PathBiasExtremeRate circuits succeed *and* PathBiasDropGuards
|
|
is set to 1, we disable use of that guard. +
|
|
+
|
|
When we have seen more than PathBiasScaleThreshold
|
|
circuits through a guard, we scale our observations by 0.5 (governed by
|
|
the consensus) so that new observations don't get swamped by old ones. +
|
|
+
|
|
By default, or if a negative value is provided for one of these options,
|
|
Tor uses reasonable defaults from the networkstatus consensus document.
|
|
If no defaults are available there, these options default to 150, .70,
|
|
.50, .30, 0, and 300 respectively.
|
|
|
|
[[PathBiasUseThreshold]] **PathBiasUseThreshold** __NUM__ +
|
|
|
|
[[PathBiasNoticeUseRate]] **PathBiasNoticeUseRate** __NUM__ +
|
|
|
|
[[PathBiasExtremeUseRate]] **PathBiasExtremeUseRate** __NUM__ +
|
|
|
|
[[PathBiasScaleUseThreshold]] **PathBiasScaleUseThreshold** __NUM__::
|
|
Similar to the above options, these options override the default behavior
|
|
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.
|
|
+
|
|
By default, or if a negative value is provided for one of these options,
|
|
Tor uses reasonable defaults from the networkstatus consensus document.
|
|
If no defaults are available there, these options default to 20, .80,
|
|
.60, and 100, respectively.
|
|
|
|
[[ClientUseIPv6]] **ClientUseIPv6** **0**|**1**::
|
|
If this option is set to 1, Tor might connect to entry nodes over
|
|
IPv6. Note that clients configured with an IPv6 address in a
|
|
**Bridge** line will try connecting over IPv6 even if
|
|
**ClientUseIPv6** is set to 0. (Default: 0)
|
|
|
|
[[ClientPreferIPv6ORPort]] **ClientPreferIPv6ORPort** **0**|**1**::
|
|
If this option is set to 1, Tor prefers an OR port with an IPv6
|
|
address over one with IPv4 if a given entry node has both. Other
|
|
things may influence the choice. This option breaks a tie to the
|
|
favor of IPv6. (Default: 0)
|
|
|
|
[[PathsNeededToBuildCircuits]] **PathsNeededToBuildCircuits** __NUM__::
|
|
Tor clients don't build circuits for user traffic until they know
|
|
about enough of the network so that they could potentially construct
|
|
enough of the possible paths through the network. If this option
|
|
is set to a fraction between 0.25 and 0.95, Tor won't build circuits
|
|
until it has enough descriptors or microdescriptors to construct
|
|
that fraction of possible paths. Note that setting this option too low
|
|
can make your Tor client less anonymous, and setting it too high can
|
|
prevent your Tor client from bootstrapping. If this option is negative,
|
|
Tor will use a default value chosen by the directory
|
|
authorities. (Default: -1.)
|
|
|
|
[[Support022HiddenServices]] **Support022HiddenServices** **0**|**1**|**auto**::
|
|
Tor hidden services running versions before 0.2.3.x required clients to
|
|
send timestamps, which can potentially be used to distinguish clients
|
|
whose view of the current time is skewed. If this option is set to 0, we
|
|
do not send this timestamp, and hidden services on obsolete Tor versions
|
|
will not work. If this option is set to 1, we send the timestamp. If
|
|
this optoin is "auto", we take a recommendation from the latest consensus
|
|
document. (Default: auto)
|
|
|
|
|
|
SERVER OPTIONS
|
|
--------------
|
|
|
|
The following options are useful only for servers (that is, if ORPort
|
|
is non-zero):
|
|
|
|
[[Address]] **Address** __address__::
|
|
The IP address or fully qualified domain name of this server (e.g.
|
|
moria.mit.edu). You can leave this unset, and Tor will guess your IP
|
|
address. This IP address is the one used to tell clients and other
|
|
servers where to find your Tor server; it doesn't affect the IP that your
|
|
Tor client binds to. To bind to a different address, use the
|
|
*ListenAddress and OutboundBindAddress options.
|
|
|
|
[[AllowSingleHopExits]] **AllowSingleHopExits** **0**|**1**::
|
|
This option controls whether clients can use this server as a single hop
|
|
proxy. If set to 1, clients can use this server as an exit even if it is
|
|
the only hop in the circuit. Note that most clients will refuse to use
|
|
servers that set this option, since most clients have
|
|
ExcludeSingleHopRelays set. (Default: 0)
|
|
|
|
[[AssumeReachable]] **AssumeReachable** **0**|**1**::
|
|
This option is used when bootstrapping a new Tor network. If set to 1,
|
|
don't do self-reachability testing; just upload your server descriptor
|
|
immediately. If **AuthoritativeDirectory** is also set, this option
|
|
instructs the dirserver to bypass remote reachability testing too and list
|
|
all connected servers as running.
|
|
|
|
[[BridgeRelay]] **BridgeRelay** **0**|**1**::
|
|
Sets the relay to act as a "bridge" with respect to relaying connections
|
|
from bridge users to the Tor network. It mainly causes Tor to publish a
|
|
server descriptor to the bridge database, rather than publishing a relay
|
|
descriptor to the public directory authorities.
|
|
|
|
[[ContactInfo]] **ContactInfo** __email_address__::
|
|
Administrative contact information for this relay or bridge. This line
|
|
can be used to contact you if your relay or bridge is misconfigured or
|
|
something else goes wrong. Note that we archive and publish all
|
|
descriptors containing these lines and that Google indexes them, so
|
|
spammers might also collect them. You may want to obscure the fact
|
|
that it's an email address and/or generate a new address for this
|
|
purpose.
|
|
|
|
[[ExitPolicy]] **ExitPolicy** __policy__,__policy__,__...__::
|
|
Set an exit policy for this server. Each policy is of the form
|
|
"**accept**|**reject** __ADDR__[/__MASK__][:__PORT__]". If /__MASK__ is
|
|
omitted then this policy just applies to the host given. Instead of giving
|
|
a host or network you can also use "\*" to denote the universe (0.0.0.0/0).
|
|
__PORT__ can be a single port number, an interval of ports
|
|
"__FROM_PORT__-__TO_PORT__", or "\*". If __PORT__ is omitted, that means
|
|
"\*". +
|
|
+
|
|
For example, "accept 18.7.22.69:\*,reject 18.0.0.0/8:\*,accept \*:\*" would
|
|
reject any traffic destined for MIT except for web.mit.edu, and accept
|
|
anything else. +
|
|
+
|
|
To specify all internal and link-local networks (including 0.0.0.0/8,
|
|
169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, and
|
|
172.16.0.0/12), you can use the "private" alias instead of an address.
|
|
These addresses are rejected by default (at the beginning of your exit
|
|
policy), along with your public IP address, unless you set the
|
|
ExitPolicyRejectPrivate config option to 0. For example, once you've done
|
|
that, you could allow HTTP to 127.0.0.1 and block all other connections to
|
|
internal networks with "accept 127.0.0.1:80,reject private:\*", though that
|
|
may also allow connections to your own computer that are addressed to its
|
|
public (external) IP address. See RFC 1918 and RFC 3330 for more details
|
|
about internal and reserved IP address space. +
|
|
+
|
|
This directive can be specified multiple times so you don't have to put it
|
|
all on one line. +
|
|
+
|
|
Policies are considered first to last, and the first match wins. If you
|
|
want to \_replace_ the default exit policy, end your exit policy with
|
|
either a reject \*:* or an accept \*:*. Otherwise, you're \_augmenting_
|
|
(prepending to) the default exit policy. The default exit policy is: +
|
|
|
|
reject *:25
|
|
reject *:119
|
|
reject *:135-139
|
|
reject *:445
|
|
reject *:563
|
|
reject *:1214
|
|
reject *:4661-4666
|
|
reject *:6346-6429
|
|
reject *:6699
|
|
reject *:6881-6999
|
|
accept *:*
|
|
|
|
[[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**::
|
|
Reject all private (local) networks, along with your own public IP address,
|
|
at the beginning of your exit policy. See above entry on ExitPolicy.
|
|
(Default: 1)
|
|
|
|
[[IPv6Exit]] **IPv6Exit** **0**|**1**::
|
|
If set, and we are an exit node, allow clients to use us for IPv6
|
|
traffic. (Default: 0)
|
|
|
|
[[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]::
|
|
If we have more onionskins queued for processing than we can process in
|
|
this amount of time, reject new ones. (Default: 1750 msec)
|
|
|
|
[[MyFamily]] **MyFamily** __node__,__node__,__...__::
|
|
Declare that this Tor server is controlled or administered by a group or
|
|
organization identical or similar to that of the other servers, defined by
|
|
their identity fingerprints or nicknames. When two servers both declare
|
|
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.
|
|
+
|
|
When listing a node, it's better to list it by fingerprint than by
|
|
nickname: fingerprints are more reliable.
|
|
|
|
[[Nickname]] **Nickname** __name__::
|
|
Set the server's nickname to \'name'. Nicknames must be between 1 and 19
|
|
characters inclusive, and must contain only the characters [a-zA-Z0-9].
|
|
|
|
[[NumCPUs]] **NumCPUs** __num__::
|
|
How many processes to use at once for decrypting onionskins and other
|
|
parallelizable operations. If this is set to 0, Tor will try to detect
|
|
how many CPUs you have, defaulting to 1 if it can't tell. (Default: 0)
|
|
|
|
[[ORPort]] **ORPort** \['address':]__PORT__|**auto** [_flags_]::
|
|
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)
|
|
+
|
|
Tor recognizes these flags on each ORPort:
|
|
**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**::
|
|
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**::
|
|
If the address is absent, or resolves to both an IPv4 and an IPv6
|
|
address, only listen to the IPv4 address.
|
|
**IPv6Only**::
|
|
If the address is absent, or resolves to both an IPv4 and an IPv6
|
|
address, only listen to the IPv6 address.
|
|
+
|
|
For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and
|
|
IPv4Only and IPv6Only are mutually exclusive.
|
|
|
|
[[ORListenAddress]] **ORListenAddress** __IP__[:__PORT__]::
|
|
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.
|
|
+
|
|
This option is deprecated; you can get the same behavior with ORPort now
|
|
that it supports NoAdvertise and explicit addresses.
|
|
|
|
[[PortForwarding]] **PortForwarding** **0**|**1**::
|
|
Attempt to automatically forward the DirPort and ORPort on a NAT router
|
|
connecting this Tor server to the Internet. If set, Tor will try both
|
|
NAT-PMP (common on Apple routers) and UPnP (common on routers from other
|
|
manufacturers). (Default: 0)
|
|
|
|
[[PortForwardingHelper]] **PortForwardingHelper** __filename__|__pathname__::
|
|
If PortForwarding is set, use this executable to configure the forwarding.
|
|
If set to a filename, the system path will be searched for the executable.
|
|
If set to a path, only the specified path will be executed.
|
|
(Default: tor-fw-helper)
|
|
|
|
[[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.
|
|
+
|
|
If this option is set to 0, Tor will not publish its
|
|
descriptors to any directories. (This is useful if you're testing
|
|
out your server, or if you're using a Tor controller that handles directory
|
|
publishing for you.) Otherwise, Tor will publish its descriptors of all
|
|
type(s) specified. The default is "1",
|
|
which means "if running as a server, publish the
|
|
appropriate descriptors to the authorities".
|
|
|
|
[[ShutdownWaitLength]] **ShutdownWaitLength** __NUM__::
|
|
When we get a SIGINT and we're a server, we begin shutting down:
|
|
we close listeners and start refusing new circuits. After **NUM**
|
|
seconds, we exit. If we get a second SIGINT, we exit immediately.
|
|
(Default: 30 seconds)
|
|
|
|
[[SSLKeyLifetime]] **SSLKeyLifetime** __N__ **minutes**|**hours**|**days**|**weeks**::
|
|
When creating a link certificate for our outermost SSL handshake,
|
|
set its lifetime to this amount of time. If set to 0, Tor will choose
|
|
some reasonable random defaults. (Default: 0)
|
|
|
|
[[HeartbeatPeriod]] **HeartbeatPeriod** __N__ **minutes**|**hours**|**days**|**weeks**::
|
|
Log a heartbeat message every **HeartbeatPeriod** seconds. This is
|
|
a log level __notice__ message, designed to let you know your Tor
|
|
server is still alive and doing useful things. Settings this
|
|
to 0 will disable the heartbeat. (Default: 6 hours)
|
|
|
|
[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**|**TBytes**::
|
|
Never send more than the specified number of bytes in a given accounting
|
|
period, or receive more than that number in the period. For example, with
|
|
AccountingMax set to 1 GByte, a server could send 900 MBytes and
|
|
receive 800 MBytes and continue running. It will only hibernate once
|
|
one of the two reaches 1 GByte. When the number of bytes gets low,
|
|
Tor will stop accepting new connections and circuits. When the
|
|
number of bytes is exhausted, Tor will hibernate until some
|
|
time in the next accounting period. To prevent all servers from waking at
|
|
the same time, Tor will also wait until a random point in each period
|
|
before waking up. If you have bandwidth cost issues, enabling hibernation
|
|
is preferable to setting a low bandwidth, since it provides users with a
|
|
collection of fast servers that are up some of the time, which is more
|
|
useful than a set of slow servers that are always "available".
|
|
|
|
[[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__::
|
|
Specify how long accounting periods last. If **month** is given, each
|
|
accounting period runs from the time __HH:MM__ on the __dayth__ day of one
|
|
month to the same day and time of the next. (The day must be between 1 and
|
|
28.) If **week** is given, each accounting period runs from the time __HH:MM__
|
|
of the __dayth__ day of one week to the same day and time of the next week,
|
|
with Monday as day 1 and Sunday as day 7. If **day** is given, each
|
|
accounting period runs from the time __HH:MM__ each day to the same time on
|
|
the next day. All times are local, and given in 24-hour time. (Default:
|
|
"month 1 0:00")
|
|
|
|
[[RefuseUnknownExits]] **RefuseUnknownExits** **0**|**1**|**auto**::
|
|
Prevent nodes that don't appear in the consensus from exiting using this
|
|
relay. If the option is 1, we always block exit attempts from such
|
|
nodes; if it's 0, we never do, and if the option is "auto", then we do
|
|
whatever the authorities suggest in the consensus (and block if the consensus
|
|
is quiet on the issue). (Default: auto)
|
|
|
|
[[ServerDNSResolvConfFile]] **ServerDNSResolvConfFile** __filename__::
|
|
Overrides the default DNS configuration with the configuration in
|
|
__filename__. The file format is the same as the standard Unix
|
|
"**resolv.conf**" file (7). This option, like all other ServerDNS options,
|
|
only affects name lookups that your server does on behalf of clients.
|
|
(Defaults to use the system DNS configuration.)
|
|
|
|
[[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**::
|
|
If this option is false, Tor exits immediately if there are problems
|
|
parsing the system DNS configuration or connecting to nameservers.
|
|
Otherwise, Tor continues to periodically retry the system nameservers until
|
|
it eventually succeeds. (Default: 1)
|
|
|
|
[[ServerDNSSearchDomains]] **ServerDNSSearchDomains** **0**|**1**::
|
|
If set to 1, then we will search for addresses in the local search domain.
|
|
For example, if this system is configured to believe it is in
|
|
"example.com", and a client tries to connect to "www", the client will be
|
|
connected to "www.example.com". This option only affects name lookups that
|
|
your server does on behalf of clients. (Default: 0)
|
|
|
|
[[ServerDNSDetectHijacking]] **ServerDNSDetectHijacking** **0**|**1**::
|
|
When this option is set to 1, we will test periodically to determine
|
|
whether our local nameservers have been configured to hijack failing DNS
|
|
requests (usually to an advertising site). If they are, we will attempt to
|
|
correct this. This option only affects name lookups that your server does
|
|
on behalf of clients. (Default: 1)
|
|
|
|
[[ServerDNSTestAddresses]] **ServerDNSTestAddresses** __address__,__address__,__...__::
|
|
When we're detecting DNS hijacking, make sure that these __valid__ addresses
|
|
aren't getting redirected. If they are, then our DNS is completely useless,
|
|
and we'll reset our exit policy to "reject *:*". This option only affects
|
|
name lookups that your server does on behalf of clients. (Default:
|
|
"www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org")
|
|
|
|
[[ServerDNSAllowNonRFC953Hostnames]] **ServerDNSAllowNonRFC953Hostnames** **0**|**1**::
|
|
When this option is disabled, Tor does not try to resolve hostnames
|
|
containing illegal characters (like @ and :) rather than sending them to an
|
|
exit node to be resolved. This helps trap accidental attempts to resolve
|
|
URLs and so on. This option only affects name lookups that your server does
|
|
on behalf of clients. (Default: 0)
|
|
|
|
[[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**::
|
|
When this option is enabled and BridgeRelay is also enabled, and we have
|
|
GeoIP data, Tor keeps a per-country count of how many client
|
|
addresses have contacted it so that it can help the bridge authority guess
|
|
which countries have blocked access to it. (Default: 1)
|
|
|
|
[[ServerDNSRandomizeCase]] **ServerDNSRandomizeCase** **0**|**1**::
|
|
When this option is set, Tor sets the case of each character randomly in
|
|
outgoing DNS requests, and makes sure that the case matches in DNS replies.
|
|
This so-called "0x20 hack" helps resist some types of DNS poisoning attack.
|
|
For more information, see "Increased DNS Forgery Resistance through
|
|
0x20-Bit Encoding". This option only affects name lookups that your server
|
|
does on behalf of clients. (Default: 1)
|
|
|
|
[[GeoIPFile]] **GeoIPFile** __filename__::
|
|
A filename containing IPv4 GeoIP data, for use with by-country statistics.
|
|
|
|
[[GeoIPv6File]] **GeoIPv6File** __filename__::
|
|
A filename containing IPv6 GeoIP data, for use with by-country statistics.
|
|
|
|
[[TLSECGroup]] **TLSECGroup** **P224**|**P256**::
|
|
What EC group should we try to use for incoming TLS connections?
|
|
P224 is faster, but makes us stand out more. Has no effect if
|
|
we're a client, or if our OpenSSL version lacks support for ECDHE.
|
|
(Default: P256)
|
|
|
|
[[CellStatistics]] **CellStatistics** **0**|**1**::
|
|
When this option is enabled, Tor writes statistics on the mean time that
|
|
cells spend in circuit queues to disk every 24 hours. (Default: 0)
|
|
|
|
[[DirReqStatistics]] **DirReqStatistics** **0**|**1**::
|
|
When this option is enabled, a Tor directory writes statistics on the
|
|
number and response time of network status requests to disk every 24
|
|
hours. (Default: 1)
|
|
|
|
[[EntryStatistics]] **EntryStatistics** **0**|**1**::
|
|
When this option is enabled, Tor writes statistics on the number of
|
|
directly connecting clients to disk every 24 hours. (Default: 0)
|
|
|
|
[[ExitPortStatistics]] **ExitPortStatistics** **0**|**1**::
|
|
When this option is enabled, Tor writes statistics on the number of relayed
|
|
bytes and opened stream per exit port to disk every 24 hours. (Default: 0)
|
|
|
|
[[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**::
|
|
When this option is enabled, Tor writes statistics on the bidirectional use
|
|
of connections to disk every 24 hours. (Default: 0)
|
|
|
|
[[ExtraInfoStatistics]] **ExtraInfoStatistics** **0**|**1**::
|
|
When this option is enabled, Tor includes previously gathered statistics in
|
|
its extra-info documents that it uploads to the directory authorities.
|
|
(Default: 1)
|
|
|
|
[[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**::
|
|
When this option is enabled, Tor routers allow EXTEND request to
|
|
localhost, RFC1918 addresses, and so on. This can create security issues;
|
|
you should probably leave it off. (Default: 0)
|
|
|
|
[[MaxMemInQueues]] **MaxMemInQueues** __N__ **bytes**|**KB**|**MB**|**GB**::
|
|
This option configures a threshold above which Tor will assume that it
|
|
needs to stop queueing or buffering data because it's about to run out of
|
|
memory. If it hits this threshold, it will begin killing circuits until
|
|
it has recovered at least 10% of this memory. Do not set this option too
|
|
low, or your relay may be unreliable under load. This option only
|
|
affects some queues, so the actual process size will be larger than
|
|
this. If this option is set to 0, Tor will try to pick a reasonable
|
|
default based on your system's physical memory. (Default: 0)
|
|
|
|
DIRECTORY SERVER OPTIONS
|
|
------------------------
|
|
|
|
The following options are useful only for directory servers (that is,
|
|
if DirPort is non-zero):
|
|
|
|
[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__::
|
|
When this option is set, it takes an HTML file and publishes it as "/" on
|
|
the DirPort. Now relay operators can provide a disclaimer without needing
|
|
to set up a separate webserver. There's a sample disclaimer in
|
|
contrib/operator-tools/tor-exit-notice.html.
|
|
|
|
[[HidServDirectoryV2]] **HidServDirectoryV2** **0**|**1**::
|
|
When this option is set, Tor accepts and serves v2 hidden service
|
|
descriptors. Setting DirPort is not required for this, because clients
|
|
connect via the ORPort by default. (Default: 1)
|
|
|
|
[[DirPort]] **DirPort** \['address':]__PORT__|**auto** [_flags_]::
|
|
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)
|
|
+
|
|
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.
|
|
+
|
|
This option is deprecated; you can get the same behavior with DirPort now
|
|
that it supports NoAdvertise and explicit addresses.
|
|
|
|
[[DirPolicy]] **DirPolicy** __policy__,__policy__,__...__::
|
|
Set an entrance policy for this server, to limit who can connect to the
|
|
directory ports. The policies have the same form as exit policies above,
|
|
except that port specifiers are ignored. Any address not matched by
|
|
some entry in the policy is accepted.
|
|
|
|
|
|
DIRECTORY AUTHORITY SERVER OPTIONS
|
|
----------------------------------
|
|
|
|
The following options enable operation as a directory authority, and
|
|
control how Tor behaves as a directory authority. You should not need
|
|
to adjust any of them if you're running a regular relay or exit server
|
|
on the public Tor network.
|
|
|
|
[[AuthoritativeDirectory]] **AuthoritativeDirectory** **0**|**1**::
|
|
When this option is set to 1, Tor operates as an authoritative directory
|
|
server. Instead of caching the directory, it generates its own list of
|
|
good servers, signs it, and sends that to the clients. Unless the clients
|
|
already have you listed as a trusted directory, you probably do not want
|
|
to set this option. Please coordinate with the other admins at
|
|
tor-ops@torproject.org if you think you should be a directory.
|
|
|
|
[[V3AuthoritativeDirectory]] **V3AuthoritativeDirectory** **0**|**1**::
|
|
When this option is set in addition to **AuthoritativeDirectory**, Tor
|
|
generates version 3 network statuses and serves descriptors, etc as
|
|
described in doc/spec/dir-spec.txt (for Tor clients and servers running at
|
|
least 0.2.0.x).
|
|
|
|
[[VersioningAuthoritativeDirectory]] **VersioningAuthoritativeDirectory** **0**|**1**::
|
|
When this option is set to 1, Tor adds information on which versions of
|
|
Tor are still believed safe for use to the published directory. Each
|
|
version 1 authority is automatically a versioning authority; version 2
|
|
authorities provide this service optionally. See **RecommendedVersions**,
|
|
**RecommendedClientVersions**, and **RecommendedServerVersions**.
|
|
|
|
[[NamingAuthoritativeDirectory]] **NamingAuthoritativeDirectory** **0**|**1**::
|
|
When this option is set to 1, then the server advertises that it has
|
|
opinions about nickname-to-fingerprint bindings. It will include these
|
|
opinions in its published network-status pages, by listing servers with
|
|
the flag "Named" if a correct binding between that nickname and fingerprint
|
|
has been registered with the dirserver. Naming dirservers will refuse to
|
|
accept or publish descriptors that contradict a registered binding. See
|
|
**approved-routers** in the **FILES** section below.
|
|
|
|
[[RecommendedVersions]] **RecommendedVersions** __STRING__::
|
|
STRING is a comma-separated list of Tor versions currently believed to be
|
|
safe. The list is included in each directory, and nodes which pull down the
|
|
directory learn whether they need to upgrade. This option can appear
|
|
multiple times: the values from multiple lines are spliced together. When
|
|
this is set then **VersioningAuthoritativeDirectory** should be set too.
|
|
|
|
[[RecommendedClientVersions]] **RecommendedClientVersions** __STRING__::
|
|
STRING is a comma-separated list of Tor versions currently believed to be
|
|
safe for clients to use. This information is included in version 2
|
|
directories. If this is not set then the value of **RecommendedVersions**
|
|
is used. When this is set then **VersioningAuthoritativeDirectory** should
|
|
be set too.
|
|
|
|
[[BridgeAuthoritativeDir]] **BridgeAuthoritativeDir** **0**|**1**::
|
|
When this option is set in addition to **AuthoritativeDirectory**, Tor
|
|
accepts and serves router descriptors, but it caches and serves the main
|
|
networkstatus documents rather than generating its own. (Default: 0)
|
|
|
|
[[MinUptimeHidServDirectoryV2]] **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
|
|
Minimum uptime of a v2 hidden service directory to be accepted as such by
|
|
authoritative directories. (Default: 25 hours)
|
|
|
|
[[RecommendedServerVersions]] **RecommendedServerVersions** __STRING__::
|
|
STRING is a comma-separated list of Tor versions currently believed to be
|
|
safe for servers to use. This information is included in version 2
|
|
directories. If this is not set then the value of **RecommendedVersions**
|
|
is used. When this is set then **VersioningAuthoritativeDirectory** should
|
|
be set too.
|
|
|
|
[[ConsensusParams]] **ConsensusParams** __STRING__::
|
|
STRING is a space-separated list of key=value pairs that Tor will include
|
|
in the "params" line of its networkstatus vote.
|
|
|
|
[[DirAllowPrivateAddresses]] **DirAllowPrivateAddresses** **0**|**1**::
|
|
If set to 1, Tor will accept router descriptors with arbitrary "Address"
|
|
elements. Otherwise, if the address is not an IP address or is a private IP
|
|
address, it will reject the router descriptor. (Default: 0)
|
|
|
|
[[AuthDirBadDir]] **AuthDirBadDir** __AddressPattern...__::
|
|
Authoritative directories only. A set of address patterns for servers that
|
|
will be listed as bad directories in any network status document this
|
|
authority publishes, if **AuthDirListBadDirs** 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
|
|
"accept" or "reject", and ports are not needed.)
|
|
|
|
[[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.
|
|
|
|
[[AuthDirInvalid]] **AuthDirInvalid** __AddressPattern...__::
|
|
Authoritative directories only. A set of address patterns for servers that
|
|
will never be listed as "valid" in any network status document that this
|
|
authority publishes.
|
|
|
|
[[AuthDirReject]] **AuthDirReject** __AddressPattern__...::
|
|
Authoritative directories only. A set of address patterns for servers that
|
|
will never be listed at all in any network status document that this
|
|
authority publishes, or accepted as an OR address in any descriptor
|
|
submitted for publication by this authority.
|
|
|
|
[[AuthDirBadDirCCs]] **AuthDirBadDirCCs** __CC__,... +
|
|
|
|
[[AuthDirBadExitCCs]] **AuthDirBadExitCCs** __CC__,... +
|
|
|
|
[[AuthDirInvalidCCs]] **AuthDirInvalidCCs** __CC__,... +
|
|
|
|
[[AuthDirRejectCCs]] **AuthDirRejectCCs** __CC__,...::
|
|
Authoritative directories only. These options contain a comma-separated
|
|
list of country codes such that any server in one of those country codes
|
|
will be marked as a bad directory/bad exit/invalid for use, or rejected
|
|
entirely.
|
|
|
|
[[AuthDirListBadDirs]] **AuthDirListBadDirs** **0**|**1**::
|
|
Authoritative directories only. If set to 1, this directory has some
|
|
opinion about which nodes are unsuitable as directory caches. (Do not set
|
|
this to 1 unless you plan to list non-functioning directories as bad;
|
|
otherwise, you are effectively voting in favor of every declared
|
|
directory.)
|
|
|
|
[[AuthDirListBadExits]] **AuthDirListBadExits** **0**|**1**::
|
|
Authoritative directories only. If set to 1, this directory has some
|
|
opinion about which nodes are unsuitable as exit nodes. (Do not set this to
|
|
1 unless you plan to list non-functioning exits as bad; otherwise, you are
|
|
effectively voting in favor of every declared exit as an exit.)
|
|
|
|
[[AuthDirRejectUnlisted]] **AuthDirRejectUnlisted** **0**|**1**::
|
|
Authoritative directories only. If set to 1, the directory server rejects
|
|
all uploaded server descriptors that aren't explicitly listed in the
|
|
fingerprints file. This acts as a "panic button" if we get hit with a Sybil
|
|
attack. (Default: 0)
|
|
|
|
[[AuthDirMaxServersPerAddr]] **AuthDirMaxServersPerAddr** __NUM__::
|
|
Authoritative directories only. The maximum number of servers that we will
|
|
list as acceptable on a single IP address. Set this to "0" for "no limit".
|
|
(Default: 2)
|
|
|
|
[[AuthDirMaxServersPerAuthAddr]] **AuthDirMaxServersPerAuthAddr** __NUM__::
|
|
Authoritative directories only. Like AuthDirMaxServersPerAddr, but applies
|
|
to addresses shared with directory authorities. (Default: 5)
|
|
|
|
[[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
Authoritative directories only. If non-zero, always vote the
|
|
Fast flag for any relay advertising this amount of capacity or
|
|
more. (Default: 100 KBytes)
|
|
|
|
[[AuthDirGuardBWGuarantee]] **AuthDirGuardBWGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
Authoritative directories only. If non-zero, this advertised capacity
|
|
or more is always sufficient to satisfy the bandwidth requirement
|
|
for the Guard flag. (Default: 250 KBytes)
|
|
|
|
[[BridgePassword]] **BridgePassword** __Password__::
|
|
If set, contains an HTTP authenticator that tells a bridge authority to
|
|
serve all requested bridge information. Used by the (only partially
|
|
implemented) "bridge community" design, where a community of bridge
|
|
relay operators all use an alternate bridge directory authority,
|
|
and their target user audience can periodically fetch the list of
|
|
available community bridges to stay up-to-date. (Default: not set)
|
|
|
|
[[V3AuthVotingInterval]] **V3AuthVotingInterval** __N__ **minutes**|**hours**::
|
|
V3 authoritative directories only. Configures the server's preferred voting
|
|
interval. Note that voting will __actually__ happen at an interval chosen
|
|
by consensus from all the authorities' preferred intervals. This time
|
|
SHOULD divide evenly into a day. (Default: 1 hour)
|
|
|
|
[[V3AuthVoteDelay]] **V3AuthVoteDelay** __N__ **minutes**|**hours**::
|
|
V3 authoritative directories only. Configures the server's preferred delay
|
|
between publishing its vote and assuming it has all the votes from all the
|
|
other authorities. Note that the actual time used is not the server's
|
|
preferred time, but the consensus of all preferences. (Default: 5 minutes)
|
|
|
|
[[V3AuthDistDelay]] **V3AuthDistDelay** __N__ **minutes**|**hours**::
|
|
V3 authoritative directories only. Configures the server's preferred delay
|
|
between publishing its consensus and signature and assuming it has all the
|
|
signatures from all the other authorities. Note that the actual time used
|
|
is not the server's preferred time, but the consensus of all preferences.
|
|
(Default: 5 minutes)
|
|
|
|
[[V3AuthNIntervalsValid]] **V3AuthNIntervalsValid** __NUM__::
|
|
V3 authoritative directories only. Configures the number of VotingIntervals
|
|
for which each consensus should be valid for. Choosing high numbers
|
|
increases network partitioning risks; choosing low numbers increases
|
|
directory traffic. Note that the actual number of intervals used is not the
|
|
server's preferred number, but the consensus of all preferences. Must be at
|
|
least 2. (Default: 3)
|
|
|
|
[[V3BandwidthsFile]] **V3BandwidthsFile** __FILENAME__::
|
|
V3 authoritative directories only. Configures the location of the
|
|
bandwidth-authority generated file storing information on relays' measured
|
|
bandwidth capacities. (Default: unset)
|
|
|
|
[[V3AuthUseLegacyKey]] **V3AuthUseLegacyKey** **0**|**1**::
|
|
If set, the directory authority will sign consensuses not only with its
|
|
own signing key, but also with a "legacy" key and certificate with a
|
|
different identity. This feature is used to migrate directory authority
|
|
keys in the event of a compromise. (Default: 0)
|
|
|
|
[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
|
|
Tells an authority, or other node tracking node reliability and history,
|
|
that fine-grained information about nodes can be discarded when it hasn't
|
|
changed for a given amount of time. (Default: 24 hours)
|
|
|
|
[[VoteOnHidServDirectoriesV2]] **VoteOnHidServDirectoriesV2** **0**|**1**::
|
|
When this option is set in addition to **AuthoritativeDirectory**, Tor
|
|
votes on whether to accept relays as hidden service directories.
|
|
(Default: 1)
|
|
|
|
[[AuthDirHasIPv6Connectivity]] **AuthDirHasIPv6Connectivity** **0**|**1**::
|
|
Authoritative directories only. When set to 0, OR ports with an
|
|
IPv6 address are being accepted without reachability testing.
|
|
When set to 1, IPv6 OR ports are being tested just like IPv4 OR
|
|
ports. (Default: 0)
|
|
|
|
[[MinMeasuredBWsForAuthToIgnoreAdvertised]] **MinMeasuredBWsForAuthToIgnoreAdvertised** __N__::
|
|
A total value, in abstract bandwidth units, describing how much
|
|
measured total bandwidth an authority should have observed on the network
|
|
before it will treat advertised bandwidths as wholly
|
|
unreliable. (Default: 500)
|
|
|
|
HIDDEN SERVICE OPTIONS
|
|
----------------------
|
|
|
|
The following options are used to configure a hidden service.
|
|
|
|
[[HiddenServiceDir]] **HiddenServiceDir** __DIRECTORY__::
|
|
Store data files for a hidden service in DIRECTORY. Every hidden service
|
|
must have a separate directory. You may use this option multiple times to
|
|
specify multiple services. DIRECTORY must be an existing directory.
|
|
|
|
[[HiddenServicePort]] **HiddenServicePort** __VIRTPORT__ [__TARGET__]::
|
|
Configure a virtual port VIRTPORT for a hidden service. You may use this
|
|
option multiple times; each time applies to the service using the most
|
|
recent hiddenservicedir. By default, this option maps the virtual port to
|
|
the same port on 127.0.0.1 over TCP. You may override the target port,
|
|
address, or both by specifying a target of addr, port, or addr:port.
|
|
You may also have multiple lines with the same VIRTPORT: when a user
|
|
connects to that VIRTPORT, one of the TARGETs from those lines will be
|
|
chosen at random.
|
|
|
|
[[PublishHidServDescriptors]] **PublishHidServDescriptors** **0**|**1**::
|
|
If set to 0, Tor will run any hidden services you configure, but it won't
|
|
advertise them to the rendezvous directory. This option is only useful if
|
|
you're using a Tor controller that handles hidserv publishing for you.
|
|
(Default: 1)
|
|
|
|
[[HiddenServiceVersion]] **HiddenServiceVersion** __version__,__version__,__...__::
|
|
A list of rendezvous service descriptor versions to publish for the hidden
|
|
service. Currently, only version 2 is supported. (Default: 2)
|
|
|
|
[[HiddenServiceAuthorizeClient]] **HiddenServiceAuthorizeClient** __auth-type__ __client-name__,__client-name__,__...__::
|
|
If configured, the hidden service is accessible for authorized clients
|
|
only. The auth-type can either be \'basic' for a general-purpose
|
|
authorization protocol or \'stealth' for a less scalable protocol that also
|
|
hides service activity from unauthorized clients. Only clients that are
|
|
listed here are authorized to access the hidden service. Valid client names
|
|
are 1 to 16 characters long and only use characters in A-Za-z0-9+-_ (no
|
|
spaces). If this option is set, the hidden service is not accessible for
|
|
clients without authorization any more. Generated authorization data can be
|
|
found in the hostname file. Clients need to put this authorization data in
|
|
their configuration file using **HidServAuth**.
|
|
|
|
[[RendPostPeriod]] **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
|
|
Every time the specified period elapses, Tor uploads any rendezvous
|
|
service descriptors to the directory servers. This information is also
|
|
uploaded whenever it changes. (Default: 1 hour)
|
|
|
|
[[HiddenServiceDirGroupReadable]] **HiddenServiceDirGroupReadable** **0**|**1**::
|
|
If this option is set to 1, allow the filesystem group to read the
|
|
hidden service directory and hostname file. If the option is set to 0,
|
|
only owner is able to read the hidden service directory. (Default: 0)
|
|
Has no effect on Windows.
|
|
|
|
TESTING NETWORK OPTIONS
|
|
-----------------------
|
|
|
|
The following options are used for running a testing Tor network.
|
|
|
|
[[TestingTorNetwork]] **TestingTorNetwork** **0**|**1**::
|
|
If set to 1, Tor adjusts default values of the configuration options below,
|
|
so that it is easier to set up a testing Tor network. May only be set if
|
|
non-default set of DirAuthorities is set. Cannot be unset while Tor is
|
|
running.
|
|
(Default: 0) +
|
|
|
|
ServerDNSAllowBrokenConfig 1
|
|
DirAllowPrivateAddresses 1
|
|
EnforceDistinctSubnets 0
|
|
AssumeReachable 1
|
|
AuthDirMaxServersPerAddr 0
|
|
AuthDirMaxServersPerAuthAddr 0
|
|
ClientDNSRejectInternalAddresses 0
|
|
ClientRejectInternalAddresses 0
|
|
CountPrivateBandwidth 1
|
|
ExitPolicyRejectPrivate 0
|
|
ExtendAllowPrivateAddresses 1
|
|
V3AuthVotingInterval 5 minutes
|
|
V3AuthVoteDelay 20 seconds
|
|
V3AuthDistDelay 20 seconds
|
|
MinUptimeHidServDirectoryV2 0 seconds
|
|
TestingV3AuthInitialVotingInterval 5 minutes
|
|
TestingV3AuthInitialVoteDelay 20 seconds
|
|
TestingV3AuthInitialDistDelay 20 seconds
|
|
TestingAuthDirTimeToLearnReachability 0 minutes
|
|
TestingEstimatedDescriptorPropagationTime 0 minutes
|
|
TestingServerDownloadSchedule 0, 0, 0, 5, 10, 15, 20, 30, 60
|
|
TestingClientDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60
|
|
TestingServerConsensusDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60
|
|
TestingClientConsensusDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60
|
|
TestingBridgeDownloadSchedule 60, 30, 30, 60
|
|
TestingClientMaxIntervalWithoutRequest 5 seconds
|
|
TestingDirConnectionMaxStall 30 seconds
|
|
TestingConsensusMaxDownloadTries 80
|
|
TestingDescriptorMaxDownloadTries 80
|
|
TestingMicrodescMaxDownloadTries 80
|
|
TestingCertMaxDownloadTries 80
|
|
TestingEnableConnBwEvent 1
|
|
TestingEnableCellStatsEvent 1
|
|
TestingEnableTbEmptyEvent 1
|
|
|
|
[[TestingV3AuthInitialVotingInterval]] **TestingV3AuthInitialVotingInterval** __N__ **minutes**|**hours**::
|
|
Like V3AuthVotingInterval, but for initial voting interval before the first
|
|
consensus has been created. Changing this requires that
|
|
**TestingTorNetwork** is set. (Default: 30 minutes)
|
|
|
|
[[TestingV3AuthInitialVoteDelay]] **TestingV3AuthInitialVoteDelay** __N__ **minutes**|**hours**::
|
|
Like V3AuthVoteDelay, but for initial voting interval before
|
|
the first consensus has been created. Changing this requires that
|
|
**TestingTorNetwork** is set. (Default: 5 minutes)
|
|
|
|
[[TestingV3AuthInitialDistDelay]] **TestingV3AuthInitialDistDelay** __N__ **minutes**|**hours**::
|
|
Like V3AuthDistDelay, but for initial voting interval before
|
|
the first consensus has been created. Changing this requires that
|
|
**TestingTorNetwork** is set. (Default: 5 minutes)
|
|
|
|
[[TestingV3AuthVotingStartOffset]] **TestingV3AuthVotingStartOffset** __N__ **seconds**|**minutes**|**hours**::
|
|
Directory authorities offset voting start time by this much.
|
|
Changing this requires that **TestingTorNetwork** is set. (Default: 0)
|
|
|
|
[[TestingAuthDirTimeToLearnReachability]] **TestingAuthDirTimeToLearnReachability** __N__ **minutes**|**hours**::
|
|
After starting as an authority, do not make claims about whether routers
|
|
are Running until this much time has passed. Changing this requires
|
|
that **TestingTorNetwork** is set. (Default: 30 minutes)
|
|
|
|
[[TestingEstimatedDescriptorPropagationTime]] **TestingEstimatedDescriptorPropagationTime** __N__ **minutes**|**hours**::
|
|
Clients try downloading router descriptors from directory caches after this
|
|
time. Changing this requires that **TestingTorNetwork** is set. (Default:
|
|
10 minutes)
|
|
|
|
[[TestingMinFastFlagThreshold]] **TestingMinFastFlagThreshold** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
Minimum value for the Fast flag. Overrides the ordinary minimum taken
|
|
from the consensus when TestingTorNetwork is set. (Default: 0.)
|
|
|
|
[[TestingServerDownloadSchedule]] **TestingServerDownloadSchedule** __N__,__N__,__...__::
|
|
Schedule for when servers should download things in general. Changing this
|
|
requires that **TestingTorNetwork** is set. (Default: 0, 0, 0, 60, 60, 120,
|
|
300, 900, 2147483647)
|
|
|
|
[[TestingClientDownloadSchedule]] **TestingClientDownloadSchedule** __N__,__N__,__...__::
|
|
Schedule for when clients should download things in general. Changing this
|
|
requires that **TestingTorNetwork** is set. (Default: 0, 0, 60, 300, 600,
|
|
2147483647)
|
|
|
|
[[TestingServerConsensusDownloadSchedule]] **TestingServerConsensusDownloadSchedule** __N__,__N__,__...__::
|
|
Schedule for when servers should download consensuses. Changing this
|
|
requires that **TestingTorNetwork** is set. (Default: 0, 0, 60, 300, 600,
|
|
1800, 1800, 1800, 1800, 1800, 3600, 7200)
|
|
|
|
[[TestingClientConsensusDownloadSchedule]] **TestingClientConsensusDownloadSchedule** __N__,__N__,__...__::
|
|
Schedule for when clients should download consensuses. Changing this
|
|
requires that **TestingTorNetwork** is set. (Default: 0, 0, 60, 300, 600,
|
|
1800, 3600, 3600, 3600, 10800, 21600, 43200)
|
|
|
|
[[TestingBridgeDownloadSchedule]] **TestingBridgeDownloadSchedule** __N__,__N__,__...__::
|
|
Schedule for when clients should download bridge descriptors. Changing this
|
|
requires that **TestingTorNetwork** is set. (Default: 3600, 900, 900, 3600)
|
|
|
|
[[TestingClientMaxIntervalWithoutRequest]] **TestingClientMaxIntervalWithoutRequest** __N__ **seconds**|**minutes**::
|
|
When directory clients have only a few descriptors to request, they batch
|
|
them until they have more, or until this amount of time has passed.
|
|
Changing this requires that **TestingTorNetwork** is set. (Default: 10
|
|
minutes)
|
|
|
|
[[TestingDirConnectionMaxStall]] **TestingDirConnectionMaxStall** __N__ **seconds**|**minutes**::
|
|
Let a directory connection stall this long before expiring it.
|
|
Changing this requires that **TestingTorNetwork** is set. (Default:
|
|
5 minutes)
|
|
|
|
[[TestingConsensusMaxDownloadTries]] **TestingConsensusMaxDownloadTries** __NUM__::
|
|
Try this often to download a consensus before giving up. Changing
|
|
this requires that **TestingTorNetwork** is set. (Default: 8)
|
|
|
|
[[TestingDescriptorMaxDownloadTries]] **TestingDescriptorMaxDownloadTries** __NUM__::
|
|
Try this often to download a router descriptor before giving up.
|
|
Changing this requires that **TestingTorNetwork** is set. (Default: 8)
|
|
|
|
[[TestingMicrodescMaxDownloadTries]] **TestingMicrodescMaxDownloadTries** __NUM__::
|
|
Try this often to download a microdesc descriptor before giving up.
|
|
Changing this requires that **TestingTorNetwork** is set. (Default: 8)
|
|
|
|
[[TestingCertMaxDownloadTries]] **TestingCertMaxDownloadTries** __NUM__::
|
|
Try this often to download a v3 authority certificate before giving up.
|
|
Changing this requires that **TestingTorNetwork** is set. (Default: 8)
|
|
|
|
[[TestingDirAuthVoteGuard]] **TestingDirAuthVoteGuard** __node__,__node__,__...__::
|
|
A list of identity fingerprints, nicknames, 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.
|
|
+
|
|
In order for this option to have any effect, **TestingTorNetwork**
|
|
has to be set.
|
|
|
|
[[TestingEnableConnBwEvent]] **TestingEnableConnBwEvent** **0**|**1**::
|
|
If this option is set, then Tor controllers may register for CONN_BW
|
|
events. Changing this requires that **TestingTorNetwork** is set.
|
|
(Default: 0)
|
|
|
|
[[TestingEnableCellStatsEvent]] **TestingEnableCellStatsEvent** **0**|**1**::
|
|
If this option is set, then Tor controllers may register for CELL_STATS
|
|
events. Changing this requires that **TestingTorNetwork** is set.
|
|
(Default: 0)
|
|
|
|
[[TestingEnableTbEmptyEvent]] **TestingEnableTbEmptyEvent** **0**|**1**::
|
|
If this option is set, then Tor controllers may register for TB_EMPTY
|
|
events. Changing this requires that **TestingTorNetwork** is set.
|
|
(Default: 0)
|
|
|
|
[[TestingMinExitFlagThreshold]] **TestingMinExitFlagThreshold** __N__ **KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**::
|
|
Sets a lower-bound for assigning an exit flag when running as an
|
|
authority on a testing network. Overrides the usual default lower bound
|
|
of 4 KB. (Default: 0)
|
|
|
|
SIGNALS
|
|
-------
|
|
|
|
Tor catches the following signals:
|
|
|
|
[[SIGTERM]] **SIGTERM**::
|
|
Tor will catch this, clean up and sync to disk if necessary, and exit.
|
|
|
|
[[SIGINT]] **SIGINT**::
|
|
Tor clients behave as with SIGTERM; but Tor servers will do a controlled
|
|
slow shutdown, closing listeners and waiting 30 seconds before exiting.
|
|
(The delay can be configured with the ShutdownWaitLength config option.)
|
|
|
|
[[SIGHUP]] **SIGHUP**::
|
|
The signal instructs Tor to reload its configuration (including closing and
|
|
reopening logs), and kill and restart its helper processes if applicable.
|
|
|
|
[[SIGUSR1]] **SIGUSR1**::
|
|
Log statistics about current connections, past connections, and throughput.
|
|
|
|
[[SIGUSR2]] **SIGUSR2**::
|
|
Switch all logs to loglevel debug. You can go back to the old loglevels by
|
|
sending a SIGHUP.
|
|
|
|
[[SIGCHLD]] **SIGCHLD**::
|
|
Tor receives this signal when one of its helper processes has exited, so it
|
|
can clean up.
|
|
|
|
[[SIGPIPE]] **SIGPIPE**::
|
|
Tor catches this signal and ignores it.
|
|
|
|
[[SIGXFSZ]] **SIGXFSZ**::
|
|
If this signal exists on your platform, Tor catches and ignores it.
|
|
|
|
FILES
|
|
-----
|
|
|
|
**@CONFDIR@/torrc**::
|
|
The configuration file, which contains "option value" pairs.
|
|
|
|
**$HOME/.torrc**::
|
|
Fallback location for torrc, if @CONFDIR@/torrc is not found.
|
|
|
|
**@LOCALSTATEDIR@/lib/tor/**::
|
|
The tor process stores keys and other data here.
|
|
|
|
__DataDirectory__**/cached-status/**::
|
|
The most recently downloaded network status document for each authority.
|
|
Each file holds one such document; the filenames are the hexadecimal
|
|
identity key fingerprints of the directory authorities. Mostly obsolete.
|
|
|
|
__DataDirectory__**/cached-certs**::
|
|
This file holds downloaded directory key certificates that are used to
|
|
verify authenticity of documents generated by Tor directory authorities.
|
|
|
|
__DataDirectory__**/cached-consensus** and/or **cached-microdesc-consensus**::
|
|
The most recent consensus network status document we've downloaded.
|
|
|
|
__DataDirectory__**/cached-descriptors** and **cached-descriptors.new**::
|
|
These files hold downloaded router statuses. Some routers may appear more
|
|
than once; if so, the most recently published descriptor is used. Lines
|
|
beginning with @-signs are annotations that contain more information about
|
|
a given router. The ".new" file is an append-only journal; when it gets
|
|
too large, all entries are merged into a new cached-descriptors file.
|
|
|
|
__DataDirectory__**/cached-microdescs** and **cached-microdescs.new**::
|
|
These files hold downloaded microdescriptors. Lines beginning with
|
|
@-signs are annotations that contain more information about a given
|
|
router. The ".new" file is an append-only journal; when it gets too
|
|
large, all entries are merged into a new cached-microdescs file.
|
|
|
|
__DataDirectory__**/cached-routers** and **cached-routers.new**::
|
|
Obsolete versions of cached-descriptors and cached-descriptors.new. When
|
|
Tor can't find the newer files, it looks here instead.
|
|
|
|
__DataDirectory__**/state**::
|
|
A set of persistent key-value mappings. These are documented in
|
|
the file. These include:
|
|
- The current entry guards and their status.
|
|
- The current bandwidth accounting values (unused so far; see
|
|
below).
|
|
- When the file was last written
|
|
- What version of Tor generated the state file
|
|
- A short history of bandwidth usage, as produced in the router
|
|
descriptors.
|
|
|
|
__DataDirectory__**/bw_accounting**::
|
|
Used to track bandwidth accounting values (when the current period starts
|
|
and ends; how much has been read and written so far this period). This file
|
|
is obsolete, and the data is now stored in the \'state' file as well. Only
|
|
used when bandwidth accounting is enabled.
|
|
|
|
__DataDirectory__**/control_auth_cookie**::
|
|
Used for cookie authentication with the controller. Location can be
|
|
overridden by the CookieAuthFile config option. Regenerated on startup. See
|
|
control-spec.txt for details. Only used when cookie authentication is
|
|
enabled.
|
|
|
|
__DataDirectory__**/lock**::
|
|
This file is used to prevent two Tor instances from using same data
|
|
directory. If access to this file is locked, data directory is already
|
|
in use by Tor.
|
|
|
|
__DataDirectory__**/keys/***::
|
|
Only used by servers. Holds identity keys and onion keys.
|
|
|
|
__DataDirectory__**/fingerprint**::
|
|
Only used by servers. Holds the fingerprint of the server's identity key.
|
|
|
|
__DataDirectory__**/hashed-fingerprint**::
|
|
Only used by bridges. Holds the hashed fingerprint of the bridge's
|
|
identity key. (That is, the hash of the hash of the identity key.)
|
|
|
|
__DataDirectory__**/approved-routers**::
|
|
Only for naming authoritative directory servers (see
|
|
**NamingAuthoritativeDirectory**). This file lists nickname to identity
|
|
bindings. Each line lists a nickname and a fingerprint separated by
|
|
whitespace. See your **fingerprint** file in the __DataDirectory__ for an
|
|
example line. If the nickname is **!reject** then descriptors from the
|
|
given identity (fingerprint) are rejected by this server. If it is
|
|
**!invalid** then descriptors are accepted but marked in the directory as
|
|
not valid, that is, not recommended.
|
|
|
|
__DataDirectory__**/v3-status-votes**::
|
|
Only for authoritative directory servers. This file contains status votes
|
|
from all the authoritative directory servers and is used to generate the
|
|
network consensus document.
|
|
|
|
__DataDirectory__**/unverified-consensus**::
|
|
This file contains a network consensus document that has been downloaded,
|
|
but which we didn't have the right certificates to check yet.
|
|
|
|
__DataDirectory__**/unverified-microdesc-consensus**::
|
|
This file contains a microdescriptor-flavored network consensus document
|
|
that has been downloaded, but which we didn't have the right certificates
|
|
to check yet.
|
|
|
|
__DataDirectory__**/unparseable-desc**::
|
|
Onion router descriptors that Tor was unable to parse are dumped to this
|
|
file. Only used for debugging.
|
|
|
|
__DataDirectory__**/router-stability**::
|
|
Only used by authoritative directory servers. Tracks measurements for
|
|
router mean-time-between-failures so that authorities have a good idea of
|
|
how to set their Stable flags.
|
|
|
|
__DataDirectory__**/stats/dirreq-stats**::
|
|
Only used by directory caches and authorities. This file is used to
|
|
collect directory request statistics.
|
|
|
|
__DataDirectory__**/stats/entry-stats**::
|
|
Only used by servers. This file is used to collect incoming connection
|
|
statistics by Tor entry nodes.
|
|
|
|
__DataDirectory__**/stats/bridge-stats**::
|
|
Only used by servers. This file is used to collect incoming connection
|
|
statistics by Tor bridges.
|
|
|
|
__DataDirectory__**/stats/exit-stats**::
|
|
Only used by servers. This file is used to collect outgoing connection
|
|
statistics by Tor exit routers.
|
|
|
|
__DataDirectory__**/stats/buffer-stats**::
|
|
Only used by servers. This file is used to collect buffer usage
|
|
history.
|
|
|
|
__DataDirectory__**/stats/conn-stats**::
|
|
Only used by servers. This file is used to collect approximate connection
|
|
history (number of active connections over time).
|
|
|
|
__HiddenServiceDirectory__**/hostname**::
|
|
The <base32-encoded-fingerprint>.onion domain name for this hidden service.
|
|
If the hidden service is restricted to authorized clients only, this file
|
|
also contains authorization data for all clients.
|
|
|
|
__HiddenServiceDirectory__**/private_key**::
|
|
The private key for this hidden service.
|
|
|
|
__HiddenServiceDirectory__**/client_keys**::
|
|
Authorization data for a hidden service that is only accessible by
|
|
authorized clients.
|
|
|
|
SEE ALSO
|
|
--------
|
|
**torsocks**(1), **torify**(1) +
|
|
|
|
**https://www.torproject.org/**
|
|
|
|
|
|
BUGS
|
|
----
|
|
|
|
Plenty, probably. Tor is still in development. Please report them.
|
|
|
|
AUTHORS
|
|
-------
|
|
Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at alum.mit.edu].
|