doc/tor.1.txt

   1 // Copyright (c) The Tor Project, Inc.
   2 // See LICENSE for licensing information
   3 // This is an asciidoc file used to generate the manpage/html reference.
   4 // Learn asciidoc on http://www.methods.co.nz/asciidoc/userguide.html
   5 TOR(1)
   6 ======
   7
   8 NAME
   9 ----
  10 tor - The second-generation onion router
  11
  12
  13 SYNOPSIS
  14 --------
  15 **tor** [__OPTION__ __value__]...
  16
  17 DESCRIPTION
  18 -----------
  19 __tor__ is a connection-oriented anonymizing communication
  20 service. Users choose a source-routed path through a set of nodes, and
  21 negotiate a "virtual circuit" through the network, in which each node
  22 knows its predecessor and successor, but no others. Traffic flowing down
  23 the circuit is unwrapped by a symmetric key at each node, which reveals
  24 the downstream node. +
  25
  26 Basically __tor__ provides a distributed network of servers ("onion routers").
  27 Users bounce their TCP streams -- web traffic, ftp, ssh, etc -- around the
  28 routers, and recipients, observers, and even the routers themselves have
  29 difficulty tracking the source of the stream.
  30
  31 OPTIONS
  32 -------
  33 **-h**, **-help**::
  34     Display a short help message and exit.
  35
  36 **-f** __FILE__::
  37     FILE contains further "option value" pairs. (Default: @CONFDIR@/torrc)
  38
  39 **--hash-password**::
  40     Generates a hashed password for control port access.
  41
  42 **--list-fingerprint**::
  43     Generate your keys and output your nickname and fingerprint.
  44
  45 **--verify-config**::
  46     Verify the configuration file is valid.
  47
  48 **--nt-service**::
  49     **--service [install|remove|start|stop]** Manage the Tor Windows
  50     NT/2000/XP service. Current instructions can be found at
  51     https://wiki.torproject.org/noreply/TheOnionRouter/TorFAQ#WinNTService
  52
  53 **--list-torrc-options**::
  54     List all valid options.
  55
  56 **--version**::
  57     Display Tor version and exit.
  58
  59 **--quiet**::
  60     Do not start Tor with a console log unless explicitly requested to do so.
  61     (By default, Tor starts out logging messages at level "notice" or higher to
  62     the console, until it has parsed its configuration.)
  63
  64 Other options can be specified either on the command-line (--option
  65     value), or in the configuration file (option value or option "value").
  66     Options are case-insensitive. C-style escaped characters are allowed inside
  67     quoted values.   Options on the command line take precedence over
  68     options found in the configuration file, except indicated otherwise.  To
  69     split one configuration entry into multiple lines, use a single \ before
  70     the end of the line.  Comments can be used in such multiline entries, but
  71     they must start at the beginning of a line.
  72
  73 **BandwidthRate** __N__ **bytes**|**KB**|**MB**|**GB**::
  74     A token bucket limits the average incoming bandwidth usage on this node to
  75     the specified number of bytes per second, and the average outgoing
  76     bandwidth usage to that same value.  If you want to run a relay in the
  77     public network, this needs to be _at the very least_ 20 KB (that is,
  78     20480 bytes). (Default: 5 MB)
  79
  80 **BandwidthBurst** __N__ **bytes**|**KB**|**MB**|**GB**::
  81     Limit the maximum token bucket size (also known as the burst) to the given
  82     number of bytes in each direction. (Default: 10 MB)
  83
  84 **MaxAdvertisedBandwidth** __N__ **bytes**|**KB**|**MB**|**GB**::
  85     If set, we will not advertise more than this amount of bandwidth for our
  86     BandwidthRate. Server operators who want to reduce the number of clients
  87     who ask to build circuits through them (since this is proportional to
  88     advertised bandwidth rate) can thus reduce the CPU demands on their server
  89     without impacting network performance.
  90
  91 **RelayBandwidthRate** __N__ **bytes**|**KB**|**MB**|**GB**::
  92     If not 0, a separate token bucket limits the average incoming bandwidth
  93     usage for \_relayed traffic_ on this node to the specified number of bytes
  94     per second, and the average outgoing bandwidth usage to that same value.
  95     Relayed traffic currently is calculated to include answers to directory
  96     requests, but that may change in future versions. (Default: 0)
  97
  98 **RelayBandwidthBurst** __N__ **bytes**|**KB**|**MB**|**GB**::
  99     If not 0, limit the maximum token bucket size (also known as the burst) for
 100     \_relayed traffic_ to the given number of bytes in each direction.
 101     (Default: 0)
 102
 103 **PerConnBWRate** __N__ **bytes**|**KB**|**MB**|**GB**::
 104     If set, do separate rate limiting for each connection from a non-relay.
 105     You should never need to change this value, since a network-wide value is
 106     published in the consensus and your relay will use that value. (Default: 0)
 107
 108 **PerConnBWBurst** __N__ **bytes**|**KB**|**MB**|**GB**::
 109     If set, do separate rate limiting for each connection from a non-relay.
 110     You should never need to change this value, since a network-wide value is
 111     published in the consensus and your relay will use that value. (Default: 0)
 112
 113 **ClientTransportPlugin** __transport__ socks4|socks5 __IP__:__PORT__::
 114 **ClientTransportPlugin** __transport__ exec __path-to-binary__ [options]::
 115     In its first form, when set along with a corresponding Bridge line, the Tor
 116     client forwards its traffic to a SOCKS-speaking proxy on "IP:PORT". It's the
 117     duty of that proxy to properly forward the traffic to the bridge. +
 118  +
 119     In its second form, when set along with a corresponding Bridge line, the Tor
 120     client launches the pluggable transport proxy exacutable in
 121     __path-to-binary__ using __options__ as its command-line options, and
 122     forwards its traffic to it. It's the duty of that proxy to properly forward
 123     the traffic to the bridge.
 124
 125 **ServerTransportPlugin** __transport__ exec __path-to-binary__ [options]::
 126     The Tor relay launches the pluggable transport proxy in __path-to-binary__
 127     using __options__ as its command-line options, and expects to receive
 128     proxied client traffic from it.
 129
 130 **ConnLimit** __NUM__::
 131     The minimum number of file descriptors that must be available to the Tor
 132     process before it will start. Tor will ask the OS for as many file
 133     descriptors as the OS will allow (you can find this by "ulimit -H -n").
 134     If this number is less than ConnLimit, then Tor will refuse to start. +
 135  +
 136     You probably don't need to adjust this. It has no effect on Windows
 137     since that platform lacks getrlimit(). (Default: 1000)
 138
 139 **DisableNetwork** **0**|**1**::
 140     When this option is set, we don't listen for or accept any connections
 141     other than controller connections, and we don't make any outbound
 142     connections.  Controllers sometimes use this option to avoid using
 143     the network until Tor is fully configured. (Default: 0)
 144
 145 **ConstrainedSockets** **0**|**1**::
 146     If set, Tor will tell the kernel to attempt to shrink the buffers for all
 147     sockets to the size specified in **ConstrainedSockSize**. This is useful for
 148     virtual servers and other environments where system level TCP buffers may
 149     be limited. If you're on a virtual server, and you encounter the "Error
 150     creating network socket: No buffer space available" message, you are
 151     likely experiencing this problem. +
 152  +
 153     The preferred solution is to have the admin increase the buffer pool for
 154     the host itself via /proc/sys/net/ipv4/tcp_mem or equivalent facility;
 155     this configuration option is a second-resort. +
 156  +
 157     The DirPort option should also not be used if TCP buffers are scarce. The
 158     cached directory requests consume additional sockets which exacerbates
 159     the problem. +
 160  +
 161     You should **not** enable this feature unless you encounter the "no buffer
 162     space available" issue. Reducing the TCP buffers affects window size for
 163     the TCP stream and will reduce throughput in proportion to round trip
 164     time on long paths. (Default: 0.)
 165
 166 **ConstrainedSockSize** __N__ **bytes**|**KB**::
 167     When **ConstrainedSockets** is enabled the receive and transmit buffers for
 168     all sockets will be set to this limit. Must be a value between 2048 and
 169     262144, in 1024 byte increments. Default of 8192 is recommended.
 170
 171 **ControlPort** __PORT__|**auto**::
 172     If set, Tor will accept connections on this port and allow those
 173     connections to control the Tor process using the Tor Control Protocol
 174     (described in control-spec.txt). Note: unless you also specify one or
 175     more of **HashedControlPassword** or **CookieAuthentication**,
 176     setting this option will cause Tor to allow any process on the local
 177     host to control it. (Setting both authentication methods means either
 178     method is sufficient to authenticate to Tor.) This
 179     option is required for many Tor controllers; most use the value of 9051.
 180     Set it to "auto" to have Tor pick a port for you. (Default: 0).
 181
 182 **ControlListenAddress** __IP__[:__PORT__]::
 183     Bind the controller listener to this address. If you specify a port, bind
 184     to this port rather than the one specified in ControlPort. We strongly
 185     recommend that you leave this alone unless you know what you're doing,
 186     since giving attackers access to your control listener is really
 187     dangerous. (Default: 127.0.0.1) This directive can be specified multiple
 188     times to bind to multiple addresses/ports.
 189
 190 **ControlSocket** __Path__::
 191     Like ControlPort, but listens on a Unix domain socket, rather than a TCP
 192     socket. (Unix and Unix-like systems only.)
 193
 194 **ControlSocketsGroupWritable** **0**|**1**::
 195     If this option is set to 0, don't allow the filesystem group to read and
 196     write unix sockets (e.g. ControlSocket). If the option is set to 1, make
 197     the control socket readable and writable by the default GID. (Default: 0)
 198
 199 **HashedControlPassword** __hashed_password__::
 200     Allow connections on the control port if they present
 201     the password whose one-way hash is __hashed_password__. You
 202     can compute the hash of a password by running "tor --hash-password
 203     __password__". You can provide several acceptable passwords by using more
 204     than one HashedControlPassword line.
 205
 206 **CookieAuthentication** **0**|**1**::
 207     If this option is set to 1, allow connections on the control port
 208     when the connecting process knows the contents of a file named
 209     "control_auth_cookie", which Tor will create in its data directory. This
 210     authentication method should only be used on systems with good filesystem
 211     security. (Default: 0)
 212
 213 **CookieAuthFile** __Path__::
 214     If set, this option overrides the default location and file name
 215     for Tor's cookie file. (See CookieAuthentication above.)
 216
 217 **CookieAuthFileGroupReadable** **0**|**1**|__Groupname__::
 218     If this option is set to 0, don't allow the filesystem group to read the
 219     cookie file. If the option is set to 1, make the cookie file readable by
 220     the default GID. [Making the file readable by other groups is not yet
 221     implemented; let us know if you need this for some reason.] (Default: 0).
 222
 223 **ControlPortWriteToFile** __Path__::
 224     If set, Tor writes the address and port of any control port it opens to
 225     this address.  Usable by controllers to learn the actual control port
 226     when ControlPort is set to "auto".
 227
 228 **ControlPortFileGroupReadable** **0**|**1**::
 229     If this option is set to 0, don't allow the filesystem group to read the
 230     control port file. If the option is set to 1, make the control port
 231     file readable by the default GID. (Default: 0).
 232
 233 **DataDirectory** __DIR__::
 234     Store working data in DIR (Default: @LOCALSTATEDIR@/lib/tor)
 235
 236 **DirServer** [__nickname__] [**flags**] __address__:__port__ __fingerprint__::
 237     Use a nonstandard authoritative directory server at the provided address
 238     and port, with the specified key fingerprint. This option can be repeated
 239     many times, for multiple authoritative directory servers. Flags are
 240     separated by spaces, and determine what kind of an authority this directory
 241     is. By default, every authority is authoritative for current ("v2")-style
 242     directories, unless the "no-v2" flag is given. If the "v1" flags is
 243     provided, Tor will use this server as an authority for old-style (v1)
 244     directories as well. (Only directory mirrors care about this.) Tor will
 245     use this server as an authority for hidden service information if the "hs"
 246     flag is set, or if the "v1" flag is set and the "no-hs" flag is **not** set.
 247     Tor will use this authority as a bridge authoritative directory if the
 248     "bridge" flag is set. If a flag "orport=**port**" is given, Tor will use the
 249     given port when opening encrypted tunnels to the dirserver. Lastly, if a
 250     flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority
 251     whose v3 long-term signing key has the fingerprint **fp**. +
 252  +
 253     If no **dirserver** line is given, Tor will use the default directory
 254     servers. NOTE: this option is intended for setting up a private Tor
 255     network with its own directory authorities. If you use it, you will be
 256     distinguishable from other users, because you won't believe the same
 257     authorities they do.
 258
 259 **DynamicDHGroups** **0**|**1**::
 260     If this option is set to 1, when running as a server, generate our
 261     own Diffie-Hellman group instead of using the one from Apache's mod_ssl.
 262     This option may help circumvent censorship based on static
 263     Diffie-Hellman parameters. (Default: 1).
 264
 265 **AlternateDirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ +
 266
 267 **AlternateHSAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ +
 268
 269 **AlternateBridgeAuthority** [__nickname__] [**flags**] __address__:__port__ __ fingerprint__::
 270     As DirServer, but replaces less of the default directory authorities. Using
 271     AlternateDirAuthority replaces the default Tor directory authorities, but
 272     leaves the hidden service authorities and bridge authorities in place.
 273     Similarly, Using AlternateHSAuthority replaces the default hidden service
 274     authorities, but not the directory or bridge authorities.
 275
 276 **DisableAllSwap** **0**|**1**::
 277     If set to 1, Tor will attempt to lock all current and future memory pages,
 278     so that memory cannot be paged out. Windows, OS X and Solaris are currently
 279     not supported. We believe that this feature works on modern Gnu/Linux
 280     distributions, and that it should work on *BSD systems (untested). This
 281     option requires that you start your Tor as root, and you should use the
 282     **User** option to properly reduce Tor's privileges. (Default: 0)
 283
 284 **DisableDebuggerAttachment** **0**|**1**::
 285    If set to 1, Tor will attempt to prevent basic debugging attachment attempts
 286    by other processes. It has no impact for users who wish to attach if they
 287    have CAP_SYS_PTRACE or if they are root.  We believe that this feature
 288    works on modern Gnu/Linux distributions, and that it may also work on *BSD
 289    systems (untested).  Some modern Gnu/Linux systems such as Ubuntu have the
 290    kernel.yama.ptrace_scope sysctl and by default enable it as an attempt to
 291    limit the PTRACE scope for all user processes by default. This feature will
 292    attempt to limit the PTRACE scope for Tor specifically - it will not attempt
 293    to alter the system wide ptrace scope as it may not even exist. If you wish
 294    to attach to Tor with a debugger such as gdb or strace you will want to set
 295    this to 0 for the duration of your debugging. Normal users should leave it
 296    on. Disabling this option while Tor is running is prohibited. (Default: 1)
 297
 298 **FetchDirInfoEarly** **0**|**1**::
 299     If set to 1, Tor will always fetch directory information like other
 300     directory caches, even if you don't meet the normal criteria for fetching
 301     early. Normal users should leave it off. (Default: 0)
 302
 303 **FetchDirInfoExtraEarly** **0**|**1**::
 304     If set to 1, Tor will fetch directory information before other directory
 305     caches. It will attempt to download directory information closer to the
 306     start of the consensus period. Normal users should leave it off.
 307     (Default: 0)
 308
 309 **FetchHidServDescriptors** **0**|**1**::
 310     If set to 0, Tor will never fetch any hidden service descriptors from the
 311     rendezvous directories. This option is only useful if you're using a Tor
 312     controller that handles hidden service fetches for you. (Default: 1)
 313
 314 **FetchServerDescriptors** **0**|**1**::
 315     If set to 0, Tor will never fetch any network status summaries or server
 316     descriptors from the directory servers. This option is only useful if
 317     you're using a Tor controller that handles directory fetches for you.
 318     (Default: 1)
 319
 320 **FetchUselessDescriptors** **0**|**1**::
 321     If set to 1, Tor will fetch every non-obsolete descriptor from the
 322     authorities that it hears about. Otherwise, it will avoid fetching useless
 323     descriptors, for example for routers that are not running. This option is
 324     useful if you're using the contributed "exitlist" script to enumerate Tor
 325     nodes that exit to certain addresses. (Default: 0)
 326
 327 **HTTPProxy** __host__[:__port__]::
 328     Tor will make all its directory requests through this host:port (or host:80
 329     if port is not specified), rather than connecting directly to any directory
 330     servers.
 331
 332 **HTTPProxyAuthenticator** __username:password__::
 333     If defined, Tor will use this username:password for Basic HTTP proxy
 334     authentication, as in RFC 2617. This is currently the only form of HTTP
 335     proxy authentication that Tor supports; feel free to submit a patch if you
 336     want it to support others.
 337
 338 **HTTPSProxy** __host__[:__port__]::
 339     Tor will make all its OR (SSL) connections through this host:port (or
 340     host:443 if port is not specified), via HTTP CONNECT rather than connecting
 341     directly to servers. You may want to set **FascistFirewall** to restrict
 342     the set of ports you might try to connect to, if your HTTPS proxy only
 343     allows connecting to certain ports.
 344
 345 **HTTPSProxyAuthenticator** __username:password__::
 346     If defined, Tor will use this username:password for Basic HTTPS proxy
 347     authentication, as in RFC 2617. This is currently the only form of HTTPS
 348     proxy authentication that Tor supports; feel free to submit a patch if you
 349     want it to support others.
 350
 351 **Socks4Proxy** __host__[:__port__]::
 352     Tor will make all OR connections through the SOCKS 4 proxy at host:port
 353     (or host:1080 if port is not specified).
 354
 355 **Socks5Proxy** __host__[:__port__]::
 356     Tor will make all OR connections through the SOCKS 5 proxy at host:port
 357     (or host:1080 if port is not specified).
 358
 359 **Socks5ProxyUsername** __username__ +
 360
 361 **Socks5ProxyPassword** __password__::
 362     If defined, authenticate to the SOCKS 5 server using username and password
 363     in accordance to RFC 1929. Both username and password must be between 1 and
 364     255 characters.
 365
 366 **KeepalivePeriod** __NUM__::
 367     To keep firewalls from expiring connections, send a padding keepalive cell
 368     every NUM seconds on open connections that are in use. If the connection
 369     has no open circuits, it will instead be closed after NUM seconds of
 370     idleness. (Default: 5 minutes)
 371
 372 **Log** __minSeverity__[-__maxSeverity__] **stderr**|**stdout**|**syslog**::
 373     Send all messages between __minSeverity__ and __maxSeverity__ to the standard
 374     output stream, the standard error stream, or to the system log. (The
 375     "syslog" value is only supported on Unix.) Recognized severity levels are
 376     debug, info, notice, warn, and err. We advise using "notice" in most cases,
 377     since anything more verbose may provide sensitive information to an
 378     attacker who obtains the logs. If only one severity level is given, all
 379     messages of that level or higher will be sent to the listed destination.
 380
 381 **Log** __minSeverity__[-__maxSeverity__] **file** __FILENAME__::
 382     As above, but send log messages to the listed filename. The
 383     "Log" option may appear more than once in a configuration file.
 384     Messages are sent to all the logs that match their severity
 385     level.
 386
 387 **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **file** __FILENAME__ +
 388
 389 **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **stderr**|**stdout**|**syslog**::
 390     As above, but select messages by range of log severity __and__ by a
 391     set of "logging domains".  Each logging domain corresponds to an area of
 392     functionality inside Tor.  You can specify any number of severity ranges
 393     for a single log statement, each of them prefixed by a comma-separated
 394     list of logging domains.  You can prefix a domain with $$~$$ to indicate
 395     negation, and use * to indicate "all domains".  If you specify a severity
 396     range without a list of domains, it matches all domains. +
 397  +
 398     This is an advanced feature which is most useful for debugging one or two
 399     of Tor's subsystems at a time. +
 400  +
 401     The currently recognized domains are: general, crypto, net, config, fs,
 402     protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge,
 403     acct, hist, and handshake.  Domain names are case-insensitive. +
 404  +
 405     For example, "`Log [handshake]debug [~net,~mm]info notice stdout`" sends
 406     to stdout: all handshake messages of any severity, all info-and-higher
 407     messages from domains other than networking and memory management, and all
 408     messages of severity notice or higher.
 409
 410 **LogMessageDomains** **0**|**1**::
 411     If 1, Tor includes message domains with each log message.  Every log
 412     message currently has at least one domain; most currently have exactly
 413     one.  This doesn't affect controller log messages. (Default: 0)
 414
 415 **OutboundBindAddress** __IP__::
 416     Make all outbound connections originate from the IP address specified. This
 417     is only useful when you have multiple network interfaces, and you want all
 418     of Tor's outgoing connections to use a single one.  This setting will be
 419     ignored for connections to the loopback addresses (127.0.0.0/8 and ::1).
 420
 421 **PidFile** __FILE__::
 422     On startup, write our PID to FILE. On clean shutdown, remove
 423     FILE.
 424
 425 **ProtocolWarnings** **0**|**1**::
 426     If 1, Tor will log with severity \'warn' various cases of other parties not
 427     following the Tor specification. Otherwise, they are logged with severity
 428     \'info'. (Default: 0)
 429
 430 **RunAsDaemon** **0**|**1**::
 431     If 1, Tor forks and daemonizes to the background. This option has no effect
 432     on Windows; instead you should use the --service command-line option.
 433     (Default: 0)
 434
 435 **LogTimeGranularity** __NUM__::
 436     Set the resolution of timestamps in Tor's logs to NUM milliseconds.
 437     NUM must be positive and either a divisor or a multiple of 1 second.
 438     Note that this option only controls the granularity written by Tor to
 439     a file or console log.  Tor does not (for example) "batch up" log
 440     messages to affect times logged by a controller, times attached to
 441     syslog messages, or the mtime fields on log files.  (Default: 1 second)
 442
 443 **SafeLogging** **0**|**1**|**relay**::
 444     Tor can scrub potentially sensitive strings from log messages (e.g.
 445     addresses) by replacing them with the string [scrubbed]. This way logs can
 446     still be useful, but they don't leave behind personally identifying
 447     information about what sites a user might have visited. +
 448  +
 449     If this option is set to 0, Tor will not perform any scrubbing, if it is
 450     set to 1, all potentially sensitive strings are replaced. If it is set to
 451     relay, all log messages generated when acting as a relay are sanitized, but
 452     all messages generated when acting as a client are not. (Default: 1)
 453
 454 **User** __UID__::
 455     On startup, setuid to this user and setgid to their primary group.
 456
 457 **HardwareAccel** **0**|**1**::
 458     If non-zero, try to use built-in (static) crypto hardware acceleration when
 459     available. (Default: 0)
 460
 461 **AccelName** __NAME__::
 462     When using OpenSSL hardware crypto acceleration attempt to load the dynamic
 463     engine of this name. This must be used for any dynamic hardware engine.
 464     Names can be verified with the openssl engine command.
 465
 466 **AccelDir** __DIR__::
 467     Specify this option if using dynamic hardware acceleration and the engine
 468     implementation library resides somewhere other than the OpenSSL default.
 469
 470 **AvoidDiskWrites** **0**|**1**::
 471     If non-zero, try to write to disk less frequently than we would otherwise.
 472     This is useful when running on flash memory or other media that support
 473     only a limited number of writes. (Default: 0)
 474
 475 **TunnelDirConns** **0**|**1**::
 476     If non-zero, when a directory server we contact supports it, we will build
 477     a one-hop circuit and make an encrypted connection via its ORPort.
 478     (Default: 1)
 479
 480 **PreferTunneledDirConns** **0**|**1**::
 481     If non-zero, we will avoid directory servers that don't support tunneled
 482     directory connections, when possible. (Default: 1)
 483
 484 **CircuitPriorityHalflife** __NUM1__::
 485     If this value is set, we override the default algorithm for choosing which
 486     circuit's cell to deliver or relay next. When the value is 0, we
 487     round-robin between the active circuits on a connection, delivering one
 488     cell from each in turn. When the value is positive, we prefer delivering
 489     cells from whichever connection has the lowest weighted cell count, where
 490     cells are weighted exponentially according to the supplied
 491     CircuitPriorityHalflife value (in seconds). If this option is not set at
 492     all, we use the behavior recommended in the current consensus
 493     networkstatus. This is an advanced option; you generally shouldn't have
 494     to mess with it. (Default: not set.)
 495
 496 **DisableIOCP** **0**|**1**::
 497     If Tor was built to use the Libevent's "bufferevents" networking code
 498     and you're running on Windows, setting this option to 1 will tell Libevent
 499     not to use the Windows IOCP networking API.  (Default: 1)
 500
 501 **UserspaceIOCPBuffers** **0**|**1**::
 502     If IOCP is enabled (see DisableIOCP above), setting this option to 1
 503     will tell Tor to disable kernel-space TCP buffers, in order to avoid
 504     needless copy operations and try not to run out of non-paged RAM.
 505     This feature is experimental; don't use it yet unless you're eager to
 506     help tracking down bugs. (Default: 0)
 507
 508 **_UseFilteringSSLBufferevents** **0**|**1**::
 509     Tells Tor to do its SSL communication using a chain of
 510     bufferevents: one for SSL and one for networking.  This option has no
 511     effect if bufferevents are disabled (in which case it can't turn on), or
 512     if IOCP bufferevents are enabled (in which case it can't turn off).  This
 513     option is useful for debugging only; most users shouldn't touch it.
 514     (Default: 0)
 515
 516 **CountPrivateBandwidth** **0**|**1**::
 517     If this option is set, then Tor's rate-limiting applies not only to
 518     remote connections, but also to connections to private addresses like
 519     127.0.0.1 or 10.0.0.1.  This is mostly useful for debugging
 520     rate-limiting.  (Default: 0)
 521
 522 CLIENT OPTIONS
 523 --------------
 524
 525 The following options are useful only for clients (that is, if
 526 **SocksPort**, **TransPort**, **DNSPort**, or **NATDPort** is non-zero):
 527
 528 **AllowInvalidNodes** **entry**|**exit**|**middle**|**introduction**|**rendezvous**|**...**::
 529     If some Tor servers are obviously not working right, the directory
 530     authorities can manually mark them as invalid, meaning that it's not
 531     recommended you use them for entry or exit positions in your circuits. You
 532     can opt to use them in some circuit positions, though. The default is
 533     "middle,rendezvous", and other choices are not advised.
 534
 535 **ExcludeSingleHopRelays** **0**|**1**::
 536     This option controls whether circuits built by Tor will include relays with
 537     the AllowSingleHopExits flag set to true. If ExcludeSingleHopRelays is set
 538     to 0, these relays will be included. Note that these relays might be at
 539     higher risk of being seized or observed, so they are not normally
 540     included.  Also note that relatively few clients turn off this option,
 541     so using these relays might make your client stand out.
 542     (Default: 1)
 543
 544 **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]::
 545     When set along with UseBridges, instructs Tor to use the relay at
 546     "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint"
 547     is provided (using the same format as for DirServer), we will verify that
 548     the relay running at that location has the right fingerprint. We also use
 549     fingerprint to look up the bridge descriptor at the bridge authority, if
 550     it's provided and if UpdateBridgesFromAuthority is set too.  +
 551  +
 552     If "transport" is provided, and matches to a ClientTransportPlugin
 553     line, we use that pluggable transports proxy to transfer data to
 554     the bridge.
 555
 556 **LearnCircuitBuildTimeout** **0**|**1**::
 557     If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1)
 558
 559 **CircuitBuildTimeout** __NUM__::
 560
 561     Try for at most NUM seconds when building circuits. If the circuit isn't
 562     open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this
 563     value serves as the initial value to use before a timeout is learned. If
 564     LearnCircuitBuildTimeout is 0, this value is the only value used.
 565     (Default: 60 seconds.)
 566
 567 **CircuitIdleTimeout** __NUM__::
 568     If we have kept a clean (never used) circuit around for NUM seconds, then
 569     close it. This way when the Tor client is entirely idle, it can expire all
 570     of its circuits, and then expire its TLS connections. Also, if we end up
 571     making a circuit that is not useful for exiting any of the requests we're
 572     receiving, it won't forever take up a slot in the circuit list. (Default: 1
 573     hour.)
 574
 575 **CircuitStreamTimeout** __NUM__::
 576     If non-zero, this option overrides our internal timeout schedule for how
 577     many seconds until we detach a stream from a circuit and try a new circuit.
 578     If your network is particularly slow, you might want to set this to a
 579     number like 60. (Default: 0)
 580
 581 **ClientOnly** **0**|**1**::
 582     If set to 1, Tor will under no circumstances run as a relay or serve
 583     directory requests. This config option is mostly meaningless: we
 584     added it back when we were considering having Tor clients auto-promote
 585     themselves to being relays if they were stable and fast enough. The
 586     current behavior is simply that Tor is a client unless ORPort or
 587     DirPort are configured. (Default: 0)
 588
 589 **ExcludeNodes** __node__,__node__,__...__::
 590     A list of identity fingerprints, nicknames, country codes and address
 591     patterns of nodes to avoid when building a circuit.
 592     (Example:
 593     ExcludeNodes SlowServer, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) +
 594  +
 595     By default, this option is treated as a preference that Tor is allowed
 596     to override in order to keep working.
 597     For example, if you try to connect to a hidden service,
 598     but you have excluded all of the hidden service's introduction points,
 599     Tor will connect to one of them anyway.  If you do not want this
 600     behavior, set the StrictNodes option (documented below).  +
 601  +
 602     Note also that if you are a relay, this (and the other node selection
 603     options below) only affects your own circuits that Tor builds for you.
 604     Clients can still build circuits through you to any node.  Controllers
 605     can tell Tor to build circuits through any node.
 606
 607
 608 **ExcludeExitNodes** __node__,__node__,__...__::
 609     A list of identity fingerprints, nicknames, country codes and address
 610     patterns of nodes to never use when picking an exit node---that is, a
 611     node that delivers traffic for you outside the Tor network.   Note that any
 612     node listed in ExcludeNodes is automatically considered to be part of this
 613     list too.  See also the caveats on the "ExitNodes" option below.
 614
 615 **ExitNodes** __node__,__node__,__...__::
 616     A list of identity fingerprints, nicknames, country codes and address
 617     patterns of nodes to use as exit node---that is, a
 618     node that delivers traffic for you outside the Tor network. +
 619  +
 620     Note that if you list too few nodes here, or if you exclude too many exit
 621     nodes with ExcludeExitNodes, you can degrade functionality.  For example,
 622     if none of the exits you list allows traffic on port 80 or 443, you won't
 623     be able to browse the web. +
 624  +
 625     Note also that not every circuit is used to deliver traffic outside of
 626     the Tor network.  It is normal to see non-exit circuits (such as those
 627     used to connect to hidden services, those that do directory fetches,
 628     those used for relay reachability self-tests, and so on) that end
 629     at a non-exit node.  To
 630     keep a node from being used entirely, see ExcludeNodes and StrictNodes. +
 631  +
 632     The ExcludeNodes option overrides this option: any node listed in both
 633     ExitNodes and ExcludeNodes is treated as excluded. +
 634  +
 635     The .exit address notation, if enabled via AllowDotExit, overrides
 636     this option.
 637
 638 **EntryNodes** __node__,__node__,__...__::
 639     A list of identity fingerprints, nicknames, and country codes of nodes
 640     to use for the first hop in your normal circuits.
 641     Normal circuits include all
 642     circuits except for direct connections to directory servers.  The Bridge
 643     option overrides this option; if you have configured bridges and
 644     UseBridges is 1, the Bridges are used as your entry nodes. +
 645  +
 646     The ExcludeNodes option overrides this option: any node listed in both
 647     EntryNodes and ExcludeNodes is treated as excluded.
 648
 649 **StrictNodes** **0**|**1**::
 650     If StrictNodes is set to 1, Tor will treat the ExcludeNodes option as a
 651     requirement to follow for all the circuits you generate, even if doing so
 652     will break functionality for you.  If StrictNodes is set to 0, Tor will
 653     still try to avoid nodes in the ExcludeNodes list, but it will err on the
 654     side of avoiding unexpected errors.  Specifically, StrictNodes 0 tells
 655     Tor that it is okay to use an excluded node when it is *necessary* to
 656     perform relay reachability self-tests, connect to
 657     a hidden service, provide a hidden service to a client, fulfill a .exit
 658     request, upload directory information, or download directory information.
 659     (Default: 0)
 660
 661 **FascistFirewall** **0**|**1**::
 662     If 1, Tor will only create outgoing connections to ORs running on ports
 663     that your firewall allows (defaults to 80 and 443; see **FirewallPorts**).
 664     This will allow you to run Tor as a client behind a firewall with
 665     restrictive policies, but will not allow you to run as a server behind such
 666     a firewall. If you prefer more fine-grained control, use
 667     ReachableAddresses instead.
 668
 669 **FirewallPorts** __PORTS__::
 670     A list of ports that your firewall allows you to connect to. Only used when
 671     **FascistFirewall** is set. This option is deprecated; use ReachableAddresses
 672     instead. (Default: 80, 443)
 673
 674 **ReachableAddresses** __ADDR__[/__MASK__][:__PORT__]...::
 675     A comma-separated list of IP addresses and ports that your firewall allows
 676     you to connect to. The format is as for the addresses in ExitPolicy, except
 677     that "accept" is understood unless "reject" is explicitly provided. For
 678     example, \'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept
 679     \*:80' means that your firewall allows connections to everything inside net
 680     99, rejects port 80 connections to net 18, and accepts connections to port
 681     80 otherwise. (Default: \'accept \*:*'.)
 682
 683 **ReachableDirAddresses** __ADDR__[/__MASK__][:__PORT__]...::
 684     Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
 685     these restrictions when fetching directory information, using standard HTTP
 686     GET requests. If not set explicitly then the value of
 687     **ReachableAddresses** is used. If **HTTPProxy** is set then these
 688     connections will go through that proxy.
 689
 690 **ReachableORAddresses** __ADDR__[/__MASK__][:__PORT__]...::
 691     Like **ReachableAddresses**, a list of addresses and ports. Tor will obey
 692     these restrictions when connecting to Onion Routers, using TLS/SSL. If not
 693     set explicitly then the value of **ReachableAddresses** is used. If
 694     **HTTPSProxy** is set then these connections will go through that proxy. +
 695  +
 696     The separation between **ReachableORAddresses** and
 697     **ReachableDirAddresses** is only interesting when you are connecting
 698     through proxies (see **HTTPProxy** and **HTTPSProxy**). Most proxies limit
 699     TLS connections (which Tor uses to connect to Onion Routers) to port 443,
 700     and some limit HTTP GET requests (which Tor uses for fetching directory
 701     information) to port 80.
 702
 703 **HidServAuth** __onion-address__ __auth-cookie__ [__service-name__]::
 704     Client authorization for a hidden service. Valid onion addresses contain 16
 705     characters in a-z2-7 plus ".onion", and valid auth cookies contain 22
 706     characters in A-Za-z0-9+/. The service name is only used for internal
 707     purposes, e.g., for Tor controllers. This option may be used multiple times
 708     for different hidden services. If a hidden service uses authorization and
 709     this option is not set, the hidden service is not accessible. Hidden
 710     services can be configured to require authorization using the
 711     **HiddenServiceAuthorizeClient** option.
 712
 713 **CloseHSClientCircuitsImmediatelyOnTimeout** **0**|**1**::
 714     If 1, Tor will close unfinished hidden service client circuits
 715     which have not moved closer to connecting to their destination
 716     hidden service when their internal state has not changed for the
 717     duration of the current circuit-build timeout.  Otherwise, such
 718     circuits will be left open, in the hope that they will finish
 719     connecting to their destination hidden services.  In either case,
 720     another set of introduction and rendezvous circuits for the same
 721     destination hidden service will be launched. (Default: 0)
 722
 723 **CloseHSServiceRendCircuitsImmediatelyOnTimeout** **0**|**1**::
 724     If 1, Tor will close unfinished hidden-service-side rendezvous
 725     circuits after the current circuit-build timeout.  Otherwise, such
 726     circuits will be left open, in the hope that they will finish
 727     connecting to their destinations.  In either case, another
 728     rendezvous circuit for the same destination client will be
 729     launched. (Default: 0)
 730
 731 **LongLivedPorts** __PORTS__::
 732     A list of ports for services that tend to have long-running connections
 733     (e.g. chat and interactive shells). Circuits for streams that use these
 734     ports will contain only high-uptime nodes, to reduce the chance that a node
 735     will go down before the stream is finished. (Default: 21, 22, 706, 1863,
 736     5050, 5190, 5222, 5223, 6523, 6667, 6697, 8300)
 737
 738 **MapAddress** __address__ __newaddress__::
 739     When a request for address arrives to Tor, it will transform to newaddress
 740     before processing it. For example, if you always want connections to
 741     www.example.com to exit via __torserver__ (where __torserver__ is the
 742     nickname of the server), use "MapAddress www.example.com
 743     www.example.com.torserver.exit". If the value is prefixed with a
 744     "\*.", matches an entire domain. For example, if you
 745     always want connections to example.com and any if its subdomains
 746     to exit via
 747     __torserver__ (where __torserver__ is the nickname of the server), use
 748     "MapAddress \*.example.com \*.example.com.torserver.exit". (Note the
 749     leading "*." in each part of the directive.) You can also redirect all
 750     subdomains of a domain to a single address. For example, "MapAddress
 751     *.example.com www.example.com". +
 752  +
 753     NOTES:
 754
 755     1. When evaluating MapAddress expressions Tor stops when it hits the most
 756     recently added expression that matches the requested address. So if you
 757     have the following in your torrc, www.torproject.org will map to 1.1.1.1:
 758
 759      MapAddress www.torproject.org 2.2.2.2
 760      MapAddress www.torproject.org 1.1.1.1
 761
 762     2. Tor evaluates the MapAddress configuration until it finds no matches. So
 763     if you have the following in your torrc, www.torproject.org will map to
 764     2.2.2.2:
 765
 766       MapAddress 1.1.1.1 2.2.2.2
 767       MapAddress www.torproject.org 1.1.1.1
 768
 769     3. The following MapAddress expression is invalid (and will be
 770     ignored) because you cannot map from a specific address to a wildcard
 771     address:
 772
 773       MapAddress www.torproject.org *.torproject.org.torserver.exit
 774
 775     4. Using a wildcard to match only part of a string (as in *ample.com) is
 776     also invalid.
 777
 778 **NewCircuitPeriod** __NUM__::
 779     Every NUM seconds consider whether to build a new circuit. (Default: 30
 780     seconds)
 781
 782 **MaxCircuitDirtiness** __NUM__::
 783     Feel free to reuse a circuit that was first used at most NUM seconds ago,
 784     but never attach a new stream to a circuit that is too old. (Default: 10
 785     minutes)
 786
 787 **MaxClientCircuitsPending** __NUM__::
 788     Do not allow more than NUM circuits to be pending at a time for handling
 789     client streams. A circuit is pending if we have begun constructing it,
 790     but it has not yet been completely constructed.  (Default: 32)
 791
 792 **NodeFamily** __node__,__node__,__...__::
 793     The Tor servers, defined by their identity fingerprints or nicknames,
 794     constitute a "family" of similar or co-administered servers, so never use
 795     any two of them in the same circuit. Defining a NodeFamily is only needed
 796     when a server doesn't list the family itself (with MyFamily). This option
 797     can be used multiple times.  In addition to nodes, you can also list
 798     IP address and ranges and country codes in {curly braces}.
 799
 800 **EnforceDistinctSubnets** **0**|**1**::
 801     If 1, Tor will not put two servers whose IP addresses are "too close" on
 802     the same circuit. Currently, two addresses are "too close" if they lie in
 803     the same /16 range. (Default: 1)
 804
 805 **SOCKSPort** \['address':]__port__|**auto** [_isolation flags_]::
 806     Open this port to listen for connections from SOCKS-speaking
 807     applications. Set this to 0 if you don't want to allow application
 808     connections via SOCKS. Set it to "auto" to have Tor pick a port for
 809     you. This directive can be specified multiple times to bind
 810     to multiple addresses/ports. (Default: 9050) +
 811  +
 812     The _isolation flags_ arguments give Tor rules for which streams
 813     received on this SOCKSPort are allowed to share circuits with one
 814     another.  Recognized isolation flags are:
 815     **IsolateClientAddr**;;
 816         Don't share circuits with streams from a different
 817         client address.  (On by default and strongly recommended;
 818         you can disable it with **NoIsolateClientAddr**.)
 819     **IsolateSOCKSAuth**;;
 820         Don't share circuits with streams for which different
 821         SOCKS authentication was provided. (On by default;
 822         you can disable it with **NoIsolateSOCKSAuth**.)
 823     **IsolateClientProtocol**;;
 824         Don't share circuits with streams using a different protocol.
 825         (SOCKS 4, SOCKS 5, TransPort connections, NATDPort connections,
 826         and DNSPort requests are all considered to be different protocols.)
 827     **IsolateDestPort**;;
 828         Don't share circuits with streams targetting a different
 829         destination port.
 830     **IsolateDestAddr**;;
 831         Don't share circuits with streams targetting a different
 832         destination address.
 833     **SessionGroup=**__INT__;;
 834         If no other isolation rules would prevent it, allow streams
 835         on this port to share circuits with streams from every other
 836         port with the same session group.  (By default, streams received
 837         on different ports are always isolated from one another.)
 838
 839 **SOCKSListenAddress** __IP__[:__PORT__]::
 840     Bind to this address to listen for connections from Socks-speaking
 841     applications. (Default: 127.0.0.1) You can also specify a port (e.g.
 842     192.168.0.1:9100). This directive can be specified multiple times to bind
 843     to multiple addresses/ports.  (DEPRECATED: As of 0.2.3.x-alpha, you can
 844     now use multiple SOCKSPort entries, and provide addresses for SOCKSPort
 845     entries, so SOCKSListenAddress no longer has a purpose.  For backward
 846     compatibility, SOCKSListenAddress is only allowed when SOCKSPort is just
 847     a port number.)
 848
 849 **SocksPolicy** __policy__,__policy__,__...__::
 850     Set an entrance policy for this server, to limit who can connect to the
 851     SocksPort and DNSPort ports. The policies have the same form as exit
 852     policies below.
 853
 854 **SocksTimeout** __NUM__::
 855     Let a socks connection wait NUM seconds handshaking, and NUM seconds
 856     unattached waiting for an appropriate circuit, before we fail it. (Default:
 857     2 minutes.)
 858
 859 **TokenBucketRefillInterval** __NUM__ [**msec**|**second**]::
 860     Set the refill interval of Tor's token bucket to NUM milliseconds.
 861     NUM must be between 1 and 1000, inclusive.  Note that the configured
 862     bandwidth limits are still expressed in bytes per second: this
 863     option only affects the frequency with which Tor checks to see whether
 864     previously exhausted connections may read again. (Default: 100 msec.)
 865
 866 **TrackHostExits** __host__,__.domain__,__...__::
 867     For each value in the comma separated list, Tor will track recent
 868     connections to hosts that match this value and attempt to reuse the same
 869     exit node for each. If the value is prepended with a \'.\', it is treated as
 870     matching an entire domain. If one of the values is just a \'.', it means
 871     match everything. This option is useful if you frequently connect to sites
 872     that will expire all your authentication cookies (i.e. log you out) if
 873     your IP address changes. Note that this option does have the disadvantage
 874     of making it more clear that a given history is associated with a single
 875     user. However, most people who would wish to observe this will observe it
 876     through cookies or other protocol-specific means anyhow.
 877
 878 **TrackHostExitsExpire** __NUM__::
 879     Since exit servers go up and down, it is desirable to expire the
 880     association between host and exit server after NUM seconds. The default is
 881     1800 seconds (30 minutes).
 882
 883 **UpdateBridgesFromAuthority** **0**|**1**::
 884     When set (along with UseBridges), Tor will try to fetch bridge descriptors
 885     from the configured bridge authorities when feasible. It will fall back to
 886     a direct request if the authority responds with a 404. (Default: 0)
 887
 888 **UseBridges** **0**|**1**::
 889     When set, Tor will fetch descriptors for each bridge listed in the "Bridge"
 890     config lines, and use these relays as both entry guards and directory
 891     guards. (Default: 0)
 892
 893 **UseEntryGuards** **0**|**1**::
 894     If this option is set to 1, we pick a few long-term entry servers, and try
 895     to stick with them. This is desirable because constantly changing servers
 896     increases the odds that an adversary who owns some servers will observe a
 897     fraction of your paths. (Defaults to 1.)
 898
 899 **NumEntryGuards** __NUM__::
 900     If UseEntryGuards is set to 1, we will try to pick a total of NUM routers
 901     as long-term entries for our circuits. (Defaults to 3.)
 902
 903 **SafeSocks** **0**|**1**::
 904     When this option is enabled, Tor will reject application connections that
 905     use unsafe variants of the socks protocol -- ones that only provide an IP
 906     address, meaning the application is doing a DNS resolve first.
 907     Specifically, these are socks4 and socks5 when not doing remote DNS.
 908     (Defaults to 0.)
 909
 910 **TestSocks** **0**|**1**::
 911     When this option is enabled, Tor will make a notice-level log entry for
 912     each connection to the Socks port indicating whether the request used a
 913     safe socks protocol or an unsafe one (see above entry on SafeSocks). This
 914     helps to determine whether an application using Tor is possibly leaking
 915     DNS requests. (Default: 0)
 916
 917 **WarnUnsafeSocks** **0**|**1**::
 918     When this option is enabled, Tor will warn whenever a request is
 919     received that only contains an IP address instead of a hostname. Allowing
 920     applications to do DNS resolves themselves is usually a bad idea and
 921     can leak your location to attackers. (Default: 1)
 922
 923 **VirtualAddrNetwork** __Address__/__bits__::
 924     When Tor needs to assign a virtual (unused) address because of a MAPADDRESS
 925     command from the controller or the AutomapHostsOnResolve feature, Tor
 926     picks an unassigned address from this range. (Default:
 927     127.192.0.0/10) +
 928  +
 929     When providing proxy server service to a network of computers using a tool
 930     like dns-proxy-tor, change this address to "10.192.0.0/10" or
 931     "172.16.0.0/12". The default **VirtualAddrNetwork** address range on a
 932     properly configured machine will route to the loopback interface. For
 933     local use, no change to the default VirtualAddrNetwork setting is needed.
 934
 935 **AllowNonRFC953Hostnames** **0**|**1**::
 936     When this option is disabled, Tor blocks hostnames containing illegal
 937     characters (like @ and :) rather than sending them to an exit node to be
 938     resolved. This helps trap accidental attempts to resolve URLs and so on.
 939     (Default: 0)
 940
 941 **AllowDotExit** **0**|**1**::
 942     If enabled, we convert "www.google.com.foo.exit" addresses on the
 943     SocksPort/TransPort/NATDPort into "www.google.com" addresses that exit from
 944     the node "foo". Disabled by default since attacking websites and exit
 945     relays can use it to manipulate your path selection. (Default: 0)
 946
 947 **FastFirstHopPK** **0**|**1**::
 948     When this option is disabled, Tor uses the public key step for the first
 949     hop of creating circuits. Skipping it is generally safe since we have
 950     already used TLS to authenticate the relay and to establish forward-secure
 951     keys. Turning this option off makes circuit building slower. +
 952  +
 953     Note that Tor will always use the public key step for the first hop if it's
 954     operating as a relay, and it will never use the public key step if it
 955     doesn't yet know the onion key of the first hop. (Default: 1)
 956
 957 **TransPort**  \['address':]__port__|**auto** [_isolation flags_]::
 958     Open this port to listen for transparent proxy connections.  Set this to
 959     0 if you don't want to allow transparent proxy connections.  Set the port
 960     to "auto" to have Tor pick a port for you. This directive can be
 961     specified multiple times to bind to multiple addresses/ports.  See
 962     SOCKSPort for an explanation of isolation flags. +
 963  +
 964     TransPort requires OS support for transparent proxies, such as BSDs' pf or
 965     Linux's IPTables. If you're planning to use Tor as a transparent proxy for
 966     a network, you'll want to examine and change VirtualAddrNetwork from the
 967     default setting. You'll also want to set the TransListenAddress option for
 968     the network you'd like to proxy. (Default: 0).
 969
 970 **TransListenAddress** __IP__[:__PORT__]::
 971     Bind to this address to listen for transparent proxy connections. (Default:
 972     127.0.0.1). This is useful for exporting a transparent proxy server to an
 973     entire network. (DEPRECATED: As of 0.2.3.x-alpha, you can
 974     now use multiple TransPort entries, and provide addresses for TransPort
 975     entries, so TransListenAddress no longer has a purpose.  For backward
 976     compatibility, TransListenAddress is only allowed when TransPort is just
 977     a port number.)
 978
 979 **NATDPort** \['address':]__port__|**auto** [_isolation flags_]::
 980     Open this port to listen for connections from old versions of ipfw (as
 981     included in old versions of FreeBSD, etc) using the NATD protocol.
 982     Use 0 if you don't want to allow NATD connections.  Set the port
 983     to "auto" to have Tor pick a port for you. This directive can be
 984     specified multiple times to bind to multiple addresses/ports.  See
 985     SOCKSPort for an explanation of isolation flags. +
 986  +
 987     This option is only for people who cannot use TransPort. (Default: 0)
 988
 989 **NATDListenAddress** __IP__[:__PORT__]::
 990     Bind to this address to listen for NATD connections. (DEPRECATED: As of
 991     0.2.3.x-alpha, you can now use multiple NATDPort entries, and provide
 992     addresses for NATDPort entries, so NATDListenAddress no longer has a
 993     purpose.  For backward compatibility, NATDListenAddress is only allowed
 994     when NATDPort is just a port number.)
 995
 996 **AutomapHostsOnResolve** **0**|**1**::
 997     When this option is enabled, and we get a request to resolve an address
 998     that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an
 999     unused virtual address to that address, and return the new virtual address.
1000     This is handy for making ".onion" addresses work with applications that
1001     resolve an address and then connect to it. (Default: 0).
1002
1003 **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__::
1004     A comma-separated list of suffixes to use with **AutomapHostsOnResolve**.
1005     The "." suffix is equivalent to "all addresses." (Default: .exit,.onion).
1006
1007 **DNSPort** \['address':]__port__|**auto** [_isolation flags_]::
1008     If non-zero, open this port to listen for UDP DNS requests, and resolve
1009     them anonymously.  Set the port to "auto" to have Tor pick a port for
1010     you. This directive can be specified multiple times to bind to multiple
1011     addresses/ports. See SOCKSPort for an explanation of isolation
1012     flags. (Default: 0).
1013
1014 **DNSListenAddress** __IP__[:__PORT__]::
1015     Bind to this address to listen for DNS connections. (DEPRECATED: As of
1016     0.2.3.x-alpha, you can now use multiple DNSPort entries, and provide
1017     addresses for DNSPort entries, so DNSListenAddress no longer has a
1018     purpose.  For backward compatibility, DNSListenAddress is only allowed
1019     when DNSPort is just a port number.)
1020
1021 **ClientDNSRejectInternalAddresses** **0**|**1**::
1022     If true, Tor does not believe any anonymously retrieved DNS answer that
1023     tells it that an address resolves to an internal address (like 127.0.0.1 or
1024     192.168.0.1). This option prevents certain browser-based attacks; don't
1025     turn it off unless you know what you're doing. (Default: 1).
1026
1027 **ClientRejectInternalAddresses** **0**|**1**::
1028     If true, Tor does not try to fulfill requests to connect to an internal
1029     address (like 127.0.0.1 or 192.168.0.1) __unless a exit node is
1030     specifically requested__ (for example, via a .exit hostname, or a
1031     controller request).  (Default: 1).
1032
1033 **DownloadExtraInfo** **0**|**1**::
1034     If true, Tor downloads and caches "extra-info" documents. These documents
1035     contain information about servers other than the information in their
1036     regular router descriptors. Tor does not use this information for anything
1037     itself; to save bandwidth, leave this option turned off. (Default: 0).
1038
1039 **FallbackNetworkstatusFile** __FILENAME__::
1040     If Tor doesn't have a cached networkstatus file, it starts out using this
1041     one instead. Even if this file is out of date, Tor can still use it to
1042     learn about directory mirrors, so it doesn't need to put load on the
1043     authorities. (Default: None).
1044
1045 **WarnPlaintextPorts** __port__,__port__,__...__::
1046     Tells Tor to issue a warnings whenever the user tries to make an anonymous
1047     connection to one of these ports. This option is designed to alert users
1048     to services that risk sending passwords in the clear. (Default:
1049     23,109,110,143).
1050
1051 **RejectPlaintextPorts** __port__,__port__,__...__::
1052     Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor
1053     will instead refuse to make the connection. (Default: None).
1054
1055 **AllowSingleHopCircuits** **0**|**1**::
1056     When this option is set, the attached Tor controller can use relays
1057     that have the **AllowSingleHopExits** option turned on to build
1058     one-hop Tor connections.  (Default: 0)
1059
1060 **OptimisticData** **0**|**1**|**auto**::
1061     When this option is set, and Tor is using an exit node that supports
1062     the feature, it will try optimistically to send data to the exit node
1063     without waiting for the exit node to report whether the connection
1064     succeeded.  This can save a round-trip time for protocols like HTTP
1065     where the client talks first.  If OptimisticData is set to **auto**,
1066     Tor will look at the UseOptimisticData parameter in the networkstatus.
1067     (Default: auto)
1068
1069 **Tor2webMode** **0**|**1**::
1070     When this option is set, Tor connects to hidden services
1071     **non-anonymously**.  This option also disables client connections to
1072     non-hidden-service hostnames through Tor. It **must only** be used when
1073     running a tor2web Hidden Service web proxy.
1074     To enable this option the compile time flag --enable-tor2webmode must be
1075     specified. (Default: 0)
1076
1077 **UseMicrodescriptors** **0**|**1**|**auto**::
1078     Microdescriptors are a smaller version of the information that Tor needs
1079     in order to build its circuits.  Using microdescriptors makes Tor clients
1080     download less directory information, thus saving bandwidth.  Directory
1081     caches need to fetch regular descriptors and microdescriptors, so this
1082     option doesn't save any bandwidth for them.  If this option is set to
1083     "auto" (recommended) then it is on for all clients that do not set
1084     FetchUselessDescriptors. (Default: auto)
1085
1086 SERVER OPTIONS
1087 --------------
1088
1089 The following options are useful only for servers (that is, if ORPort
1090 is non-zero):
1091
1092 **Address** __address__::
1093     The IP address or fully qualified domain name of this server (e.g.
1094     moria.mit.edu). You can leave this unset, and Tor will guess your IP
1095     address.  This IP address is the one used to tell clients and other
1096     servers where to find your Tor server; it doesn't affect the IP that your
1097     Tor client binds to.  To bind to a different address, use the
1098     *ListenAddress and OutboundBindAddress options.
1099
1100 **AllowSingleHopExits** **0**|**1**::
1101     This option controls whether clients can use this server as a single hop
1102     proxy. If set to 1, clients can use this server as an exit even if it is
1103     the only hop in the circuit.  Note that most clients will refuse to use
1104     servers that set this option, since most clients have
1105     ExcludeSingleHopRelays set.  (Default: 0)
1106
1107 **AssumeReachable** **0**|**1**::
1108     This option is used when bootstrapping a new Tor network. If set to 1,
1109     don't do self-reachability testing; just upload your server descriptor
1110     immediately. If **AuthoritativeDirectory** is also set, this option
1111     instructs the dirserver to bypass remote reachability testing too and list
1112     all connected servers as running.
1113
1114 **BridgeRelay** **0**|**1**::
1115     Sets the relay to act as a "bridge" with respect to relaying connections
1116     from bridge users to the Tor network. It mainly causes Tor to publish a
1117     server descriptor to the bridge database, rather than publishing a relay
1118     descriptor to the public directory authorities.
1119
1120 **ContactInfo** __email_address__::
1121     Administrative contact information for server. This line might get picked
1122     up by spam harvesters, so you may want to obscure the fact that it's an
1123     email address.
1124
1125 **ExitPolicy** __policy__,__policy__,__...__::
1126     Set an exit policy for this server. Each policy is of the form
1127     "**accept**|**reject** __ADDR__[/__MASK__][:__PORT__]". If /__MASK__ is
1128     omitted then this policy just applies to the host given. Instead of giving
1129     a host or network you can also use "\*" to denote the universe (0.0.0.0/0).
1130     __PORT__ can be a single port number, an interval of ports
1131     "__FROM_PORT__-__TO_PORT__", or "\*". If __PORT__ is omitted, that means
1132     "\*". +
1133  +
1134     For example, "accept 18.7.22.69:\*,reject 18.0.0.0/8:\*,accept \*:\*" would
1135     reject any traffic destined for MIT except for web.mit.edu, and accept
1136     anything else. +
1137  +
1138     To specify all internal and link-local networks (including 0.0.0.0/8,
1139     169.254.0.0/16,    127.0.0.0/8,    192.168.0.0/16, 10.0.0.0/8, and
1140     172.16.0.0/12), you can use the "private" alias instead of an address.
1141     These addresses are rejected by default (at the beginning of your exit
1142     policy), along with your public IP address, unless you set the
1143     ExitPolicyRejectPrivate config option to 0. For example, once you've done
1144     that, you could allow HTTP to 127.0.0.1 and block all other connections to
1145     internal networks with "accept 127.0.0.1:80,reject private:\*", though that
1146     may also allow connections to your own computer that are addressed to its
1147     public (external) IP address. See RFC 1918 and RFC 3330 for more details
1148     about internal and reserved IP address space. +
1149  +
1150     This directive can be specified multiple times so you don't have to put it
1151     all on one line. +
1152  +
1153     Policies are considered first to last, and the first match wins. If you
1154     want to \_replace_ the default exit policy, end your exit policy with
1155     either a reject \*:* or an accept \*:*. Otherwise, you're \_augmenting_
1156     (prepending to) the default exit policy. The default exit policy is: +
1157
1158        reject *:25
1159        reject *:119
1160        reject *:135-139
1161        reject *:445
1162        reject *:563
1163        reject *:1214
1164        reject *:4661-4666
1165        reject *:6346-6429
1166        reject *:6699
1167        reject *:6881-6999
1168        accept *:*
1169
1170 **ExitPolicyRejectPrivate** **0**|**1**::
1171     Reject all private (local) networks, along with your own public IP address,
1172     at the beginning of your exit policy. See above entry on ExitPolicy.
1173     (Default: 1)
1174
1175 **MaxOnionsPending** __NUM__::
1176     If you have more than this number of onionskins queued for decrypt, reject
1177     new ones. (Default: 100)
1178
1179 **MyFamily** __node__,__node__,__...__::
1180     Declare that this Tor server is controlled or administered by a group or
1181     organization identical or similar to that of the other servers, defined by
1182     their identity fingerprints or nicknames. When two servers both declare
1183     that they are in the same \'family', Tor clients will not use them in the
1184     same circuit. (Each server only needs to list the other servers in its
1185     family; it doesn't need to list itself, but it won't hurt.) Do not list
1186     any bridge relay as it would compromise its concealment.
1187
1188 **Nickname** __name__::
1189     Set the server's nickname to \'name'. Nicknames must be between 1 and 19
1190     characters inclusive, and must contain only the characters [a-zA-Z0-9].
1191
1192 **NumCPUs** __num__::
1193     How many processes to use at once for decrypting onionskins and other
1194     parallelizable operations.  If this is set to 0, Tor will try to detect
1195     how many CPUs you have, defaulting to 1 if it can't tell.  (Default: 0)
1196
1197 **ORPort** __PORT__|**auto**::
1198     Advertise this port to listen for connections from Tor clients and
1199     servers.  This option is required to be a Tor server.
1200     Set it to "auto" to have Tor pick a port for you. (Default: 0).
1201
1202 **ORListenAddress** __IP__[:__PORT__]::
1203     Bind to this IP address to listen for connections from Tor clients and
1204     servers. If you specify a port, bind to this port rather than the one
1205     specified in ORPort. (Default: 0.0.0.0) This directive can be specified
1206     multiple times to bind to multiple addresses/ports.
1207
1208 **PortForwarding** **0**|**1**::
1209     Attempt to automatically forward the DirPort and ORPort on a NAT router
1210     connecting this Tor server to the Internet. If set, Tor will try both
1211     NAT-PMP (common on Apple routers) and UPnP (common on routers from other
1212     manufacturers). (Default: 0)
1213
1214 **PortForwardingHelper** __filename__|__pathname__::
1215     If PortForwarding is set, use this executable to configure the forwarding.
1216     If set to a filename, the system path will be searched for the executable.
1217     If set to a path, only the specified path will be executed.
1218     (Default: tor-fw-helper)
1219
1220 **PublishServerDescriptor** **0**|**1**|**v1**|**v2**|**v3**|**bridge**,**...**::
1221     This option specifies which descriptors Tor will publish when acting as
1222     a relay. You can
1223     choose multiple arguments, separated by commas.
1224  +
1225     If this option is set to 0, Tor will not publish its
1226     descriptors to any directories. (This is useful if you're testing
1227     out your server, or if you're using a Tor controller that handles directory
1228     publishing for you.) Otherwise, Tor will publish its descriptors of all
1229     type(s) specified. The default is "1",
1230     which means "if running as a server, publish the
1231     appropriate descriptors to the authorities".
1232
1233 **ShutdownWaitLength** __NUM__::
1234     When we get a SIGINT and we're a server, we begin shutting down:
1235     we close listeners and start refusing new circuits. After **NUM**
1236     seconds, we exit. If we get a second SIGINT, we exit immedi-
1237     ately. (Default: 30 seconds)
1238
1239 **HeartbeatPeriod**  __N__ **minutes**|**hours**|**days**|**weeks**::
1240     Log a heartbeat message every **HeartbeatPeriod** seconds. This is
1241     a log level __info__ message, designed to let you know your Tor
1242     server is still alive and doing useful things. Settings this
1243     to 0 will disable the heartbeat. (Default: 6 hours)
1244
1245 **AccountingMax** __N__ **bytes**|**KB**|**MB**|**GB**|**TB**::
1246     Never send more than the specified number of bytes in a given accounting
1247     period, or receive more than that number in the period. For example, with
1248     AccountingMax set to 1 GB, a server could send 900 MB and receive 800 MB
1249     and continue running. It will only hibernate once one of the two reaches 1
1250     GB. When the number of bytes gets low, Tor will stop accepting new
1251     connections and circuits.  When the number of bytes
1252     is exhausted, Tor will hibernate until some
1253     time in the next accounting period. To prevent all servers from waking at
1254     the same time, Tor will also wait until a random point in each period
1255     before waking up. If you have bandwidth cost issues, enabling hibernation
1256     is preferable to setting a low bandwidth, since it provides users with a
1257     collection of fast servers that are up some of the time, which is more
1258     useful than a set of slow servers that are always "available".
1259
1260 **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__::
1261     Specify how long accounting periods last. If **month** is given, each
1262     accounting period runs from the time __HH:MM__ on the __dayth__ day of one
1263     month to the same day and time of the next. (The day must be between 1 and
1264     28.) If **week** is given, each accounting period runs from the time __HH:MM__
1265     of the __dayth__ day of one week to the same day and time of the next week,
1266     with Monday as day 1 and Sunday as day 7. If **day** is given, each
1267     accounting period runs from the time __HH:MM__ each day to the same time on
1268     the next day. All times are local, and given in 24-hour time. (Defaults to
1269     "month 1 0:00".)
1270
1271 **RefuseUnknownExits** **0**|**1**|**auto**::
1272     Prevent nodes that don't appear in the consensus from exiting using this
1273     relay.  If the option is 1, we always block exit attempts from such
1274     nodes; if it's 0, we never do, and if the option is "auto", then we do
1275     whatever the authorities suggest in the consensus. (Defaults to auto.)
1276
1277 **ServerDNSResolvConfFile** __filename__::
1278     Overrides the default DNS configuration with the configuration in
1279     __filename__. The file format is the same as the standard Unix
1280     "**resolv.conf**" file (7). This option, like all other ServerDNS options,
1281     only affects name lookups that your server does on behalf of clients.
1282     (Defaults to use the system DNS configuration.)
1283
1284 **ServerDNSAllowBrokenConfig** **0**|**1**::
1285     If this option is false, Tor exits immediately if there are problems
1286     parsing the system DNS configuration or connecting to nameservers.
1287     Otherwise, Tor continues to periodically retry the system nameservers until
1288     it eventually succeeds. (Defaults to "1".)
1289
1290 **ServerDNSSearchDomains** **0**|**1**::
1291     If set to 1, then we will search for addresses in the local search domain.
1292     For example, if this system is configured to believe it is in
1293     "example.com", and a client tries to connect to "www", the client will be
1294     connected to "www.example.com". This option only affects name lookups that
1295     your server does on behalf of clients. (Defaults to "0".)
1296
1297 **ServerDNSDetectHijacking** **0**|**1**::
1298     When this option is set to 1, we will test periodically to determine
1299     whether our local nameservers have been configured to hijack failing DNS
1300     requests (usually to an advertising site). If they are, we will attempt to
1301     correct this. This option only affects name lookups that your server does
1302     on behalf of clients. (Defaults to "1".)
1303
1304 **ServerDNSTestAddresses** __address__,__address__,__...__::
1305     When we're detecting DNS hijacking, make sure that these __valid__ addresses
1306     aren't getting redirected. If they are, then our DNS is completely useless,
1307     and we'll reset our exit policy to "reject *:*". This option only affects
1308     name lookups that your server does on behalf of clients. (Defaults to
1309     "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org".)
1310
1311 **ServerDNSAllowNonRFC953Hostnames** **0**|**1**::
1312     When this option is disabled, Tor does not try to resolve hostnames
1313     containing illegal characters (like @ and :) rather than sending them to an
1314     exit node to be resolved. This helps trap accidental attempts to resolve
1315     URLs and so on. This option only affects name lookups that your server does
1316     on behalf of clients. (Default: 0)
1317
1318 **BridgeRecordUsageByCountry** **0**|**1**::
1319     When this option is enabled and BridgeRelay is also enabled, and we have
1320     GeoIP data, Tor keeps a keep a per-country count of how many client
1321     addresses have contacted it so that it can help the bridge authority guess
1322     which countries have blocked access to it. (Default: 1)
1323
1324 **ServerDNSRandomizeCase** **0**|**1**::
1325     When this option is set, Tor sets the case of each character randomly in
1326     outgoing DNS requests, and makes sure that the case matches in DNS replies.
1327     This so-called "0x20 hack" helps resist some types of DNS poisoning attack.
1328     For more information, see "Increased DNS Forgery Resistance through
1329     0x20-Bit Encoding". This option only affects name lookups that your server
1330     does on behalf of clients. (Default: 1)
1331
1332 **GeoIPFile** __filename__::
1333     A filename containing GeoIP data, for use with BridgeRecordUsageByCountry.
1334
1335 **CellStatistics** **0**|**1**::
1336     When this option is enabled, Tor writes statistics on the mean time that
1337     cells spend in circuit queues to disk every 24 hours. (Default: 0)
1338
1339 **DirReqStatistics** **0**|**1**::
1340     When this option is enabled, Tor writes statistics on the number and
1341     response time of network status requests to disk every 24 hours.
1342     (Default: 0)
1343
1344 **EntryStatistics** **0**|**1**::
1345     When this option is enabled, Tor writes statistics on the number of
1346     directly connecting clients to disk every 24 hours. (Default: 0)
1347
1348 **ExitPortStatistics** **0**|**1**::
1349     When this option is enabled, Tor writes statistics on the number of relayed
1350     bytes and opened stream per exit port to disk every 24 hours. (Default: 0)
1351
1352 **ConnDirectionStatistics** **0**|**1**::
1353     When this option is enabled, Tor writes statistics on the bidirectional use
1354     of connections to disk every 24 hours. (Default: 0)
1355
1356 **ExtraInfoStatistics** **0**|**1**::
1357     When this option is enabled, Tor includes previously gathered statistics in
1358     its extra-info documents that it uploads to the directory authorities.
1359     (Default: 0)
1360
1361 DIRECTORY SERVER OPTIONS
1362 ------------------------
1363
1364 The following options are useful only for directory servers (that is,
1365 if DirPort is non-zero):
1366
1367 **AuthoritativeDirectory** **0**|**1**::
1368     When this option is set to 1, Tor operates as an authoritative directory
1369     server. Instead of caching the directory, it generates its own list of
1370     good servers, signs it, and sends that to the clients. Unless the clients
1371     already have you listed as a trusted directory, you probably do not want
1372     to set this option. Please coordinate with the other admins at
1373     tor-ops@torproject.org if you think you should be a directory.
1374
1375 **DirPortFrontPage** __FILENAME__::
1376     When this option is set, it takes an HTML file and publishes it as "/" on
1377     the DirPort. Now relay operators can provide a disclaimer without needing
1378     to set up a separate webserver. There's a sample disclaimer in
1379     contrib/tor-exit-notice.html.
1380
1381 **V1AuthoritativeDirectory** **0**|**1**::
1382     When this option is set in addition to **AuthoritativeDirectory**, Tor
1383     generates version 1 directory and running-routers documents (for legacy
1384     Tor clients up to 0.1.0.x).
1385
1386 **V2AuthoritativeDirectory** **0**|**1**::
1387     When this option is set in addition to **AuthoritativeDirectory**, Tor
1388     generates version 2 network statuses and serves descriptors, etc as
1389     described in doc/spec/dir-spec-v2.txt (for Tor clients and servers running
1390     0.1.1.x and 0.1.2.x).
1391
1392 **V3AuthoritativeDirectory** **0**|**1**::
1393     When this option is set in addition to **AuthoritativeDirectory**, Tor
1394     generates version 3 network statuses and serves descriptors, etc as
1395     described in doc/spec/dir-spec.txt (for Tor clients and servers running at
1396     least 0.2.0.x).
1397
1398 **VersioningAuthoritativeDirectory** **0**|**1**::
1399     When this option is set to 1, Tor adds information on which versions of
1400     Tor are still believed safe for use to the published directory. Each
1401     version 1 authority is automatically a versioning authority; version 2
1402     authorities provide this service optionally. See **RecommendedVersions**,
1403     **RecommendedClientVersions**, and **RecommendedServerVersions**.
1404
1405 **NamingAuthoritativeDirectory** **0**|**1**::
1406     When this option is set to 1, then the server advertises that it has
1407     opinions about nickname-to-fingerprint bindings. It will include these
1408     opinions in its published network-status pages, by listing servers with
1409     the flag "Named" if a correct binding between that nickname and fingerprint
1410     has been registered with the dirserver. Naming dirservers will refuse to
1411     accept or publish descriptors that contradict a registered binding. See
1412     **approved-routers** in the **FILES** section below.
1413
1414 **HSAuthoritativeDir** **0**|**1**::
1415     When this option is set in addition to **AuthoritativeDirectory**, Tor also
1416     accepts and serves v0 hidden service descriptors,
1417     which are produced and used by Tor 0.2.1.x and older. (Default: 0)
1418
1419 **HidServDirectoryV2** **0**|**1**::
1420     When this option is set, Tor accepts and serves v2 hidden service
1421     descriptors. Setting DirPort is not required for this, because clients
1422     connect via the ORPort by default. (Default: 1)
1423
1424 **BridgeAuthoritativeDir** **0**|**1**::
1425     When this option is set in addition to **AuthoritativeDirectory**, Tor
1426     accepts and serves router descriptors, but it caches and serves the main
1427     networkstatus documents rather than generating its own. (Default: 0)
1428
1429 **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
1430     Minimum uptime of a v2 hidden service directory to be accepted as such by
1431     authoritative directories. (Default: 25 hours)
1432
1433 **DirPort** __PORT__|**auto**::
1434     If this option is nonzero, advertise the directory service on this port.
1435     Set it to "auto" to have Tor pick a port for you.  (Default: 0)
1436
1437 **DirListenAddress** __IP__[:__PORT__]::
1438     Bind the directory service to this address. If you specify a port, bind to
1439     this port rather than the one specified in DirPort.  (Default: 0.0.0.0)
1440     This directive can be specified multiple times  to bind to multiple
1441     addresses/ports.
1442
1443 **DirPolicy** __policy__,__policy__,__...__::
1444     Set an entrance policy for this server, to limit who can connect to the
1445     directory ports. The policies have the same form as exit policies above.
1446
1447 **FetchV2Networkstatus** **0**|**1**::
1448     If set, we try to fetch the (obsolete, unused) version 2 network status
1449     consensus documents from the directory authorities. No currently
1450     supported Tor version uses them.  (Default: 0.)
1451
1452
1453 DIRECTORY AUTHORITY SERVER OPTIONS
1454 ----------------------------------
1455
1456 **RecommendedVersions** __STRING__::
1457     STRING is a comma-separated list of Tor versions currently believed to be
1458     safe. The list is included in each directory, and nodes which pull down the
1459     directory learn whether they need to upgrade. This option can appear
1460     multiple times: the values from multiple lines are spliced together. When
1461     this is set then **VersioningAuthoritativeDirectory** should be set too.
1462
1463 **RecommendedClientVersions** __STRING__::
1464     STRING is a comma-separated list of Tor versions currently believed to be
1465     safe for clients to use. This information is included in version 2
1466     directories. If this is not set then the value of **RecommendedVersions**
1467     is used. When this is set then **VersioningAuthoritativeDirectory** should
1468     be set too.
1469
1470 **RecommendedServerVersions** __STRING__::
1471     STRING is a comma-separated list of Tor versions currently believed to be
1472     safe for servers to use. This information is included in version 2
1473     directories. If this is not set then the value of **RecommendedVersions**
1474     is used. When this is set then **VersioningAuthoritativeDirectory** should
1475     be set too.
1476
1477 **ConsensusParams** __STRING__::
1478     STRING is a space-separated list of key=value pairs that Tor will include
1479     in the "params" line of its networkstatus vote.
1480
1481 **DirAllowPrivateAddresses** **0**|**1**::
1482     If set to 1, Tor will accept router descriptors with arbitrary "Address"
1483     elements. Otherwise, if the address is not an IP address or is a private IP
1484     address, it will reject the router descriptor. Defaults to 0.
1485
1486 **AuthDirBadDir** __AddressPattern...__::
1487     Authoritative directories only. A set of address patterns for servers that
1488     will be listed as bad directories in any network status document this
1489     authority publishes, if **AuthDirListBadDirs** is set.
1490
1491 **AuthDirBadExit** __AddressPattern...__::
1492     Authoritative directories only. A set of address patterns for servers that
1493     will be listed as bad exits in any network status document this authority
1494     publishes, if **AuthDirListBadExits** is set.
1495
1496 **AuthDirInvalid** __AddressPattern...__::
1497     Authoritative directories only. A set of address patterns for servers that
1498     will never be listed as "valid" in any network status document that this
1499     authority publishes.
1500
1501 **AuthDirReject** __AddressPattern__...::
1502     Authoritative directories only. A set of address patterns for servers that
1503     will never be listed at all in any network status document that this
1504     authority publishes, or accepted as an OR address in any descriptor
1505     submitted for publication by this authority.
1506
1507 **AuthDirBadDirCCs** __CC__,... +
1508
1509 **AuthDirBadExitCCs** __CC__,... +
1510
1511 **AuthDirInvalidCCs** __CC__,... +
1512
1513 **AuthDirRejectCCs** __CC__,...::
1514     Authoritative directories only. These options contain a comma-separated
1515     list of country codes such that any server in one of those country codes
1516     will be marked as a bad directory/bad exit/invalid for use, or rejected
1517     entirely.
1518
1519 **AuthDirListBadDirs** **0**|**1**::
1520     Authoritative directories only. If set to 1, this directory has some
1521     opinion about which nodes are unsuitable as directory caches. (Do not set
1522     this to 1 unless you plan to list non-functioning directories as bad;
1523     otherwise, you are effectively voting in favor  of every declared
1524     directory.)
1525
1526 **AuthDirListBadExits** **0**|**1**::
1527     Authoritative directories only. If set to 1, this directory has some
1528     opinion about which nodes are unsuitable as exit nodes. (Do not set this to
1529     1 unless you plan to list non-functioning exits as bad; otherwise, you are
1530     effectively voting in favor of every declared exit as an exit.)
1531
1532 **AuthDirRejectUnlisted** **0**|**1**::
1533     Authoritative directories only. If set to 1, the directory server rejects
1534     all uploaded server descriptors that aren't explicitly listed in the
1535     fingerprints file. This acts as a "panic button" if we get hit with a Sybil
1536     attack. (Default: 0)
1537
1538 **AuthDirMaxServersPerAddr** __NUM__::
1539     Authoritative directories only. The maximum number of servers that we will
1540     list as acceptable on a single IP address. Set this to "0" for "no limit".
1541     (Default: 2)
1542
1543 **AuthDirMaxServersPerAuthAddr** __NUM__::
1544     Authoritative directories only. Like AuthDirMaxServersPerAddr, but applies
1545     to addresses shared with directory authorities. (Default: 5)
1546
1547 **AuthDirFastGuarantee** __N__ **bytes**|**KB**|**MB**|**GB**::
1548     Authoritative directories only. If non-zero, always vote the
1549     Fast flag for any relay advertising this amount of capacity or
1550     more. (Default: 100 KB)
1551
1552 **AuthDirGuardBWGuarantee** __N__ **bytes**|**KB**|**MB**|**GB**::
1553     Authoritative directories only. If non-zero, this advertised capacity
1554     or more is always sufficient to satisfy the bandwidth requirement
1555     for the Guard flag. (Default: 250 KB)
1556
1557 **BridgePassword** __Password__::
1558     If set, contains an HTTP authenticator that tells a bridge authority to
1559     serve all requested bridge information. Used by the (only partially
1560     implemented) "bridge community" design, where a community of bridge
1561     relay operators all use an alternate bridge directory authority,
1562     and their target user audience can periodically fetch the list of
1563     available community bridges to stay up-to-date. (Default: not set.)
1564
1565 **V3AuthVotingInterval** __N__ **minutes**|**hours**::
1566     V3 authoritative directories only. Configures the server's preferred voting
1567     interval. Note that voting will __actually__ happen at an interval chosen
1568     by consensus from all the authorities' preferred intervals. This time
1569     SHOULD divide evenly into a day. (Default: 1 hour)
1570
1571 **V3AuthVoteDelay** __N__ **minutes**|**hours**::
1572     V3 authoritative directories only. Configures the server's preferred delay
1573     between publishing its vote and assuming it has all the votes from all the
1574     other authorities. Note that the actual time used is not the server's
1575     preferred time, but the consensus of all preferences. (Default: 5 minutes.)
1576
1577 **V3AuthDistDelay** __N__ **minutes**|**hours**::
1578     V3 authoritative directories only. Configures the server's preferred  delay
1579     between publishing its consensus and signature and assuming  it has all the
1580     signatures from all the other authorities. Note that the actual time used
1581     is not the server's preferred time,  but the consensus of all preferences.
1582     (Default: 5 minutes.)
1583
1584 **V3AuthNIntervalsValid** __NUM__::
1585     V3 authoritative directories only. Configures the number of VotingIntervals
1586     for which each consensus should be valid for. Choosing high numbers
1587     increases network partitioning risks; choosing low numbers increases
1588     directory traffic. Note that the actual number of intervals used is not the
1589     server's preferred number, but the consensus of all preferences. Must be at
1590     least 2. (Default: 3.)
1591
1592 **V3BandwidthsFile** __FILENAME__::
1593     V3 authoritative directories only. Configures the location of the
1594     bandiwdth-authority generated file storing information on relays' measured
1595     bandwidth capacities. (Default: unset.)
1596
1597 **V3AuthUseLegacyKey** **0**|**1**::
1598     If set, the directory authority will sign consensuses not only with its
1599     own signing key, but also with a "legacy" key and certificate with a
1600     different identity.  This feature is used to migrate directory authority
1601     keys in the event of a compromise.  (Default: 0.)
1602
1603 **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
1604     Tells an authority, or other node tracking node reliability and history,
1605     that fine-grained information about nodes can be discarded when it hasn't
1606     changed for a given amount of time.  (Default: 24 hours)
1607
1608 **VoteOnHidServDirectoriesV2** **0**|**1**::
1609     When this option is set in addition to **AuthoritativeDirectory**, Tor
1610     votes on whether to accept relays as hidden service directories.
1611     (Default: 1)
1612
1613 HIDDEN SERVICE OPTIONS
1614 ----------------------
1615
1616 The following options are used to configure a hidden service.
1617
1618 **HiddenServiceDir** __DIRECTORY__::
1619     Store data files for a hidden service in DIRECTORY. Every hidden service
1620     must have a separate directory. You may use this option  multiple times to
1621     specify multiple services. DIRECTORY must be an existing directory.
1622
1623 **HiddenServicePort** __VIRTPORT__ [__TARGET__]::
1624     Configure a virtual port VIRTPORT for a hidden service. You may use this
1625     option multiple times; each time applies to the service using the most
1626     recent hiddenservicedir. By default, this option maps the virtual port to
1627     the same port on 127.0.0.1. You may override the target port, address, or
1628     both by specifying a target of addr, port, or addr:port. You may also have
1629     multiple lines with  the same VIRTPORT: when a user connects to that
1630     VIRTPORT, one of the TARGETs from those lines will be chosen at random.
1631
1632 **PublishHidServDescriptors** **0**|**1**::
1633     If set to 0, Tor will run any hidden services you configure, but it won't
1634     advertise them to the rendezvous directory. This option is only useful if
1635     you're using a Tor controller that handles hidserv publishing for you.
1636     (Default: 1)
1637
1638 **HiddenServiceVersion** __version__,__version__,__...__::
1639     A list of rendezvous service descriptor versions to publish for the hidden
1640     service. Currently, only version 2 is supported. (Default: 2)
1641
1642 **HiddenServiceAuthorizeClient** __auth-type__ __client-name__,__client-name__,__...__::
1643     If configured, the hidden service is accessible for authorized clients
1644     only. The auth-type can either be \'basic' for a general-purpose
1645     authorization protocol or \'stealth' for a less scalable protocol that also
1646     hides service activity from unauthorized clients. Only clients that are
1647     listed here are authorized to access the hidden service. Valid client names
1648     are 1 to 19 characters  long and only use characters in A-Za-z0-9+-_ (no
1649     spaces). If this option is set, the hidden service is not accessible for
1650     clients without authorization any more. Generated authorization data can be
1651     found in the hostname file. Clients need to put this authorization data in
1652     their configuration file using **HidServAuth**.
1653
1654 **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**::
1655     Every time the specified period elapses, Tor uploads any rendezvous
1656     service descriptors to the directory servers. This information  is also
1657     uploaded whenever it changes. (Default: 1 hour)
1658
1659 TESTING NETWORK OPTIONS
1660 -----------------------
1661
1662 The following options are used for running a testing Tor network.
1663
1664 **TestingTorNetwork** **0**|**1**::
1665     If set to 1, Tor adjusts default values of the configuration options below,
1666     so that it is easier to set up a testing Tor network. May only be set if
1667     non-default set of DirServers is set. Cannot be unset while Tor is running.
1668     (Default: 0) +
1669
1670        ServerDNSAllowBrokenConfig 1
1671        DirAllowPrivateAddresses 1
1672        EnforceDistinctSubnets 0
1673        AssumeReachable 1
1674        AuthDirMaxServersPerAddr 0
1675        AuthDirMaxServersPerAuthAddr 0
1676        ClientDNSRejectInternalAddresses 0
1677        ClientRejectInternalAddresses 0
1678        CountPrivateBandwidth 1
1679        ExitPolicyRejectPrivate 0
1680        V3AuthVotingInterval 5 minutes
1681        V3AuthVoteDelay 20 seconds
1682        V3AuthDistDelay 20 seconds
1683        MinUptimeHidServDirectoryV2 0 seconds
1684        TestingV3AuthInitialVotingInterval 5 minutes
1685        TestingV3AuthInitialVoteDelay 20 seconds
1686        TestingV3AuthInitialDistDelay 20 seconds
1687        TestingAuthDirTimeToLearnReachability 0 minutes
1688        TestingEstimatedDescriptorPropagationTime 0 minutes
1689
1690 **TestingV3AuthInitialVotingInterval** __N__ **minutes**|**hours**::
1691     Like V3AuthVotingInterval, but for initial voting interval before the first
1692     consensus has been created. Changing this requires that
1693     **TestingTorNetwork** is set. (Default: 30 minutes)
1694
1695 **TestingV3AuthInitialVoteDelay** __N__ **minutes**|**hours**::
1696     Like TestingV3AuthInitialVoteDelay, but for initial voting interval before
1697     the first consensus has been created. Changing this requires that
1698     **TestingTorNetwork** is set. (Default: 5 minutes)
1699
1700 **TestingV3AuthInitialDistDelay** __N__ **minutes**|**hours**::
1701     Like TestingV3AuthInitialDistDelay, but for initial voting interval before
1702     the first consensus has been created. Changing this requires that
1703     **TestingTorNetwork** is set. (Default: 5 minutes)
1704
1705 **TestingAuthDirTimeToLearnReachability** __N__ **minutes**|**hours**::
1706     After starting as an authority, do not make claims about whether routers
1707     are Running until this much time has passed. Changing this requires
1708     that **TestingTorNetwork** is set.  (Default: 30 minutes)
1709
1710 **TestingEstimatedDescriptorPropagationTime** __N__ **minutes**|**hours**::
1711     Clients try downloading router descriptors from directory caches after this
1712     time. Changing this requires that **TestingTorNetwork** is set. (Default:
1713     10 minutes)
1714
1715 SIGNALS
1716 -------
1717
1718 Tor catches the following signals:
1719
1720 **SIGTERM**::
1721     Tor will catch this, clean up and sync to disk if necessary, and exit.
1722
1723 **SIGINT**::
1724     Tor clients behave as with SIGTERM; but Tor servers will do a controlled
1725     slow shutdown, closing listeners and waiting 30 seconds before exiting.
1726     (The delay can be configured with the ShutdownWaitLength config option.)
1727
1728 **SIGHUP**::
1729     The signal instructs Tor to reload its configuration (including closing and
1730     reopening logs), and kill and restart its helper processes if applicable.
1731
1732 **SIGUSR1**::
1733     Log statistics about current connections, past connections, and throughput.
1734
1735 **SIGUSR2**::
1736     Switch all logs to loglevel debug. You can go back to the old loglevels by
1737     sending a SIGHUP.
1738
1739 **SIGCHLD**::
1740     Tor receives this signal when one of its helper processes has exited, so it
1741     can clean up.
1742
1743 **SIGPIPE**::
1744     Tor catches this signal and ignores it.
1745
1746 **SIGXFSZ**::
1747     If this signal exists on your platform, Tor catches and ignores it.
1748
1749 FILES
1750 -----
1751
1752 **@CONFDIR@/torrc**::
1753     The configuration file, which contains "option value" pairs.
1754
1755 **@LOCALSTATEDIR@/lib/tor/**::
1756     The tor process stores keys and other data here.
1757
1758 __DataDirectory__**/cached-status/**::
1759     The most recently downloaded network status document for each authority.
1760     Each file holds one such document; the filenames are the hexadecimal
1761     identity key fingerprints of the directory authorities.
1762
1763 __DataDirectory__**/cached-descriptors** and **cached-descriptors.new**::
1764     These files hold downloaded router statuses. Some routers may appear more
1765     than once; if so, the most recently published descriptor is used. Lines
1766     beginning with @-signs are annotations that contain more information about
1767     a given router. The ".new" file is an append-only journal; when it gets
1768     too large, all entries are merged into a new cached-descriptors file.
1769
1770 __DataDirectory__**/cached-routers** and **cached-routers.new**::
1771     Obsolete versions of cached-descriptors and cached-descriptors.new. When
1772     Tor can't find the newer files, it looks here instead.
1773
1774 __DataDirectory__**/state**::
1775     A set of persistent key-value mappings. These are documented in
1776     the file. These include:
1777             - The current entry guards and their status.
1778             - The current bandwidth accounting values (unused so far; see
1779             below).
1780             - When the file was last written
1781             - What version of Tor generated the state file
1782             - A short history of bandwidth usage, as produced in the router
1783             descriptors.
1784
1785 __DataDirectory__**/bw_accounting**::
1786     Used to track bandwidth accounting values (when the current period starts
1787     and ends; how much has been read and written so far this period). This file
1788     is obsolete, and the data is now stored in the \'state' file as well. Only
1789     used when bandwidth accounting is enabled.
1790
1791 __DataDirectory__**/control_auth_cookie**::
1792     Used for cookie authentication with the controller. Location can be
1793     overridden by the CookieAuthFile config option. Regenerated on startup. See
1794     control-spec.txt for details. Only used when cookie authentication is
1795     enabled.
1796
1797 __DataDirectory__**/keys/***::
1798     Only used by servers. Holds identity keys and onion keys.
1799
1800 __DataDirectory__**/fingerprint**::
1801     Only used by servers. Holds the fingerprint of the server's identity key.
1802
1803 __DataDirectory__**/approved-routers**::
1804     Only for naming authoritative directory servers (see
1805     **NamingAuthoritativeDirectory**). This file lists nickname to identity
1806     bindings. Each line lists a nickname and a fingerprint separated by
1807     whitespace. See your **fingerprint** file in the __DataDirectory__ for an
1808     example line. If the nickname is **!reject** then descriptors from the
1809     given identity (fingerprint) are rejected by this server. If it is
1810     **!invalid** then descriptors are accepted but marked in the directory as
1811     not valid, that is, not recommended.
1812
1813 __DataDirectory__**/router-stability**::
1814     Only used by authoritative directory servers. Tracks measurements for
1815     router mean-time-between-failures so that authorities have a good idea of
1816     how to set their Stable flags.
1817
1818 __HiddenServiceDirectory__**/hostname**::
1819     The <base32-encoded-fingerprint>.onion domain name for this hidden service.
1820     If the hidden service is restricted to authorized clients only, this file
1821     also contains authorization data for all clients.
1822
1823 __HiddenServiceDirectory__**/private_key**::
1824     The private key for this hidden service.
1825
1826 __HiddenServiceDirectory__**/client_keys**::
1827     Authorization data for a hidden service that is only accessible by
1828     authorized clients.
1829
1830 SEE ALSO
1831 --------
1832 **privoxy**(1), **tsocks**(1), **torify**(1) +
1833
1834 **https://www.torproject.org/**
1835
1836
1837 BUGS
1838 ----
1839
1840 Plenty, probably. Tor is still in development. Please report them.
1841
1842 AUTHORS
1843 -------
1844 Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at alum.mit.edu].
1845