From 456be93956d1f0acfa50dc3bc19ac6e2b9d2d77a Mon Sep 17 00:00:00 2001 From: David Goulet Date: Tue, 14 Jul 2020 09:02:03 -0400 Subject: doc: Move manpages into doc/man/ Closes #40044 Signed-off-by: David Goulet --- doc/include.am | 44 +- doc/man/tor-gencert.1.txt | 92 + doc/man/tor-print-ed-signing-cert.1.txt | 38 + doc/man/tor-resolve.1.txt | 54 + doc/man/tor.1.txt | 3839 +++++++++++++++++++++++++++++++ doc/man/torify.1.txt | 40 + doc/tor-gencert.1.txt | 92 - doc/tor-print-ed-signing-cert.1.txt | 38 - doc/tor-resolve.1.txt | 54 - doc/tor.1.txt | 3839 ------------------------------- doc/torify.1.txt | 40 - 11 files changed, 4085 insertions(+), 4085 deletions(-) create mode 100644 doc/man/tor-gencert.1.txt create mode 100644 doc/man/tor-print-ed-signing-cert.1.txt create mode 100644 doc/man/tor-resolve.1.txt create mode 100644 doc/man/tor.1.txt create mode 100644 doc/man/torify.1.txt delete mode 100644 doc/tor-gencert.1.txt delete mode 100644 doc/tor-print-ed-signing-cert.1.txt delete mode 100644 doc/tor-resolve.1.txt delete mode 100644 doc/tor.1.txt delete mode 100644 doc/torify.1.txt (limited to 'doc') diff --git a/doc/include.am b/doc/include.am index 5e0c90b0cd..d3e757f3bb 100644 --- a/doc/include.am +++ b/doc/include.am @@ -12,7 +12,7 @@ # part of the source distribution, so that people without asciidoc can # just use the .1 and .html files. -all_mans = doc/tor doc/tor-gencert doc/tor-resolve doc/torify doc/tor-print-ed-signing-cert +all_mans = doc/man/tor doc/man/tor-gencert doc/man/tor-resolve doc/man/torify doc/man/tor-print-ed-signing-cert if USE_ASCIIDOC txt_in = $(all_mans:=.1.txt) @@ -76,17 +76,17 @@ $(html_in) : $(man_in) : $(AM_V_GEN)$(top_srcdir)/doc/asciidoc-helper.sh man @A2X@ $(top_srcdir)/$@ -doc/tor.1.in: doc/tor.1.txt -doc/torify.1.in: doc/torify.1.txt -doc/tor-gencert.1.in: doc/tor-gencert.1.txt -doc/tor-resolve.1.in: doc/tor-resolve.1.txt -doc/tor-print-ed-signing-cert.1.in: doc/tor-print-ed-signing-cert.1.txt +doc/man/tor.1.in: doc/man/tor.1.txt +doc/man/torify.1.in: doc/man/torify.1.txt +doc/man/tor-gencert.1.in: doc/man/tor-gencert.1.txt +doc/man/tor-resolve.1.in: doc/man/tor-resolve.1.txt +doc/man/tor-print-ed-signing-cert.1.in: doc/man/tor-print-ed-signing-cert.1.txt -doc/tor.html.in: doc/tor.1.txt -doc/torify.html.in: doc/torify.1.txt -doc/tor-gencert.html.in: doc/tor-gencert.1.txt -doc/tor-resolve.html.in: doc/tor-resolve.1.txt -doc/tor-print-ed-signing-cert.html.in: doc/tor-print-ed-signing-cert.1.txt +doc/man/tor.html.in: doc/man/tor.1.txt +doc/man/torify.html.in: doc/man/torify.1.txt +doc/man/tor-gencert.html.in: doc/man/tor-gencert.1.txt +doc/man/tor-resolve.html.in: doc/man/tor-resolve.1.txt +doc/man/tor-print-ed-signing-cert.html.in: doc/man/tor-print-ed-signing-cert.1.txt # use config.status to swap all machine-specific magic strings # in the asciidoc with their replacements. @@ -97,17 +97,17 @@ $(asciidoc_product) : fi $(AM_V_at)$(top_builddir)/config.status -q --file=$@; -doc/tor.html: doc/tor.html.in -doc/tor-gencert.html: doc/tor-gencert.html.in -doc/tor-resolve.html: doc/tor-resolve.html.in -doc/tor-print-ed-signing-cert.html: doc/tor-print-ed-signing-cert.html.in -doc/torify.html: doc/torify.html.in - -doc/tor.1: doc/tor.1.in -doc/tor-gencert.1: doc/tor-gencert.1.in -doc/tor-resolve.1: doc/tor-resolve.1.in -doc/tor-print-ed-signing-cert.1: doc/tor-print-ed-signing-cert.1.in -doc/torify.1: doc/torify.1.in +doc/man/tor.html: doc/man/tor.html.in +doc/man/tor-gencert.html: doc/man/tor-gencert.html.in +doc/man/tor-resolve.html: doc/man/tor-resolve.html.in +doc/man/tor-print-ed-signing-cert.html: doc/man/tor-print-ed-signing-cert.html.in +doc/man/torify.html: doc/man/torify.html.in + +doc/man/tor.1: doc/man/tor.1.in +doc/man/tor-gencert.1: doc/man/tor-gencert.1.in +doc/man/tor-resolve.1: doc/man/tor-resolve.1.in +doc/man/tor-print-ed-signing-cert.1: doc/man/tor-print-ed-signing-cert.1.in +doc/man/torify.1: doc/man/torify.1.in CLEANFILES+= $(asciidoc_product) DISTCLEANFILES+= $(html_in) $(man_in) diff --git a/doc/man/tor-gencert.1.txt b/doc/man/tor-gencert.1.txt new file mode 100644 index 0000000000..26f68b29c0 --- /dev/null +++ b/doc/man/tor-gencert.1.txt @@ -0,0 +1,92 @@ +// Copyright (c) The Tor Project, Inc. +// See LICENSE for licensing information +// This is an asciidoc file used to generate the manpage/html reference. +// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html +:man source: Tor +:man manual: Tor Manual +tor-gencert(1) +============== +Nick Mathewson + +NAME +---- +tor-gencert - Generate certs and keys for Tor directory authorities + +SYNOPSIS +-------- +**tor-gencert** [-h|--help] [-v] [-r|--reuse] [--create-identity-key] [-i __id_file__] [-c +__cert_file__] [-m __num__] [-a __address__:__port__] + +DESCRIPTION +----------- +**tor-gencert** generates certificates and private keys for use by Tor +directory authorities running the v3 Tor directory protocol, as used by +Tor 0.2.0 and later. If you are not running a directory authority, you +don't need to use tor-gencert. + + +Every directory authority has a long term authority __identity__ __key__ (which +is distinct from the identity key it uses as a Tor server); this key +should be kept offline in a secure location. It is used to certify +shorter-lived __signing__ __keys__, which are kept online and used by the +directory authority to sign votes and consensus documents. + + +After you use this program to generate a signing key and a certificate, +copy those files to the keys subdirectory of your Tor process, and send +Tor a SIGHUP signal. DO NOT COPY THE IDENTITY KEY. + +OPTIONS +------- +**-v**:: + Display verbose output. + +**-h** or **--help**:: + Display help text and exit. + +**-r** or **--reuse**:: + Generate a new certificate, but not a new signing key. This can be used to + change the address or lifetime associated with a given key. + +**--create-identity-key**:: + Generate a new identity key. You should only use this option the first time + you run tor-gencert; in the future, you should use the identity key that's + already there. + +**-i** __FILENAME__:: + Read the identity key from the specified file. If the file is not present + and --create-identity-key is provided, create the identity key in the + specified file. Default: "./authority_identity_key" + +**-s** __FILENAME__:: + Write the signing key to the specified file. Default: + "./authority_signing_key" + +**-c** __FILENAME__:: + Write the certificate to the specified file. Default: + "./authority_certificate" + +**-m** __NUM__:: + Number of months that the certificate should be valid. Default: 12. + +**--passphrase-fd** __FILEDES__:: + Filedescriptor to read the passphrase from. Ends at the first NUL or + newline. Default: read from the terminal. + +**-a** __address__:__port__:: + If provided, advertise the address:port combination as this authority's + preferred directory port in its certificate. If the address is a hostname, + the hostname is resolved to an IP before it's published. + +BUGS +---- +This probably doesn't run on Windows. That's not a big issue, since we don't +really want authorities to be running on Windows anyway. + +SEE ALSO +-------- +**tor**(1) + + +See also the "dir-spec.txt" file, distributed with Tor. + +AUTHORS +------- + Roger Dingledine , Nick Mathewson . diff --git a/doc/man/tor-print-ed-signing-cert.1.txt b/doc/man/tor-print-ed-signing-cert.1.txt new file mode 100644 index 0000000000..71c8b67ec4 --- /dev/null +++ b/doc/man/tor-print-ed-signing-cert.1.txt @@ -0,0 +1,38 @@ +// Copyright (c) The Tor Project, Inc. +// See LICENSE for licensing information +// This is an asciidoc file used to generate the manpage/html reference. +// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html +:man source: Tor +:man manual: Tor Manual +tor-print-ed-signing-cert(1) +============================ +Tor Project, Inc. + +NAME +---- +tor-print-ed-signing-cert - print expiration date of ed25519 signing certificate + +SYNOPSIS +-------- +**tor-print-ed-signing-cert** ____ + +DESCRIPTION +----------- +**tor-print-ed-signing-cert** is utility program for Tor relay operators to +check expiration date of ed25519 signing certificate. + +Expiration date is printed in three formats: + +* Human-readable timestamp, localized to current timezone. +* RFC 1123 timestamp (at GMT timezone). +* Unix time value. + +SEE ALSO +-------- +**tor**(1) + + +https://spec.torproject.org/cert-spec + +AUTHORS +------- +Roger Dingledine , Nick Mathewson . diff --git a/doc/man/tor-resolve.1.txt b/doc/man/tor-resolve.1.txt new file mode 100644 index 0000000000..17a77e482f --- /dev/null +++ b/doc/man/tor-resolve.1.txt @@ -0,0 +1,54 @@ +// Copyright (c) The Tor Project, Inc. +// See LICENSE for licensing information +// This is an asciidoc file used to generate the manpage/html reference. +// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html +:man source: Tor +:man manual: Tor Manual +tor-resolve(1) +============== +Peter Palfrader + +NAME +---- +tor-resolve - resolve a hostname to an IP address via tor + +SYNOPSIS +-------- +**tor-resolve** [-4|-5] [-v] [-x] [-p __socksport__] __hostname__ [__sockshost__[:__socksport__]] + +DESCRIPTION +----------- +**tor-resolve** is a simple script to connect to a SOCKS proxy that knows about +the SOCKS RESOLVE command, hand it a hostname, and return an IP address. + +By default, **tor-resolve** uses the Tor server running on 127.0.0.1 on SOCKS +port 9050. If this isn't what you want, you should specify an explicit +__sockshost__ and/or __socksport__ on the command line. + +OPTIONS +------- +**-v**:: + Display verbose output. + +**-x**:: + Perform a reverse lookup: get the PTR record for an IPv4 address. + +**-5**:: + Use the SOCKS5 protocol. (Default) + +**-4**:: + Use the SOCKS4a protocol rather than the default SOCKS5 protocol. Doesn't + support reverse DNS. + +**-p** __socksport__:: + Override the default SOCKS port without setting the hostname. + +SEE ALSO +-------- +**tor**(1), **torify**(1). + + +For protocol details, see: https://spec.torproject.org/socks-extensions + +AUTHORS +------- +Roger Dingledine , Nick Mathewson . diff --git a/doc/man/tor.1.txt b/doc/man/tor.1.txt new file mode 100644 index 0000000000..ca54fa125b --- /dev/null +++ b/doc/man/tor.1.txt @@ -0,0 +1,3839 @@ +// Copyright (c) The Tor Project, Inc. +// See LICENSE for licensing information +// This is an asciidoc file used to generate the manpage/html reference. +// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html +:man source: Tor +:man manual: Tor Manual +// compat-mode tells Asciidoctor tools to process this as legacy AsciiDoc +:compat-mode: +// attribute to make it easier to write names containing double underscores +:dbl_: __ += TOR(1) +:toc: + +== NAME + +tor - The second-generation onion router + +== SYNOPSIS + +**tor** [__OPTION__ __value__]... + +== DESCRIPTION + +Tor is a connection-oriented anonymizing communication service. Users +choose a source-routed path through a set of nodes, and negotiate a +"virtual circuit" through the network. Each node in a virtual circuit +knows its predecessor and successor nodes, but no other nodes. Traffic +flowing down the circuit is unwrapped by a symmetric key at each node, +which reveals the downstream node. + + +Basically, Tor provides a distributed network of servers or relays +("onion routers"). Users bounce their TCP streams, including web +traffic, ftp, ssh, etc., around the network, so that recipients, +observers, and even the relays themselves have difficulty tracking the +source of the stream. + +[NOTE] +By default, **tor** acts as a client only. To help the network by +providing bandwidth as a relay, change the **ORPort** configuration +option as mentioned below. Please also consult the documentation on +the Tor Project's website. + +== COMMAND-LINE OPTIONS + +Tor has a powerful command-line interface. This section lists optional +arguments you can specify at the command line using the **`tor`** +command. + +Configuration options can be specified on the command line in the +format **`--`**_OptionName_ _OptionValue_, on the command line in the +format _OptionName_ _OptionValue_, or in a configuration file. For +instance, you can tell Tor to start listening for SOCKS connections on +port 9999 by passing either **`--SocksPort 9999`** or **`SocksPort +9999`** on the command line, or by specifying **`SocksPort 9999`** in +the configuration file. On the command line, quote option values that +contain spaces. For instance, if you want Tor to log all debugging +messages to **`debug.log`**, you must specify **`--Log "debug file +debug.log"`**. + +NOTE: Configuration options on the command line override those in +configuration files. See **<>** for more information. + +The following options in this section are only recognized on the +**`tor`** command line, not in a configuration file. + +[[opt-h]] **`-h`**, **`--help`**:: + Display a short help message and exit. + +[[opt-f]] **`-f`** __FILE__:: + Specify a new configuration file to contain further Tor configuration + options, or pass *-* to make Tor read its configuration from standard + input. (Default: **`@CONFDIR@/torrc`**, or **`$HOME/.torrc`** if + that file is not found) + +[[opt-allow-missing-torrc]] **`--allow-missing-torrc`**:: + Allow the configuration file specified by **`-f`** to be missing, + if the defaults-torrc file (see below) is accessible. + +[[opt-defaults-torrc]] **`--defaults-torrc`** __FILE__:: + Specify a file in which to find default values for Tor options. The + contents of this file are overridden by those in the regular + configuration file, and by those on the command line. (Default: + **`@CONFDIR@/torrc-defaults`**.) + +[[opt-ignore-missing-torrc]] **`--ignore-missing-torrc`**:: + Specify that Tor should treat a missing torrc file as though it + were empty. Ordinarily, Tor does this for missing default torrc files, + but not for those specified on the command line. + +[[opt-hash-password]] **`--hash-password`** __PASSWORD__:: + Generate a hashed password for control port access. + +[[opt-list-fingerprint]] **`--list-fingerprint`**:: + Generate your keys and output your nickname and fingerprint. + +[[opt-verify-config]] **`--verify-config`**:: + Verify whether the configuration file is valid. + +[[opt-dump-config]] **`--dump-config`** **`short`**|**`full`**:: + Write a list of Tor's configured options to standard output. + When the `short` flag is selected, only write the options that + are different from their default values + When `full` is selected, write every option. + +[[opt-serviceinstall]] **`--service install`** [**`--options`** __command-line options__]:: + Install an instance of Tor as a Windows service, with the provided + command-line options. Current instructions can be found at + https://www.torproject.org/docs/faq#NTService + +[[opt-service]] **`--service`** **`remove`**|**`start`**|**`stop`**:: + Remove, start, or stop a configured Tor Windows service. + +[[opt-nt-service]] **`--nt-service`**:: + Used internally to implement a Windows service. + +[[opt-list-torrc-options]] **`--list-torrc-options`**:: + List all valid options. + +[[opt-list-deprecated-options]] **`--list-deprecated-options`**:: + List all valid options that are scheduled to become obsolete in a + future version. (This is a warning, not a promise.) + +[[opt-list-modules]] **`--list-modules`**:: + List whether each optional module has been compiled into Tor. + (Any module not listed is not optional in this version of Tor.) + +[[opt-version]] **`--version`**:: + Display Tor version and exit. The output is a single line of the format + "Tor version [version number]." (The version number format + is as specified in version-spec.txt.) + +[[opt-quiet]] **`--quiet`**|**`--hush`**:: + Override the default console logging behavior. By default, Tor + starts out logging messages at level "notice" and higher to the + console. It stops doing so after it parses its configuration, if + the configuration tells it to log anywhere else. These options + override the default console logging behavior. Use the + **`--hush`** option if you want Tor to log only warnings and + errors to the console, or use the **`--quiet`** option if you want + Tor not to log to the console at all. + +[[opt-keygen]] **`--keygen`** [**`--newpass`**]:: + Running **`tor --keygen`** creates a new ed25519 master identity key + for a relay, or only a fresh temporary signing key and + certificate, if you already have a master key. Optionally, you + can encrypt the master identity key with a passphrase. When Tor + asks you for a passphrase and you don't want to encrypt the master + key, just don't enter any passphrase when asked. + + + + Use the **`--newpass`** option with **`--keygen`** only when you + need to add, change, or remove a passphrase on an existing ed25519 + master identity key. You will be prompted for the old passphase + (if any), and the new passphrase (if any). ++ +[NOTE] + When generating a master key, you may want to use + **`--DataDirectory`** to control where the keys and certificates + will be stored, and **`--SigningKeyLifetime`** to control their + lifetimes. See <> to learn more about the + behavior of these options. You must have write access to the + specified DataDirectory. ++ +[normal] + To use the generated files, you must copy them to the + __DataDirectory__/**`keys`** directory of your Tor daemon, and + make sure that they are owned by the user actually running the Tor + daemon on your system. + +**`--passphrase-fd`** __FILEDES__:: + File descriptor to read the passphrase from. Note that unlike with the + tor-gencert program, the entire file contents are read and used as + the passphrase, including any trailing newlines. + If the file descriptor is not specified, the passphrase is read + from the terminal by default. + +[[opt-key-expiration]] **`--key-expiration`** [__purpose__]:: + The __purpose__ specifies which type of key certificate to determine + the expiration of. The only currently recognised __purpose__ is + "sign". + + + + Running **`tor --key-expiration sign`** will attempt to find your + signing key certificate and will output, both in the logs as well + as to stdout, the signing key certificate's expiration time in + ISO-8601 format. For example, the output sent to stdout will be + of the form: "signing-cert-expiry: 2017-07-25 08:30:15 UTC" + +[[opt-dbg]] **--dbg-**...:: + Tor may support other options beginning with the string "dbg". These + are intended for use by developers to debug and test Tor. They are + not supported or guaranteed to be stable, and you should probably + not use them. + + +[[conf-format]] +== THE CONFIGURATION FILE FORMAT + +All configuration options in a configuration are written on a single line by +default. They take the form of an option name and a value, or an option name +and a quoted value (option value or option "value"). Anything after a # +character is treated as a comment. Options are +case-insensitive. C-style escaped characters are allowed inside quoted +values. To split one configuration entry into multiple lines, use a single +backslash character (\) before the end of the line. Comments can be used in +such multiline entries, but they must start at the beginning of a line. + +Configuration options can be imported from files or folders using the %include +option with the value being a path. If the path is a file, the options from the +file will be parsed as if they were written where the %include option is. If +the path is a folder, all files on that folder will be parsed following lexical +order. Files starting with a dot are ignored. Files on subfolders are ignored. +The %include option can be used recursively. +New configuration files or directories cannot be added to already running Tor +instance if **Sandbox** is enabled. + +By default, an option on the command line overrides an option found in the +configuration file, and an option in a configuration file overrides one in +the defaults file. + +This rule is simple for options that take a single value, but it can become +complicated for options that are allowed to occur more than once: if you +specify four SocksPorts in your configuration file, and one more SocksPort on +the command line, the option on the command line will replace __all__ of the +SocksPorts in the configuration file. If this isn't what you want, prefix +the option name with a plus sign (+), and it will be appended to the previous +set of options instead. For example, setting SocksPort 9100 will use only +port 9100, but setting +SocksPort 9100 will use ports 9100 and 9050 (because +this is the default). + +Alternatively, you might want to remove every instance of an option in the +configuration file, and not replace it at all: you might want to say on the +command line that you want no SocksPorts at all. To do that, prefix the +option name with a forward slash (/). You can use the plus sign (+) and the +forward slash (/) in the configuration file and on the command line. + +== GENERAL OPTIONS + +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + +[[AccelDir]] **AccelDir** __DIR__:: + Specify this option if using dynamic hardware acceleration and the engine + implementation library resides somewhere other than the OpenSSL default. + Can not be changed while tor is running. + +[[AccelName]] **AccelName** __NAME__:: + When using OpenSSL hardware crypto acceleration attempt to load the dynamic + engine of this name. This must be used for any dynamic hardware engine. + Names can be verified with the openssl engine command. Can not be changed + while tor is running. + + + + If the engine name is prefixed with a "!", then Tor will exit if the + engine cannot be loaded. + +[[AlternateBridgeAuthority]] **AlternateBridgeAuthority** [__nickname__] [**flags**] __ipv4address__:__port__ __ fingerprint__:: +[[AlternateDirAuthority]] **AlternateDirAuthority** [__nickname__] [**flags**] __ipv4address__:__port__ __fingerprint__:: + These options behave as DirAuthority, but they replace fewer of the + default directory authorities. Using + AlternateDirAuthority replaces the default Tor directory authorities, but + leaves the default bridge authorities in + place. Similarly, + AlternateBridgeAuthority replaces the default bridge authority, + but leaves the directory authorities alone. + +[[AndroidIdentityTag]] **AndroidIdentityTag** __tag__:: + When logging to Android's logging subsystem, adds a tag to the log identity + such that log entries are marked with "Tor-__tag__". Can not be changed while + tor is running. (Default: none) + +[[AvoidDiskWrites]] **AvoidDiskWrites** **0**|**1**:: + If non-zero, try to write to disk less frequently than we would otherwise. + This is useful when running on flash memory or other media that support + only a limited number of writes. (Default: 0) + +[[BandwidthBurst]] **BandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Limit the maximum token bucket size (also known as the burst) to the given + number of bytes in each direction. (Default: 1 GByte) + +[[BandwidthRate]] **BandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + A token bucket limits the average incoming bandwidth usage on this node + to the specified number of bytes per second, and the average outgoing + bandwidth usage to that same value. If you want to run a relay in the + public network, this needs to be _at the very least_ 75 KBytes for a + relay (that is, 600 kbits) or 50 KBytes for a bridge (400 kbits) -- but of + course, more is better; we recommend at least 250 KBytes (2 mbits) if + possible. (Default: 1 GByte) + + + + Note that this option, and other bandwidth-limiting options, apply to TCP + data only: They do not count TCP headers or DNS traffic. + + + + Tor uses powers of two, not powers of ten, so 1 GByte is + 1024*1024*1024 bytes as opposed to 1 billion bytes. + + + + With this option, and in other options that take arguments in bytes, + KBytes, and so on, other formats are also supported. Notably, "KBytes" can + also be written as "kilobytes" or "kb"; "MBytes" can be written as + "megabytes" or "MB"; "kbits" can be written as "kilobits"; and so forth. + Case doesn't matter. + Tor also accepts "byte" and "bit" in the singular. + The prefixes "tera" and "T" are also recognized. + If no units are given, we default to bytes. + To avoid confusion, we recommend writing "bytes" or "bits" explicitly, + since it's easy to forget that "B" means bytes, not bits. + +[[CacheDirectory]] **CacheDirectory** __DIR__:: + Store cached directory data in DIR. Can not be changed while tor is + running. + (Default: uses the value of DataDirectory.) + +[[CacheDirectoryGroupReadable]] **CacheDirectoryGroupReadable** **0**|**1**|**auto**:: + If this option is set to 0, don't allow the filesystem group to read the + CacheDirectory. If the option is set to 1, make the CacheDirectory readable + by the default GID. If the option is "auto", then we use the + setting for DataDirectoryGroupReadable when the CacheDirectory is the + same as the DataDirectory, and 0 otherwise. (Default: auto) + +[[CircuitPriorityHalflife]] **CircuitPriorityHalflife** __NUM__:: + If this value is set, we override the default algorithm for choosing which + circuit's cell to deliver or relay next. It is delivered first to the + circuit that has the lowest weighted cell count, where cells are weighted + exponentially according to this value (in seconds). If the value is -1, it + is taken from the consensus if possible else it will fallback to the + default value of 30. Minimum: 1, Maximum: 2147483647. This can be defined + as a float value. This is an advanced option; you generally shouldn't have + to mess with it. (Default: -1) + +[[ClientTransportPlugin]] **ClientTransportPlugin** __transport__ socks4|socks5 __IP__:__PORT__:: +**ClientTransportPlugin** __transport__ exec __path-to-binary__ [options]:: + In its first form, when set along with a corresponding Bridge line, the Tor + client forwards its traffic to a SOCKS-speaking proxy on "IP:PORT". + (IPv4 addresses should written as-is; IPv6 addresses should be wrapped in + square brackets.) It's the + duty of that proxy to properly forward the traffic to the bridge. + + + + In its second form, when set along with a corresponding Bridge line, the Tor + client launches the pluggable transport proxy executable in + __path-to-binary__ using __options__ as its command-line options, and + forwards its traffic to it. It's the duty of that proxy to properly forward + the traffic to the bridge. (Default: none) + +[[ConnLimit]] **ConnLimit** __NUM__:: + The minimum number of file descriptors that must be available to the Tor + process before it will start. Tor will ask the OS for as many file + descriptors as the OS will allow (you can find this by "ulimit -H -n"). + If this number is less than ConnLimit, then Tor will refuse to start. + + + + Tor relays need thousands of sockets, to connect to every other relay. + If you are running a private bridge, you can reduce the number of sockets + that Tor uses. For example, to limit Tor to 500 sockets, run + "ulimit -n 500" in a shell. Then start tor in the same shell, with + **ConnLimit 500**. You may also need to set **DisableOOSCheck 0**. + + + + Unless you have severely limited sockets, you probably don't need to + adjust **ConnLimit** itself. It has no effect on Windows, since that + platform lacks getrlimit(). (Default: 1000) + +[[ConstrainedSockets]] **ConstrainedSockets** **0**|**1**:: + If set, Tor will tell the kernel to attempt to shrink the buffers for all + sockets to the size specified in **ConstrainedSockSize**. This is useful for + virtual servers and other environments where system level TCP buffers may + be limited. If you're on a virtual server, and you encounter the "Error + creating network socket: No buffer space available" message, you are + likely experiencing this problem. + + + + The preferred solution is to have the admin increase the buffer pool for + the host itself via /proc/sys/net/ipv4/tcp_mem or equivalent facility; + this configuration option is a second-resort. + + + + The DirPort option should also not be used if TCP buffers are scarce. The + cached directory requests consume additional sockets which exacerbates + the problem. + + + + You should **not** enable this feature unless you encounter the "no buffer + space available" issue. Reducing the TCP buffers affects window size for + the TCP stream and will reduce throughput in proportion to round trip + time on long paths. (Default: 0) + +[[ConstrainedSockSize]] **ConstrainedSockSize** __N__ **bytes**|**KBytes**:: + When **ConstrainedSockets** is enabled the receive and transmit buffers for + all sockets will be set to this limit. Must be a value between 2048 and + 262144, in 1024 byte increments. Default of 8192 is recommended. + +[[ControlPort]] **ControlPort** ['address'**:**]{empty}__port__|**unix:**__path__|**auto** [__flags__]:: + If set, Tor will accept connections on this port and allow those + connections to control the Tor process using the Tor Control Protocol + (described in control-spec.txt in + https://spec.torproject.org[torspec]). Note: unless you also + specify one or more of **HashedControlPassword** or + **CookieAuthentication**, setting this option will cause Tor to allow + any process on the local host to control it. (Setting both authentication + methods means either method is sufficient to authenticate to Tor.) This + option is required for many Tor controllers; most use the value of 9051. + If a unix domain socket is used, you may quote the path using standard + C escape sequences. You can specify this directive multiple times, to + bind to multiple address/port pairs. + Set it to "auto" to have Tor pick a port for you. (Default: 0) + + + + Recognized flags are: + **GroupWritable**;; + Unix domain sockets only: makes the socket get created as + group-writable. + **WorldWritable**;; + Unix domain sockets only: makes the socket get created as + world-writable. + **RelaxDirModeCheck**;; + Unix domain sockets only: Do not insist that the directory + that holds the socket be read-restricted. + +[[ControlPortFileGroupReadable]] **ControlPortFileGroupReadable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read the + control port file. If the option is set to 1, make the control port + file readable by the default GID. (Default: 0) + +[[ControlPortWriteToFile]] **ControlPortWriteToFile** __Path__:: + If set, Tor writes the address and port of any control port it opens to + this address. Usable by controllers to learn the actual control port + when ControlPort is set to "auto". + +[[ControlSocket]] **ControlSocket** __Path__:: + Like ControlPort, but listens on a Unix domain socket, rather than a TCP + socket. '0' disables ControlSocket. (Unix and Unix-like systems only.) + (Default: 0) + +[[ControlSocketsGroupWritable]] **ControlSocketsGroupWritable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read and + write unix sockets (e.g. ControlSocket). If the option is set to 1, make + the control socket readable and writable by the default GID. (Default: 0) + +[[CookieAuthentication]] **CookieAuthentication** **0**|**1**:: + If this option is set to 1, allow connections on the control port + when the connecting process knows the contents of a file named + "control_auth_cookie", which Tor will create in its data directory. This + authentication method should only be used on systems with good filesystem + security. (Default: 0) + +[[CookieAuthFile]] **CookieAuthFile** __Path__:: + If set, this option overrides the default location and file name + for Tor's cookie file. (See <>.) + +[[CookieAuthFileGroupReadable]] **CookieAuthFileGroupReadable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read the + cookie file. If the option is set to 1, make the cookie file readable by + the default GID. [Making the file readable by other groups is not yet + implemented; let us know if you need this for some reason.] (Default: 0) + +[[CountPrivateBandwidth]] **CountPrivateBandwidth** **0**|**1**:: + If this option is set, then Tor's rate-limiting applies not only to + remote connections, but also to connections to private addresses like + 127.0.0.1 or 10.0.0.1. This is mostly useful for debugging + rate-limiting. (Default: 0) + +[[DataDirectory]] **DataDirectory** __DIR__:: + Store working data in DIR. Can not be changed while tor is running. + (Default: ~/.tor if your home directory is not /; otherwise, + @LOCALSTATEDIR@/lib/tor. On Windows, the default is + your ApplicationData folder.) + +[[DataDirectoryGroupReadable]] **DataDirectoryGroupReadable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read the + DataDirectory. If the option is set to 1, make the DataDirectory readable + by the default GID. (Default: 0) + +[[DirAuthority]] **DirAuthority** [__nickname__] [**flags**] __ipv4address__:__dirport__ __fingerprint__:: + Use a nonstandard authoritative directory server at the provided address + and port, with the specified key fingerprint. This option can be repeated + many times, for multiple authoritative directory servers. Flags are + separated by spaces, and determine what kind of an authority this directory + is. By default, an authority is not authoritative for any directory style + or version unless an appropriate flag is given. + + + + Tor will use this authority as a bridge authoritative directory if the + "bridge" flag is set. If a flag "orport=**orport**" is given, Tor will + use the given port when opening encrypted tunnels to the dirserver. If a + flag "weight=**num**" is given, then the directory server is chosen + randomly with probability proportional to that weight (default 1.0). If a + flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority + whose v3 long-term signing key has the fingerprint **fp**. Lastly, + if an "ipv6=**[**__ipv6address__**]**:__orport__" flag is present, then + the directory authority is listening for IPv6 connections on the + indicated IPv6 address and OR Port. + + + + Tor will contact the authority at __ipv4address__ to + download directory documents. Clients always use the ORPort. Relays + usually use the DirPort, but will use the ORPort in some circumstances. + If an IPv6 ORPort is supplied, clients will also download directory + documents at the IPv6 ORPort, if they are configured to use IPv6. + + + + If no **DirAuthority** line is given, Tor will use the default directory + authorities. NOTE: this option is intended for setting up a private Tor + network with its own directory authorities. If you use it, you will be + distinguishable from other users, because you won't believe the same + authorities they do. + +[[DirAuthorityFallbackRate]] **DirAuthorityFallbackRate** __NUM__:: + When configured to use both directory authorities and fallback + directories, the directory authorities also work as fallbacks. They are + chosen with their regular weights, multiplied by this number, which + should be 1.0 or less. The default is less than 1, to reduce load on + authorities. (Default: 0.1) + +[[DisableAllSwap]] **DisableAllSwap** **0**|**1**:: + If set to 1, Tor will attempt to lock all current and future memory pages, + so that memory cannot be paged out. Windows, OS X and Solaris are currently + not supported. We believe that this feature works on modern Gnu/Linux + distributions, and that it should work on *BSD systems (untested). This + option requires that you start your Tor as root, and you should use the + **User** option to properly reduce Tor's privileges. + Can not be changed while tor is running. (Default: 0) + +[[DisableDebuggerAttachment]] **DisableDebuggerAttachment** **0**|**1**:: + If set to 1, Tor will attempt to prevent basic debugging attachment attempts + by other processes. This may also keep Tor from generating core files if + it crashes. It has no impact for users who wish to attach if they + have CAP_SYS_PTRACE or if they are root. We believe that this feature + works on modern Gnu/Linux distributions, and that it may also work on *BSD + systems (untested). Some modern Gnu/Linux systems such as Ubuntu have the + kernel.yama.ptrace_scope sysctl and by default enable it as an attempt to + limit the PTRACE scope for all user processes by default. This feature will + attempt to limit the PTRACE scope for Tor specifically - it will not attempt + to alter the system wide ptrace scope as it may not even exist. If you wish + to attach to Tor with a debugger such as gdb or strace you will want to set + this to 0 for the duration of your debugging. Normal users should leave it + on. Disabling this option while Tor is running is prohibited. (Default: 1) + +[[DisableNetwork]] **DisableNetwork** **0**|**1**:: + When this option is set, we don't listen for or accept any connections + other than controller connections, and we close (and don't reattempt) + any outbound + connections. Controllers sometimes use this option to avoid using + the network until Tor is fully configured. Tor will make still certain + network-related calls (like DNS lookups) as a part of its configuration + process, even if DisableNetwork is set. (Default: 0) + +[[ExtendByEd25519ID]] **ExtendByEd25519ID** **0**|**1**|**auto**:: + If this option is set to 1, we always try to include a relay's Ed25519 ID + when telling the preceding relay in a circuit to extend to it. + If this option is set to 0, we never include Ed25519 IDs when extending + circuits. If the option is set to "auto", we obey a + parameter in the consensus document. (Default: auto) + +[[ExtORPort]] **ExtORPort** ['address'**:**]{empty}__port__|**auto**:: + Open this port to listen for Extended ORPort connections from your + pluggable transports. + + (Default: **DataDirectory**/extended_orport_auth_cookie) + +[[ExtORPortCookieAuthFile]] **ExtORPortCookieAuthFile** __Path__:: + If set, this option overrides the default location and file name + for the Extended ORPort's cookie file -- the cookie file is needed + for pluggable transports to communicate through the Extended ORPort. + +[[ExtORPortCookieAuthFileGroupReadable]] **ExtORPortCookieAuthFileGroupReadable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read the + Extended OR Port cookie file. If the option is set to 1, make the cookie + file readable by the default GID. [Making the file readable by other + groups is not yet implemented; let us know if you need this for some + reason.] (Default: 0) + +[[FallbackDir]] **FallbackDir** __ipv4address__:__dirport__ orport=__orport__ id=__fingerprint__ [weight=__num__] [ipv6=**[**__ipv6address__**]**:__orport__]:: + When tor is unable to connect to any directory cache for directory info + (usually because it doesn't know about any yet) it tries a hard-coded + directory. Relays try one directory authority at a time. Clients try + multiple directory authorities and FallbackDirs, to avoid hangs on + startup if a hard-coded directory is down. Clients wait for a few seconds + between each attempt, and retry FallbackDirs more often than directory + authorities, to reduce the load on the directory authorities. + + + + FallbackDirs should be stable relays with stable IP addresses, ports, + and identity keys. They must have a DirPort. + + + + By default, the directory authorities are also FallbackDirs. Specifying a + FallbackDir replaces Tor's default hard-coded FallbackDirs (if any). + (See <> for an explanation of each flag.) + +[[FetchDirInfoEarly]] **FetchDirInfoEarly** **0**|**1**:: + If set to 1, Tor will always fetch directory information like other + directory caches, even if you don't meet the normal criteria for fetching + early. Normal users should leave it off. (Default: 0) + +[[FetchDirInfoExtraEarly]] **FetchDirInfoExtraEarly** **0**|**1**:: + If set to 1, Tor will fetch directory information before other directory + caches. It will attempt to download directory information closer to the + start of the consensus period. Normal users should leave it off. + (Default: 0) + +[[FetchHidServDescriptors]] **FetchHidServDescriptors** **0**|**1**:: + If set to 0, Tor will never fetch any hidden service descriptors from the + rendezvous directories. This option is only useful if you're using a Tor + controller that handles hidden service fetches for you. (Default: 1) + +[[FetchServerDescriptors]] **FetchServerDescriptors** **0**|**1**:: + If set to 0, Tor will never fetch any network status summaries or server + descriptors from the directory servers. This option is only useful if + you're using a Tor controller that handles directory fetches for you. + (Default: 1) + +[[FetchUselessDescriptors]] **FetchUselessDescriptors** **0**|**1**:: + If set to 1, Tor will fetch every consensus flavor, and all server + descriptors and authority certificates referenced by those consensuses, + except for extra info descriptors. When this option is 1, Tor will also + keep fetching descriptors, even when idle. + If set to 0, Tor will avoid fetching useless descriptors: flavors that it + is not using to build circuits, and authority certificates it does not + trust. When Tor hasn't built any application circuits, it will go idle, + and stop fetching descriptors. This option is useful if you're using a + tor client with an external parser that uses a full consensus. + This option fetches all documents except extrainfo descriptors, + **DirCache** fetches and serves all documents except extrainfo + descriptors, **DownloadExtraInfo*** fetches extrainfo documents, and serves + them if **DirCache** is on, and **UseMicrodescriptors** changes the + flavour of consensues and descriptors that is fetched and used for + building circuits. (Default: 0) + +[[HardwareAccel]] **HardwareAccel** **0**|**1**:: + If non-zero, try to use built-in (static) crypto hardware acceleration when + available. Can not be changed while tor is running. (Default: 0) + +[[HashedControlPassword]] **HashedControlPassword** __hashed_password__:: + Allow connections on the control port if they present + the password whose one-way hash is __hashed_password__. You + can compute the hash of a password by running "tor --hash-password + __password__". You can provide several acceptable passwords by using more + than one HashedControlPassword line. + +[[HTTPProxy]] **HTTPProxy** __host__[:__port__]:: + Tor will make all its directory requests through this host:port (or host:80 + if port is not specified), rather than connecting directly to any directory + servers. (DEPRECATED: As of 0.3.1.0-alpha you should use HTTPSProxy.) + +[[HTTPProxyAuthenticator]] **HTTPProxyAuthenticator** __username:password__:: + If defined, Tor will use this username:password for Basic HTTP proxy + authentication, as in RFC 2617. This is currently the only form of HTTP + proxy authentication that Tor supports; feel free to submit a patch if you + want it to support others. (DEPRECATED: As of 0.3.1.0-alpha you should use + HTTPSProxyAuthenticator.) + +[[HTTPSProxy]] **HTTPSProxy** __host__[:__port__]:: + Tor will make all its OR (SSL) connections through this host:port (or + host:443 if port is not specified), via HTTP CONNECT rather than connecting + directly to servers. You may want to set **FascistFirewall** to restrict + the set of ports you might try to connect to, if your HTTPS proxy only + allows connecting to certain ports. + +[[HTTPSProxyAuthenticator]] **HTTPSProxyAuthenticator** __username:password__:: + If defined, Tor will use this username:password for Basic HTTPS proxy + authentication, as in RFC 2617. This is currently the only form of HTTPS + proxy authentication that Tor supports; feel free to submit a patch if you + want it to support others. + +[[KeepalivePeriod]] **KeepalivePeriod** __NUM__:: + To keep firewalls from expiring connections, send a padding keepalive cell + every NUM seconds on open connections that are in use. (Default: 5 minutes) + +[[KeepBindCapabilities]] **KeepBindCapabilities** **0**|**1**|**auto**:: + On Linux, when we are started as root and we switch our identity using + the **User** option, the **KeepBindCapabilities** option tells us whether to + try to retain our ability to bind to low ports. If this value is 1, we + try to keep the capability; if it is 0 we do not; and if it is **auto**, + we keep the capability only if we are configured to listen on a low port. + Can not be changed while tor is running. + (Default: auto.) + +[[Log]] **Log** __minSeverity__[-__maxSeverity__] **stderr**|**stdout**|**syslog**:: + Send all messages between __minSeverity__ and __maxSeverity__ to the standard + output stream, the standard error stream, or to the system log. (The + "syslog" value is only supported on Unix.) Recognized severity levels are + debug, info, notice, warn, and err. We advise using "notice" in most cases, + since anything more verbose may provide sensitive information to an + attacker who obtains the logs. If only one severity level is given, all + messages of that level or higher will be sent to the listed destination. + + + + Some low-level logs may be sent from signal handlers, so their destination + logs must be signal-safe. These low-level logs include backtraces, + logging function errors, and errors in code called by logging functions. + Signal-safe logs are always sent to stderr or stdout. They are also sent to + a limited number of log files that are configured to log messages at error + severity from the bug or general domains. They are never sent as syslogs, + android logs, control port log events, or to any API-based log + destinations. + +[[Log2]] **Log** __minSeverity__[-__maxSeverity__] **file** __FILENAME__:: + As above, but send log messages to the listed filename. The + "Log" option may appear more than once in a configuration file. + Messages are sent to all the logs that match their severity + level. + +[[Log3]] **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **file** __FILENAME__ + + +[[Log4]] **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **stderr**|**stdout**|**syslog**:: + As above, but select messages by range of log severity __and__ by a + set of "logging domains". Each logging domain corresponds to an area of + functionality inside Tor. You can specify any number of severity ranges + for a single log statement, each of them prefixed by a comma-separated + list of logging domains. You can prefix a domain with $$~$$ to indicate + negation, and use * to indicate "all domains". If you specify a severity + range without a list of domains, it matches all domains. + + + + This is an advanced feature which is most useful for debugging one or two + of Tor's subsystems at a time. + + + + The currently recognized domains are: general, crypto, net, config, fs, + protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge, + acct, hist, handshake, heartbeat, channel, sched, guard, consdiff, dos, + process, pt, btrack, and mesg. + Domain names are case-insensitive. + + + + For example, "`Log [handshake]debug [~net,~mm]info notice stdout`" sends + to stdout: all handshake messages of any severity, all info-and-higher + messages from domains other than networking and memory management, and all + messages of severity notice or higher. + +[[LogMessageDomains]] **LogMessageDomains** **0**|**1**:: + If 1, Tor includes message domains with each log message. Every log + message currently has at least one domain; most currently have exactly + one. This doesn't affect controller log messages. (Default: 0) + +[[LogTimeGranularity]] **LogTimeGranularity** __NUM__:: + Set the resolution of timestamps in Tor's logs to NUM milliseconds. + NUM must be positive and either a divisor or a multiple of 1 second. + Note that this option only controls the granularity written by Tor to + a file or console log. Tor does not (for example) "batch up" log + messages to affect times logged by a controller, times attached to + syslog messages, or the mtime fields on log files. (Default: 1 second) + +[[MaxAdvertisedBandwidth]] **MaxAdvertisedBandwidth** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + If set, we will not advertise more than this amount of bandwidth for our + BandwidthRate. Server operators who want to reduce the number of clients + who ask to build circuits through them (since this is proportional to + advertised bandwidth rate) can thus reduce the CPU demands on their server + without impacting network performance. + +[[MaxUnparseableDescSizeToLog]] **MaxUnparseableDescSizeToLog** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**:: + Unparseable descriptors (e.g. for votes, consensuses, routers) are logged + in separate files by hash, up to the specified size in total. Note that + only files logged during the lifetime of this Tor process count toward the + total; this is intended to be used to debug problems without opening live + servers to resource exhaustion attacks. (Default: 10 MBytes) + +[[NoExec]] **NoExec** **0**|**1**:: + If this option is set to 1, then Tor will never launch another + executable, regardless of the settings of ClientTransportPlugin + or ServerTransportPlugin. Once this option has been set to 1, + it cannot be set back to 0 without restarting Tor. (Default: 0) + +[[OutboundBindAddress]] **OutboundBindAddress** __IP__:: + Make all outbound connections originate from the IP address specified. This + is only useful when you have multiple network interfaces, and you want all + of Tor's outgoing connections to use a single one. This option may + be used twice, once with an IPv4 address and once with an IPv6 address. + IPv6 addresses should be wrapped in square brackets. + This setting will be ignored for connections to the loopback addresses + (127.0.0.0/8 and ::1), and is not used for DNS requests as well. + +[[OutboundBindAddressExit]] **OutboundBindAddressExit** __IP__:: + Make all outbound exit connections originate from the IP address + specified. This option overrides **OutboundBindAddress** for the + same IP version. This option may be used twice, once with an IPv4 + address and once with an IPv6 address. + IPv6 addresses should be wrapped in square brackets. + This setting will be ignored + for connections to the loopback addresses (127.0.0.0/8 and ::1). + +[[OutboundBindAddressOR]] **OutboundBindAddressOR** __IP__:: + Make all outbound non-exit (relay and other) connections + originate from the IP address specified. This option overrides + **OutboundBindAddress** for the same IP version. This option may + be used twice, once with an IPv4 address and once with an IPv6 + address. IPv6 addresses should be wrapped in square brackets. + This setting will be ignored for connections to the loopback + addresses (127.0.0.0/8 and ::1). + +[[OwningControllerProcess]] **{dbl_}OwningControllerProcess** __PID__:: + Make Tor instance periodically check for presence of a controller process + with given PID and terminate itself if this process is no longer alive. + Polling interval is 15 seconds. + +[[PerConnBWBurst]] **PerConnBWBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + If this option is set manually, or via the "perconnbwburst" consensus + field, Tor will use it for separate rate limiting for each connection + from a non-relay. (Default: 0) + +[[PerConnBWRate]] **PerConnBWRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + If this option is set manually, or via the "perconnbwrate" consensus + field, Tor will use it for separate rate limiting for each connection + from a non-relay. (Default: 0) + +[[PidFile]] **PidFile** __FILE__:: + On startup, write our PID to FILE. On clean shutdown, remove + FILE. Can not be changed while tor is running. + +[[ProtocolWarnings]] **ProtocolWarnings** **0**|**1**:: + If 1, Tor will log with severity \'warn' various cases of other parties not + following the Tor specification. Otherwise, they are logged with severity + \'info'. (Default: 0) + +[[RelayBandwidthBurst]] **RelayBandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + If not 0, limit the maximum token bucket size (also known as the burst) for + \_relayed traffic_ to the given number of bytes in each direction. + They do not include directory fetches by the relay (from authority + or other relays), because that is considered "client" activity. (Default: 0) + +[[RelayBandwidthRate]] **RelayBandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + If not 0, a separate token bucket limits the average incoming bandwidth + usage for \_relayed traffic_ on this node to the specified number of bytes + per second, and the average outgoing bandwidth usage to that same value. + Relayed traffic currently is calculated to include answers to directory + requests, but that may change in future versions. They do not include directory + fetches by the relay (from authority or other relays), because that is considered + "client" activity. (Default: 0) + +[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: + Tells an authority, or other node tracking node reliability and history, + that fine-grained information about nodes can be discarded when it hasn't + changed for a given amount of time. (Default: 24 hours) + +[[RunAsDaemon]] **RunAsDaemon** **0**|**1**:: + If 1, Tor forks and daemonizes to the background. This option has no effect + on Windows; instead you should use the --service command-line option. + Can not be changed while tor is running. + (Default: 0) + +[[SafeLogging]] **SafeLogging** **0**|**1**|**relay**:: + Tor can scrub potentially sensitive strings from log messages (e.g. + addresses) by replacing them with the string [scrubbed]. This way logs can + still be useful, but they don't leave behind personally identifying + information about what sites a user might have visited. + + + + If this option is set to 0, Tor will not perform any scrubbing, if it is + set to 1, all potentially sensitive strings are replaced. If it is set to + relay, all log messages generated when acting as a relay are sanitized, but + all messages generated when acting as a client are not. + Note: Tor may not heed this option when logging at log levels below Notice. + (Default: 1) + +[[Sandbox]] **Sandbox** **0**|**1**:: + If set to 1, Tor will run securely through the use of a syscall sandbox. + Otherwise the sandbox will be disabled. The option is currently an + experimental feature. It only works on Linux-based operating systems, + and only when Tor has been built with the libseccomp library. This option + can not be changed while tor is running. + + + + When the **Sandbox** is 1, the following options can not be changed when tor + is running: + **Address**, + **ConnLimit**, + **CookieAuthFile**, + **DirPortFrontPage**, + **ExtORPortCookieAuthFile**, + **Logs**, + **ServerDNSResolvConfFile**, + **ClientOnionAuthDir** (and any files in it won't reload on HUP signal). + + + + Launching new Onion Services through the control port is not supported + with current syscall sandboxing implementation. + + + + Tor must remain in client or server mode (some changes to **ClientOnly** + and **ORPort** are not allowed). Currently, if **Sandbox** is 1, + **ControlPort** command "GETINFO address" will not work. + + + + When using %include in the tor configuration files, reloading the tor + configuration is not supported after adding new configuration files or + directories. + + + + (Default: 0) + +[[Schedulers]] **Schedulers** **KIST**|**KISTLite**|**Vanilla**:: + Specify the scheduler type that tor should use. The scheduler is + responsible for moving data around within a Tor process. This is an ordered + list by priority which means that the first value will be tried first and if + unavailable, the second one is tried and so on. It is possible to change + these values at runtime. This option mostly effects relays, and most + operators should leave it set to its default value. + (Default: KIST,KISTLite,Vanilla) + + + + The possible scheduler types are: + + + **KIST**: Kernel-Informed Socket Transport. Tor will use TCP information + from the kernel to make informed decisions regarding how much data to send + and when to send it. KIST also handles traffic in batches (see + <>) in order to improve traffic prioritization decisions. + As implemented, KIST will only work on Linux kernel version 2.6.39 or + higher. + + + + **KISTLite**: Same as KIST but without kernel support. Tor will use all + the same mechanics as with KIST, including the batching, but its decisions + regarding how much data to send will not be as good. KISTLite will work on + all kernels and operating systems, and the majority of the benefits of KIST + are still realized with KISTLite. + + + + **Vanilla**: The scheduler that Tor used before KIST was implemented. It + sends as much data as possible, as soon as possible. Vanilla will work on + all kernels and operating systems. + +// Out of order because it logically belongs near the Schedulers option +[[KISTSchedRunInterval]] **KISTSchedRunInterval** __NUM__ **msec**:: + If KIST or KISTLite is used in the Schedulers option, this controls at which + interval the scheduler tick is. If the value is 0 msec, the value is taken + from the consensus if possible else it will fallback to the default 10 + msec. Maximum possible value is 100 msec. (Default: 0 msec) + +// Out of order because it logically belongs near the Schedulers option +[[KISTSockBufSizeFactor]] **KISTSockBufSizeFactor** __NUM__:: + If KIST is used in Schedulers, this is a multiplier of the per-socket + limit calculation of the KIST algorithm. (Default: 1.0) + + +[[ServerTransportListenAddr]] **ServerTransportListenAddr** __transport__ __IP__:__PORT__:: + When this option is set, Tor will suggest __IP__:__PORT__ as the + listening address of any pluggable transport proxy that tries to + launch __transport__. (IPv4 addresses should written as-is; IPv6 + addresses should be wrapped in square brackets.) (Default: none) + +[[ServerTransportOptions]] **ServerTransportOptions** __transport__ __k=v__ __k=v__ ...:: + When this option is set, Tor will pass the __k=v__ parameters to + any pluggable transport proxy that tries to launch __transport__. + + (Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd cache=/var/lib/tor/cache) (Default: none) + +[[ServerTransportPlugin]] **ServerTransportPlugin** __transport__ exec __path-to-binary__ [options]:: + The Tor relay launches the pluggable transport proxy in __path-to-binary__ + using __options__ as its command-line options, and expects to receive + proxied client traffic from it. (Default: none) + +[[Socks4Proxy]] **Socks4Proxy** __host__[:__port__]:: + Tor will make all OR connections through the SOCKS 4 proxy at host:port + (or host:1080 if port is not specified). + +[[Socks5Proxy]] **Socks5Proxy** __host__[:__port__]:: + Tor will make all OR connections through the SOCKS 5 proxy at host:port + (or host:1080 if port is not specified). + +// Out of order because Username logically precedes Password +[[Socks5ProxyUsername]] **Socks5ProxyUsername** __username__ + + +[[Socks5ProxyPassword]] **Socks5ProxyPassword** __password__:: + If defined, authenticate to the SOCKS 5 server using username and password + in accordance to RFC 1929. Both username and password must be between 1 and + 255 characters. + +[[SyslogIdentityTag]] **SyslogIdentityTag** __tag__:: + When logging to syslog, adds a tag to the syslog identity such that + log entries are marked with "Tor-__tag__". Can not be changed while tor is + running. (Default: none) + +[[TCPProxy]] **TCPProxy** __protocol__ __host__:__port__:: + Tor will use the given protocol to make all its OR (SSL) connections through + a TCP proxy on host:port, rather than connecting directly to servers. You may + want to set **FascistFirewall** to restrict the set of ports you might try to + connect to, if your proxy only allows connecting to certain ports. There is no + equivalent option for directory connections, because all Tor client versions + that support this option download directory documents via OR connections. + ++ + The only protocol supported right now 'haproxy'. This option is only for + clients. (Default: none) + ++ + The HAProxy version 1 proxy protocol is described in detail at + https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt + ++ + Both source IP address and source port will be set to zero. + +[[TruncateLogFile]] **TruncateLogFile** **0**|**1**:: + If 1, Tor will overwrite logs at startup and in response to a HUP signal, + instead of appending to them. (Default: 0) + +[[UnixSocksGroupWritable]] **UnixSocksGroupWritable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read and + write unix sockets (e.g. SocksPort unix:). If the option is set to 1, make + the Unix socket readable and writable by the default GID. (Default: 0) + +[[UseDefaultFallbackDirs]] **UseDefaultFallbackDirs** **0**|**1**:: + Use Tor's default hard-coded FallbackDirs (if any). (When a + FallbackDir line is present, it replaces the hard-coded FallbackDirs, + regardless of the value of UseDefaultFallbackDirs.) (Default: 1) + +[[User]] **User** __Username__:: + On startup, setuid to this user and setgid to their primary group. + Can not be changed while tor is running. + +== CLIENT OPTIONS + +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + +The following options are useful only for clients (that is, if +**SocksPort**, **HTTPTunnelPort**, **TransPort**, **DNSPort**, or +**NATDPort** is non-zero): + +[[AllowNonRFC953Hostnames]] **AllowNonRFC953Hostnames** **0**|**1**:: + When this option is disabled, Tor blocks hostnames containing illegal + characters (like @ and :) rather than sending them to an exit node to be + resolved. This helps trap accidental attempts to resolve URLs and so on. + (Default: 0) + +[[AutomapHostsOnResolve]] **AutomapHostsOnResolve** **0**|**1**:: + When this option is enabled, and we get a request to resolve an address + that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an + unused virtual address to that address, and return the new virtual address. + This is handy for making ".onion" addresses work with applications that + resolve an address and then connect to it. (Default: 0) + +[[AutomapHostsSuffixes]] **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__:: + A comma-separated list of suffixes to use with **AutomapHostsOnResolve**. + The "." suffix is equivalent to "all addresses." (Default: .exit,.onion). + +[[Bridge]] **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]:: + When set along with UseBridges, instructs Tor to use the relay at + "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint" + is provided (using the same format as for DirAuthority), we will verify that + the relay running at that location has the right fingerprint. We also use + fingerprint to look up the bridge descriptor at the bridge authority, if + it's provided and if UpdateBridgesFromAuthority is set too. + + + + If "transport" is provided, it must match a ClientTransportPlugin line. We + then use that pluggable transport's proxy to transfer data to the bridge, + rather than connecting to the bridge directly. Some transports use a + transport-specific method to work out the remote address to connect to. + These transports typically ignore the "IP:ORPort" specified in the bridge + line. + + + + Tor passes any "key=val" settings to the pluggable transport proxy as + per-connection arguments when connecting to the bridge. Consult + the documentation of the pluggable transport for details of what + arguments it supports. + +[[CircuitPadding]] **CircuitPadding** **0**|**1**:: + If set to 0, Tor will not pad client circuits with additional cover + traffic. Only clients may set this option. This option should be offered + via the UI to mobile users for use where bandwidth may be expensive. If + set to 1, padding will be negotiated as per the consensus and relay + support (unlike ConnectionPadding, CircuitPadding cannot be force-enabled). + (Default: 1) + +// Out of order because it logically belongs after CircuitPadding +[[ReducedCircuitPadding]] **ReducedCircuitPadding** **0**|**1**:: + If set to 1, Tor will only use circuit padding algorithms that have low + overhead. Only clients may set this option. This option should be offered + via the UI to mobile users for use where bandwidth may be expensive. + (Default: 0) + +[[ClientBootstrapConsensusAuthorityDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses from authorities + if they are bootstrapping (that is, they don't have a usable, reasonably + live consensus). Only used by clients fetching from a list of fallback + directory mirrors. This schedule is advanced by (potentially concurrent) + connection attempts, unlike other schedules, which are advanced by + connection failures. (Default: 6) + +[[ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses from authorities + if they are bootstrapping (that is, they don't have a usable, reasonably + live consensus). Only used by clients which don't have or won't fetch + from a list of fallback directory mirrors. This schedule is advanced by + (potentially concurrent) connection attempts, unlike other schedules, + which are advanced by connection failures. (Default: 0) + +[[ClientBootstrapConsensusFallbackDownloadInitialDelay]] **ClientBootstrapConsensusFallbackDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses from fallback + directory mirrors if they are bootstrapping (that is, they don't have a + usable, reasonably live consensus). Only used by clients fetching from a + list of fallback directory mirrors. This schedule is advanced by + (potentially concurrent) connection attempts, unlike other schedules, + which are advanced by connection failures. (Default: 0) + +[[ClientBootstrapConsensusMaxInProgressTries]] **ClientBootstrapConsensusMaxInProgressTries** __NUM__:: + Try this many simultaneous connections to download a consensus before + waiting for one to complete, timeout, or error out. (Default: 3) + +[[ClientDNSRejectInternalAddresses]] **ClientDNSRejectInternalAddresses** **0**|**1**:: + If true, Tor does not believe any anonymously retrieved DNS answer that + tells it that an address resolves to an internal address (like 127.0.0.1 or + 192.168.0.1). This option prevents certain browser-based attacks; it + is not allowed to be set on the default network. (Default: 1) + +[[ClientOnionAuthDir]] **ClientOnionAuthDir** __path__:: + Path to the directory containing v3 hidden service authorization files. + Each file is for a single onion address, and the files MUST have the suffix + ".auth_private" (i.e. "bob_onion.auth_private"). The content format MUST be: + + + :descriptor:x25519: + + + The MUST NOT have the ".onion" suffix. The + is the base32 representation of the raw key bytes + only (32 bytes for x25519). See Appendix G in the rend-spec-v3.txt file of + https://spec.torproject.org/[torspec] for more information. + +[[ClientOnly]] **ClientOnly** **0**|**1**:: + If set to 1, Tor will not run as a relay or serve + directory requests, even if the ORPort, ExtORPort, or DirPort options are + set. (This config option is + mostly unnecessary: we added it back when we were considering having + Tor clients auto-promote themselves to being relays if they were stable + and fast enough. The current behavior is simply that Tor is a client + unless ORPort, ExtORPort, or DirPort are configured.) (Default: 0) + +[[ClientPreferIPv6DirPort]] **ClientPreferIPv6DirPort** **0**|**1**|**auto**:: + If this option is set to 1, Tor prefers a directory port with an IPv6 + address over one with IPv4, for direct connections, if a given directory + server has both. (Tor also prefers an IPv6 DirPort if IPv4Client is set to + 0.) If this option is set to auto, clients prefer IPv4. Other things may + influence the choice. This option breaks a tie to the favor of IPv6. + (Default: auto) (DEPRECATED: This option has had no effect for some + time.) + +[[ClientPreferIPv6ORPort]] **ClientPreferIPv6ORPort** **0**|**1**|**auto**:: + If this option is set to 1, Tor prefers an OR port with an IPv6 + address over one with IPv4 if a given entry node has both. (Tor also + prefers an IPv6 ORPort if IPv4Client is set to 0.) If this option is set + to auto, Tor bridge clients prefer the configured bridge address, and + other clients prefer IPv4. Other things may influence the choice. This + option breaks a tie to the favor of IPv6. (Default: auto) + +[[ClientRejectInternalAddresses]] **ClientRejectInternalAddresses** **0**|**1**:: + If true, Tor does not try to fulfill requests to connect to an internal + address (like 127.0.0.1 or 192.168.0.1) __unless an exit node is + specifically requested__ (for example, via a .exit hostname, or a + controller request). If true, multicast DNS hostnames for machines on the + local network (of the form *.local) are also rejected. (Default: 1) + +[[ClientUseIPv4]] **ClientUseIPv4** **0**|**1**:: + If this option is set to 0, Tor will avoid connecting to directory servers + and entry nodes over IPv4. Note that clients with an IPv4 + address in a **Bridge**, proxy, or pluggable transport line will try + connecting over IPv4 even if **ClientUseIPv4** is set to 0. (Default: 1) + +[[ClientUseIPv6]] **ClientUseIPv6** **0**|**1**:: + If this option is set to 1, Tor might connect to directory servers or + entry nodes over IPv6. For IPv6 only hosts, you need to also set + **ClientUseIPv4** to 0 to disable IPv4. Note that clients configured with + an IPv6 address in a **Bridge**, proxy, or pluggable transportline will + try connecting over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0) + +[[ConnectionPadding]] **ConnectionPadding** **0**|**1**|**auto**:: + This option governs Tor's use of padding to defend against some forms of + traffic analysis. If it is set to 'auto', Tor will send padding only + if both the client and the relay support it. If it is set to 0, Tor will + not send any padding cells. If it is set to 1, Tor will still send padding + for client connections regardless of relay support. Only clients may set + this option. This option should be offered via the UI to mobile users + for use where bandwidth may be expensive. + (Default: auto) + +// Out of order because it logically belongs after ConnectionPadding +[[ReducedConnectionPadding]] **ReducedConnectionPadding** **0**|**1**:: + If set to 1, Tor will not not hold OR connections open for very long, + and will send less padding on these connections. Only clients may set + this option. This option should be offered via the UI to mobile users + for use where bandwidth may be expensive. (Default: 0) + +[[DNSPort]] **DNSPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: + If non-zero, open this port to listen for UDP DNS requests, and resolve + them anonymously. This port only handles A, AAAA, and PTR requests---it + doesn't handle arbitrary DNS request types. Set the port to "auto" to + have Tor pick a port for + you. This directive can be specified multiple times to bind to multiple + addresses/ports. See <> for an explanation of isolation + flags. (Default: 0) + +[[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**:: + If true, Tor downloads and caches "extra-info" documents. These documents + contain information about servers other than the information in their + regular server descriptors. Tor does not use this information for anything + itself; to save bandwidth, leave this option turned off. (Default: 0) + +[[EnforceDistinctSubnets]] **EnforceDistinctSubnets** **0**|**1**:: + If 1, Tor will not put two servers whose IP addresses are "too close" on + the same circuit. Currently, two addresses are "too close" if they lie in + the same /16 range. (Default: 1) + +[[FascistFirewall]] **FascistFirewall** **0**|**1**:: + If 1, Tor will only create outgoing connections to ORs running on ports + that your firewall allows (defaults to 80 and 443; see <>). + This will allow you to run Tor as a client behind a firewall with + restrictive policies, but will not allow you to run as a server behind such + a firewall. If you prefer more fine-grained control, use + ReachableAddresses instead. + +[[FirewallPorts]] **FirewallPorts** __PORTS__:: + A list of ports that your firewall allows you to connect to. Only used when + **FascistFirewall** is set. This option is deprecated; use ReachableAddresses + instead. (Default: 80, 443) + +[[HidServAuth]] **HidServAuth** __onion-address__ __auth-cookie__ [__service-name__]:: + Client authorization for a v2 hidden service. Valid onion addresses contain 16 + characters in a-z2-7 plus ".onion", and valid auth cookies contain 22 + characters in A-Za-z0-9+/. The service name is only used for internal + purposes, e.g., for Tor controllers. This option may be used multiple times + for different hidden services. If a hidden service uses authorization and + this option is not set, the hidden service is not accessible. Hidden + services can be configured to require authorization using the + **HiddenServiceAuthorizeClient** option. + +[[HTTPTunnelPort]] **HTTPTunnelPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: + Open this port to listen for proxy connections using the "HTTP CONNECT" + protocol instead of SOCKS. Set this to + 0 if you don't want to allow "HTTP CONNECT" connections. Set the port + to "auto" to have Tor pick a port for you. This directive can be + specified multiple times to bind to multiple addresses/ports. If multiple + entries of this option are present in your configuration file, Tor will + perform stream isolation between listeners by default. See + <> for an explanation of isolation flags. (Default: 0) + +[[LongLivedPorts]] **LongLivedPorts** __PORTS__:: + A list of ports for services that tend to have long-running connections + (e.g. chat and interactive shells). Circuits for streams that use these + ports will contain only high-uptime nodes, to reduce the chance that a node + will go down before the stream is finished. Note that the list is also + honored for circuits (both client and service side) involving hidden + services whose virtual port is in this list. (Default: 21, 22, 706, + 1863, 5050, 5190, 5222, 5223, 6523, 6667, 6697, 8300) + +[[MapAddress]] **MapAddress** __address__ __newaddress__:: + When a request for address arrives to Tor, it will transform to newaddress + before processing it. For example, if you always want connections to + www.example.com to exit via __torserver__ (where __torserver__ is the + fingerprint of the server), use "MapAddress www.example.com + www.example.com.torserver.exit". If the value is prefixed with a + "\*.", matches an entire domain. For example, if you + always want connections to example.com and any if its subdomains + to exit via + __torserver__ (where __torserver__ is the fingerprint of the server), use + "MapAddress \*.example.com \*.example.com.torserver.exit". (Note the + leading "*." in each part of the directive.) You can also redirect all + subdomains of a domain to a single address. For example, "MapAddress + *.example.com www.example.com". If the specified exit is not available, + or the exit can not connect to the site, Tor will fail any connections + to the mapped address.+ + + + NOTES: + + 1. When evaluating MapAddress expressions Tor stops when it hits the most + recently added expression that matches the requested address. So if you + have the following in your torrc, www.torproject.org will map to + 198.51.100.1: + + MapAddress www.torproject.org 192.0.2.1 + MapAddress www.torproject.org 198.51.100.1 + + 2. Tor evaluates the MapAddress configuration until it finds no matches. So + if you have the following in your torrc, www.torproject.org will map to + 203.0.113.1: + + MapAddress 198.51.100.1 203.0.113.1 + MapAddress www.torproject.org 198.51.100.1 + + 3. The following MapAddress expression is invalid (and will be + ignored) because you cannot map from a specific address to a wildcard + address: + + MapAddress www.torproject.org *.torproject.org.torserver.exit + + 4. Using a wildcard to match only part of a string (as in *ample.com) is + also invalid. + + 5. Tor maps hostnames and IP addresses separately. If you MapAddress + a DNS name, but use an IP address to connect, then Tor will ignore the + DNS name mapping. + + 6. MapAddress does not apply to redirects in the application protocol. + For example, HTTP redirects and alt-svc headers will ignore mappings + for the original address. You can use a wildcard mapping to handle + redirects within the same site. + +[[MaxCircuitDirtiness]] **MaxCircuitDirtiness** __NUM__:: + Feel free to reuse a circuit that was first used at most NUM seconds ago, + but never attach a new stream to a circuit that is too old. For hidden + services, this applies to the __last__ time a circuit was used, not the + first. Circuits with streams constructed with SOCKS authentication via + SocksPorts that have **KeepAliveIsolateSOCKSAuth** also remain alive + for MaxCircuitDirtiness seconds after carrying the last such stream. + (Default: 10 minutes) + +[[MaxClientCircuitsPending]] **MaxClientCircuitsPending** __NUM__:: + Do not allow more than NUM circuits to be pending at a time for handling + client streams. A circuit is pending if we have begun constructing it, + but it has not yet been completely constructed. (Default: 32) + +[[NATDPort]] **NATDPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: + Open this port to listen for connections from old versions of ipfw (as + included in old versions of FreeBSD, etc) using the NATD protocol. + Use 0 if you don't want to allow NATD connections. Set the port + to "auto" to have Tor pick a port for you. This directive can be + specified multiple times to bind to multiple addresses/ports. If multiple + entries of this option are present in your configuration file, Tor will + perform stream isolation between listeners by default. See + <> for an explanation of isolation flags. + + + + This option is only for people who cannot use TransPort. (Default: 0) + +[[NewCircuitPeriod]] **NewCircuitPeriod** __NUM__:: + Every NUM seconds consider whether to build a new circuit. (Default: 30 + seconds) + +[[OptimisticData]] **OptimisticData** **0**|**1**|**auto**:: + When this option is set, and Tor is using an exit node that supports + the feature, it will try optimistically to send data to the exit node + without waiting for the exit node to report whether the connection + succeeded. This can save a round-trip time for protocols like HTTP + where the client talks first. If OptimisticData is set to **auto**, + Tor will look at the UseOptimisticData parameter in the networkstatus. + (Default: auto) + +// These are out of order because they logically belong together +[[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ + + +[[PathBiasDropGuards]] **PathBiasDropGuards** __NUM__ + + +[[PathBiasExtremeRate]] **PathBiasExtremeRate** __NUM__ + + +[[PathBiasNoticeRate]] **PathBiasNoticeRate** __NUM__ + + +[[PathBiasWarnRate]] **PathBiasWarnRate** __NUM__ + + +[[PathBiasScaleThreshold]] **PathBiasScaleThreshold** __NUM__:: + These options override the default behavior of Tor's (**currently + experimental**) path bias detection algorithm. To try to find broken or + misbehaving guard nodes, Tor looks for nodes where more than a certain + fraction of circuits through that guard fail to get built. + + + + The PathBiasCircThreshold option controls how many circuits we need to build + through a guard before we make these checks. The PathBiasNoticeRate, + PathBiasWarnRate and PathBiasExtremeRate options control what fraction of + circuits must succeed through a guard so we won't write log messages. + If less than PathBiasExtremeRate circuits succeed *and* PathBiasDropGuards + is set to 1, we disable use of that guard. + + + + When we have seen more than PathBiasScaleThreshold + circuits through a guard, we scale our observations by 0.5 (governed by + the consensus) so that new observations don't get swamped by old ones. + + + + By default, or if a negative value is provided for one of these options, + Tor uses reasonable defaults from the networkstatus consensus document. + If no defaults are available there, these options default to 150, .70, + .50, .30, 0, and 300 respectively. + +// These are out of order because they logically belong together +[[PathBiasUseThreshold]] **PathBiasUseThreshold** __NUM__ + + +[[PathBiasNoticeUseRate]] **PathBiasNoticeUseRate** __NUM__ + + +[[PathBiasExtremeUseRate]] **PathBiasExtremeUseRate** __NUM__ + + +[[PathBiasScaleUseThreshold]] **PathBiasScaleUseThreshold** __NUM__:: + Similar to the above options, these options override the default behavior + of Tor's (**currently experimental**) path use bias detection algorithm. + + + + Where as the path bias parameters govern thresholds for successfully + building circuits, these four path use bias parameters govern thresholds + only for circuit usage. Circuits which receive no stream usage + are not counted by this detection algorithm. A used circuit is considered + successful if it is capable of carrying streams or otherwise receiving + well-formed responses to RELAY cells. + + + + By default, or if a negative value is provided for one of these options, + Tor uses reasonable defaults from the networkstatus consensus document. + If no defaults are available there, these options default to 20, .80, + .60, and 100, respectively. + +[[PathsNeededToBuildCircuits]] **PathsNeededToBuildCircuits** __NUM__:: + Tor clients don't build circuits for user traffic until they know + about enough of the network so that they could potentially construct + enough of the possible paths through the network. If this option + is set to a fraction between 0.25 and 0.95, Tor won't build circuits + until it has enough descriptors or microdescriptors to construct + that fraction of possible paths. Note that setting this option too low + can make your Tor client less anonymous, and setting it too high can + prevent your Tor client from bootstrapping. If this option is negative, + Tor will use a default value chosen by the directory authorities. If the + directory authorities do not choose a value, Tor will default to 0.6. + (Default: -1) + +[[ReachableAddresses]] **ReachableAddresses** __IP__[/__MASK__][:__PORT__]...:: + A comma-separated list of IP addresses and ports that your firewall allows + you to connect to. The format is as for the addresses in ExitPolicy, except + that "accept" is understood unless "reject" is explicitly provided. For + example, \'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept + \*:80' means that your firewall allows connections to everything inside net + 99, rejects port 80 connections to net 18, and accepts connections to port + 80 otherwise. (Default: \'accept \*:*'.) + +[[ReachableDirAddresses]] **ReachableDirAddresses** __IP__[/__MASK__][:__PORT__]...:: + Like **ReachableAddresses**, a list of addresses and ports. Tor will obey + these restrictions when fetching directory information, using standard HTTP + GET requests. If not set explicitly then the value of + **ReachableAddresses** is used. If **HTTPProxy** is set then these + connections will go through that proxy. (DEPRECATED: This option has + had no effect for some time.) + +[[ReachableORAddresses]] **ReachableORAddresses** __IP__[/__MASK__][:__PORT__]...:: + Like **ReachableAddresses**, a list of addresses and ports. Tor will obey + these restrictions when connecting to Onion Routers, using TLS/SSL. If not + set explicitly then the value of **ReachableAddresses** is used. If + **HTTPSProxy** is set then these connections will go through that proxy. + + + + The separation between **ReachableORAddresses** and + **ReachableDirAddresses** is only interesting when you are connecting + through proxies (see <> and <>). Most proxies limit + TLS connections (which Tor uses to connect to Onion Routers) to port 443, + and some limit HTTP GET requests (which Tor uses for fetching directory + information) to port 80. + +[[SafeSocks]] **SafeSocks** **0**|**1**:: + When this option is enabled, Tor will reject application connections that + use unsafe variants of the socks protocol -- ones that only provide an IP + address, meaning the application is doing a DNS resolve first. + Specifically, these are socks4 and socks5 when not doing remote DNS. + (Default: 0) + +// Out of order because it logically belongs after SafeSocks +[[TestSocks]] **TestSocks** **0**|**1**:: + When this option is enabled, Tor will make a notice-level log entry for + each connection to the Socks port indicating whether the request used a + safe socks protocol or an unsafe one (see <>). This + helps to determine whether an application using Tor is possibly leaking + DNS requests. (Default: 0) + +// Out of order because it logically belongs with SafeSocks +[[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__:: + Tells Tor to issue a warnings whenever the user tries to make an anonymous + connection to one of these ports. This option is designed to alert users + to services that risk sending passwords in the clear. (Default: + 23,109,110,143) + +// Out of order because it logically belongs with SafeSocks +[[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__:: + Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor + will instead refuse to make the connection. (Default: None) + +[[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__:: + Set an entrance policy for this server, to limit who can connect to the + SocksPort and DNSPort ports. The policies have the same form as exit + policies below, except that port specifiers are ignored. Any address + not matched by some entry in the policy is accepted. + +[[SocksPort]] **SocksPort** ['address'**:**]{empty}__port__|**unix:**__path__|**auto** [_flags_] [_isolation flags_]:: + Open this port to listen for connections from SOCKS-speaking + applications. Set this to 0 if you don't want to allow application + connections via SOCKS. Set it to "auto" to have Tor pick a port for + you. This directive can be specified multiple times to bind + to multiple addresses/ports. If a unix domain socket is used, you may + quote the path using standard C escape sequences. Most flags are off by + default, except where specified. Flags that are on by default can be + disabled by putting "No" before the flag name. + (Default: 9050) + + + + NOTE: Although this option allows you to specify an IP address + other than localhost, you should do so only with extreme caution. + The SOCKS protocol is unencrypted and (as we use it) + unauthenticated, so exposing it in this way could leak your + information to anybody watching your network, and allow anybody + to use your computer as an open proxy. + + + + If multiple entries of this option are present in your configuration + file, Tor will perform stream isolation between listeners by default. + The _isolation flags_ arguments give Tor rules for which streams + received on this SocksPort are allowed to share circuits with one + another. Recognized isolation flags are: + **IsolateClientAddr**;; + Don't share circuits with streams from a different + client address. (On by default and strongly recommended when + supported; you can disable it with **NoIsolateClientAddr**. + Unsupported and force-disabled when using Unix domain sockets.) + **IsolateSOCKSAuth**;; + Don't share circuits with streams for which different + SOCKS authentication was provided. (For HTTPTunnelPort + connections, this option looks at the Proxy-Authorization and + X-Tor-Stream-Isolation headers. On by default; + you can disable it with **NoIsolateSOCKSAuth**.) + **IsolateClientProtocol**;; + Don't share circuits with streams using a different protocol. + (SOCKS 4, SOCKS 5, HTTPTunnelPort connections, TransPort connections, + NATDPort connections, and DNSPort requests are all considered to be + different protocols.) + **IsolateDestPort**;; + Don't share circuits with streams targeting a different + destination port. + **IsolateDestAddr**;; + Don't share circuits with streams targeting a different + destination address. + **KeepAliveIsolateSOCKSAuth**;; + If **IsolateSOCKSAuth** is enabled, keep alive circuits while they have + at least one stream with SOCKS authentication active. After such a + circuit is idle for more than MaxCircuitDirtiness seconds, it can be + closed. + **SessionGroup=**__INT__;; + If no other isolation rules would prevent it, allow streams + on this port to share circuits with streams from every other + port with the same session group. (By default, streams received + on different SocksPorts, TransPorts, etc are always isolated from one + another. This option overrides that behavior.) + +// Anchor only for formatting, not visible in the man page. +[[OtherSocksPortFlags]]:: + Other recognized __flags__ for a SocksPort are: + **NoIPv4Traffic**;; + Tell exits to not connect to IPv4 addresses in response to SOCKS + requests on this connection. + **IPv6Traffic**;; + Tell exits to allow IPv6 addresses in response to SOCKS requests on + this connection, so long as SOCKS5 is in use. (SOCKS4 can't handle + IPv6.) + **PreferIPv6**;; + Tells exits that, if a host has both an IPv4 and an IPv6 address, + we would prefer to connect to it via IPv6. (IPv4 is the default.) + **NoDNSRequest**;; + Do not ask exits to resolve DNS addresses in SOCKS5 requests. Tor will + connect to IPv4 addresses, IPv6 addresses (if IPv6Traffic is set) and + .onion addresses. + **NoOnionTraffic**;; + Do not connect to .onion addresses in SOCKS5 requests. + **OnionTrafficOnly**;; + Tell the tor client to only connect to .onion addresses in response to + SOCKS5 requests on this connection. This is equivalent to NoDNSRequest, + NoIPv4Traffic, NoIPv6Traffic. The corresponding NoOnionTrafficOnly + flag is not supported. + **CacheIPv4DNS**;; + Tells the client to remember IPv4 DNS answers we receive from exit + nodes via this connection. + **CacheIPv6DNS**;; + Tells the client to remember IPv6 DNS answers we receive from exit + nodes via this connection. + **GroupWritable**;; + Unix domain sockets only: makes the socket get created as + group-writable. + **WorldWritable**;; + Unix domain sockets only: makes the socket get created as + world-writable. + **CacheDNS**;; + Tells the client to remember all DNS answers we receive from exit + nodes via this connection. + **UseIPv4Cache**;; + Tells the client to use any cached IPv4 DNS answers we have when making + requests via this connection. (NOTE: This option, or UseIPv6Cache + or UseDNSCache, can harm your anonymity, and probably + won't help performance as much as you might expect. Use with care!) + **UseIPv6Cache**;; + Tells the client to use any cached IPv6 DNS answers we have when making + requests via this connection. + **UseDNSCache**;; + Tells the client to use any cached DNS answers we have when making + requests via this connection. + **NoPreferIPv6Automap**;; + When serving a hostname lookup request on this port that + should get automapped (according to AutomapHostsOnResolve), + if we could return either an IPv4 or an IPv6 answer, prefer + an IPv4 answer. (Tor prefers IPv6 by default.) + **PreferSOCKSNoAuth**;; + Ordinarily, when an application offers both "username/password + authentication" and "no authentication" to Tor via SOCKS5, Tor + selects username/password authentication so that IsolateSOCKSAuth can + work. This can confuse some applications, if they offer a + username/password combination then get confused when asked for + one. You can disable this behavior, so that Tor will select "No + authentication" when IsolateSOCKSAuth is disabled, or when this + option is set. + **ExtendedErrors**;; + Return extended error code in the SOCKS reply. So far, the possible + errors are: + + X'F0' Onion Service Descriptor Can Not be Found + + The requested onion service descriptor can't be found on the + hashring and thus not reachable by the client. (v3 only) + + X'F1' Onion Service Descriptor Is Invalid + + The requested onion service descriptor can't be parsed or + signature validation failed. (v3 only) + + X'F2' Onion Service Introduction Failed + + All introduction attempts failed either due to a combination of + NACK by the intro point or time out. (v3 only) + + X'F3' Onion Service Rendezvous Failed + + Every rendezvous circuit has timed out and thus the client is + unable to rendezvous with the service. (v3 only) + + X'F4' Onion Service Missing Client Authorization + + Client was able to download the requested onion service descriptor + but is unable to decrypt its content because it is missing client + authorization information. (v3 only) + + X'F5' Onion Service Wrong Client Authorization + + Client was able to download the requested onion service descriptor + but is unable to decrypt its content using the client + authorization information it has. This means the client access + were revoked. (v3 only) + + X'F6' Onion Service Invalid Address + + The given .onion address is invalid. In one of these cases this + error is returned: address checksum doesn't match, ed25519 public + key is invalid or the encoding is invalid. (v3 only) + + X'F7' Onion Service Introduction Timed Out + + Similar to X'F2' code but in this case, all introduction attempts + have failed due to a time out. (v3 only) + +// Anchor only for formatting, not visible in the man page. +[[SocksPortFlagsMisc]]:: + Flags are processed left to right. If flags conflict, the last flag on the + line is used, and all earlier flags are ignored. No error is issued for + conflicting flags. + +[[TokenBucketRefillInterval]] **TokenBucketRefillInterval** __NUM__ [**msec**|**second**]:: + Set the refill delay interval of Tor's token bucket to NUM milliseconds. + NUM must be between 1 and 1000, inclusive. When Tor is out of bandwidth, + on a connection or globally, it will wait up to this long before it tries + to use that connection again. + Note that bandwidth limits are still expressed in bytes per second: this + option only affects the frequency with which Tor checks to see whether + previously exhausted connections may read again. + Can not be changed while tor is running. (Default: 100 msec) + +[[TrackHostExits]] **TrackHostExits** __host__,__.domain__,__...__:: + For each value in the comma separated list, Tor will track recent + connections to hosts that match this value and attempt to reuse the same + exit node for each. If the value is prepended with a \'.\', it is treated as + matching an entire domain. If one of the values is just a \'.', it means + match everything. This option is useful if you frequently connect to sites + that will expire all your authentication cookies (i.e. log you out) if + your IP address changes. Note that this option does have the disadvantage + of making it more clear that a given history is associated with a single + user. However, most people who would wish to observe this will observe it + through cookies or other protocol-specific means anyhow. + +[[TrackHostExitsExpire]] **TrackHostExitsExpire** __NUM__:: + Since exit servers go up and down, it is desirable to expire the + association between host and exit server after NUM seconds. The default is + 1800 seconds (30 minutes). + +[[TransPort]] **TransPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: + Open this port to listen for transparent proxy connections. Set this to + 0 if you don't want to allow transparent proxy connections. Set the port + to "auto" to have Tor pick a port for you. This directive can be + specified multiple times to bind to multiple addresses/ports. If multiple + entries of this option are present in your configuration file, Tor will + perform stream isolation between listeners by default. See + <> for an explanation of isolation flags. + + + + TransPort requires OS support for transparent proxies, such as BSDs' pf or + Linux's IPTables. If you're planning to use Tor as a transparent proxy for + a network, you'll want to examine and change VirtualAddrNetwork from the + default setting. (Default: 0) + +[[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**:: + TransProxyType may only be enabled when there is transparent proxy listener + enabled. + + + + Set this to "TPROXY" if you wish to be able to use the TPROXY Linux module + to transparently proxy connections that are configured using the TransPort + option. Detailed information on how to configure the TPROXY + feature can be found in the Linux kernel source tree in the file + Documentation/networking/tproxy.txt. + + + + Set this option to "ipfw" to use the FreeBSD ipfw interface. + + + + On *BSD operating systems when using pf, set this to "pf-divert" to take + advantage of +divert-to+ rules, which do not modify the packets like + +rdr-to+ rules do. Detailed information on how to configure pf to use + +divert-to+ rules can be found in the pf.conf(5) manual page. On OpenBSD, + +divert-to+ is available to use on versions greater than or equal to + OpenBSD 4.4. + + + + Set this to "default", or leave it unconfigured, to use regular IPTables + on Linux, or to use pf +rdr-to+ rules on *BSD systems. + + + + (Default: "default") + +[[UpdateBridgesFromAuthority]] **UpdateBridgesFromAuthority** **0**|**1**:: + When set (along with UseBridges), Tor will try to fetch bridge descriptors + from the configured bridge authorities when feasible. It will fall back to + a direct request if the authority responds with a 404. (Default: 0) + +[[UseBridges]] **UseBridges** **0**|**1**:: + When set, Tor will fetch descriptors for each bridge listed in the "Bridge" + config lines, and use these relays as both entry guards and directory + guards. (Default: 0) + +[[UseEntryGuards]] **UseEntryGuards** **0**|**1**:: + If this option is set to 1, we pick a few long-term entry servers, and try + to stick with them. This is desirable because constantly changing servers + increases the odds that an adversary who owns some servers will observe a + fraction of your paths. Entry Guards can not be used by Directory + Authorities or Single Onion Services. In these cases, + this option is ignored. (Default: 1) + +[[UseGuardFraction]] **UseGuardFraction** **0**|**1**|**auto**:: + This option specifies whether clients should use the + guardfraction information found in the consensus during path + selection. If it's set to 'auto', clients will do what the + UseGuardFraction consensus parameter tells them to do. (Default: auto) + +//Out of order because it logically belongs after the UseEntryGuards option +[[GuardLifetime]] **GuardLifetime** __N__ **days**|**weeks**|**months**:: + If UseEntryGuards is set, minimum time to keep a guard on our guard list + before picking a new one. If less than one day, we use defaults from the + consensus directory. (Default: 0) + +//Out of order because it logically belongs after the UseEntryGuards option +[[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__:: + If UseEntryGuards is set to 1, we try to make sure we have at least NUM + routers to use as directory guards. If this option is set to 0, use the + value from the guard-n-primary-dir-guards-to-use consensus parameter, and + default to 3 if the consensus parameter isn't set. (Default: 0) + +//Out of order because it logically belongs after the UseEntryGuards option +[[NumEntryGuards]] **NumEntryGuards** __NUM__:: + If UseEntryGuards is set to 1, we will try to pick a total of NUM routers + as long-term entries for our circuits. If NUM is 0, we try to learn the + number from the guard-n-primary-guards-to-use consensus parameter, and + default to 1 if the consensus parameter isn't set. (Default: 0) + +//Out of order because it logically belongs after the UseEntryGuards option +[[NumPrimaryGuards]] **NumPrimaryGuards** __NUM__:: + If UseEntryGuards is set to 1, we will try to pick NUM routers for our + primary guard list, which is the set of routers we strongly prefer when + connecting to the Tor network. If NUM is 0, we try to learn the number from + the guard-n-primary-guards consensus parameter, and default to 3 if the + consensus parameter isn't set. (Default: 0) + +[[UseMicrodescriptors]] **UseMicrodescriptors** **0**|**1**|**auto**:: + Microdescriptors are a smaller version of the information that Tor needs + in order to build its circuits. Using microdescriptors makes Tor clients + download less directory information, thus saving bandwidth. Directory + caches need to fetch regular descriptors and microdescriptors, so this + option doesn't save any bandwidth for them. For legacy reasons, auto is + accepted, but it has the same effect as 1. (Default: auto) + +[[VirtualAddrNetworkIPv4]] **VirtualAddrNetworkIPv4** __IPv4Address__/__bits__ + + +[[VirtualAddrNetworkIPv6]] **VirtualAddrNetworkIPv6** [__IPv6Address__]/__bits__:: + When Tor needs to assign a virtual (unused) address because of a MAPADDRESS + command from the controller or the AutomapHostsOnResolve feature, Tor + picks an unassigned address from this range. (Defaults: + 127.192.0.0/10 and [FE80::]/10 respectively.) + + + + When providing proxy server service to a network of computers using a tool + like dns-proxy-tor, change the IPv4 network to "10.192.0.0/10" or + "172.16.0.0/12" and change the IPv6 network to "[FC00::]/7". + The default **VirtualAddrNetwork** address ranges on a + properly configured machine will route to the loopback or link-local + interface. The maximum number of bits for the network prefix is set to 104 + for IPv6 and 16 for IPv4. However, a wider network - smaller prefix length + - is preferable since it reduces the chances for an attacker to guess the + used IP. For local use, no change to the default VirtualAddrNetwork setting + is needed. + +== CIRCUIT TIMEOUT OPTIONS + +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + +The following options are useful for configuring timeouts related +to building Tor circuits and using them: + +[[CircuitsAvailableTimeout]] **CircuitsAvailableTimeout** __NUM__:: + Tor will attempt to keep at least one open, unused circuit available for + this amount of time. This option governs how long idle circuits are kept + open, as well as the amount of time Tor will keep a circuit open to each + of the recently used ports. This way when the Tor client is entirely + idle, it can expire all of its circuits, and then expire its TLS + connections. Note that the actual timeout value is uniformly randomized + from the specified value to twice that amount. (Default: 30 minutes; + Max: 24 hours) + +// Out of order because it logically belongs before the CircuitBuildTimeout option +[[LearnCircuitBuildTimeout]] **LearnCircuitBuildTimeout** **0**|**1**:: + If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1) + +[[CircuitBuildTimeout]] **CircuitBuildTimeout** __NUM__:: + Try for at most NUM seconds when building circuits. If the circuit isn't + open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this + value serves as the initial value to use before a timeout is learned. If + LearnCircuitBuildTimeout is 0, this value is the only value used. + (Default: 60 seconds) + +[[CircuitStreamTimeout]] **CircuitStreamTimeout** __NUM__:: + If non-zero, this option overrides our internal timeout schedule for how + many seconds until we detach a stream from a circuit and try a new circuit. + If your network is particularly slow, you might want to set this to a + number like 60. (Default: 0) + +[[SocksTimeout]] **SocksTimeout** __NUM__:: + Let a socks connection wait NUM seconds handshaking, and NUM seconds + unattached waiting for an appropriate circuit, before we fail it. (Default: + 2 minutes) + +== DORMANT MODE OPTIONS + +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + +Tor can enter dormant mode to conserve power and network bandwidth. +The following options control when Tor enters and leaves dormant mode: + +[[DormantCanceledByStartup]] **DormantCanceledByStartup** **0**|**1**:: + By default, Tor starts in active mode if it was active the last time + it was shut down, and in dormant mode if it was dormant. But if + this option is true, Tor treats every startup event as user + activity, and Tor will never start in Dormant mode, even if it has + been unused for a long time on previous runs. (Default: 0) + + + Note: Packagers and application developers should change the value of + this option only with great caution: it has the potential to + create spurious traffic on the network. This option should only + be used if Tor is started by an affirmative user activity (like + clicking on an applcation or running a command), and not if Tor + is launched for some other reason (for example, by a startup + process, or by an application that launches itself on every login.) + +[[DormantClientTimeout]] **DormantClientTimeout** __N__ **minutes**|**hours**|**days**|**weeks**:: + If Tor spends this much time without any client activity, + enter a dormant state where automatic circuits are not built, and + directory information is not fetched. + Does not affect servers or onion services. Must be at least 10 minutes. + (Default: 24 hours) + +[[DormantOnFirstStartup]] **DormantOnFirstStartup** **0**|**1**:: + If true, then the first time Tor starts up with a fresh DataDirectory, + it starts in dormant mode, and takes no actions until the user has made + a request. (This mode is recommended if installing a Tor client for a + user who might not actually use it.) If false, Tor bootstraps the first + time it is started, whether it sees a user request or not. + + + After the first time Tor starts, it begins in dormant mode if it was + dormant before, and not otherwise. (Default: 0) + +[[DormantTimeoutDisabledByIdleStreams]] **DormantTimeoutDisabledByIdleStreams** **0**|**1**:: + If true, then any open client stream (even one not reading or writing) + counts as client activity for the purpose of DormantClientTimeout. + If false, then only network activity counts. (Default: 1) + +== NODE SELECTION OPTIONS + +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + +The following options restrict the nodes that a tor client +(or onion service) can use while building a circuit. +These options can weaken your anonymity by making your client behavior +different from other Tor clients: + +[[EntryNodes]] **EntryNodes** __node__,__node__,__...__:: + A list of identity fingerprints and country codes of nodes + to use for the first hop in your normal circuits. + Normal circuits include all + circuits except for direct connections to directory servers. The Bridge + option overrides this option; if you have configured bridges and + UseBridges is 1, the Bridges are used as your entry nodes. + + + + The ExcludeNodes option overrides this option: any node listed in both + EntryNodes and ExcludeNodes is treated as excluded. See + <> for more information on how to specify nodes. + +[[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__:: + A list of identity fingerprints, country codes, and address + patterns of nodes to avoid when building a circuit. Country codes are + 2-letter ISO3166 codes, and must + be wrapped in braces; fingerprints may be preceded by a dollar sign. + (Example: + ExcludeNodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + + + By default, this option is treated as a preference that Tor is allowed + to override in order to keep working. + For example, if you try to connect to a hidden service, + but you have excluded all of the hidden service's introduction points, + Tor will connect to one of them anyway. If you do not want this + behavior, set the StrictNodes option (documented below). + + + + Note also that if you are a relay, this (and the other node selection + options below) only affects your own circuits that Tor builds for you. + Clients can still build circuits through you to any node. Controllers + can tell Tor to build circuits through any node. + + + + Country codes are case-insensitive. The code "\{??}" refers to nodes whose + country can't be identified. No country code, including \{??}, works if + no GeoIPFile can be loaded. See also the <> option below. + +// Out of order because it logically belongs after the ExcludeNodes option +[[ExcludeExitNodes]] **ExcludeExitNodes** __node__,__node__,__...__:: + A list of identity fingerprints, country codes, and address + patterns of nodes to never use when picking an exit node---that is, a + node that delivers traffic for you *outside* the Tor network. Note that any + node listed in ExcludeNodes is automatically considered to be part of this + list too. See + <> for more information on how to specify + nodes. See also the caveats on the <> option below. + +[[ExitNodes]] **ExitNodes** __node__,__node__,__...__:: + A list of identity fingerprints, country codes, and address + patterns of nodes to use as exit node---that is, a + node that delivers traffic for you *outside* the Tor network. See + <> for more information on how to specify nodes. + + + + Note that if you list too few nodes here, or if you exclude too many exit + nodes with ExcludeExitNodes, you can degrade functionality. For example, + if none of the exits you list allows traffic on port 80 or 443, you won't + be able to browse the web. + + + + Note also that not every circuit is used to deliver traffic *outside* of + the Tor network. It is normal to see non-exit circuits (such as those + used to connect to hidden services, those that do directory fetches, + those used for relay reachability self-tests, and so on) that end + at a non-exit node. To + keep a node from being used entirely, see <> and <>. + + + + The ExcludeNodes option overrides this option: any node listed in both + ExitNodes and ExcludeNodes is treated as excluded. + + + + The .exit address notation, if enabled via MapAddress, overrides + this option. + +[[GeoIPExcludeUnknown]] **GeoIPExcludeUnknown** **0**|**1**|**auto**:: + If this option is set to 'auto', then whenever any country code is set in + ExcludeNodes or ExcludeExitNodes, all nodes with unknown country (\{??} and + possibly \{A1}) are treated as excluded as well. If this option is set to + '1', then all unknown countries are treated as excluded in ExcludeNodes + and ExcludeExitNodes. This option has no effect when a GeoIP file isn't + configured or can't be found. (Default: auto) + +[[HSLayer2Nodes]] **HSLayer2Nodes** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, country codes, and + address patterns of nodes that are allowed to be used as the + second hop in all client or service-side Onion Service circuits. + This option mitigates attacks where the adversary runs middle nodes + and induces your client or service to create many circuits, in order + to discover your primary guard node. + (Default: Any node in the network may be used in the second hop.) + + + (Example: + HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + + + When this is set, the resulting hidden service paths will + look like: + + + C - G - L2 - M - Rend + + C - G - L2 - M - HSDir + + C - G - L2 - M - Intro + + S - G - L2 - M - Rend + + S - G - L2 - M - HSDir + + S - G - L2 - M - Intro + + + + where C is this client, S is the service, G is the Guard node, + L2 is a node from this option, and M is a random middle node. + Rend, HSDir, and Intro point selection is not affected by this + option. + + + This option may be combined with HSLayer3Nodes to create + paths of the form: + + + C - G - L2 - L3 - Rend + + C - G - L2 - L3 - M - HSDir + + C - G - L2 - L3 - M - Intro + + S - G - L2 - L3 - M - Rend + + S - G - L2 - L3 - HSDir + + S - G - L2 - L3 - Intro + + + + ExcludeNodes have higher priority than HSLayer2Nodes, + which means that nodes specified in ExcludeNodes will not be + picked. + + + When either this option or HSLayer3Nodes are set, the /16 subnet + and node family restrictions are removed for hidden service + circuits. Additionally, we allow the guard node to be present + as the Rend, HSDir, and IP node, and as the hop before it. This + is done to prevent the adversary from inferring information + about our guard, layer2, and layer3 node choices at later points + in the path. + + + This option is meant to be managed by a Tor controller such as + https://github.com/mikeperry-tor/vanguards that selects and + updates this set of nodes for you. Hence it does not do load + balancing if fewer than 20 nodes are selected, and if no nodes in + HSLayer2Nodes are currently available for use, Tor will not work. + Please use extreme care if you are setting this option manually. + +[[HSLayer3Nodes]] **HSLayer3Nodes** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, country codes, and + address patterns of nodes that are allowed to be used as the + third hop in all client and service-side Onion Service circuits. + This option mitigates attacks where the adversary runs middle nodes + and induces your client or service to create many circuits, in order + to discover your primary or Layer2 guard nodes. + (Default: Any node in the network may be used in the third hop.) + + + (Example: + HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + + + When this is set by itself, the resulting hidden service paths + will look like: + + C - G - M - L3 - Rend + + C - G - M - L3 - M - HSDir + + C - G - M - L3 - M - Intro + + S - G - M - L3 - M - Rend + + S - G - M - L3 - HSDir + + S - G - M - L3 - Intro + + where C is this client, S is the service, G is the Guard node, + L2 is a node from this option, and M is a random middle node. + Rend, HSDir, and Intro point selection is not affected by this + option. + + + While it is possible to use this option by itself, it should be + combined with HSLayer2Nodes to create paths of the form: + + + C - G - L2 - L3 - Rend + + C - G - L2 - L3 - M - HSDir + + C - G - L2 - L3 - M - Intro + + S - G - L2 - L3 - M - Rend + + S - G - L2 - L3 - HSDir + + S - G - L2 - L3 - Intro + + + + ExcludeNodes have higher priority than HSLayer3Nodes, + which means that nodes specified in ExcludeNodes will not be + picked. + + + When either this option or HSLayer2Nodes are set, the /16 subnet + and node family restrictions are removed for hidden service + circuits. Additionally, we allow the guard node to be present + as the Rend, HSDir, and IP node, and as the hop before it. This + is done to prevent the adversary from inferring information + about our guard, layer2, and layer3 node choices at later points + in the path. + + + This option is meant to be managed by a Tor controller such as + https://github.com/mikeperry-tor/vanguards that selects and + updates this set of nodes for you. Hence it does not do load + balancing if fewer than 20 nodes are selected, and if no nodes in + HSLayer3Nodes are currently available for use, Tor will not work. + Please use extreme care if you are setting this option manually. + +[[MiddleNodes]] **MiddleNodes** __node__,__node__,__...__:: + A list of identity fingerprints and country codes of nodes + to use for "middle" hops in your normal circuits. + Normal circuits include all circuits except for direct connections + to directory servers. Middle hops are all hops other than exit and entry. ++ + This is an **experimental** feature that is meant to be used by researchers + and developers to test new features in the Tor network safely. Using it + without care will strongly influence your anonymity. Other tor features may + not work with MiddleNodes. This feature might get removed in the future. ++ + The HSLayer2Node and HSLayer3Node options override this option for onion + service circuits, if they are set. The vanguards addon will read this + option, and if set, it will set HSLayer2Nodes and HSLayer3Nodes to nodes + from this set. ++ + The ExcludeNodes option overrides this option: any node listed in both + MiddleNodes and ExcludeNodes is treated as excluded. See + the <> for more information on how to specify nodes. + +[[NodeFamily]] **NodeFamily** __node__,__node__,__...__:: + The Tor servers, defined by their identity fingerprints, + constitute a "family" of similar or co-administered servers, so never use + any two of them in the same circuit. Defining a NodeFamily is only needed + when a server doesn't list the family itself (with MyFamily). This option + can be used multiple times; each instance defines a separate family. In + addition to nodes, you can also list IP address and ranges and country + codes in {curly braces}. See <> for more + information on how to specify nodes. + +[[StrictNodes]] **StrictNodes** **0**|**1**:: + If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes option + as a requirement to follow for all the circuits you generate, even if + doing so will break functionality for you (StrictNodes does not apply to + ExcludeExitNodes, ExitNodes, MiddleNodes, or MapAddress). If StrictNodes + is set to 0, Tor will still try to avoid nodes in the ExcludeNodes list, + but it will err on the side of avoiding unexpected errors. + Specifically, StrictNodes 0 tells Tor that it is okay to use an excluded + node when it is *necessary* to perform relay reachability self-tests, + connect to a hidden service, provide a hidden service to a client, + fulfill a .exit request, upload directory information, or download + directory information. (Default: 0) + +[[server-options]] +== SERVER OPTIONS + +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + +The following options are useful only for servers (that is, if ORPort +is non-zero): + +[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Limits the max number of bytes sent and received within a set time period + using a given calculation rule (see <> and <>). + Useful if you need to stay under a specific bandwidth. By default, the + number used for calculation is the max of either the bytes sent or + received. For example, with AccountingMax set to 1 TByte, a server + could send 900 GBytes and receive 800 GBytes and continue running. + It will only hibernate once one of the two reaches 1 TByte. This can + be changed to use the sum of the both bytes received and sent by setting + the AccountingRule option to "sum" (total bandwidth in/out). When the + number of bytes remaining gets low, Tor will stop accepting new connections + and circuits. When the number of bytes is exhausted, Tor will hibernate + until some time in the next accounting period. To prevent all servers + from waking at the same time, Tor will also wait until a random point + in each period before waking up. If you have bandwidth cost issues, + enabling hibernation is preferable to setting a low bandwidth, since + it provides users with a collection of fast servers that are up some + of the time, which is more useful than a set of slow servers that are + always "available". + + + + Note that (as also described in the Bandwidth section) Tor uses + powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not + one billion. Be careful: some internet service providers might count + GBytes differently. + +[[AccountingRule]] **AccountingRule** **sum**|**max**|**in**|**out**:: + How we determine when our AccountingMax has been reached (when we + should hibernate) during a time interval. Set to "max" to calculate + using the higher of either the sent or received bytes (this is the + default functionality). Set to "sum" to calculate using the sent + plus received bytes. Set to "in" to calculate using only the + received bytes. Set to "out" to calculate using only the sent bytes. + (Default: max) + +[[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__:: + Specify how long accounting periods last. If **month** is given, + each accounting period runs from the time __HH:MM__ on the __dayth__ day of one + month to the same day and time of the next. The relay will go at full speed, + use all the quota you specify, then hibernate for the rest of the period. (The + day must be between 1 and 28.) If **week** is given, each accounting period + runs from the time __HH:MM__ of the __dayth__ day of one week to the same day + and time of the next week, with Monday as day 1 and Sunday as day 7. If **day** + is given, each accounting period runs from the time __HH:MM__ each day to the + same time on the next day. All times are local, and given in 24-hour time. + (Default: "month 1 0:00") + +[[Address]] **Address** __address__:: + The IPv4 address of this server, or a fully qualified domain name of + this server that resolves to an IPv4 address. You can leave this + unset, and Tor will try to guess your IPv4 address. This IPv4 + address is the one used to tell clients and other servers where to + find your Tor server; it doesn't affect the address that your server + binds to. To bind to a different address, use the ORPort and + OutboundBindAddress options. + +[[AssumeReachable]] **AssumeReachable** **0**|**1**:: + This option is used when bootstrapping a new Tor network. If set to 1, + don't do self-reachability testing; just upload your server descriptor + immediately. (Default: 0) + +[[AssumeReachableIPv6]] **AssumeReachableIPv6** **0**|**1**|**auto**:: + Like **AssumeReachable**, but affects only the relay's own IPv6 ORPort. + If this value is set to "auto", then Tor will look at **AssumeReachable** + instead. (Default: auto) + +[[BridgeRelay]] **BridgeRelay** **0**|**1**:: + Sets the relay to act as a "bridge" with respect to relaying connections + from bridge users to the Tor network. It mainly causes Tor to publish a + server descriptor to the bridge database, rather than + to the public directory authorities. + + + + Note: make sure that no MyFamily lines are present in your torrc when + relay is configured in bridge mode. + +//Out of order because it logically belongs after BridgeRelay. +[[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**:: + When this option is enabled and BridgeRelay is also enabled, and we have + GeoIP data, Tor keeps a per-country count of how many client + addresses have contacted it so that it can help the bridge authority guess + which countries have blocked access to it. If ExtraInfoStatistics is + enabled, it will be published as part of the extra-info document. + (Default: 1) + +//Out of order because it logically belongs after BridgeRelay. +[[BridgeDistribution]] **BridgeDistribution** __string__:: + If set along with BridgeRelay, Tor will include a new line in its + bridge descriptor which indicates to the BridgeDB service how it + would like its bridge address to be given out. Set it to "none" if + you want BridgeDB to avoid distributing your bridge address, or "any" to + let BridgeDB decide. (Default: any) + +[[ContactInfo]] **ContactInfo** __email_address__:: + Administrative contact information for this relay or bridge. This line + can be used to contact you if your relay or bridge is misconfigured or + something else goes wrong. Note that we archive and publish all + descriptors containing these lines and that Google indexes them, so + spammers might also collect them. You may want to obscure the fact + that it's an email address and/or generate a new address for this + purpose. + + + + ContactInfo **must** be set to a working address if you run more than one + relay or bridge. (Really, everybody running a relay or bridge should set + it.) + +[[DisableOOSCheck]] **DisableOOSCheck** **0**|**1**:: + This option disables the code that closes connections when Tor notices + that it is running low on sockets. Right now, it is on by default, + since the existing out-of-sockets mechanism tends to kill OR connections + more than it should. (Default: 1) + +[[ExitPolicy]] **ExitPolicy** __policy__,__policy__,__...__:: + Set an exit policy for this server. Each policy is of the form + "**accept[6]**|**reject[6]** __ADDR__[/__MASK__][:__PORT__]". If /__MASK__ is + omitted then this policy just applies to the host given. Instead of giving + a host or network you can also use "\*" to denote the universe (0.0.0.0/0 + and ::/0), or \*4 to denote all IPv4 addresses, and \*6 to denote all IPv6 + addresses. + __PORT__ can be a single port number, an interval of ports + "__FROM_PORT__-__TO_PORT__", or "\*". If __PORT__ is omitted, that means + "\*". + + + + For example, "accept 18.7.22.69:\*,reject 18.0.0.0/8:\*,accept \*:\*" would + reject any IPv4 traffic destined for MIT except for web.mit.edu, and accept + any other IPv4 or IPv6 traffic. + + + + Tor also allows IPv6 exit policy entries. For instance, "reject6 [FC00::]/7:\*" + rejects all destinations that share 7 most significant bit prefix with + address FC00::. Respectively, "accept6 [C000::]/3:\*" accepts all destinations + that share 3 most significant bit prefix with address C000::. + + + + accept6 and reject6 only produce IPv6 exit policy entries. Using an IPv4 + address with accept6 or reject6 is ignored and generates a warning. + accept/reject allows either IPv4 or IPv6 addresses. Use \*4 as an IPv4 + wildcard address, and \*6 as an IPv6 wildcard address. accept/reject * + expands to matching IPv4 and IPv6 wildcard address rules. + + + + To specify all IPv4 and IPv6 internal and link-local networks (including + 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, + 172.16.0.0/12, [::]/8, [FC00::]/7, [FE80::]/10, [FEC0::]/10, [FF00::]/8, + and [::]/127), you can use the "private" alias instead of an address. + ("private" always produces rules for IPv4 and IPv6 addresses, even when + used with accept6/reject6.) + + + + Private addresses are rejected by default (at the beginning of your exit + policy), along with any configured primary public IPv4 and IPv6 addresses. + These private addresses are rejected unless you set the + ExitPolicyRejectPrivate config option to 0. For example, once you've done + that, you could allow HTTP to 127.0.0.1 and block all other connections to + internal networks with "accept 127.0.0.1:80,reject private:\*", though that + may also allow connections to your own computer that are addressed to its + public (external) IP address. See RFC 1918 and RFC 3330 for more details + about internal and reserved IP address space. See + <> if you want to block every address on the + relay, even those that aren't advertised in the descriptor. + + + + This directive can be specified multiple times so you don't have to put it + all on one line. + + + + Policies are considered first to last, and the first match wins. If you + want to allow the same ports on IPv4 and IPv6, write your rules using + accept/reject \*. If you want to allow different ports on IPv4 and IPv6, + write your IPv6 rules using accept6/reject6 \*6, and your IPv4 rules using + accept/reject \*4. If you want to \_replace_ the default exit policy, end + your exit policy with either a reject \*:* or an accept \*:*. Otherwise, + you're \_augmenting_ (prepending to) the default exit policy. + + + + If you want to use a reduced exit policy rather than the default exit + policy, set "ReducedExitPolicy 1". If you want to _replace_ the default + exit policy with your custom exit policy, end your exit policy with either + a reject *:* or an accept *:*. Otherwise, you're _augmenting_ (prepending + to) the default or reduced exit policy. + + + + The default exit policy is: + + reject *:25 + reject *:119 + reject *:135-139 + reject *:445 + reject *:563 + reject *:1214 + reject *:4661-4666 + reject *:6346-6429 + reject *:6699 + reject *:6881-6999 + accept *:* + +// Anchor only for formatting, not visible in the man page. +[[ExitPolicyDefault]]:: + Since the default exit policy uses accept/reject *, it applies to both + IPv4 and IPv6 addresses. + +[[ExitPolicyRejectLocalInterfaces]] **ExitPolicyRejectLocalInterfaces** **0**|**1**:: + Reject all IPv4 and IPv6 addresses that the relay knows about, at the + beginning of your exit policy. This includes any OutboundBindAddress, the + bind addresses of any port options, such as ControlPort or DNSPort, and any + public IPv4 and IPv6 addresses on any interface on the relay. (If IPv6Exit + is not set, all IPv6 addresses will be rejected anyway.) + See above entry on <>. + This option is off by default, because it lists all public relay IP + addresses in the ExitPolicy, even those relay operators might prefer not + to disclose. + (Default: 0) + +[[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**:: + Reject all private (local) networks, along with the relay's advertised + public IPv4 and IPv6 addresses, at the beginning of your exit policy. + See above entry on <>. + (Default: 1) + +[[ExitRelay]] **ExitRelay** **0**|**1**|**auto**:: + Tells Tor whether to run as an exit relay. If Tor is running as a + non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to + exit according to the ExitPolicy option, the ReducedExitPolicy option, + or the default ExitPolicy (if no other exit policy option is specified). + + + + If ExitRelay is set to 0, no traffic is allowed to exit, and the + ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored. + + + + If ExitRelay is set to "auto", then Tor checks the ExitPolicy, + ReducedExitPolicy, and IPv6Exit options. If at least one of these options + is set, Tor behaves as if ExitRelay were set to 1. If none of these exit + policy options are set, Tor behaves as if ExitRelay were set to 0. + (Default: auto) + +[[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**:: + When this option is enabled, Tor will connect to relays on localhost, + RFC1918 addresses, and so on. In particular, Tor will make direct OR + connections, and Tor routers allow EXTEND requests, to these private + addresses. (Tor will always allow connections to bridges, proxies, and + pluggable transports configured on private addresses.) Enabling this + option can create security issues; you should probably leave it off. + (Default: 0) + +[[GeoIPFile]] **GeoIPFile** __filename__:: + A filename containing IPv4 GeoIP data, for use with by-country statistics. + +[[GeoIPv6File]] **GeoIPv6File** __filename__:: + A filename containing IPv6 GeoIP data, for use with by-country statistics. + +[[HeartbeatPeriod]] **HeartbeatPeriod** __N__ **minutes**|**hours**|**days**|**weeks**:: + Log a heartbeat message every **HeartbeatPeriod** seconds. This is + a log level __notice__ message, designed to let you know your Tor + server is still alive and doing useful things. Settings this + to 0 will disable the heartbeat. Otherwise, it must be at least 30 + minutes. (Default: 6 hours) + +[[IPv6Exit]] **IPv6Exit** **0**|**1**:: + If set, and we are an exit node, allow clients to use us for IPv6 traffic. + When this option is set and ExitRelay is auto, we act as if ExitRelay + is 1. (Default: 0) + +[[KeyDirectory]] **KeyDirectory** __DIR__:: + Store secret keys in DIR. Can not be changed while tor is + running. + (Default: the "keys" subdirectory of DataDirectory.) + +[[KeyDirectoryGroupReadable]] **KeyDirectoryGroupReadable** **0**|**1**|**auto**:: + If this option is set to 0, don't allow the filesystem group to read the + KeyDirectory. If the option is set to 1, make the KeyDirectory readable + by the default GID. If the option is "auto", then we use the + setting for DataDirectoryGroupReadable when the KeyDirectory is the + same as the DataDirectory, and 0 otherwise. (Default: auto) + +[[MainloopStats]] **MainloopStats** **0**|**1**:: + Log main loop statistics every **HeartbeatPeriod** seconds. This is a log + level __notice__ message designed to help developers instrumenting Tor's + main event loop. (Default: 0) + +[[MaxMemInQueues]] **MaxMemInQueues** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: + This option configures a threshold above which Tor will assume that it + needs to stop queueing or buffering data because it's about to run out of + memory. If it hits this threshold, it will begin killing circuits until + it has recovered at least 10% of this memory. Do not set this option too + low, or your relay may be unreliable under load. This option only + affects some queues, so the actual process size will be larger than + this. If this option is set to 0, Tor will try to pick a reasonable + default based on your system's physical memory. (Default: 0) + +[[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]:: + If we have more onionskins queued for processing than we can process in + this amount of time, reject new ones. (Default: 1750 msec) + +[[MyFamily]] **MyFamily** __fingerprint__,__fingerprint__,...:: + Declare that this Tor relay is controlled or administered by a group or + organization identical or similar to that of the other relays, defined by + their (possibly $-prefixed) identity fingerprints. + This option can be repeated many times, for + convenience in defining large families: all fingerprints in all MyFamily + lines are merged into one list. + When two relays both declare that they are in the + same \'family', Tor clients will not use them in the same circuit. (Each + relay only needs to list the other servers in its family; it doesn't need to + list itself, but it won't hurt if it does.) Do not list any bridge relay as it would + compromise its concealment. + + + + If you run more than one relay, the MyFamily option on each relay + **must** list all other relays, as described above. + + + + Note: do not use MyFamily when configuring your Tor instance as a + bridge. + +[[Nickname]] **Nickname** __name__:: + Set the server's nickname to \'name'. Nicknames must be between 1 and 19 + characters inclusive, and must contain only the characters [a-zA-Z0-9]. + If not set, **Unnamed** will be used. Relays can always be uniquely identified + by their identity fingerprints. + +[[NumCPUs]] **NumCPUs** __num__:: + How many processes to use at once for decrypting onionskins and other + parallelizable operations. If this is set to 0, Tor will try to detect + how many CPUs you have, defaulting to 1 if it can't tell. (Default: 0) + +[[OfflineMasterKey]] **OfflineMasterKey** **0**|**1**:: + If non-zero, the Tor relay will never generate or load its master secret + key. Instead, you'll have to use "tor --keygen" to manage the permanent + ed25519 master identity key, as well as the corresponding temporary + signing keys and certificates. (Default: 0) + +[[ORPort]] **ORPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]:: + Advertise this port to listen for connections from Tor clients and + servers. This option is required to be a Tor server. + Set it to "auto" to have Tor pick a port for you. Set it to 0 to not + run an ORPort at all. This option can occur more than once. (Default: 0) + + + + Tor recognizes these flags on each ORPort: + **NoAdvertise**;; + By default, we bind to a port and tell our users about it. If + NoAdvertise is specified, we don't advertise, but listen anyway. This + can be useful if the port everybody will be connecting to (for + example, one that's opened on our firewall) is somewhere else. + **NoListen**;; + By default, we bind to a port and tell our users about it. If + NoListen is specified, we don't bind, but advertise anyway. This + can be useful if something else (for example, a firewall's port + forwarding configuration) is causing connections to reach us. + **IPv4Only**;; + If the address is absent, or resolves to both an IPv4 and an IPv6 + address, only listen to the IPv4 address. + **IPv6Only**;; + If the address is absent, or resolves to both an IPv4 and an IPv6 + address, only listen to the IPv6 address. + +// Anchor only for formatting, not visible in the man page. +[[ORPortFlagsExclusive]]:: + For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and + IPv4Only and IPv6Only are mutually exclusive. + +[[PublishServerDescriptor]] **PublishServerDescriptor** **0**|**1**|**v3**|**bridge**,**...**:: + This option specifies which descriptors Tor will publish when acting as + a relay. You can + choose multiple arguments, separated by commas. + + + + If this option is set to 0, Tor will not publish its + descriptors to any directories. (This is useful if you're testing + out your server, or if you're using a Tor controller that handles + directory publishing for you.) Otherwise, Tor will publish its + descriptors of all type(s) specified. The default is "1", which + means "if running as a relay or bridge, publish descriptors to the + appropriate authorities". Other possibilities are "v3", meaning + "publish as if you're a relay", and "bridge", meaning "publish as + if you're a bridge". + +[[ReducedExitPolicy]] **ReducedExitPolicy** **0**|**1**:: + If set, use a reduced exit policy rather than the default one. + + + + The reduced exit policy is an alternative to the default exit policy. It + allows as many Internet services as possible while still blocking the + majority of TCP ports. Currently, the policy allows approximately 65 ports. + This reduces the odds that your node will be used for peer-to-peer + applications. + + + + The reduced exit policy is: + + accept *:20-21 + accept *:22 + accept *:23 + accept *:43 + accept *:53 + accept *:79 + accept *:80-81 + accept *:88 + accept *:110 + accept *:143 + accept *:194 + accept *:220 + accept *:389 + accept *:443 + accept *:464 + accept *:465 + accept *:531 + accept *:543-544 + accept *:554 + accept *:563 + accept *:587 + accept *:636 + accept *:706 + accept *:749 + accept *:873 + accept *:902-904 + accept *:981 + accept *:989-990 + accept *:991 + accept *:992 + accept *:993 + accept *:994 + accept *:995 + accept *:1194 + accept *:1220 + accept *:1293 + accept *:1500 + accept *:1533 + accept *:1677 + accept *:1723 + accept *:1755 + accept *:1863 + accept *:2082 + accept *:2083 + accept *:2086-2087 + accept *:2095-2096 + accept *:2102-2104 + accept *:3128 + accept *:3389 + accept *:3690 + accept *:4321 + accept *:4643 + accept *:5050 + accept *:5190 + accept *:5222-5223 + accept *:5228 + accept *:5900 + accept *:6660-6669 + accept *:6679 + accept *:6697 + accept *:8000 + accept *:8008 + accept *:8074 + accept *:8080 + accept *:8082 + accept *:8087-8088 + accept *:8232-8233 + accept *:8332-8333 + accept *:8443 + accept *:8888 + accept *:9418 + accept *:9999 + accept *:10000 + accept *:11371 + accept *:19294 + accept *:19638 + accept *:50002 + accept *:64738 + reject *:* + + (Default: 0) + +[[RefuseUnknownExits]] **RefuseUnknownExits** **0**|**1**|**auto**:: + Prevent nodes that don't appear in the consensus from exiting using this + relay. If the option is 1, we always block exit attempts from such + nodes; if it's 0, we never do, and if the option is "auto", then we do + whatever the authorities suggest in the consensus (and block if the consensus + is quiet on the issue). (Default: auto) + +[[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**:: + If this option is false, Tor exits immediately if there are problems + parsing the system DNS configuration or connecting to nameservers. + Otherwise, Tor continues to periodically retry the system nameservers until + it eventually succeeds. (Default: 1) + +[[ServerDNSAllowNonRFC953Hostnames]] **ServerDNSAllowNonRFC953Hostnames** **0**|**1**:: + When this option is disabled, Tor does not try to resolve hostnames + containing illegal characters (like @ and :) rather than sending them to an + exit node to be resolved. This helps trap accidental attempts to resolve + URLs and so on. This option only affects name lookups that your server does + on behalf of clients. (Default: 0) + +[[ServerDNSDetectHijacking]] **ServerDNSDetectHijacking** **0**|**1**:: + When this option is set to 1, we will test periodically to determine + whether our local nameservers have been configured to hijack failing DNS + requests (usually to an advertising site). If they are, we will attempt to + correct this. This option only affects name lookups that your server does + on behalf of clients. (Default: 1) + +[[ServerDNSRandomizeCase]] **ServerDNSRandomizeCase** **0**|**1**:: + When this option is set, Tor sets the case of each character randomly in + outgoing DNS requests, and makes sure that the case matches in DNS replies. + This so-called "0x20 hack" helps resist some types of DNS poisoning attack. + For more information, see "Increased DNS Forgery Resistance through + 0x20-Bit Encoding". This option only affects name lookups that your server + does on behalf of clients. (Default: 1) + +[[ServerDNSResolvConfFile]] **ServerDNSResolvConfFile** __filename__:: + Overrides the default DNS configuration with the configuration in + __filename__. The file format is the same as the standard Unix + "**resolv.conf**" file (7). This option, like all other ServerDNS options, + only affects name lookups that your server does on behalf of clients. + (Defaults to use the system DNS configuration or a localhost DNS service + in case no nameservers are found in a given configuration.) + +[[ServerDNSSearchDomains]] **ServerDNSSearchDomains** **0**|**1**:: + If set to 1, then we will search for addresses in the local search domain. + For example, if this system is configured to believe it is in + "example.com", and a client tries to connect to "www", the client will be + connected to "www.example.com". This option only affects name lookups that + your server does on behalf of clients. (Default: 0) + +[[ServerDNSTestAddresses]] **ServerDNSTestAddresses** __hostname__,__hostname__,__...__:: + When we're detecting DNS hijacking, make sure that these __valid__ addresses + aren't getting redirected. If they are, then our DNS is completely useless, + and we'll reset our exit policy to "reject \*:*". This option only affects + name lookups that your server does on behalf of clients. (Default: + "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org") + +[[ShutdownWaitLength]] **ShutdownWaitLength** __NUM__:: + When we get a SIGINT and we're a server, we begin shutting down: + we close listeners and start refusing new circuits. After **NUM** + seconds, we exit. If we get a second SIGINT, we exit immediately. + (Default: 30 seconds) + +[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**:: + For how long should each Ed25519 signing key be valid? Tor uses a + permanent master identity key that can be kept offline, and periodically + generates new "signing" keys that it uses online. This option + configures their lifetime. + (Default: 30 days) + +[[SSLKeyLifetime]] **SSLKeyLifetime** __N__ **minutes**|**hours**|**days**|**weeks**:: + When creating a link certificate for our outermost SSL handshake, + set its lifetime to this amount of time. If set to 0, Tor will choose + some reasonable random defaults. (Default: 0) + +== STATISTICS OPTIONS + +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + +Relays publish most statistics in a document called the +extra-info document. The following options affect the different +types of statistics that Tor relays collect and publish: + +[[CellStatistics]] **CellStatistics** **0**|**1**:: + Relays only. + When this option is enabled, Tor collects statistics about cell + processing (i.e. mean time a cell is spending in a queue, mean + number of cells in a queue and mean number of processed cells per + circuit) and writes them into disk every 24 hours. Onion router + operators may use the statistics for performance monitoring. + If ExtraInfoStatistics is enabled, it will published as part of + the extra-info document. (Default: 0) + +[[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**:: + Relays only. + When this option is enabled, Tor writes statistics on the amounts of + traffic it passes between itself and other relays to disk every 24 + hours. Enables relay operators to monitor how much their relay is + being used as middle node in the circuit. If ExtraInfoStatistics is + enabled, it will be published as part of the extra-info document. + (Default: 0) + +[[DirReqStatistics]] **DirReqStatistics** **0**|**1**:: + Relays and bridges only. + When this option is enabled, a Tor directory writes statistics on the + number and response time of network status requests to disk every 24 + hours. Enables relay and bridge operators to monitor how much their + server is being used by clients to learn about Tor network. + If ExtraInfoStatistics is enabled, it will published as part of + the extra-info document. (Default: 1) + +[[EntryStatistics]] **EntryStatistics** **0**|**1**:: + Relays only. + When this option is enabled, Tor writes statistics on the number of + directly connecting clients to disk every 24 hours. Enables relay + operators to monitor how much inbound traffic that originates from + Tor clients passes through their server to go further down the + Tor network. If ExtraInfoStatistics is enabled, it will be published + as part of the extra-info document. (Default: 0) + +[[ExitPortStatistics]] **ExitPortStatistics** **0**|**1**:: + Exit relays only. + When this option is enabled, Tor writes statistics on the number of + relayed bytes and opened stream per exit port to disk every 24 hours. + Enables exit relay operators to measure and monitor amounts of traffic + that leaves Tor network through their exit node. If ExtraInfoStatistics + is enabled, it will be published as part of the extra-info document. + (Default: 0) + +[[ExtraInfoStatistics]] **ExtraInfoStatistics** **0**|**1**:: + When this option is enabled, Tor includes previously gathered statistics in + its extra-info documents that it uploads to the directory authorities. + Disabling this option also removes bandwidth usage statistics, and + GeoIPFile and GeoIPv6File hashes from the extra-info file. Bridge + ServerTransportPlugin lines are always included in the extra-info file, + because they are required by BridgeDB. + (Default: 1) + +[[HiddenServiceStatistics]] **HiddenServiceStatistics** **0**|**1**:: + Relays only. + When this option is enabled, a Tor relay writes obfuscated + statistics on its role as hidden-service directory, introduction + point, or rendezvous point to disk every 24 hours. If ExtraInfoStatistics + is enabled, it will be published as part of the extra-info document. + (Default: 1) + +[[PaddingStatistics]] **PaddingStatistics** **0**|**1**:: + Relays and bridges only. + When this option is enabled, Tor collects statistics for padding cells + sent and received by this relay, in addition to total cell counts. + These statistics are rounded, and omitted if traffic is low. This + information is important for load balancing decisions related to padding. + If ExtraInfoStatistics is enabled, it will be published + as a part of the extra-info document. (Default: 1) + +== DIRECTORY SERVER OPTIONS + +The following options are useful only for directory servers. (Relays with +enough bandwidth automatically become directory servers; see <> for +details.) + +[[DirCache]] **DirCache** **0**|**1**:: + When this option is set, Tor caches all current directory documents except + extra info documents, and accepts client requests for them. If + **DownloadExtraInfo** is set, cached extra info documents are also cached. + Setting **DirPort** is not required for **DirCache**, because clients + connect via the ORPort by default. Setting either DirPort or BridgeRelay + and setting DirCache to 0 is not supported. (Default: 1) + +[[DirPolicy]] **DirPolicy** __policy__,__policy__,__...__:: + Set an entrance policy for this server, to limit who can connect to the + directory ports. The policies have the same form as exit policies above, + except that port specifiers are ignored. Any address not matched by + some entry in the policy is accepted. + +[[DirPort]] **DirPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]:: + If this option is nonzero, advertise the directory service on this port. + Set it to "auto" to have Tor pick a port for you. This option can occur + more than once, but only one advertised DirPort is supported: all + but one DirPort must have the **NoAdvertise** flag set. (Default: 0) + + + + The same flags are supported here as are supported by ORPort. + +[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__:: + When this option is set, it takes an HTML file and publishes it as "/" on + the DirPort. Now relay operators can provide a disclaimer without needing + to set up a separate webserver. There's a sample disclaimer in + contrib/operator-tools/tor-exit-notice.html. + +[[MaxConsensusAgeForDiffs]] **MaxConsensusAgeForDiffs** __N__ **minutes**|**hours**|**days**|**weeks**:: + When this option is nonzero, Tor caches will not try to generate + consensus diffs for any consensus older than this amount of time. + If this option is set to zero, Tor will pick a reasonable default from + the current networkstatus document. You should not set this + option unless your cache is severely low on disk space or CPU. + If you need to set it, keeping it above 3 or 4 hours will help clients + much more than setting it to zero. + (Default: 0) + + +== DENIAL OF SERVICE MITIGATION OPTIONS + +Tor has three built-in mitigation options that can be individually +enabled/disabled and fine-tuned, but by default Tor directory authorities will +define reasonable values for relays and no explicit configuration is required +to make use of these protections. The mitigations take place at relays, +and are as follows: + + 1. If a single client address makes too many concurrent connections (this is + configurable via DoSConnectionMaxConcurrentCount), hang up on further + connections. + + + 2. If a single client IP address (v4 or v6) makes circuits too quickly + (default values are more than 3 per second, with an allowed burst of 90, + see <> and + <>) while also having + too many connections open (default is 3, see + <>), + tor will refuse any new circuit (CREATE + cells) for the next while (random value between 1 and 2 hours). + + + 3. If a client asks to establish a rendezvous point to you directly (ex: + Tor2Web client), ignore the request. + +These defenses can be manually controlled by torrc options, but relays will +also take guidance from consensus parameters using these same names, so there's +no need to configure anything manually. In doubt, do not change those values. + +The values set by the consensus, if any, can be found here: +https://consensus-health.torproject.org/#consensusparams + +If any of the DoS mitigations are enabled, a heartbeat message will appear in +your log at NOTICE level which looks like: + + DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses. + 2238 connections closed. 8052 single hop clients refused. + +The following options are useful only for a public relay. They control the +Denial of Service mitigation subsystem described above. + +//Out of order because it logically belongs before the other DoSCircuitCreation options. +[[DoSCircuitCreationEnabled]] **DoSCircuitCreationEnabled** **0**|**1**|**auto**:: + + Enable circuit creation DoS mitigation. If set to 1 (enabled), tor will + cache client IPs along with statistics in order to detect circuit DoS + attacks. If an address is positively identified, tor will activate + defenses against the address. See <> + option for more details. This is a client to relay detection only. "auto" means + use the consensus parameter. If not defined in the consensus, the value is 0. + (Default: auto) + +[[DoSCircuitCreationBurst]] **DoSCircuitCreationBurst** __NUM__:: + + The allowed circuit creation burst per client IP address. If the circuit + rate and the burst are reached, a client is marked as executing a circuit + creation DoS. "0" means use the consensus parameter. If not defined in the + consensus, the value is 90. + (Default: 0) + +[[DoSCircuitCreationDefenseTimePeriod]] **DoSCircuitCreationDefenseTimePeriod** __N__ **seconds**|**minutes**|**hours**:: + + The base time period in seconds that the DoS defense is activated for. The + actual value is selected randomly for each activation from N+1 to 3/2 * N. + "0" means use the consensus parameter. If not defined in the consensus, + the value is 3600 seconds (1 hour). + (Default: 0) + +[[DoSCircuitCreationDefenseType]] **DoSCircuitCreationDefenseType** __NUM__:: + + This is the type of defense applied to a detected client address. The + possible values are: + + + 1: No defense. + + + 2: Refuse circuit creation for the DoSCircuitCreationDefenseTimePeriod period of time. + + + "0" means use the consensus parameter. If not defined in the consensus, the value is 2. + (Default: 0) + +[[DoSCircuitCreationMinConnections]] **DoSCircuitCreationMinConnections** __NUM__:: + + Minimum threshold of concurrent connections before a client address can be + flagged as executing a circuit creation DoS. In other words, once a client + address reaches the circuit rate and has a minimum of NUM concurrent + connections, a detection is positive. "0" means use the consensus + parameter. If not defined in the consensus, the value is 3. + (Default: 0) + +[[DoSCircuitCreationRate]] **DoSCircuitCreationRate** __NUM__:: + + The allowed circuit creation rate per second applied per client IP + address. If this option is 0, it obeys a consensus parameter. If not + defined in the consensus, the value is 3. + (Default: 0) + +//out of order because it logically belongs before the other DoSConnection options. +[[DoSConnectionEnabled]] **DoSConnectionEnabled** **0**|**1**|**auto**:: + + Enable the connection DoS mitigation. If set to 1 (enabled), for client + address only, this allows tor to mitigate against large number of + concurrent connections made by a single IP address. "auto" means use the + consensus parameter. If not defined in the consensus, the value is 0. + (Default: auto) + +[[DoSConnectionDefenseType]] **DoSConnectionDefenseType** __NUM__:: + + This is the type of defense applied to a detected client address for the + connection mitigation. The possible values are: + + + 1: No defense. + + + 2: Immediately close new connections. + + + "0" means use the consensus parameter. If not defined in the consensus, the value is 2. + (Default: 0) + +[[DoSConnectionMaxConcurrentCount]] **DoSConnectionMaxConcurrentCount** __NUM__:: + + The maximum threshold of concurrent connection from a client IP address. + Above this limit, a defense selected by DoSConnectionDefenseType is + applied. "0" means use the consensus parameter. If not defined in the + consensus, the value is 100. + (Default: 0) + +[[DoSRefuseSingleHopClientRendezvous]] **DoSRefuseSingleHopClientRendezvous** **0**|**1**|**auto**:: + + Refuse establishment of rendezvous points for single hop clients. In other + words, if a client directly connects to the relay and sends an + ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto" means use the + consensus parameter. If not defined in the consensus, the value is 0. + (Default: auto) + + +== DIRECTORY AUTHORITY SERVER OPTIONS + +The following options enable operation as a directory authority, and +control how Tor behaves as a directory authority. You should not need +to adjust any of them if you're running a regular relay or exit server +on the public Tor network. + +// Out of order because it logically belongs first in this section +[[AuthoritativeDirectory]] **AuthoritativeDirectory** **0**|**1**:: + When this option is set to 1, Tor operates as an authoritative directory + server. Instead of caching the directory, it generates its own list of + good servers, signs it, and sends that to the clients. Unless the clients + already have you listed as a trusted directory, you probably do not want + to set this option. + +//Out of order because it belongs with the AuthoritativeDirectory option. +[[BridgeAuthoritativeDir]] **BridgeAuthoritativeDir** **0**|**1**:: + When this option is set in addition to **AuthoritativeDirectory**, Tor + accepts and serves server descriptors, but it caches and serves the main + networkstatus documents rather than generating its own. (Default: 0) + +//Out of order because it belongs with the AuthoritativeDirectory option. +[[V3AuthoritativeDirectory]] **V3AuthoritativeDirectory** **0**|**1**:: + When this option is set in addition to **AuthoritativeDirectory**, Tor + generates version 3 network statuses and serves descriptors, etc as + described in dir-spec.txt file of https://spec.torproject.org/[torspec] + (for Tor clients and servers running at least 0.2.0.x). + +[[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: + Authoritative directories only. A set of address patterns for servers that + will be listed as bad exits in any network status document this authority + publishes, if **AuthDirListBadExits** is set. + + + + (The address pattern syntax here and in the options below + is the same as for exit policies, except that you don't need to say + "accept" or "reject", and ports are not needed.) + +[[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Authoritative directories only. If non-zero, always vote the + Fast flag for any relay advertising this amount of capacity or + more. (Default: 100 KBytes) + +[[AuthDirGuardBWGuarantee]] **AuthDirGuardBWGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Authoritative directories only. If non-zero, this advertised capacity + or more is always sufficient to satisfy the bandwidth requirement + for the Guard flag. (Default: 2 MBytes) + +[[AuthDirHasIPv6Connectivity]] **AuthDirHasIPv6Connectivity** **0**|**1**:: + Authoritative directories only. When set to 0, OR ports with an + IPv6 address are not included in the authority's votes. When set to 1, + IPv6 OR ports are tested for reachability like IPv4 OR ports. If the + reachability test succeeds, the authority votes for the IPv6 ORPort, and + votes Running for the relay. If the reachability test fails, the authority + does not vote for the IPv6 ORPort, and does not vote Running (Default: 0) + ++ + The content of the consensus depends on the number of voting authorities + that set AuthDirHasIPv6Connectivity: + + If no authorities set AuthDirHasIPv6Connectivity 1, there will be no + IPv6 ORPorts in the consensus. + + If a minority of authorities set AuthDirHasIPv6Connectivity 1, + unreachable IPv6 ORPorts will be removed from the consensus. But the + majority of IPv4-only authorities will still vote the relay as Running. + Reachable IPv6 ORPort lines will be included in the consensus + + If a majority of voting authorities set AuthDirHasIPv6Connectivity 1, + relays with unreachable IPv6 ORPorts will not be listed as Running. + Reachable IPv6 ORPort lines will be included in the consensus + (To ensure that any valid majority will vote relays with unreachable + IPv6 ORPorts not Running, 75% of authorities must set + AuthDirHasIPv6Connectivity 1.) + +[[AuthDirInvalid]] **AuthDirInvalid** __AddressPattern...__:: + Authoritative directories only. A set of address patterns for servers that + will never be listed as "valid" in any network status document that this + authority publishes. + +[[AuthDirListBadExits]] **AuthDirListBadExits** **0**|**1**:: + Authoritative directories only. If set to 1, this directory has some + opinion about which nodes are unsuitable as exit nodes. (Do not set this to + 1 unless you plan to list non-functioning exits as bad; otherwise, you are + effectively voting in favor of every declared exit as an exit.) + +[[AuthDirMaxServersPerAddr]] **AuthDirMaxServersPerAddr** __NUM__:: + Authoritative directories only. The maximum number of servers that we will + list as acceptable on a single IP address. Set this to "0" for "no limit". + (Default: 2) + +[[AuthDirPinKeys]] **AuthDirPinKeys** **0**|**1**:: + Authoritative directories only. If non-zero, do not allow any relay to + publish a descriptor if any other relay has reserved its + identity keypair. In all cases, Tor records every keypair it accepts + in a journal if it is new, or if it differs from the most recently + accepted pinning for one of the keys it contains. (Default: 1) + +[[AuthDirReject]] **AuthDirReject** __AddressPattern__...:: + Authoritative directories only. A set of address patterns for servers that + will never be listed at all in any network status document that this + authority publishes, or accepted as an OR address in any descriptor + submitted for publication by this authority. + +//Out of order because it logically belongs with the other CCs options. +[[AuthDirBadExitCCs]] **AuthDirBadExitCCs** __CC__,... + + +//Out of order because it logically belongs with the other CCs options. +[[AuthDirInvalidCCs]] **AuthDirInvalidCCs** __CC__,... + + + +[[AuthDirRejectRequestsUnderLoad]] **AuthDirRejectRequestsUnderLoad** **0**|**1**:: + If set, the directory authority will start rejecting directory requests + from non relay connections by sending a 503 error code if it is under + bandwidth pressure (reaching the configured limit if any). Relays will + always tried to be answered even if this is on. (Default: 1) + +[[AuthDirRejectCCs]] **AuthDirRejectCCs** __CC__,...:: + Authoritative directories only. These options contain a comma-separated + list of country codes such that any server in one of those country codes + will be marked as a bad exit/invalid for use, or rejected + entirely. + +[[AuthDirSharedRandomness]] **AuthDirSharedRandomness** **0**|**1**:: + Authoritative directories only. Switch for the shared random protocol. + If zero, the authority won't participate in the protocol. If non-zero + (default), the flag "shared-rand-participate" is added to the authority + vote indicating participation in the protocol. (Default: 1) + +[[AuthDirTestEd25519LinkKeys]] **AuthDirTestEd25519LinkKeys** **0**|**1**:: + Authoritative directories only. If this option is set to 0, then we treat + relays as "Running" if their RSA key is correct when we probe them, + regardless of their Ed25519 key. We should only ever set this option to 0 + if there is some major bug in Ed25519 link authentication that causes us + to label all the relays as not Running. (Default: 1) + +[[AuthDirTestReachability]] **AuthDirTestReachability** **0**|**1**:: + Authoritative directories only. If set to 1, then we periodically + check every relay we know about to see whether it is running. + If set to 0, we vote Running for every relay, and don't perform + these tests. (Default: 1) + +[[BridgePassword]] **BridgePassword** __Password__:: + If set, contains an HTTP authenticator that tells a bridge authority to + serve all requested bridge information. Used by the (only partially + implemented) "bridge community" design, where a community of bridge + relay operators all use an alternate bridge directory authority, + and their target user audience can periodically fetch the list of + available community bridges to stay up-to-date. (Default: not set) + +[[ConsensusParams]] **ConsensusParams** __STRING__:: + STRING is a space-separated list of key=value pairs that Tor will include + in the "params" line of its networkstatus vote. + +[[DirAllowPrivateAddresses]] **DirAllowPrivateAddresses** **0**|**1**:: + If set to 1, Tor will accept server descriptors with arbitrary "Address" + elements. Otherwise, if the address is not an IP address or is a private IP + address, it will reject the server descriptor. Additionally, Tor + will allow exit policies for private networks to fulfill Exit flag + requirements. (Default: 0) + +[[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: + V3 authoritative directories only. Configures the location of the + guardfraction file which contains information about how long relays + have been guards. (Default: unset) + +[[MinMeasuredBWsForAuthToIgnoreAdvertised]] **MinMeasuredBWsForAuthToIgnoreAdvertised** __N__:: + A total value, in abstract bandwidth units, describing how much + measured total bandwidth an authority should have observed on the network + before it will treat advertised bandwidths as wholly + unreliable. (Default: 500) + +[[MinUptimeHidServDirectoryV2]] **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: + Minimum uptime of a relay to be accepted as a hidden service directory + by directory authorities. (Default: 96 hours) + +[[RecommendedClientVersions]] **RecommendedClientVersions** __STRING__:: + STRING is a comma-separated list of Tor versions currently believed to be + safe for clients to use. This information is included in version 2 + directories. If this is not set then the value of **RecommendedVersions** + is used. When this is set then **VersioningAuthoritativeDirectory** should + be set too. + +[[RecommendedServerVersions]] **RecommendedServerVersions** __STRING__:: + STRING is a comma-separated list of Tor versions currently believed to be + safe for servers to use. This information is included in version 2 + directories. If this is not set then the value of **RecommendedVersions** + is used. When this is set then **VersioningAuthoritativeDirectory** should + be set too. + +[[RecommendedVersions]] **RecommendedVersions** __STRING__:: + STRING is a comma-separated list of Tor versions currently believed to be + safe. The list is included in each directory, and nodes which pull down the + directory learn whether they need to upgrade. This option can appear + multiple times: the values from multiple lines are spliced together. When + this is set then **VersioningAuthoritativeDirectory** should be set too. + +[[V3AuthDistDelay]] **V3AuthDistDelay** __N__ **seconds**|**minutes**|**hours**:: + V3 authoritative directories only. Configures the server's preferred delay + between publishing its consensus and signature and assuming it has all the + signatures from all the other authorities. Note that the actual time used + is not the server's preferred time, but the consensus of all preferences. + (Default: 5 minutes) + +[[V3AuthNIntervalsValid]] **V3AuthNIntervalsValid** __NUM__:: + V3 authoritative directories only. Configures the number of VotingIntervals + for which each consensus should be valid for. Choosing high numbers + increases network partitioning risks; choosing low numbers increases + directory traffic. Note that the actual number of intervals used is not the + server's preferred number, but the consensus of all preferences. Must be at + least 2. (Default: 3) + +[[V3AuthUseLegacyKey]] **V3AuthUseLegacyKey** **0**|**1**:: + If set, the directory authority will sign consensuses not only with its + own signing key, but also with a "legacy" key and certificate with a + different identity. This feature is used to migrate directory authority + keys in the event of a compromise. (Default: 0) + +[[V3AuthVoteDelay]] **V3AuthVoteDelay** __N__ **seconds**|**minutes**|**hours**:: + V3 authoritative directories only. Configures the server's preferred delay + between publishing its vote and assuming it has all the votes from all the + other authorities. Note that the actual time used is not the server's + preferred time, but the consensus of all preferences. (Default: 5 + minutes) + +[[V3AuthVotingInterval]] **V3AuthVotingInterval** __N__ **minutes**|**hours**:: + V3 authoritative directories only. Configures the server's preferred voting + interval. Note that voting will __actually__ happen at an interval chosen + by consensus from all the authorities' preferred intervals. This time + SHOULD divide evenly into a day. (Default: 1 hour) + +[[V3BandwidthsFile]] **V3BandwidthsFile** __FILENAME__:: + V3 authoritative directories only. Configures the location of the + bandwidth-authority generated file storing information on relays' measured + bandwidth capacities. To avoid inconsistent reads, bandwidth data should + be written to temporary file, then renamed to the configured filename. + (Default: unset) + +[[VersioningAuthoritativeDirectory]] **VersioningAuthoritativeDirectory** **0**|**1**:: + When this option is set to 1, Tor adds information on which versions of + Tor are still believed safe for use to the published directory. Each + version 1 authority is automatically a versioning authority; version 2 + authorities provide this service optionally. See <>, + <>, and <>. + +== HIDDEN SERVICE OPTIONS + +The following options are used to configure a hidden service. Some options +apply per service and some apply for the whole tor instance. + +The next section describes the per service options that can only be set +**after** the **HiddenServiceDir** directive + +**PER SERVICE OPTIONS:** + +[[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**:: + If set to 1, then connections to unrecognized ports do not cause the + current hidden service to close rendezvous circuits. (Setting this to 0 is + not an authorization mechanism; it is instead meant to be a mild + inconvenience to port-scanners.) (Default: 0) + +[[HiddenServiceAuthorizeClient]] **HiddenServiceAuthorizeClient** __auth-type__ __client-name__,__client-name__,__...__:: + If configured, the v2 hidden service is accessible for authorized clients + only. The auth-type can either be \'basic' for a general-purpose + authorization protocol or \'stealth' for a less scalable protocol that also + hides service activity from unauthorized clients. Only clients that are + listed here are authorized to access the hidden service. Valid client names + are 1 to 16 characters long and only use characters in A-Za-z0-9+-_ (no + spaces). If this option is set, the hidden service is not accessible for + clients without authorization any more. Generated authorization data can be + found in the hostname file. Clients need to put this authorization data in + their configuration file using **HidServAuth**. This option is only for v2 + services; v3 services configure client authentication in a subdirectory of + HiddenServiceDir instead (see <>). + +[[HiddenServiceDir]] **HiddenServiceDir** __DIRECTORY__:: + Store data files for a hidden service in DIRECTORY. Every hidden service + must have a separate directory. You may use this option multiple times to + specify multiple services. If DIRECTORY does not exist, Tor will create it. + Please note that you cannot add new Onion Service to already running Tor + instance if **Sandbox** is enabled. + (Note: in current versions of Tor, if DIRECTORY is a relative path, + it will be relative to the current + working directory of Tor instance, not to its DataDirectory. Do not + rely on this behavior; it is not guaranteed to remain the same in future + versions.) + +[[HiddenServiceDirGroupReadable]] **HiddenServiceDirGroupReadable** **0**|**1**:: + If this option is set to 1, allow the filesystem group to read the + hidden service directory and hostname file. If the option is set to 0, + only owner is able to read the hidden service directory. (Default: 0) + Has no effect on Windows. + +[[HiddenServiceEnableIntroDoSDefense]] **HiddenServiceEnableIntroDoSDefense** **0**|**1**:: + Enable DoS defense at the intropoint level. When this is enabled, the + rate and burst parameter (see below) will be sent to the intro point which + will then use them to apply rate limiting for introduction request to this + service. + + + The introduction point honors the consensus parameters except if this is + specifically set by the service operator using this option. The service + never looks at the consensus parameters in order to enable or disable this + defense. (Default: 0) + +//Out of order because it logically belongs after HiddenServiceEnableIntroDoSDefense. +[[HiddenServiceEnableIntroDoSBurstPerSec]] **HiddenServiceEnableIntroDoSBurstPerSec** __NUM__:: + The allowed client introduction burst per second at the introduction + point. If this option is 0, it is considered infinite and thus if + **HiddenServiceEnableIntroDoSDefense** is set, it then effectively + disables the defenses. (Default: 200) + +[[HiddenServiceEnableIntroDoSRatePerSec]] **HiddenServiceEnableIntroDoSRatePerSec** __NUM__:: + The allowed client introduction rate per second at the introduction + point. If this option is 0, it is considered infinite and thus if + **HiddenServiceEnableIntroDoSDefense** is set, it then effectively + disables the defenses. (Default: 25) + +[[HiddenServiceExportCircuitID]] **HiddenServiceExportCircuitID** __protocol__:: + The onion service will use the given protocol to expose the global circuit + identifier of each inbound client circuit. The only + protocol supported right now \'haproxy'. This option is only for v3 + services. (Default: none) + + + + The haproxy option works in the following way: when the feature is + enabled, the Tor process will write a header line when a client is connecting + to the onion service. The header will look like this: + + + + "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n" + + + + We encode the "global circuit identifier" as the last 32-bits of the first + IPv6 address. All other values in the header can safely be ignored. You can + compute the global circuit identifier using the following formula given the + IPv6 address "fc00:dead:beef:4dad::AABB:CCDD": + + + + global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) + 0xDD; + + + + In the case above, where the last 32-bits are 0xffffffff, the global circuit + identifier would be 4294967295. You can use this value together with Tor's + control port to terminate particular circuits using their global + circuit identifiers. For more information about this see control-spec.txt. + + + + The HAProxy version 1 protocol is described in detail at + https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt + +[[HiddenServiceOnionBalanceInstance]] **HiddenServiceOnionBalanceInstance** **0**|**1**:: + + If set to 1, this onion service becomes an OnionBalance instance and will + accept client connections destined to an OnionBalance frontend. In this + case, Tor expects to find a file named "ob_config" inside the + **HiddenServiceDir** directory with content: + + + MasterOnionAddress + + + where is the onion address of the OnionBalance + frontend (e.g. wrxdvcaqpuzakbfww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion). + + +[[HiddenServiceMaxStreams]] **HiddenServiceMaxStreams** __N__:: + The maximum number of simultaneous streams (connections) per rendezvous + circuit. The maximum value allowed is 65535. (Setting this to 0 will allow + an unlimited number of simultaneous streams.) (Default: 0) + +[[HiddenServiceMaxStreamsCloseCircuit]] **HiddenServiceMaxStreamsCloseCircuit** **0**|**1**:: + If set to 1, then exceeding **HiddenServiceMaxStreams** will cause the + offending rendezvous circuit to be torn down, as opposed to stream creation + requests that exceed the limit being silently ignored. (Default: 0) + +[[HiddenServiceNumIntroductionPoints]] **HiddenServiceNumIntroductionPoints** __NUM__:: + Number of introduction points the hidden service will have. You can't + have more than 10 for v2 service and 20 for v3. (Default: 3) + +[[HiddenServicePort]] **HiddenServicePort** __VIRTPORT__ [__TARGET__]:: + Configure a virtual port VIRTPORT for a hidden service. You may use this + option multiple times; each time applies to the service using the most + recent HiddenServiceDir. By default, this option maps the virtual port to + the same port on 127.0.0.1 over TCP. You may override the target port, + address, or both by specifying a target of addr, port, addr:port, or + **unix:**__path__. (You can specify an IPv6 target as [addr]:port. Unix + paths may be quoted, and may use standard C escapes.) + You may also have multiple lines with the same VIRTPORT: when a user + connects to that VIRTPORT, one of the TARGETs from those lines will be + chosen at random. Note that address-port pairs have to be comma-separated. + +[[HiddenServiceVersion]] **HiddenServiceVersion** **2**|**3**:: + A list of rendezvous service descriptor versions to publish for the hidden + service. Currently, versions 2 and 3 are supported. (Default: 3) + +[[RendPostPeriod]] **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: + Every time the specified period elapses, Tor uploads any rendezvous + service descriptors to the directory servers. This information is also + uploaded whenever it changes. Minimum value allowed is 10 minutes and + maximum is 3.5 days. This option is only for v2 services. + (Default: 1 hour) + + + +**PER INSTANCE OPTIONS:** + +[[HiddenServiceSingleHopMode]] **HiddenServiceSingleHopMode** **0**|**1**:: + **Experimental - Non Anonymous** Hidden Services on a tor instance in + HiddenServiceSingleHopMode make one-hop (direct) circuits between the onion + service server, and the introduction and rendezvous points. (Onion service + descriptors are still posted using 3-hop paths, to avoid onion service + directories blocking the service.) + This option makes every hidden service instance hosted by a tor instance a + Single Onion Service. One-hop circuits make Single Onion servers easily + locatable, but clients remain location-anonymous. However, the fact that a + client is accessing a Single Onion rather than a Hidden Service may be + statistically distinguishable. + + + + **WARNING:** Once a hidden service directory has been used by a tor + instance in HiddenServiceSingleHopMode, it can **NEVER** be used again for + a hidden service. It is best practice to create a new hidden service + directory, key, and address for each new Single Onion Service and Hidden + Service. It is not possible to run Single Onion Services and Hidden + Services from the same tor instance: they should be run on different + servers with different IP addresses. + + + + HiddenServiceSingleHopMode requires HiddenServiceNonAnonymousMode to be set + to 1. Since a Single Onion service is non-anonymous, you can not configure + a SOCKSPort on a tor instance that is running in + **HiddenServiceSingleHopMode**. Can not be changed while tor is running. + (Default: 0) + +//Out of order because it belongs after HiddenServiceSingleHopMode. +[[HiddenServiceNonAnonymousMode]] **HiddenServiceNonAnonymousMode** **0**|**1**:: + Makes hidden services non-anonymous on this tor instance. Allows the + non-anonymous HiddenServiceSingleHopMode. Enables direct connections in the + server-side hidden service protocol. If you are using this option, + you need to disable all client-side services on your Tor instance, + including setting SOCKSPort to "0". Can not be changed while tor is + running. (Default: 0) + +[[PublishHidServDescriptors]] **PublishHidServDescriptors** **0**|**1**:: + If set to 0, Tor will run any hidden services you configure, but it won't + advertise them to the rendezvous directory. This option is only useful if + you're using a Tor controller that handles hidserv publishing for you. + (Default: 1) + +[[client-authorization]] +== CLIENT AUTHORIZATION + +(Version 3 only) + +Service side: + + To configure client authorization on the service side, the + "/authorized_clients/" directory needs to exist. Each file + in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the + file name is irrelevant) and its content format MUST be: + + :: + + The supported are: "descriptor". The supported are: + "x25519". The is the base32 representation of + the raw key bytes only (32 bytes for x25519). + + Each file MUST contain one line only. Any malformed file will be + ignored. Client authorization will only be enabled for the service if tor + successfully loads at least one authorization file. + + Note that once you've configured client authorization, anyone else with the + address won't be able to access it from this point on. If no authorization is + configured, the service will be accessible to anyone with the onion address. + + Revoking a client can be done by removing their ".auth" file, however the + revocation will be in effect only after the tor process gets restarted even if + a SIGHUP takes place. + +Client side: + + To access a v3 onion service with client authorization as a client, make sure + you have ClientOnionAuthDir set in your torrc. Then, in the + directory, create an .auth_private file for the onion + service corresponding to this key (i.e. 'bob_onion.auth_private'). The + contents of the /.auth_private file should look like: + + <56-char-onion-addr-without-.onion-part>:descriptor:x25519: + +For more information, please see https://2019.www.torproject.org/docs/tor-onion-service.html.en#ClientAuthorization . + +== TESTING NETWORK OPTIONS + +The following options are used for running a testing Tor network. + +//Out of order because it logically belongs first in this section. +[[TestingTorNetwork]] **TestingTorNetwork** **0**|**1**:: + If set to 1, Tor adjusts default values of the configuration options below, + so that it is easier to set up a testing Tor network. May only be set if + non-default set of DirAuthorities is set. Cannot be unset while Tor is + running. + (Default: 0) + + + DirAllowPrivateAddresses 1 + EnforceDistinctSubnets 0 + AuthDirMaxServersPerAddr 0 + ClientBootstrapConsensusAuthorityDownloadInitialDelay 0 + ClientBootstrapConsensusFallbackDownloadInitialDelay 0 + ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay 0 + ClientDNSRejectInternalAddresses 0 + ClientRejectInternalAddresses 0 + CountPrivateBandwidth 1 + ExitPolicyRejectPrivate 0 + ExtendAllowPrivateAddresses 1 + V3AuthVotingInterval 5 minutes + V3AuthVoteDelay 20 seconds + V3AuthDistDelay 20 seconds + TestingV3AuthInitialVotingInterval 150 seconds + TestingV3AuthInitialVoteDelay 20 seconds + TestingV3AuthInitialDistDelay 20 seconds + TestingAuthDirTimeToLearnReachability 0 minutes + MinUptimeHidServDirectoryV2 0 minutes + TestingServerDownloadInitialDelay 0 + TestingClientDownloadInitialDelay 0 + TestingServerConsensusDownloadInitialDelay 0 + TestingClientConsensusDownloadInitialDelay 0 + TestingBridgeDownloadInitialDelay 10 + TestingBridgeBootstrapDownloadInitialDelay 0 + TestingClientMaxIntervalWithoutRequest 5 seconds + TestingDirConnectionMaxStall 30 seconds + TestingEnableConnBwEvent 1 + TestingEnableCellStatsEvent 1 + RendPostPeriod 2 minutes + +[[TestingAuthDirTimeToLearnReachability]] **TestingAuthDirTimeToLearnReachability** __N__ **seconds**|**minutes**|**hours**:: + After starting as an authority, do not make claims about whether routers + are Running until this much time has passed. Changing this requires + that **TestingTorNetwork** is set. (Default: 30 minutes) + +[[TestingAuthKeyLifetime]] **TestingAuthKeyLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: + Overrides the default lifetime for a signing Ed25519 TLS Link authentication + key. + (Default: 2 days) + +[[TestingAuthKeySlop]] **TestingAuthKeySlop** __N__ **seconds**|**minutes**|**hours** + + +[[TestingBridgeBootstrapDownloadInitialDelay]] **TestingBridgeBootstrapDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download each bridge descriptor when they + have just started, or when they can not contact any of their bridges. + Changing this requires that **TestingTorNetwork** is set. (Default: 0) + +[[TestingBridgeDownloadInitialDelay]] **TestingBridgeDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download each bridge descriptor when they + know that one or more of their configured bridges are running. Changing + this requires that **TestingTorNetwork** is set. (Default: 10800) + +[[TestingClientConsensusDownloadInitialDelay]] **TestingClientConsensusDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) + +[[TestingClientDownloadInitialDelay]] **TestingClientDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download things in general. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) + +[[TestingClientMaxIntervalWithoutRequest]] **TestingClientMaxIntervalWithoutRequest** __N__ **seconds**|**minutes**:: + When directory clients have only a few descriptors to request, they batch + them until they have more, or until this amount of time has passed. + Changing this requires that **TestingTorNetwork** is set. (Default: 10 + minutes) + +[[TestingDirAuthVoteExit]] **TestingDirAuthVoteExit** __node__,__node__,__...__:: + A list of identity fingerprints, country codes, and + address patterns of nodes to vote Exit for regardless of their + uptime, bandwidth, or exit policy. See <> + for more information on how to specify nodes. + + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. See <> for more + information on how to specify nodes. + +[[TestingDirAuthVoteExitIsStrict]] **TestingDirAuthVoteExitIsStrict** **0**|**1** :: + If True (1), a node will never receive the Exit flag unless it is specified + in the **TestingDirAuthVoteExit** list, regardless of its uptime, bandwidth, + or exit policy. + + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + +[[TestingDirAuthVoteGuard]] **TestingDirAuthVoteGuard** __node__,__node__,__...__:: + A list of identity fingerprints and country codes and + address patterns of nodes to vote Guard for regardless of their + uptime and bandwidth. See <> for more + information on how to specify nodes. + + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + +[[TestingDirAuthVoteGuardIsStrict]] **TestingDirAuthVoteGuardIsStrict** **0**|**1** :: + If True (1), a node will never receive the Guard flag unless it is specified + in the **TestingDirAuthVoteGuard** list, regardless of its uptime and bandwidth. + + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + +[[TestingDirAuthVoteHSDir]] **TestingDirAuthVoteHSDir** __node__,__node__,__...__:: + A list of identity fingerprints and country codes and + address patterns of nodes to vote HSDir for regardless of their + uptime and DirPort. See <> for more + information on how to specify nodes. + + + + In order for this option to have any effect, **TestingTorNetwork** + must be set. + +[[TestingDirAuthVoteHSDirIsStrict]] **TestingDirAuthVoteHSDirIsStrict** **0**|**1** :: + If True (1), a node will never receive the HSDir flag unless it is specified + in the **TestingDirAuthVoteHSDir** list, regardless of its uptime and DirPort. + + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + +[[TestingDirConnectionMaxStall]] **TestingDirConnectionMaxStall** __N__ **seconds**|**minutes**:: + Let a directory connection stall this long before expiring it. + Changing this requires that **TestingTorNetwork** is set. (Default: + 5 minutes) + +[[TestingEnableCellStatsEvent]] **TestingEnableCellStatsEvent** **0**|**1**:: + If this option is set, then Tor controllers may register for CELL_STATS + events. Changing this requires that **TestingTorNetwork** is set. + (Default: 0) + +[[TestingEnableConnBwEvent]] **TestingEnableConnBwEvent** **0**|**1**:: + If this option is set, then Tor controllers may register for CONN_BW + events. Changing this requires that **TestingTorNetwork** is set. + (Default: 0) + +[[TestingLinkCertLifetime]] **TestingLinkCertLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: + Overrides the default lifetime for the certificates used to authenticate + our X509 link cert with our ed25519 signing key. + (Default: 2 days) + +[[TestingLinkKeySlop]] **TestingLinkKeySlop** __N__ **seconds**|**minutes**|**hours** + + +[[TestingMinExitFlagThreshold]] **TestingMinExitFlagThreshold** __N__ **KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Sets a lower-bound for assigning an exit flag when running as an + authority on a testing network. Overrides the usual default lower bound + of 4 KBytes. (Default: 0) + +[[TestingMinFastFlagThreshold]] **TestingMinFastFlagThreshold** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Minimum value for the Fast flag. Overrides the ordinary minimum taken + from the consensus when TestingTorNetwork is set. (Default: 0.) + +[[TestingServerConsensusDownloadInitialDelay]] **TestingServerConsensusDownloadInitialDelay** __N__:: + Initial delay in seconds for when servers should download consensuses. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) + +[[TestingServerDownloadInitialDelay]] **TestingServerDownloadInitialDelay** __N__:: + Initial delay in seconds for when servers should download things in general. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) + +[[TestingSigningKeySlop]] **TestingSigningKeySlop** __N__ **seconds**|**minutes**|**hours**:: + How early before the official expiration of a an Ed25519 signing key do + we replace it and issue a new key? + (Default: 3 hours for link and auth; 1 day for signing.) + +[[TestingV3AuthInitialDistDelay]] **TestingV3AuthInitialDistDelay** __N__ **seconds**|**minutes**|**hours**:: + Like V3AuthDistDelay, but for initial voting interval before + the first consensus has been created. Changing this requires that + **TestingTorNetwork** is set. (Default: 5 minutes) + +[[TestingV3AuthInitialVoteDelay]] **TestingV3AuthInitialVoteDelay** __N__ **seconds**|**minutes**|**hours**:: + Like V3AuthVoteDelay, but for initial voting interval before + the first consensus has been created. Changing this requires that + **TestingTorNetwork** is set. (Default: 5 minutes) + +[[TestingV3AuthInitialVotingInterval]] **TestingV3AuthInitialVotingInterval** __N__ **seconds**|**minutes**|**hours**:: + Like V3AuthVotingInterval, but for initial voting interval before the first + consensus has been created. Changing this requires that + **TestingTorNetwork** is set. (Default: 30 minutes) + +[[TestingV3AuthVotingStartOffset]] **TestingV3AuthVotingStartOffset** __N__ **seconds**|**minutes**|**hours**:: + Directory authorities offset voting start time by this much. + Changing this requires that **TestingTorNetwork** is set. (Default: 0) + + +== NON-PERSISTENT OPTIONS + +These options are not saved to the torrc file by the "SAVECONF" controller +command. Other options of this type are documented in control-spec.txt, +section 5.4. End-users should mostly ignore them. + +[[UnderscorePorts]] **{dbl_}ControlPort**, **{dbl_}DirPort**, **{dbl_}DNSPort**, **{dbl_}ExtORPort**, **{dbl_}NATDPort**, **{dbl_}ORPort**, **{dbl_}SocksPort**, **{dbl_}TransPort**:: + These underscore-prefixed options are variants of the regular Port + options. They behave the same, except they are not saved to the + torrc file by the controller's SAVECONF command. + + +== SIGNALS + +Tor catches the following signals: + +[[SIGTERM]] **SIGTERM**:: + Tor will catch this, clean up and sync to disk if necessary, and exit. + +[[SIGINT]] **SIGINT**:: + Tor clients behave as with SIGTERM; but Tor servers will do a controlled + slow shutdown, closing listeners and waiting 30 seconds before exiting. + (The delay can be configured with the ShutdownWaitLength config option.) + +[[SIGHUP]] **SIGHUP**:: + The signal instructs Tor to reload its configuration (including closing and + reopening logs), and kill and restart its helper processes if applicable. + +[[SIGUSR1]] **SIGUSR1**:: + Log statistics about current connections, past connections, and throughput. + +[[SIGUSR2]] **SIGUSR2**:: + Switch all logs to loglevel debug. You can go back to the old loglevels by + sending a SIGHUP. + +[[SIGCHLD]] **SIGCHLD**:: + Tor receives this signal when one of its helper processes has exited, so it + can clean up. + +[[SIGPIPE]] **SIGPIPE**:: + Tor catches this signal and ignores it. + +[[SIGXFSZ]] **SIGXFSZ**:: + If this signal exists on your platform, Tor catches and ignores it. + +== FILES + +**`@CONFDIR@/torrc`**:: + Default location of the configuration file. + +**`$HOME/.torrc`**:: + Fallback location for torrc, if @CONFDIR@/torrc is not found. + +**`@LOCALSTATEDIR@/lib/tor/`**:: + The tor process stores keys and other data here. + +__CacheDirectory__/**`cached-certs`**:: + Contains downloaded directory key certificates that are used to verify + authenticity of documents generated by the Tor directory authorities. + +__CacheDirectory__/**`cached-consensus`** and/or **`cached-microdesc-consensus`**:: + The most recent consensus network status document we've downloaded. + +__CacheDirectory__/**`cached-descriptors`** and **`cached-descriptors.new`**:: + These files contain the downloaded router statuses. Some routers may appear + more than once; if so, the most recently published descriptor is + used. Lines beginning with **`@`**-signs are annotations that contain more + information about a given router. The **`.new`** file is an append-only + journal; when it gets too large, all entries are merged into a new + cached-descriptors file. + +__CacheDirectory__/**`cached-extrainfo`** and **`cached-extrainfo.new`**:: + Similar to **cached-descriptors**, but holds optionally-downloaded + "extra-info" documents. Relays use these documents to send inessential + information about statistics, bandwidth history, and network health to the + authorities. They aren't fetched by default. See <> + for more information. + +__CacheDirectory__/**`cached-microdescs`** and **`cached-microdescs.new`**:: + These files hold downloaded microdescriptors. Lines beginning with + **`@`**-signs are annotations that contain more information about a given + router. The **`.new`** file is an append-only journal; when it gets too + large, all entries are merged into a new cached-microdescs file. + +__DataDirectory__/**`state`**:: + Contains a set of persistent key-value mappings. These include: + - the current entry guards and their status. + - the current bandwidth accounting values. + - when the file was last written + - what version of Tor generated the state file + - a short history of bandwidth usage, as produced in the server + descriptors. + +__DataDirectory__/**`sr-state`**:: + _Authority only_. This file is used to record information about the current + status of the shared-random-value voting state. + +__CacheDirectory__/**`diff-cache`**:: + _Directory cache only_. Holds older consensuses and diffs from oldest to + the most recent consensus of each type compressed in various ways. Each + file contains a set of key-value arguments describing its contents, + followed by a single NUL byte, followed by the main file contents. + +__DataDirectory__/**`bw_accounting`**:: + This file is obsolete and the data is now stored in the **`state`** file + instead. Used to track bandwidth accounting values (when the current period + starts and ends; how much has been read and written so far this period). + +__DataDirectory__/**`control_auth_cookie`**:: + This file can be used only when cookie authentication is enabled. Used for + cookie authentication with the controller. Location can be overridden by + the `CookieAuthFile` configuration option. Regenerated on startup. See + control-spec.txt in https://spec.torproject.org/[torspec] for details. + +__DataDirectory__/**`lock`**:: + This file is used to prevent two Tor instances from using the same data + directory. If access to this file is locked, data directory is already in + use by Tor. + +__DataDirectory__/**`key-pinning-journal`**:: + Used by authorities. A line-based file that records mappings between + RSA1024 and Ed25519 identity keys. Authorities enforce these mappings, so + that once a relay has picked an Ed25519 key, stealing or factoring the + RSA1024 key will no longer let an attacker impersonate the relay. + +__KeyDirectory__/**`authority_identity_key`**:: + A v3 directory authority's master identity key, used to authenticate its + signing key. Tor doesn't use this while it's running. The tor-gencert + program uses this. If you're running an authority, you should keep this key + offline, and not put it in this file. + +__KeyDirectory__/**`authority_certificate`**:: + Only directory authorities use this file. A v3 directory authority's + certificate which authenticates the authority's current vote- and + consensus-signing key using its master identity key. + +__KeyDirectory__/**`authority_signing_key`**:: + Only directory authorities use this file. A v3 directory authority's + signing key that is used to sign votes and consensuses. Corresponds to the + **authority_certificate** cert. + +__KeyDirectory__/**`legacy_certificate`**:: + As authority_certificate; used only when `V3AuthUseLegacyKey` is set. See + documentation for <>. + +__KeyDirectory__/**`legacy_signing_key`**:: + As authority_signing_key: used only when `V3AuthUseLegacyKey` is set. See + documentation for <>. + +__KeyDirectory__/**`secret_id_key`**:: + A relay's RSA1024 permanent identity key, including private and public + components. Used to sign router descriptors, and to sign other keys. + +__KeyDirectory__/**`ed25519_master_id_public_key`**:: + The public part of a relay's Ed25519 permanent identity key. + +__KeyDirectory__/**`ed25519_master_id_secret_key`**:: + The private part of a relay's Ed25519 permanent identity key. This key is + used to sign the medium-term ed25519 signing key. This file can be kept + offline or encrypted. If so, Tor will not be able to generate new signing + keys automatically; you'll need to use `tor --keygen` to do so. + +__KeyDirectory__/**`ed25519_signing_secret_key`**:: + The private and public components of a relay's medium-term Ed25519 signing + key. This key is authenticated by the Ed25519 master key, which in turn + authenticates other keys (and router descriptors). + +__KeyDirectory__/**`ed25519_signing_cert`**:: + The certificate which authenticates "ed25519_signing_secret_key" as having + been signed by the Ed25519 master key. + +__KeyDirectory__/**`secret_onion_key`** and **`secret_onion_key.old`**:: + A relay's RSA1024 short-term onion key. Used to decrypt old-style ("TAP") + circuit extension requests. The **`.old`** file holds the previously + generated key, which the relay uses to handle any requests that were made + by clients that didn't have the new one. + +__KeyDirectory__/**`secret_onion_key_ntor`** and **`secret_onion_key_ntor.old`**:: + A relay's Curve25519 short-term onion key. Used to handle modern ("ntor") + circuit extension requests. The **`.old`** file holds the previously + generated key, which the relay uses to handle any requests that were made + by clients that didn't have the new one. + +__DataDirectory__/**`fingerprint`**:: + Only used by servers. Contains the fingerprint of the server's identity key. + +__DataDirectory__/**`hashed-fingerprint`**:: + Only used by bridges. Contains the hashed fingerprint of the bridge's + identity key. (That is, the hash of the hash of the identity key.) + +__DataDirectory__/**`approved-routers`**:: + Only used by authoritative directory servers. Each line lists a status and + an identity, separated by whitespace. Identities can be hex-encoded RSA + fingerprints, or base-64 encoded ed25519 public keys. See the + **fingerprint** file in a tor relay's __DataDirectory__ for an example + fingerprint line. If the status is **!reject**, then descriptors from the + given identity are rejected by this server. If it is **!invalid** then + descriptors are accepted, but marked in the directory as not valid, that + is, not recommended. In either case, the corresponding relays are not + included in the consensus. + +__DataDirectory__/**`v3-status-votes`**:: + Only for v3 authoritative directory servers. This file contains status + votes from all the authoritative directory servers. + +__CacheDirectory__/**`unverified-consensus`**:: + Contains a network consensus document that has been downloaded, but which + we didn't have the right certificates to check yet. + +__CacheDirectory__/**`unverified-microdesc-consensus`**:: + Contains a microdescriptor-flavored network consensus document that has + been downloaded, but which we didn't have the right certificates to check + yet. + +__DataDirectory__/**`unparseable-desc`**:: + Onion server descriptors that Tor was unable to parse are dumped to this + file. Only used for debugging. + +__DataDirectory__/**`router-stability`**:: + Only used by authoritative directory servers. Tracks measurements for + router mean-time-between-failures so that authorities have a fair idea of + how to set their Stable flags. + +__DataDirectory__/**`stats/dirreq-stats`**:: + Only used by directory caches and authorities. This file is used to + collect directory request statistics. + +__DataDirectory__/**`stats/entry-stats`**:: + Only used by servers. This file is used to collect incoming connection + statistics by Tor entry nodes. + +__DataDirectory__/**`stats/bridge-stats`**:: + Only used by servers. This file is used to collect incoming connection + statistics by Tor bridges. + +__DataDirectory__/**`stats/exit-stats`**:: + Only used by servers. This file is used to collect outgoing connection + statistics by Tor exit routers. + +__DataDirectory__/**`stats/buffer-stats`**:: + Only used by servers. This file is used to collect buffer usage + history. + +__DataDirectory__/**`stats/conn-stats`**:: + Only used by servers. This file is used to collect approximate connection + history (number of active connections over time). + +__DataDirectory__/**`stats/hidserv-stats`**:: + Only used by servers. This file is used to collect approximate counts + of what fraction of the traffic is hidden service rendezvous traffic, and + approximately how many hidden services the relay has seen. + +__DataDirectory__/**networkstatus-bridges`**:: + Only used by authoritative bridge directories. Contains information + about bridges that have self-reported themselves to the bridge + authority. + +__HiddenServiceDirectory__/**`hostname`**:: + The .onion domain name for this hidden service. + If the hidden service is restricted to authorized clients only, this file + also contains authorization data for all clients. ++ +[NOTE] + The clients will ignore any extra subdomains prepended to a hidden + service hostname. Supposing you have "xyz.onion" as your hostname, you + can ask your clients to connect to "www.xyz.onion" or "irc.xyz.onion" + for virtual-hosting purposes. + +__HiddenServiceDirectory__/**`private_key`**:: + Contains the private key for this hidden service. + +__HiddenServiceDirectory__/**`client_keys`**:: + Contains authorization data for a hidden service that is only accessible by + authorized clients. + +__HiddenServiceDirectory__/**`onion_service_non_anonymous`**:: + This file is present if a hidden service key was created in + **HiddenServiceNonAnonymousMode**. + +== SEE ALSO + +For more information, refer to the Tor Project website at +https://www.torproject.org/ and the Tor specifications at +https://spec.torproject.org. See also **torsocks**(1) and **torify**(1). + +== BUGS + +Because Tor is still under development, there may be plenty of bugs. Please +report them at https://trac.torproject.org/. + +== AUTHORS + +Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at alum.mit.edu]. diff --git a/doc/man/torify.1.txt b/doc/man/torify.1.txt new file mode 100644 index 0000000000..716625f92d --- /dev/null +++ b/doc/man/torify.1.txt @@ -0,0 +1,40 @@ +// Copyright (c) The Tor Project, Inc. +// See LICENSE for licensing information +// This is an asciidoc file used to generate the manpage/html reference. +// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html +:man source: Tor +:man manual: Tor Manual +torify(1) +========= + +NAME +---- +torify - wrapper for torsocks and tor + +SYNOPSIS +-------- +**torify** __application__ [__application's__ __arguments__] + +DESCRIPTION +----------- +**torify** is a simple wrapper that calls torsocks with a tor-specific +configuration file. + +It is provided for backward compatibility; instead you should use torsocks. + +WARNING +------- +When used with torsocks, torify should not leak DNS requests or UDP data. + +torify can leak ICMP data. + +torify will not ensure that different requests are processed on +different circuits. + +SEE ALSO +-------- +**tor**(1), **torsocks**(1) + +AUTHORS +------- +Peter Palfrader and Jacob Appelbaum wrote this manual. diff --git a/doc/tor-gencert.1.txt b/doc/tor-gencert.1.txt deleted file mode 100644 index 26f68b29c0..0000000000 --- a/doc/tor-gencert.1.txt +++ /dev/null @@ -1,92 +0,0 @@ -// Copyright (c) The Tor Project, Inc. -// See LICENSE for licensing information -// This is an asciidoc file used to generate the manpage/html reference. -// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html -:man source: Tor -:man manual: Tor Manual -tor-gencert(1) -============== -Nick Mathewson - -NAME ----- -tor-gencert - Generate certs and keys for Tor directory authorities - -SYNOPSIS --------- -**tor-gencert** [-h|--help] [-v] [-r|--reuse] [--create-identity-key] [-i __id_file__] [-c -__cert_file__] [-m __num__] [-a __address__:__port__] - -DESCRIPTION ------------ -**tor-gencert** generates certificates and private keys for use by Tor -directory authorities running the v3 Tor directory protocol, as used by -Tor 0.2.0 and later. If you are not running a directory authority, you -don't need to use tor-gencert. + - -Every directory authority has a long term authority __identity__ __key__ (which -is distinct from the identity key it uses as a Tor server); this key -should be kept offline in a secure location. It is used to certify -shorter-lived __signing__ __keys__, which are kept online and used by the -directory authority to sign votes and consensus documents. + - -After you use this program to generate a signing key and a certificate, -copy those files to the keys subdirectory of your Tor process, and send -Tor a SIGHUP signal. DO NOT COPY THE IDENTITY KEY. - -OPTIONS -------- -**-v**:: - Display verbose output. - -**-h** or **--help**:: - Display help text and exit. - -**-r** or **--reuse**:: - Generate a new certificate, but not a new signing key. This can be used to - change the address or lifetime associated with a given key. - -**--create-identity-key**:: - Generate a new identity key. You should only use this option the first time - you run tor-gencert; in the future, you should use the identity key that's - already there. - -**-i** __FILENAME__:: - Read the identity key from the specified file. If the file is not present - and --create-identity-key is provided, create the identity key in the - specified file. Default: "./authority_identity_key" - -**-s** __FILENAME__:: - Write the signing key to the specified file. Default: - "./authority_signing_key" - -**-c** __FILENAME__:: - Write the certificate to the specified file. Default: - "./authority_certificate" - -**-m** __NUM__:: - Number of months that the certificate should be valid. Default: 12. - -**--passphrase-fd** __FILEDES__:: - Filedescriptor to read the passphrase from. Ends at the first NUL or - newline. Default: read from the terminal. - -**-a** __address__:__port__:: - If provided, advertise the address:port combination as this authority's - preferred directory port in its certificate. If the address is a hostname, - the hostname is resolved to an IP before it's published. - -BUGS ----- -This probably doesn't run on Windows. That's not a big issue, since we don't -really want authorities to be running on Windows anyway. - -SEE ALSO --------- -**tor**(1) + - -See also the "dir-spec.txt" file, distributed with Tor. - -AUTHORS -------- - Roger Dingledine , Nick Mathewson . diff --git a/doc/tor-print-ed-signing-cert.1.txt b/doc/tor-print-ed-signing-cert.1.txt deleted file mode 100644 index 71c8b67ec4..0000000000 --- a/doc/tor-print-ed-signing-cert.1.txt +++ /dev/null @@ -1,38 +0,0 @@ -// Copyright (c) The Tor Project, Inc. -// See LICENSE for licensing information -// This is an asciidoc file used to generate the manpage/html reference. -// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html -:man source: Tor -:man manual: Tor Manual -tor-print-ed-signing-cert(1) -============================ -Tor Project, Inc. - -NAME ----- -tor-print-ed-signing-cert - print expiration date of ed25519 signing certificate - -SYNOPSIS --------- -**tor-print-ed-signing-cert** ____ - -DESCRIPTION ------------ -**tor-print-ed-signing-cert** is utility program for Tor relay operators to -check expiration date of ed25519 signing certificate. - -Expiration date is printed in three formats: - -* Human-readable timestamp, localized to current timezone. -* RFC 1123 timestamp (at GMT timezone). -* Unix time value. - -SEE ALSO --------- -**tor**(1) + - -https://spec.torproject.org/cert-spec - -AUTHORS -------- -Roger Dingledine , Nick Mathewson . diff --git a/doc/tor-resolve.1.txt b/doc/tor-resolve.1.txt deleted file mode 100644 index 17a77e482f..0000000000 --- a/doc/tor-resolve.1.txt +++ /dev/null @@ -1,54 +0,0 @@ -// Copyright (c) The Tor Project, Inc. -// See LICENSE for licensing information -// This is an asciidoc file used to generate the manpage/html reference. -// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html -:man source: Tor -:man manual: Tor Manual -tor-resolve(1) -============== -Peter Palfrader - -NAME ----- -tor-resolve - resolve a hostname to an IP address via tor - -SYNOPSIS --------- -**tor-resolve** [-4|-5] [-v] [-x] [-p __socksport__] __hostname__ [__sockshost__[:__socksport__]] - -DESCRIPTION ------------ -**tor-resolve** is a simple script to connect to a SOCKS proxy that knows about -the SOCKS RESOLVE command, hand it a hostname, and return an IP address. - -By default, **tor-resolve** uses the Tor server running on 127.0.0.1 on SOCKS -port 9050. If this isn't what you want, you should specify an explicit -__sockshost__ and/or __socksport__ on the command line. - -OPTIONS -------- -**-v**:: - Display verbose output. - -**-x**:: - Perform a reverse lookup: get the PTR record for an IPv4 address. - -**-5**:: - Use the SOCKS5 protocol. (Default) - -**-4**:: - Use the SOCKS4a protocol rather than the default SOCKS5 protocol. Doesn't - support reverse DNS. - -**-p** __socksport__:: - Override the default SOCKS port without setting the hostname. - -SEE ALSO --------- -**tor**(1), **torify**(1). + - -For protocol details, see: https://spec.torproject.org/socks-extensions - -AUTHORS -------- -Roger Dingledine , Nick Mathewson . diff --git a/doc/tor.1.txt b/doc/tor.1.txt deleted file mode 100644 index ca54fa125b..0000000000 --- a/doc/tor.1.txt +++ /dev/null @@ -1,3839 +0,0 @@ -// Copyright (c) The Tor Project, Inc. -// See LICENSE for licensing information -// This is an asciidoc file used to generate the manpage/html reference. -// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html -:man source: Tor -:man manual: Tor Manual -// compat-mode tells Asciidoctor tools to process this as legacy AsciiDoc -:compat-mode: -// attribute to make it easier to write names containing double underscores -:dbl_: __ -= TOR(1) -:toc: - -== NAME - -tor - The second-generation onion router - -== SYNOPSIS - -**tor** [__OPTION__ __value__]... - -== DESCRIPTION - -Tor is a connection-oriented anonymizing communication service. Users -choose a source-routed path through a set of nodes, and negotiate a -"virtual circuit" through the network. Each node in a virtual circuit -knows its predecessor and successor nodes, but no other nodes. Traffic -flowing down the circuit is unwrapped by a symmetric key at each node, -which reveals the downstream node. + - -Basically, Tor provides a distributed network of servers or relays -("onion routers"). Users bounce their TCP streams, including web -traffic, ftp, ssh, etc., around the network, so that recipients, -observers, and even the relays themselves have difficulty tracking the -source of the stream. - -[NOTE] -By default, **tor** acts as a client only. To help the network by -providing bandwidth as a relay, change the **ORPort** configuration -option as mentioned below. Please also consult the documentation on -the Tor Project's website. - -== COMMAND-LINE OPTIONS - -Tor has a powerful command-line interface. This section lists optional -arguments you can specify at the command line using the **`tor`** -command. - -Configuration options can be specified on the command line in the -format **`--`**_OptionName_ _OptionValue_, on the command line in the -format _OptionName_ _OptionValue_, or in a configuration file. For -instance, you can tell Tor to start listening for SOCKS connections on -port 9999 by passing either **`--SocksPort 9999`** or **`SocksPort -9999`** on the command line, or by specifying **`SocksPort 9999`** in -the configuration file. On the command line, quote option values that -contain spaces. For instance, if you want Tor to log all debugging -messages to **`debug.log`**, you must specify **`--Log "debug file -debug.log"`**. - -NOTE: Configuration options on the command line override those in -configuration files. See **<>** for more information. - -The following options in this section are only recognized on the -**`tor`** command line, not in a configuration file. - -[[opt-h]] **`-h`**, **`--help`**:: - Display a short help message and exit. - -[[opt-f]] **`-f`** __FILE__:: - Specify a new configuration file to contain further Tor configuration - options, or pass *-* to make Tor read its configuration from standard - input. (Default: **`@CONFDIR@/torrc`**, or **`$HOME/.torrc`** if - that file is not found) - -[[opt-allow-missing-torrc]] **`--allow-missing-torrc`**:: - Allow the configuration file specified by **`-f`** to be missing, - if the defaults-torrc file (see below) is accessible. - -[[opt-defaults-torrc]] **`--defaults-torrc`** __FILE__:: - Specify a file in which to find default values for Tor options. The - contents of this file are overridden by those in the regular - configuration file, and by those on the command line. (Default: - **`@CONFDIR@/torrc-defaults`**.) - -[[opt-ignore-missing-torrc]] **`--ignore-missing-torrc`**:: - Specify that Tor should treat a missing torrc file as though it - were empty. Ordinarily, Tor does this for missing default torrc files, - but not for those specified on the command line. - -[[opt-hash-password]] **`--hash-password`** __PASSWORD__:: - Generate a hashed password for control port access. - -[[opt-list-fingerprint]] **`--list-fingerprint`**:: - Generate your keys and output your nickname and fingerprint. - -[[opt-verify-config]] **`--verify-config`**:: - Verify whether the configuration file is valid. - -[[opt-dump-config]] **`--dump-config`** **`short`**|**`full`**:: - Write a list of Tor's configured options to standard output. - When the `short` flag is selected, only write the options that - are different from their default values - When `full` is selected, write every option. - -[[opt-serviceinstall]] **`--service install`** [**`--options`** __command-line options__]:: - Install an instance of Tor as a Windows service, with the provided - command-line options. Current instructions can be found at - https://www.torproject.org/docs/faq#NTService - -[[opt-service]] **`--service`** **`remove`**|**`start`**|**`stop`**:: - Remove, start, or stop a configured Tor Windows service. - -[[opt-nt-service]] **`--nt-service`**:: - Used internally to implement a Windows service. - -[[opt-list-torrc-options]] **`--list-torrc-options`**:: - List all valid options. - -[[opt-list-deprecated-options]] **`--list-deprecated-options`**:: - List all valid options that are scheduled to become obsolete in a - future version. (This is a warning, not a promise.) - -[[opt-list-modules]] **`--list-modules`**:: - List whether each optional module has been compiled into Tor. - (Any module not listed is not optional in this version of Tor.) - -[[opt-version]] **`--version`**:: - Display Tor version and exit. The output is a single line of the format - "Tor version [version number]." (The version number format - is as specified in version-spec.txt.) - -[[opt-quiet]] **`--quiet`**|**`--hush`**:: - Override the default console logging behavior. By default, Tor - starts out logging messages at level "notice" and higher to the - console. It stops doing so after it parses its configuration, if - the configuration tells it to log anywhere else. These options - override the default console logging behavior. Use the - **`--hush`** option if you want Tor to log only warnings and - errors to the console, or use the **`--quiet`** option if you want - Tor not to log to the console at all. - -[[opt-keygen]] **`--keygen`** [**`--newpass`**]:: - Running **`tor --keygen`** creates a new ed25519 master identity key - for a relay, or only a fresh temporary signing key and - certificate, if you already have a master key. Optionally, you - can encrypt the master identity key with a passphrase. When Tor - asks you for a passphrase and you don't want to encrypt the master - key, just don't enter any passphrase when asked. + - + - Use the **`--newpass`** option with **`--keygen`** only when you - need to add, change, or remove a passphrase on an existing ed25519 - master identity key. You will be prompted for the old passphase - (if any), and the new passphrase (if any). -+ -[NOTE] - When generating a master key, you may want to use - **`--DataDirectory`** to control where the keys and certificates - will be stored, and **`--SigningKeyLifetime`** to control their - lifetimes. See <> to learn more about the - behavior of these options. You must have write access to the - specified DataDirectory. -+ -[normal] - To use the generated files, you must copy them to the - __DataDirectory__/**`keys`** directory of your Tor daemon, and - make sure that they are owned by the user actually running the Tor - daemon on your system. - -**`--passphrase-fd`** __FILEDES__:: - File descriptor to read the passphrase from. Note that unlike with the - tor-gencert program, the entire file contents are read and used as - the passphrase, including any trailing newlines. - If the file descriptor is not specified, the passphrase is read - from the terminal by default. - -[[opt-key-expiration]] **`--key-expiration`** [__purpose__]:: - The __purpose__ specifies which type of key certificate to determine - the expiration of. The only currently recognised __purpose__ is - "sign". + - + - Running **`tor --key-expiration sign`** will attempt to find your - signing key certificate and will output, both in the logs as well - as to stdout, the signing key certificate's expiration time in - ISO-8601 format. For example, the output sent to stdout will be - of the form: "signing-cert-expiry: 2017-07-25 08:30:15 UTC" - -[[opt-dbg]] **--dbg-**...:: - Tor may support other options beginning with the string "dbg". These - are intended for use by developers to debug and test Tor. They are - not supported or guaranteed to be stable, and you should probably - not use them. - - -[[conf-format]] -== THE CONFIGURATION FILE FORMAT - -All configuration options in a configuration are written on a single line by -default. They take the form of an option name and a value, or an option name -and a quoted value (option value or option "value"). Anything after a # -character is treated as a comment. Options are -case-insensitive. C-style escaped characters are allowed inside quoted -values. To split one configuration entry into multiple lines, use a single -backslash character (\) before the end of the line. Comments can be used in -such multiline entries, but they must start at the beginning of a line. - -Configuration options can be imported from files or folders using the %include -option with the value being a path. If the path is a file, the options from the -file will be parsed as if they were written where the %include option is. If -the path is a folder, all files on that folder will be parsed following lexical -order. Files starting with a dot are ignored. Files on subfolders are ignored. -The %include option can be used recursively. -New configuration files or directories cannot be added to already running Tor -instance if **Sandbox** is enabled. - -By default, an option on the command line overrides an option found in the -configuration file, and an option in a configuration file overrides one in -the defaults file. - -This rule is simple for options that take a single value, but it can become -complicated for options that are allowed to occur more than once: if you -specify four SocksPorts in your configuration file, and one more SocksPort on -the command line, the option on the command line will replace __all__ of the -SocksPorts in the configuration file. If this isn't what you want, prefix -the option name with a plus sign (+), and it will be appended to the previous -set of options instead. For example, setting SocksPort 9100 will use only -port 9100, but setting +SocksPort 9100 will use ports 9100 and 9050 (because -this is the default). - -Alternatively, you might want to remove every instance of an option in the -configuration file, and not replace it at all: you might want to say on the -command line that you want no SocksPorts at all. To do that, prefix the -option name with a forward slash (/). You can use the plus sign (+) and the -forward slash (/) in the configuration file and on the command line. - -== GENERAL OPTIONS - -// These options are in alphabetical order, with exceptions as noted. -// Please keep them that way! - -[[AccelDir]] **AccelDir** __DIR__:: - Specify this option if using dynamic hardware acceleration and the engine - implementation library resides somewhere other than the OpenSSL default. - Can not be changed while tor is running. - -[[AccelName]] **AccelName** __NAME__:: - When using OpenSSL hardware crypto acceleration attempt to load the dynamic - engine of this name. This must be used for any dynamic hardware engine. - Names can be verified with the openssl engine command. Can not be changed - while tor is running. + - + - If the engine name is prefixed with a "!", then Tor will exit if the - engine cannot be loaded. - -[[AlternateBridgeAuthority]] **AlternateBridgeAuthority** [__nickname__] [**flags**] __ipv4address__:__port__ __ fingerprint__:: -[[AlternateDirAuthority]] **AlternateDirAuthority** [__nickname__] [**flags**] __ipv4address__:__port__ __fingerprint__:: - These options behave as DirAuthority, but they replace fewer of the - default directory authorities. Using - AlternateDirAuthority replaces the default Tor directory authorities, but - leaves the default bridge authorities in - place. Similarly, - AlternateBridgeAuthority replaces the default bridge authority, - but leaves the directory authorities alone. - -[[AndroidIdentityTag]] **AndroidIdentityTag** __tag__:: - When logging to Android's logging subsystem, adds a tag to the log identity - such that log entries are marked with "Tor-__tag__". Can not be changed while - tor is running. (Default: none) - -[[AvoidDiskWrites]] **AvoidDiskWrites** **0**|**1**:: - If non-zero, try to write to disk less frequently than we would otherwise. - This is useful when running on flash memory or other media that support - only a limited number of writes. (Default: 0) - -[[BandwidthBurst]] **BandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Limit the maximum token bucket size (also known as the burst) to the given - number of bytes in each direction. (Default: 1 GByte) - -[[BandwidthRate]] **BandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - A token bucket limits the average incoming bandwidth usage on this node - to the specified number of bytes per second, and the average outgoing - bandwidth usage to that same value. If you want to run a relay in the - public network, this needs to be _at the very least_ 75 KBytes for a - relay (that is, 600 kbits) or 50 KBytes for a bridge (400 kbits) -- but of - course, more is better; we recommend at least 250 KBytes (2 mbits) if - possible. (Default: 1 GByte) + - + - Note that this option, and other bandwidth-limiting options, apply to TCP - data only: They do not count TCP headers or DNS traffic. + - + - Tor uses powers of two, not powers of ten, so 1 GByte is - 1024*1024*1024 bytes as opposed to 1 billion bytes. + - + - With this option, and in other options that take arguments in bytes, - KBytes, and so on, other formats are also supported. Notably, "KBytes" can - also be written as "kilobytes" or "kb"; "MBytes" can be written as - "megabytes" or "MB"; "kbits" can be written as "kilobits"; and so forth. - Case doesn't matter. - Tor also accepts "byte" and "bit" in the singular. - The prefixes "tera" and "T" are also recognized. - If no units are given, we default to bytes. - To avoid confusion, we recommend writing "bytes" or "bits" explicitly, - since it's easy to forget that "B" means bytes, not bits. - -[[CacheDirectory]] **CacheDirectory** __DIR__:: - Store cached directory data in DIR. Can not be changed while tor is - running. - (Default: uses the value of DataDirectory.) - -[[CacheDirectoryGroupReadable]] **CacheDirectoryGroupReadable** **0**|**1**|**auto**:: - If this option is set to 0, don't allow the filesystem group to read the - CacheDirectory. If the option is set to 1, make the CacheDirectory readable - by the default GID. If the option is "auto", then we use the - setting for DataDirectoryGroupReadable when the CacheDirectory is the - same as the DataDirectory, and 0 otherwise. (Default: auto) - -[[CircuitPriorityHalflife]] **CircuitPriorityHalflife** __NUM__:: - If this value is set, we override the default algorithm for choosing which - circuit's cell to deliver or relay next. It is delivered first to the - circuit that has the lowest weighted cell count, where cells are weighted - exponentially according to this value (in seconds). If the value is -1, it - is taken from the consensus if possible else it will fallback to the - default value of 30. Minimum: 1, Maximum: 2147483647. This can be defined - as a float value. This is an advanced option; you generally shouldn't have - to mess with it. (Default: -1) - -[[ClientTransportPlugin]] **ClientTransportPlugin** __transport__ socks4|socks5 __IP__:__PORT__:: -**ClientTransportPlugin** __transport__ exec __path-to-binary__ [options]:: - In its first form, when set along with a corresponding Bridge line, the Tor - client forwards its traffic to a SOCKS-speaking proxy on "IP:PORT". - (IPv4 addresses should written as-is; IPv6 addresses should be wrapped in - square brackets.) It's the - duty of that proxy to properly forward the traffic to the bridge. + - + - In its second form, when set along with a corresponding Bridge line, the Tor - client launches the pluggable transport proxy executable in - __path-to-binary__ using __options__ as its command-line options, and - forwards its traffic to it. It's the duty of that proxy to properly forward - the traffic to the bridge. (Default: none) - -[[ConnLimit]] **ConnLimit** __NUM__:: - The minimum number of file descriptors that must be available to the Tor - process before it will start. Tor will ask the OS for as many file - descriptors as the OS will allow (you can find this by "ulimit -H -n"). - If this number is less than ConnLimit, then Tor will refuse to start. + - + - Tor relays need thousands of sockets, to connect to every other relay. - If you are running a private bridge, you can reduce the number of sockets - that Tor uses. For example, to limit Tor to 500 sockets, run - "ulimit -n 500" in a shell. Then start tor in the same shell, with - **ConnLimit 500**. You may also need to set **DisableOOSCheck 0**. + - + - Unless you have severely limited sockets, you probably don't need to - adjust **ConnLimit** itself. It has no effect on Windows, since that - platform lacks getrlimit(). (Default: 1000) - -[[ConstrainedSockets]] **ConstrainedSockets** **0**|**1**:: - If set, Tor will tell the kernel to attempt to shrink the buffers for all - sockets to the size specified in **ConstrainedSockSize**. This is useful for - virtual servers and other environments where system level TCP buffers may - be limited. If you're on a virtual server, and you encounter the "Error - creating network socket: No buffer space available" message, you are - likely experiencing this problem. + - + - The preferred solution is to have the admin increase the buffer pool for - the host itself via /proc/sys/net/ipv4/tcp_mem or equivalent facility; - this configuration option is a second-resort. + - + - The DirPort option should also not be used if TCP buffers are scarce. The - cached directory requests consume additional sockets which exacerbates - the problem. + - + - You should **not** enable this feature unless you encounter the "no buffer - space available" issue. Reducing the TCP buffers affects window size for - the TCP stream and will reduce throughput in proportion to round trip - time on long paths. (Default: 0) - -[[ConstrainedSockSize]] **ConstrainedSockSize** __N__ **bytes**|**KBytes**:: - When **ConstrainedSockets** is enabled the receive and transmit buffers for - all sockets will be set to this limit. Must be a value between 2048 and - 262144, in 1024 byte increments. Default of 8192 is recommended. - -[[ControlPort]] **ControlPort** ['address'**:**]{empty}__port__|**unix:**__path__|**auto** [__flags__]:: - If set, Tor will accept connections on this port and allow those - connections to control the Tor process using the Tor Control Protocol - (described in control-spec.txt in - https://spec.torproject.org[torspec]). Note: unless you also - specify one or more of **HashedControlPassword** or - **CookieAuthentication**, setting this option will cause Tor to allow - any process on the local host to control it. (Setting both authentication - methods means either method is sufficient to authenticate to Tor.) This - option is required for many Tor controllers; most use the value of 9051. - If a unix domain socket is used, you may quote the path using standard - C escape sequences. You can specify this directive multiple times, to - bind to multiple address/port pairs. - Set it to "auto" to have Tor pick a port for you. (Default: 0) + - + - Recognized flags are: - **GroupWritable**;; - Unix domain sockets only: makes the socket get created as - group-writable. - **WorldWritable**;; - Unix domain sockets only: makes the socket get created as - world-writable. - **RelaxDirModeCheck**;; - Unix domain sockets only: Do not insist that the directory - that holds the socket be read-restricted. - -[[ControlPortFileGroupReadable]] **ControlPortFileGroupReadable** **0**|**1**:: - If this option is set to 0, don't allow the filesystem group to read the - control port file. If the option is set to 1, make the control port - file readable by the default GID. (Default: 0) - -[[ControlPortWriteToFile]] **ControlPortWriteToFile** __Path__:: - If set, Tor writes the address and port of any control port it opens to - this address. Usable by controllers to learn the actual control port - when ControlPort is set to "auto". - -[[ControlSocket]] **ControlSocket** __Path__:: - Like ControlPort, but listens on a Unix domain socket, rather than a TCP - socket. '0' disables ControlSocket. (Unix and Unix-like systems only.) - (Default: 0) - -[[ControlSocketsGroupWritable]] **ControlSocketsGroupWritable** **0**|**1**:: - If this option is set to 0, don't allow the filesystem group to read and - write unix sockets (e.g. ControlSocket). If the option is set to 1, make - the control socket readable and writable by the default GID. (Default: 0) - -[[CookieAuthentication]] **CookieAuthentication** **0**|**1**:: - If this option is set to 1, allow connections on the control port - when the connecting process knows the contents of a file named - "control_auth_cookie", which Tor will create in its data directory. This - authentication method should only be used on systems with good filesystem - security. (Default: 0) - -[[CookieAuthFile]] **CookieAuthFile** __Path__:: - If set, this option overrides the default location and file name - for Tor's cookie file. (See <>.) - -[[CookieAuthFileGroupReadable]] **CookieAuthFileGroupReadable** **0**|**1**:: - If this option is set to 0, don't allow the filesystem group to read the - cookie file. If the option is set to 1, make the cookie file readable by - the default GID. [Making the file readable by other groups is not yet - implemented; let us know if you need this for some reason.] (Default: 0) - -[[CountPrivateBandwidth]] **CountPrivateBandwidth** **0**|**1**:: - If this option is set, then Tor's rate-limiting applies not only to - remote connections, but also to connections to private addresses like - 127.0.0.1 or 10.0.0.1. This is mostly useful for debugging - rate-limiting. (Default: 0) - -[[DataDirectory]] **DataDirectory** __DIR__:: - Store working data in DIR. Can not be changed while tor is running. - (Default: ~/.tor if your home directory is not /; otherwise, - @LOCALSTATEDIR@/lib/tor. On Windows, the default is - your ApplicationData folder.) - -[[DataDirectoryGroupReadable]] **DataDirectoryGroupReadable** **0**|**1**:: - If this option is set to 0, don't allow the filesystem group to read the - DataDirectory. If the option is set to 1, make the DataDirectory readable - by the default GID. (Default: 0) - -[[DirAuthority]] **DirAuthority** [__nickname__] [**flags**] __ipv4address__:__dirport__ __fingerprint__:: - Use a nonstandard authoritative directory server at the provided address - and port, with the specified key fingerprint. This option can be repeated - many times, for multiple authoritative directory servers. Flags are - separated by spaces, and determine what kind of an authority this directory - is. By default, an authority is not authoritative for any directory style - or version unless an appropriate flag is given. + - + - Tor will use this authority as a bridge authoritative directory if the - "bridge" flag is set. If a flag "orport=**orport**" is given, Tor will - use the given port when opening encrypted tunnels to the dirserver. If a - flag "weight=**num**" is given, then the directory server is chosen - randomly with probability proportional to that weight (default 1.0). If a - flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority - whose v3 long-term signing key has the fingerprint **fp**. Lastly, - if an "ipv6=**[**__ipv6address__**]**:__orport__" flag is present, then - the directory authority is listening for IPv6 connections on the - indicated IPv6 address and OR Port. + - + - Tor will contact the authority at __ipv4address__ to - download directory documents. Clients always use the ORPort. Relays - usually use the DirPort, but will use the ORPort in some circumstances. - If an IPv6 ORPort is supplied, clients will also download directory - documents at the IPv6 ORPort, if they are configured to use IPv6. + - + - If no **DirAuthority** line is given, Tor will use the default directory - authorities. NOTE: this option is intended for setting up a private Tor - network with its own directory authorities. If you use it, you will be - distinguishable from other users, because you won't believe the same - authorities they do. - -[[DirAuthorityFallbackRate]] **DirAuthorityFallbackRate** __NUM__:: - When configured to use both directory authorities and fallback - directories, the directory authorities also work as fallbacks. They are - chosen with their regular weights, multiplied by this number, which - should be 1.0 or less. The default is less than 1, to reduce load on - authorities. (Default: 0.1) - -[[DisableAllSwap]] **DisableAllSwap** **0**|**1**:: - If set to 1, Tor will attempt to lock all current and future memory pages, - so that memory cannot be paged out. Windows, OS X and Solaris are currently - not supported. We believe that this feature works on modern Gnu/Linux - distributions, and that it should work on *BSD systems (untested). This - option requires that you start your Tor as root, and you should use the - **User** option to properly reduce Tor's privileges. - Can not be changed while tor is running. (Default: 0) - -[[DisableDebuggerAttachment]] **DisableDebuggerAttachment** **0**|**1**:: - If set to 1, Tor will attempt to prevent basic debugging attachment attempts - by other processes. This may also keep Tor from generating core files if - it crashes. It has no impact for users who wish to attach if they - have CAP_SYS_PTRACE or if they are root. We believe that this feature - works on modern Gnu/Linux distributions, and that it may also work on *BSD - systems (untested). Some modern Gnu/Linux systems such as Ubuntu have the - kernel.yama.ptrace_scope sysctl and by default enable it as an attempt to - limit the PTRACE scope for all user processes by default. This feature will - attempt to limit the PTRACE scope for Tor specifically - it will not attempt - to alter the system wide ptrace scope as it may not even exist. If you wish - to attach to Tor with a debugger such as gdb or strace you will want to set - this to 0 for the duration of your debugging. Normal users should leave it - on. Disabling this option while Tor is running is prohibited. (Default: 1) - -[[DisableNetwork]] **DisableNetwork** **0**|**1**:: - When this option is set, we don't listen for or accept any connections - other than controller connections, and we close (and don't reattempt) - any outbound - connections. Controllers sometimes use this option to avoid using - the network until Tor is fully configured. Tor will make still certain - network-related calls (like DNS lookups) as a part of its configuration - process, even if DisableNetwork is set. (Default: 0) - -[[ExtendByEd25519ID]] **ExtendByEd25519ID** **0**|**1**|**auto**:: - If this option is set to 1, we always try to include a relay's Ed25519 ID - when telling the preceding relay in a circuit to extend to it. - If this option is set to 0, we never include Ed25519 IDs when extending - circuits. If the option is set to "auto", we obey a - parameter in the consensus document. (Default: auto) - -[[ExtORPort]] **ExtORPort** ['address'**:**]{empty}__port__|**auto**:: - Open this port to listen for Extended ORPort connections from your - pluggable transports. + - (Default: **DataDirectory**/extended_orport_auth_cookie) - -[[ExtORPortCookieAuthFile]] **ExtORPortCookieAuthFile** __Path__:: - If set, this option overrides the default location and file name - for the Extended ORPort's cookie file -- the cookie file is needed - for pluggable transports to communicate through the Extended ORPort. - -[[ExtORPortCookieAuthFileGroupReadable]] **ExtORPortCookieAuthFileGroupReadable** **0**|**1**:: - If this option is set to 0, don't allow the filesystem group to read the - Extended OR Port cookie file. If the option is set to 1, make the cookie - file readable by the default GID. [Making the file readable by other - groups is not yet implemented; let us know if you need this for some - reason.] (Default: 0) - -[[FallbackDir]] **FallbackDir** __ipv4address__:__dirport__ orport=__orport__ id=__fingerprint__ [weight=__num__] [ipv6=**[**__ipv6address__**]**:__orport__]:: - When tor is unable to connect to any directory cache for directory info - (usually because it doesn't know about any yet) it tries a hard-coded - directory. Relays try one directory authority at a time. Clients try - multiple directory authorities and FallbackDirs, to avoid hangs on - startup if a hard-coded directory is down. Clients wait for a few seconds - between each attempt, and retry FallbackDirs more often than directory - authorities, to reduce the load on the directory authorities. + - + - FallbackDirs should be stable relays with stable IP addresses, ports, - and identity keys. They must have a DirPort. + - + - By default, the directory authorities are also FallbackDirs. Specifying a - FallbackDir replaces Tor's default hard-coded FallbackDirs (if any). - (See <> for an explanation of each flag.) - -[[FetchDirInfoEarly]] **FetchDirInfoEarly** **0**|**1**:: - If set to 1, Tor will always fetch directory information like other - directory caches, even if you don't meet the normal criteria for fetching - early. Normal users should leave it off. (Default: 0) - -[[FetchDirInfoExtraEarly]] **FetchDirInfoExtraEarly** **0**|**1**:: - If set to 1, Tor will fetch directory information before other directory - caches. It will attempt to download directory information closer to the - start of the consensus period. Normal users should leave it off. - (Default: 0) - -[[FetchHidServDescriptors]] **FetchHidServDescriptors** **0**|**1**:: - If set to 0, Tor will never fetch any hidden service descriptors from the - rendezvous directories. This option is only useful if you're using a Tor - controller that handles hidden service fetches for you. (Default: 1) - -[[FetchServerDescriptors]] **FetchServerDescriptors** **0**|**1**:: - If set to 0, Tor will never fetch any network status summaries or server - descriptors from the directory servers. This option is only useful if - you're using a Tor controller that handles directory fetches for you. - (Default: 1) - -[[FetchUselessDescriptors]] **FetchUselessDescriptors** **0**|**1**:: - If set to 1, Tor will fetch every consensus flavor, and all server - descriptors and authority certificates referenced by those consensuses, - except for extra info descriptors. When this option is 1, Tor will also - keep fetching descriptors, even when idle. - If set to 0, Tor will avoid fetching useless descriptors: flavors that it - is not using to build circuits, and authority certificates it does not - trust. When Tor hasn't built any application circuits, it will go idle, - and stop fetching descriptors. This option is useful if you're using a - tor client with an external parser that uses a full consensus. - This option fetches all documents except extrainfo descriptors, - **DirCache** fetches and serves all documents except extrainfo - descriptors, **DownloadExtraInfo*** fetches extrainfo documents, and serves - them if **DirCache** is on, and **UseMicrodescriptors** changes the - flavour of consensues and descriptors that is fetched and used for - building circuits. (Default: 0) - -[[HardwareAccel]] **HardwareAccel** **0**|**1**:: - If non-zero, try to use built-in (static) crypto hardware acceleration when - available. Can not be changed while tor is running. (Default: 0) - -[[HashedControlPassword]] **HashedControlPassword** __hashed_password__:: - Allow connections on the control port if they present - the password whose one-way hash is __hashed_password__. You - can compute the hash of a password by running "tor --hash-password - __password__". You can provide several acceptable passwords by using more - than one HashedControlPassword line. - -[[HTTPProxy]] **HTTPProxy** __host__[:__port__]:: - Tor will make all its directory requests through this host:port (or host:80 - if port is not specified), rather than connecting directly to any directory - servers. (DEPRECATED: As of 0.3.1.0-alpha you should use HTTPSProxy.) - -[[HTTPProxyAuthenticator]] **HTTPProxyAuthenticator** __username:password__:: - If defined, Tor will use this username:password for Basic HTTP proxy - authentication, as in RFC 2617. This is currently the only form of HTTP - proxy authentication that Tor supports; feel free to submit a patch if you - want it to support others. (DEPRECATED: As of 0.3.1.0-alpha you should use - HTTPSProxyAuthenticator.) - -[[HTTPSProxy]] **HTTPSProxy** __host__[:__port__]:: - Tor will make all its OR (SSL) connections through this host:port (or - host:443 if port is not specified), via HTTP CONNECT rather than connecting - directly to servers. You may want to set **FascistFirewall** to restrict - the set of ports you might try to connect to, if your HTTPS proxy only - allows connecting to certain ports. - -[[HTTPSProxyAuthenticator]] **HTTPSProxyAuthenticator** __username:password__:: - If defined, Tor will use this username:password for Basic HTTPS proxy - authentication, as in RFC 2617. This is currently the only form of HTTPS - proxy authentication that Tor supports; feel free to submit a patch if you - want it to support others. - -[[KeepalivePeriod]] **KeepalivePeriod** __NUM__:: - To keep firewalls from expiring connections, send a padding keepalive cell - every NUM seconds on open connections that are in use. (Default: 5 minutes) - -[[KeepBindCapabilities]] **KeepBindCapabilities** **0**|**1**|**auto**:: - On Linux, when we are started as root and we switch our identity using - the **User** option, the **KeepBindCapabilities** option tells us whether to - try to retain our ability to bind to low ports. If this value is 1, we - try to keep the capability; if it is 0 we do not; and if it is **auto**, - we keep the capability only if we are configured to listen on a low port. - Can not be changed while tor is running. - (Default: auto.) - -[[Log]] **Log** __minSeverity__[-__maxSeverity__] **stderr**|**stdout**|**syslog**:: - Send all messages between __minSeverity__ and __maxSeverity__ to the standard - output stream, the standard error stream, or to the system log. (The - "syslog" value is only supported on Unix.) Recognized severity levels are - debug, info, notice, warn, and err. We advise using "notice" in most cases, - since anything more verbose may provide sensitive information to an - attacker who obtains the logs. If only one severity level is given, all - messages of that level or higher will be sent to the listed destination. + - + - Some low-level logs may be sent from signal handlers, so their destination - logs must be signal-safe. These low-level logs include backtraces, - logging function errors, and errors in code called by logging functions. - Signal-safe logs are always sent to stderr or stdout. They are also sent to - a limited number of log files that are configured to log messages at error - severity from the bug or general domains. They are never sent as syslogs, - android logs, control port log events, or to any API-based log - destinations. - -[[Log2]] **Log** __minSeverity__[-__maxSeverity__] **file** __FILENAME__:: - As above, but send log messages to the listed filename. The - "Log" option may appear more than once in a configuration file. - Messages are sent to all the logs that match their severity - level. - -[[Log3]] **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **file** __FILENAME__ + - -[[Log4]] **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **stderr**|**stdout**|**syslog**:: - As above, but select messages by range of log severity __and__ by a - set of "logging domains". Each logging domain corresponds to an area of - functionality inside Tor. You can specify any number of severity ranges - for a single log statement, each of them prefixed by a comma-separated - list of logging domains. You can prefix a domain with $$~$$ to indicate - negation, and use * to indicate "all domains". If you specify a severity - range without a list of domains, it matches all domains. + - + - This is an advanced feature which is most useful for debugging one or two - of Tor's subsystems at a time. + - + - The currently recognized domains are: general, crypto, net, config, fs, - protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge, - acct, hist, handshake, heartbeat, channel, sched, guard, consdiff, dos, - process, pt, btrack, and mesg. - Domain names are case-insensitive. + - + - For example, "`Log [handshake]debug [~net,~mm]info notice stdout`" sends - to stdout: all handshake messages of any severity, all info-and-higher - messages from domains other than networking and memory management, and all - messages of severity notice or higher. - -[[LogMessageDomains]] **LogMessageDomains** **0**|**1**:: - If 1, Tor includes message domains with each log message. Every log - message currently has at least one domain; most currently have exactly - one. This doesn't affect controller log messages. (Default: 0) - -[[LogTimeGranularity]] **LogTimeGranularity** __NUM__:: - Set the resolution of timestamps in Tor's logs to NUM milliseconds. - NUM must be positive and either a divisor or a multiple of 1 second. - Note that this option only controls the granularity written by Tor to - a file or console log. Tor does not (for example) "batch up" log - messages to affect times logged by a controller, times attached to - syslog messages, or the mtime fields on log files. (Default: 1 second) - -[[MaxAdvertisedBandwidth]] **MaxAdvertisedBandwidth** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - If set, we will not advertise more than this amount of bandwidth for our - BandwidthRate. Server operators who want to reduce the number of clients - who ask to build circuits through them (since this is proportional to - advertised bandwidth rate) can thus reduce the CPU demands on their server - without impacting network performance. - -[[MaxUnparseableDescSizeToLog]] **MaxUnparseableDescSizeToLog** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**:: - Unparseable descriptors (e.g. for votes, consensuses, routers) are logged - in separate files by hash, up to the specified size in total. Note that - only files logged during the lifetime of this Tor process count toward the - total; this is intended to be used to debug problems without opening live - servers to resource exhaustion attacks. (Default: 10 MBytes) - -[[NoExec]] **NoExec** **0**|**1**:: - If this option is set to 1, then Tor will never launch another - executable, regardless of the settings of ClientTransportPlugin - or ServerTransportPlugin. Once this option has been set to 1, - it cannot be set back to 0 without restarting Tor. (Default: 0) - -[[OutboundBindAddress]] **OutboundBindAddress** __IP__:: - Make all outbound connections originate from the IP address specified. This - is only useful when you have multiple network interfaces, and you want all - of Tor's outgoing connections to use a single one. This option may - be used twice, once with an IPv4 address and once with an IPv6 address. - IPv6 addresses should be wrapped in square brackets. - This setting will be ignored for connections to the loopback addresses - (127.0.0.0/8 and ::1), and is not used for DNS requests as well. - -[[OutboundBindAddressExit]] **OutboundBindAddressExit** __IP__:: - Make all outbound exit connections originate from the IP address - specified. This option overrides **OutboundBindAddress** for the - same IP version. This option may be used twice, once with an IPv4 - address and once with an IPv6 address. - IPv6 addresses should be wrapped in square brackets. - This setting will be ignored - for connections to the loopback addresses (127.0.0.0/8 and ::1). - -[[OutboundBindAddressOR]] **OutboundBindAddressOR** __IP__:: - Make all outbound non-exit (relay and other) connections - originate from the IP address specified. This option overrides - **OutboundBindAddress** for the same IP version. This option may - be used twice, once with an IPv4 address and once with an IPv6 - address. IPv6 addresses should be wrapped in square brackets. - This setting will be ignored for connections to the loopback - addresses (127.0.0.0/8 and ::1). - -[[OwningControllerProcess]] **{dbl_}OwningControllerProcess** __PID__:: - Make Tor instance periodically check for presence of a controller process - with given PID and terminate itself if this process is no longer alive. - Polling interval is 15 seconds. - -[[PerConnBWBurst]] **PerConnBWBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - If this option is set manually, or via the "perconnbwburst" consensus - field, Tor will use it for separate rate limiting for each connection - from a non-relay. (Default: 0) - -[[PerConnBWRate]] **PerConnBWRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - If this option is set manually, or via the "perconnbwrate" consensus - field, Tor will use it for separate rate limiting for each connection - from a non-relay. (Default: 0) - -[[PidFile]] **PidFile** __FILE__:: - On startup, write our PID to FILE. On clean shutdown, remove - FILE. Can not be changed while tor is running. - -[[ProtocolWarnings]] **ProtocolWarnings** **0**|**1**:: - If 1, Tor will log with severity \'warn' various cases of other parties not - following the Tor specification. Otherwise, they are logged with severity - \'info'. (Default: 0) - -[[RelayBandwidthBurst]] **RelayBandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - If not 0, limit the maximum token bucket size (also known as the burst) for - \_relayed traffic_ to the given number of bytes in each direction. - They do not include directory fetches by the relay (from authority - or other relays), because that is considered "client" activity. (Default: 0) - -[[RelayBandwidthRate]] **RelayBandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - If not 0, a separate token bucket limits the average incoming bandwidth - usage for \_relayed traffic_ on this node to the specified number of bytes - per second, and the average outgoing bandwidth usage to that same value. - Relayed traffic currently is calculated to include answers to directory - requests, but that may change in future versions. They do not include directory - fetches by the relay (from authority or other relays), because that is considered - "client" activity. (Default: 0) - -[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: - Tells an authority, or other node tracking node reliability and history, - that fine-grained information about nodes can be discarded when it hasn't - changed for a given amount of time. (Default: 24 hours) - -[[RunAsDaemon]] **RunAsDaemon** **0**|**1**:: - If 1, Tor forks and daemonizes to the background. This option has no effect - on Windows; instead you should use the --service command-line option. - Can not be changed while tor is running. - (Default: 0) - -[[SafeLogging]] **SafeLogging** **0**|**1**|**relay**:: - Tor can scrub potentially sensitive strings from log messages (e.g. - addresses) by replacing them with the string [scrubbed]. This way logs can - still be useful, but they don't leave behind personally identifying - information about what sites a user might have visited. + - + - If this option is set to 0, Tor will not perform any scrubbing, if it is - set to 1, all potentially sensitive strings are replaced. If it is set to - relay, all log messages generated when acting as a relay are sanitized, but - all messages generated when acting as a client are not. - Note: Tor may not heed this option when logging at log levels below Notice. - (Default: 1) - -[[Sandbox]] **Sandbox** **0**|**1**:: - If set to 1, Tor will run securely through the use of a syscall sandbox. - Otherwise the sandbox will be disabled. The option is currently an - experimental feature. It only works on Linux-based operating systems, - and only when Tor has been built with the libseccomp library. This option - can not be changed while tor is running. + - + - When the **Sandbox** is 1, the following options can not be changed when tor - is running: - **Address**, - **ConnLimit**, - **CookieAuthFile**, - **DirPortFrontPage**, - **ExtORPortCookieAuthFile**, - **Logs**, - **ServerDNSResolvConfFile**, - **ClientOnionAuthDir** (and any files in it won't reload on HUP signal). + - + - Launching new Onion Services through the control port is not supported - with current syscall sandboxing implementation. + - + - Tor must remain in client or server mode (some changes to **ClientOnly** - and **ORPort** are not allowed). Currently, if **Sandbox** is 1, - **ControlPort** command "GETINFO address" will not work. + - + - When using %include in the tor configuration files, reloading the tor - configuration is not supported after adding new configuration files or - directories. + - + - (Default: 0) - -[[Schedulers]] **Schedulers** **KIST**|**KISTLite**|**Vanilla**:: - Specify the scheduler type that tor should use. The scheduler is - responsible for moving data around within a Tor process. This is an ordered - list by priority which means that the first value will be tried first and if - unavailable, the second one is tried and so on. It is possible to change - these values at runtime. This option mostly effects relays, and most - operators should leave it set to its default value. - (Default: KIST,KISTLite,Vanilla) + - + - The possible scheduler types are: - + - **KIST**: Kernel-Informed Socket Transport. Tor will use TCP information - from the kernel to make informed decisions regarding how much data to send - and when to send it. KIST also handles traffic in batches (see - <>) in order to improve traffic prioritization decisions. - As implemented, KIST will only work on Linux kernel version 2.6.39 or - higher. + - + - **KISTLite**: Same as KIST but without kernel support. Tor will use all - the same mechanics as with KIST, including the batching, but its decisions - regarding how much data to send will not be as good. KISTLite will work on - all kernels and operating systems, and the majority of the benefits of KIST - are still realized with KISTLite. + - + - **Vanilla**: The scheduler that Tor used before KIST was implemented. It - sends as much data as possible, as soon as possible. Vanilla will work on - all kernels and operating systems. - -// Out of order because it logically belongs near the Schedulers option -[[KISTSchedRunInterval]] **KISTSchedRunInterval** __NUM__ **msec**:: - If KIST or KISTLite is used in the Schedulers option, this controls at which - interval the scheduler tick is. If the value is 0 msec, the value is taken - from the consensus if possible else it will fallback to the default 10 - msec. Maximum possible value is 100 msec. (Default: 0 msec) - -// Out of order because it logically belongs near the Schedulers option -[[KISTSockBufSizeFactor]] **KISTSockBufSizeFactor** __NUM__:: - If KIST is used in Schedulers, this is a multiplier of the per-socket - limit calculation of the KIST algorithm. (Default: 1.0) - - -[[ServerTransportListenAddr]] **ServerTransportListenAddr** __transport__ __IP__:__PORT__:: - When this option is set, Tor will suggest __IP__:__PORT__ as the - listening address of any pluggable transport proxy that tries to - launch __transport__. (IPv4 addresses should written as-is; IPv6 - addresses should be wrapped in square brackets.) (Default: none) - -[[ServerTransportOptions]] **ServerTransportOptions** __transport__ __k=v__ __k=v__ ...:: - When this option is set, Tor will pass the __k=v__ parameters to - any pluggable transport proxy that tries to launch __transport__. + - (Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd cache=/var/lib/tor/cache) (Default: none) - -[[ServerTransportPlugin]] **ServerTransportPlugin** __transport__ exec __path-to-binary__ [options]:: - The Tor relay launches the pluggable transport proxy in __path-to-binary__ - using __options__ as its command-line options, and expects to receive - proxied client traffic from it. (Default: none) - -[[Socks4Proxy]] **Socks4Proxy** __host__[:__port__]:: - Tor will make all OR connections through the SOCKS 4 proxy at host:port - (or host:1080 if port is not specified). - -[[Socks5Proxy]] **Socks5Proxy** __host__[:__port__]:: - Tor will make all OR connections through the SOCKS 5 proxy at host:port - (or host:1080 if port is not specified). - -// Out of order because Username logically precedes Password -[[Socks5ProxyUsername]] **Socks5ProxyUsername** __username__ + - -[[Socks5ProxyPassword]] **Socks5ProxyPassword** __password__:: - If defined, authenticate to the SOCKS 5 server using username and password - in accordance to RFC 1929. Both username and password must be between 1 and - 255 characters. - -[[SyslogIdentityTag]] **SyslogIdentityTag** __tag__:: - When logging to syslog, adds a tag to the syslog identity such that - log entries are marked with "Tor-__tag__". Can not be changed while tor is - running. (Default: none) - -[[TCPProxy]] **TCPProxy** __protocol__ __host__:__port__:: - Tor will use the given protocol to make all its OR (SSL) connections through - a TCP proxy on host:port, rather than connecting directly to servers. You may - want to set **FascistFirewall** to restrict the set of ports you might try to - connect to, if your proxy only allows connecting to certain ports. There is no - equivalent option for directory connections, because all Tor client versions - that support this option download directory documents via OR connections. + -+ - The only protocol supported right now 'haproxy'. This option is only for - clients. (Default: none) + -+ - The HAProxy version 1 proxy protocol is described in detail at - https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt + -+ - Both source IP address and source port will be set to zero. - -[[TruncateLogFile]] **TruncateLogFile** **0**|**1**:: - If 1, Tor will overwrite logs at startup and in response to a HUP signal, - instead of appending to them. (Default: 0) - -[[UnixSocksGroupWritable]] **UnixSocksGroupWritable** **0**|**1**:: - If this option is set to 0, don't allow the filesystem group to read and - write unix sockets (e.g. SocksPort unix:). If the option is set to 1, make - the Unix socket readable and writable by the default GID. (Default: 0) - -[[UseDefaultFallbackDirs]] **UseDefaultFallbackDirs** **0**|**1**:: - Use Tor's default hard-coded FallbackDirs (if any). (When a - FallbackDir line is present, it replaces the hard-coded FallbackDirs, - regardless of the value of UseDefaultFallbackDirs.) (Default: 1) - -[[User]] **User** __Username__:: - On startup, setuid to this user and setgid to their primary group. - Can not be changed while tor is running. - -== CLIENT OPTIONS - -// These options are in alphabetical order, with exceptions as noted. -// Please keep them that way! - -The following options are useful only for clients (that is, if -**SocksPort**, **HTTPTunnelPort**, **TransPort**, **DNSPort**, or -**NATDPort** is non-zero): - -[[AllowNonRFC953Hostnames]] **AllowNonRFC953Hostnames** **0**|**1**:: - When this option is disabled, Tor blocks hostnames containing illegal - characters (like @ and :) rather than sending them to an exit node to be - resolved. This helps trap accidental attempts to resolve URLs and so on. - (Default: 0) - -[[AutomapHostsOnResolve]] **AutomapHostsOnResolve** **0**|**1**:: - When this option is enabled, and we get a request to resolve an address - that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an - unused virtual address to that address, and return the new virtual address. - This is handy for making ".onion" addresses work with applications that - resolve an address and then connect to it. (Default: 0) - -[[AutomapHostsSuffixes]] **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__:: - A comma-separated list of suffixes to use with **AutomapHostsOnResolve**. - The "." suffix is equivalent to "all addresses." (Default: .exit,.onion). - -[[Bridge]] **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]:: - When set along with UseBridges, instructs Tor to use the relay at - "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint" - is provided (using the same format as for DirAuthority), we will verify that - the relay running at that location has the right fingerprint. We also use - fingerprint to look up the bridge descriptor at the bridge authority, if - it's provided and if UpdateBridgesFromAuthority is set too. + - + - If "transport" is provided, it must match a ClientTransportPlugin line. We - then use that pluggable transport's proxy to transfer data to the bridge, - rather than connecting to the bridge directly. Some transports use a - transport-specific method to work out the remote address to connect to. - These transports typically ignore the "IP:ORPort" specified in the bridge - line. + - + - Tor passes any "key=val" settings to the pluggable transport proxy as - per-connection arguments when connecting to the bridge. Consult - the documentation of the pluggable transport for details of what - arguments it supports. - -[[CircuitPadding]] **CircuitPadding** **0**|**1**:: - If set to 0, Tor will not pad client circuits with additional cover - traffic. Only clients may set this option. This option should be offered - via the UI to mobile users for use where bandwidth may be expensive. If - set to 1, padding will be negotiated as per the consensus and relay - support (unlike ConnectionPadding, CircuitPadding cannot be force-enabled). - (Default: 1) - -// Out of order because it logically belongs after CircuitPadding -[[ReducedCircuitPadding]] **ReducedCircuitPadding** **0**|**1**:: - If set to 1, Tor will only use circuit padding algorithms that have low - overhead. Only clients may set this option. This option should be offered - via the UI to mobile users for use where bandwidth may be expensive. - (Default: 0) - -[[ClientBootstrapConsensusAuthorityDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download consensuses from authorities - if they are bootstrapping (that is, they don't have a usable, reasonably - live consensus). Only used by clients fetching from a list of fallback - directory mirrors. This schedule is advanced by (potentially concurrent) - connection attempts, unlike other schedules, which are advanced by - connection failures. (Default: 6) - -[[ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download consensuses from authorities - if they are bootstrapping (that is, they don't have a usable, reasonably - live consensus). Only used by clients which don't have or won't fetch - from a list of fallback directory mirrors. This schedule is advanced by - (potentially concurrent) connection attempts, unlike other schedules, - which are advanced by connection failures. (Default: 0) - -[[ClientBootstrapConsensusFallbackDownloadInitialDelay]] **ClientBootstrapConsensusFallbackDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download consensuses from fallback - directory mirrors if they are bootstrapping (that is, they don't have a - usable, reasonably live consensus). Only used by clients fetching from a - list of fallback directory mirrors. This schedule is advanced by - (potentially concurrent) connection attempts, unlike other schedules, - which are advanced by connection failures. (Default: 0) - -[[ClientBootstrapConsensusMaxInProgressTries]] **ClientBootstrapConsensusMaxInProgressTries** __NUM__:: - Try this many simultaneous connections to download a consensus before - waiting for one to complete, timeout, or error out. (Default: 3) - -[[ClientDNSRejectInternalAddresses]] **ClientDNSRejectInternalAddresses** **0**|**1**:: - If true, Tor does not believe any anonymously retrieved DNS answer that - tells it that an address resolves to an internal address (like 127.0.0.1 or - 192.168.0.1). This option prevents certain browser-based attacks; it - is not allowed to be set on the default network. (Default: 1) - -[[ClientOnionAuthDir]] **ClientOnionAuthDir** __path__:: - Path to the directory containing v3 hidden service authorization files. - Each file is for a single onion address, and the files MUST have the suffix - ".auth_private" (i.e. "bob_onion.auth_private"). The content format MUST be: - + - :descriptor:x25519: - + - The MUST NOT have the ".onion" suffix. The - is the base32 representation of the raw key bytes - only (32 bytes for x25519). See Appendix G in the rend-spec-v3.txt file of - https://spec.torproject.org/[torspec] for more information. - -[[ClientOnly]] **ClientOnly** **0**|**1**:: - If set to 1, Tor will not run as a relay or serve - directory requests, even if the ORPort, ExtORPort, or DirPort options are - set. (This config option is - mostly unnecessary: we added it back when we were considering having - Tor clients auto-promote themselves to being relays if they were stable - and fast enough. The current behavior is simply that Tor is a client - unless ORPort, ExtORPort, or DirPort are configured.) (Default: 0) - -[[ClientPreferIPv6DirPort]] **ClientPreferIPv6DirPort** **0**|**1**|**auto**:: - If this option is set to 1, Tor prefers a directory port with an IPv6 - address over one with IPv4, for direct connections, if a given directory - server has both. (Tor also prefers an IPv6 DirPort if IPv4Client is set to - 0.) If this option is set to auto, clients prefer IPv4. Other things may - influence the choice. This option breaks a tie to the favor of IPv6. - (Default: auto) (DEPRECATED: This option has had no effect for some - time.) - -[[ClientPreferIPv6ORPort]] **ClientPreferIPv6ORPort** **0**|**1**|**auto**:: - If this option is set to 1, Tor prefers an OR port with an IPv6 - address over one with IPv4 if a given entry node has both. (Tor also - prefers an IPv6 ORPort if IPv4Client is set to 0.) If this option is set - to auto, Tor bridge clients prefer the configured bridge address, and - other clients prefer IPv4. Other things may influence the choice. This - option breaks a tie to the favor of IPv6. (Default: auto) - -[[ClientRejectInternalAddresses]] **ClientRejectInternalAddresses** **0**|**1**:: - If true, Tor does not try to fulfill requests to connect to an internal - address (like 127.0.0.1 or 192.168.0.1) __unless an exit node is - specifically requested__ (for example, via a .exit hostname, or a - controller request). If true, multicast DNS hostnames for machines on the - local network (of the form *.local) are also rejected. (Default: 1) - -[[ClientUseIPv4]] **ClientUseIPv4** **0**|**1**:: - If this option is set to 0, Tor will avoid connecting to directory servers - and entry nodes over IPv4. Note that clients with an IPv4 - address in a **Bridge**, proxy, or pluggable transport line will try - connecting over IPv4 even if **ClientUseIPv4** is set to 0. (Default: 1) - -[[ClientUseIPv6]] **ClientUseIPv6** **0**|**1**:: - If this option is set to 1, Tor might connect to directory servers or - entry nodes over IPv6. For IPv6 only hosts, you need to also set - **ClientUseIPv4** to 0 to disable IPv4. Note that clients configured with - an IPv6 address in a **Bridge**, proxy, or pluggable transportline will - try connecting over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0) - -[[ConnectionPadding]] **ConnectionPadding** **0**|**1**|**auto**:: - This option governs Tor's use of padding to defend against some forms of - traffic analysis. If it is set to 'auto', Tor will send padding only - if both the client and the relay support it. If it is set to 0, Tor will - not send any padding cells. If it is set to 1, Tor will still send padding - for client connections regardless of relay support. Only clients may set - this option. This option should be offered via the UI to mobile users - for use where bandwidth may be expensive. - (Default: auto) - -// Out of order because it logically belongs after ConnectionPadding -[[ReducedConnectionPadding]] **ReducedConnectionPadding** **0**|**1**:: - If set to 1, Tor will not not hold OR connections open for very long, - and will send less padding on these connections. Only clients may set - this option. This option should be offered via the UI to mobile users - for use where bandwidth may be expensive. (Default: 0) - -[[DNSPort]] **DNSPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: - If non-zero, open this port to listen for UDP DNS requests, and resolve - them anonymously. This port only handles A, AAAA, and PTR requests---it - doesn't handle arbitrary DNS request types. Set the port to "auto" to - have Tor pick a port for - you. This directive can be specified multiple times to bind to multiple - addresses/ports. See <> for an explanation of isolation - flags. (Default: 0) - -[[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**:: - If true, Tor downloads and caches "extra-info" documents. These documents - contain information about servers other than the information in their - regular server descriptors. Tor does not use this information for anything - itself; to save bandwidth, leave this option turned off. (Default: 0) - -[[EnforceDistinctSubnets]] **EnforceDistinctSubnets** **0**|**1**:: - If 1, Tor will not put two servers whose IP addresses are "too close" on - the same circuit. Currently, two addresses are "too close" if they lie in - the same /16 range. (Default: 1) - -[[FascistFirewall]] **FascistFirewall** **0**|**1**:: - If 1, Tor will only create outgoing connections to ORs running on ports - that your firewall allows (defaults to 80 and 443; see <>). - This will allow you to run Tor as a client behind a firewall with - restrictive policies, but will not allow you to run as a server behind such - a firewall. If you prefer more fine-grained control, use - ReachableAddresses instead. - -[[FirewallPorts]] **FirewallPorts** __PORTS__:: - A list of ports that your firewall allows you to connect to. Only used when - **FascistFirewall** is set. This option is deprecated; use ReachableAddresses - instead. (Default: 80, 443) - -[[HidServAuth]] **HidServAuth** __onion-address__ __auth-cookie__ [__service-name__]:: - Client authorization for a v2 hidden service. Valid onion addresses contain 16 - characters in a-z2-7 plus ".onion", and valid auth cookies contain 22 - characters in A-Za-z0-9+/. The service name is only used for internal - purposes, e.g., for Tor controllers. This option may be used multiple times - for different hidden services. If a hidden service uses authorization and - this option is not set, the hidden service is not accessible. Hidden - services can be configured to require authorization using the - **HiddenServiceAuthorizeClient** option. - -[[HTTPTunnelPort]] **HTTPTunnelPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: - Open this port to listen for proxy connections using the "HTTP CONNECT" - protocol instead of SOCKS. Set this to - 0 if you don't want to allow "HTTP CONNECT" connections. Set the port - to "auto" to have Tor pick a port for you. This directive can be - specified multiple times to bind to multiple addresses/ports. If multiple - entries of this option are present in your configuration file, Tor will - perform stream isolation between listeners by default. See - <> for an explanation of isolation flags. (Default: 0) - -[[LongLivedPorts]] **LongLivedPorts** __PORTS__:: - A list of ports for services that tend to have long-running connections - (e.g. chat and interactive shells). Circuits for streams that use these - ports will contain only high-uptime nodes, to reduce the chance that a node - will go down before the stream is finished. Note that the list is also - honored for circuits (both client and service side) involving hidden - services whose virtual port is in this list. (Default: 21, 22, 706, - 1863, 5050, 5190, 5222, 5223, 6523, 6667, 6697, 8300) - -[[MapAddress]] **MapAddress** __address__ __newaddress__:: - When a request for address arrives to Tor, it will transform to newaddress - before processing it. For example, if you always want connections to - www.example.com to exit via __torserver__ (where __torserver__ is the - fingerprint of the server), use "MapAddress www.example.com - www.example.com.torserver.exit". If the value is prefixed with a - "\*.", matches an entire domain. For example, if you - always want connections to example.com and any if its subdomains - to exit via - __torserver__ (where __torserver__ is the fingerprint of the server), use - "MapAddress \*.example.com \*.example.com.torserver.exit". (Note the - leading "*." in each part of the directive.) You can also redirect all - subdomains of a domain to a single address. For example, "MapAddress - *.example.com www.example.com". If the specified exit is not available, - or the exit can not connect to the site, Tor will fail any connections - to the mapped address.+ - + - NOTES: - - 1. When evaluating MapAddress expressions Tor stops when it hits the most - recently added expression that matches the requested address. So if you - have the following in your torrc, www.torproject.org will map to - 198.51.100.1: - - MapAddress www.torproject.org 192.0.2.1 - MapAddress www.torproject.org 198.51.100.1 - - 2. Tor evaluates the MapAddress configuration until it finds no matches. So - if you have the following in your torrc, www.torproject.org will map to - 203.0.113.1: - - MapAddress 198.51.100.1 203.0.113.1 - MapAddress www.torproject.org 198.51.100.1 - - 3. The following MapAddress expression is invalid (and will be - ignored) because you cannot map from a specific address to a wildcard - address: - - MapAddress www.torproject.org *.torproject.org.torserver.exit - - 4. Using a wildcard to match only part of a string (as in *ample.com) is - also invalid. - - 5. Tor maps hostnames and IP addresses separately. If you MapAddress - a DNS name, but use an IP address to connect, then Tor will ignore the - DNS name mapping. - - 6. MapAddress does not apply to redirects in the application protocol. - For example, HTTP redirects and alt-svc headers will ignore mappings - for the original address. You can use a wildcard mapping to handle - redirects within the same site. - -[[MaxCircuitDirtiness]] **MaxCircuitDirtiness** __NUM__:: - Feel free to reuse a circuit that was first used at most NUM seconds ago, - but never attach a new stream to a circuit that is too old. For hidden - services, this applies to the __last__ time a circuit was used, not the - first. Circuits with streams constructed with SOCKS authentication via - SocksPorts that have **KeepAliveIsolateSOCKSAuth** also remain alive - for MaxCircuitDirtiness seconds after carrying the last such stream. - (Default: 10 minutes) - -[[MaxClientCircuitsPending]] **MaxClientCircuitsPending** __NUM__:: - Do not allow more than NUM circuits to be pending at a time for handling - client streams. A circuit is pending if we have begun constructing it, - but it has not yet been completely constructed. (Default: 32) - -[[NATDPort]] **NATDPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: - Open this port to listen for connections from old versions of ipfw (as - included in old versions of FreeBSD, etc) using the NATD protocol. - Use 0 if you don't want to allow NATD connections. Set the port - to "auto" to have Tor pick a port for you. This directive can be - specified multiple times to bind to multiple addresses/ports. If multiple - entries of this option are present in your configuration file, Tor will - perform stream isolation between listeners by default. See - <> for an explanation of isolation flags. + - + - This option is only for people who cannot use TransPort. (Default: 0) - -[[NewCircuitPeriod]] **NewCircuitPeriod** __NUM__:: - Every NUM seconds consider whether to build a new circuit. (Default: 30 - seconds) - -[[OptimisticData]] **OptimisticData** **0**|**1**|**auto**:: - When this option is set, and Tor is using an exit node that supports - the feature, it will try optimistically to send data to the exit node - without waiting for the exit node to report whether the connection - succeeded. This can save a round-trip time for protocols like HTTP - where the client talks first. If OptimisticData is set to **auto**, - Tor will look at the UseOptimisticData parameter in the networkstatus. - (Default: auto) - -// These are out of order because they logically belong together -[[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ + - -[[PathBiasDropGuards]] **PathBiasDropGuards** __NUM__ + - -[[PathBiasExtremeRate]] **PathBiasExtremeRate** __NUM__ + - -[[PathBiasNoticeRate]] **PathBiasNoticeRate** __NUM__ + - -[[PathBiasWarnRate]] **PathBiasWarnRate** __NUM__ + - -[[PathBiasScaleThreshold]] **PathBiasScaleThreshold** __NUM__:: - These options override the default behavior of Tor's (**currently - experimental**) path bias detection algorithm. To try to find broken or - misbehaving guard nodes, Tor looks for nodes where more than a certain - fraction of circuits through that guard fail to get built. + - + - The PathBiasCircThreshold option controls how many circuits we need to build - through a guard before we make these checks. The PathBiasNoticeRate, - PathBiasWarnRate and PathBiasExtremeRate options control what fraction of - circuits must succeed through a guard so we won't write log messages. - If less than PathBiasExtremeRate circuits succeed *and* PathBiasDropGuards - is set to 1, we disable use of that guard. + - + - When we have seen more than PathBiasScaleThreshold - circuits through a guard, we scale our observations by 0.5 (governed by - the consensus) so that new observations don't get swamped by old ones. + - + - By default, or if a negative value is provided for one of these options, - Tor uses reasonable defaults from the networkstatus consensus document. - If no defaults are available there, these options default to 150, .70, - .50, .30, 0, and 300 respectively. - -// These are out of order because they logically belong together -[[PathBiasUseThreshold]] **PathBiasUseThreshold** __NUM__ + - -[[PathBiasNoticeUseRate]] **PathBiasNoticeUseRate** __NUM__ + - -[[PathBiasExtremeUseRate]] **PathBiasExtremeUseRate** __NUM__ + - -[[PathBiasScaleUseThreshold]] **PathBiasScaleUseThreshold** __NUM__:: - Similar to the above options, these options override the default behavior - of Tor's (**currently experimental**) path use bias detection algorithm. + - + - Where as the path bias parameters govern thresholds for successfully - building circuits, these four path use bias parameters govern thresholds - only for circuit usage. Circuits which receive no stream usage - are not counted by this detection algorithm. A used circuit is considered - successful if it is capable of carrying streams or otherwise receiving - well-formed responses to RELAY cells. + - + - By default, or if a negative value is provided for one of these options, - Tor uses reasonable defaults from the networkstatus consensus document. - If no defaults are available there, these options default to 20, .80, - .60, and 100, respectively. - -[[PathsNeededToBuildCircuits]] **PathsNeededToBuildCircuits** __NUM__:: - Tor clients don't build circuits for user traffic until they know - about enough of the network so that they could potentially construct - enough of the possible paths through the network. If this option - is set to a fraction between 0.25 and 0.95, Tor won't build circuits - until it has enough descriptors or microdescriptors to construct - that fraction of possible paths. Note that setting this option too low - can make your Tor client less anonymous, and setting it too high can - prevent your Tor client from bootstrapping. If this option is negative, - Tor will use a default value chosen by the directory authorities. If the - directory authorities do not choose a value, Tor will default to 0.6. - (Default: -1) - -[[ReachableAddresses]] **ReachableAddresses** __IP__[/__MASK__][:__PORT__]...:: - A comma-separated list of IP addresses and ports that your firewall allows - you to connect to. The format is as for the addresses in ExitPolicy, except - that "accept" is understood unless "reject" is explicitly provided. For - example, \'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept - \*:80' means that your firewall allows connections to everything inside net - 99, rejects port 80 connections to net 18, and accepts connections to port - 80 otherwise. (Default: \'accept \*:*'.) - -[[ReachableDirAddresses]] **ReachableDirAddresses** __IP__[/__MASK__][:__PORT__]...:: - Like **ReachableAddresses**, a list of addresses and ports. Tor will obey - these restrictions when fetching directory information, using standard HTTP - GET requests. If not set explicitly then the value of - **ReachableAddresses** is used. If **HTTPProxy** is set then these - connections will go through that proxy. (DEPRECATED: This option has - had no effect for some time.) - -[[ReachableORAddresses]] **ReachableORAddresses** __IP__[/__MASK__][:__PORT__]...:: - Like **ReachableAddresses**, a list of addresses and ports. Tor will obey - these restrictions when connecting to Onion Routers, using TLS/SSL. If not - set explicitly then the value of **ReachableAddresses** is used. If - **HTTPSProxy** is set then these connections will go through that proxy. + - + - The separation between **ReachableORAddresses** and - **ReachableDirAddresses** is only interesting when you are connecting - through proxies (see <> and <>). Most proxies limit - TLS connections (which Tor uses to connect to Onion Routers) to port 443, - and some limit HTTP GET requests (which Tor uses for fetching directory - information) to port 80. - -[[SafeSocks]] **SafeSocks** **0**|**1**:: - When this option is enabled, Tor will reject application connections that - use unsafe variants of the socks protocol -- ones that only provide an IP - address, meaning the application is doing a DNS resolve first. - Specifically, these are socks4 and socks5 when not doing remote DNS. - (Default: 0) - -// Out of order because it logically belongs after SafeSocks -[[TestSocks]] **TestSocks** **0**|**1**:: - When this option is enabled, Tor will make a notice-level log entry for - each connection to the Socks port indicating whether the request used a - safe socks protocol or an unsafe one (see <>). This - helps to determine whether an application using Tor is possibly leaking - DNS requests. (Default: 0) - -// Out of order because it logically belongs with SafeSocks -[[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__:: - Tells Tor to issue a warnings whenever the user tries to make an anonymous - connection to one of these ports. This option is designed to alert users - to services that risk sending passwords in the clear. (Default: - 23,109,110,143) - -// Out of order because it logically belongs with SafeSocks -[[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__:: - Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor - will instead refuse to make the connection. (Default: None) - -[[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__:: - Set an entrance policy for this server, to limit who can connect to the - SocksPort and DNSPort ports. The policies have the same form as exit - policies below, except that port specifiers are ignored. Any address - not matched by some entry in the policy is accepted. - -[[SocksPort]] **SocksPort** ['address'**:**]{empty}__port__|**unix:**__path__|**auto** [_flags_] [_isolation flags_]:: - Open this port to listen for connections from SOCKS-speaking - applications. Set this to 0 if you don't want to allow application - connections via SOCKS. Set it to "auto" to have Tor pick a port for - you. This directive can be specified multiple times to bind - to multiple addresses/ports. If a unix domain socket is used, you may - quote the path using standard C escape sequences. Most flags are off by - default, except where specified. Flags that are on by default can be - disabled by putting "No" before the flag name. - (Default: 9050) + - + - NOTE: Although this option allows you to specify an IP address - other than localhost, you should do so only with extreme caution. - The SOCKS protocol is unencrypted and (as we use it) - unauthenticated, so exposing it in this way could leak your - information to anybody watching your network, and allow anybody - to use your computer as an open proxy. + - + - If multiple entries of this option are present in your configuration - file, Tor will perform stream isolation between listeners by default. - The _isolation flags_ arguments give Tor rules for which streams - received on this SocksPort are allowed to share circuits with one - another. Recognized isolation flags are: - **IsolateClientAddr**;; - Don't share circuits with streams from a different - client address. (On by default and strongly recommended when - supported; you can disable it with **NoIsolateClientAddr**. - Unsupported and force-disabled when using Unix domain sockets.) - **IsolateSOCKSAuth**;; - Don't share circuits with streams for which different - SOCKS authentication was provided. (For HTTPTunnelPort - connections, this option looks at the Proxy-Authorization and - X-Tor-Stream-Isolation headers. On by default; - you can disable it with **NoIsolateSOCKSAuth**.) - **IsolateClientProtocol**;; - Don't share circuits with streams using a different protocol. - (SOCKS 4, SOCKS 5, HTTPTunnelPort connections, TransPort connections, - NATDPort connections, and DNSPort requests are all considered to be - different protocols.) - **IsolateDestPort**;; - Don't share circuits with streams targeting a different - destination port. - **IsolateDestAddr**;; - Don't share circuits with streams targeting a different - destination address. - **KeepAliveIsolateSOCKSAuth**;; - If **IsolateSOCKSAuth** is enabled, keep alive circuits while they have - at least one stream with SOCKS authentication active. After such a - circuit is idle for more than MaxCircuitDirtiness seconds, it can be - closed. - **SessionGroup=**__INT__;; - If no other isolation rules would prevent it, allow streams - on this port to share circuits with streams from every other - port with the same session group. (By default, streams received - on different SocksPorts, TransPorts, etc are always isolated from one - another. This option overrides that behavior.) - -// Anchor only for formatting, not visible in the man page. -[[OtherSocksPortFlags]]:: - Other recognized __flags__ for a SocksPort are: - **NoIPv4Traffic**;; - Tell exits to not connect to IPv4 addresses in response to SOCKS - requests on this connection. - **IPv6Traffic**;; - Tell exits to allow IPv6 addresses in response to SOCKS requests on - this connection, so long as SOCKS5 is in use. (SOCKS4 can't handle - IPv6.) - **PreferIPv6**;; - Tells exits that, if a host has both an IPv4 and an IPv6 address, - we would prefer to connect to it via IPv6. (IPv4 is the default.) - **NoDNSRequest**;; - Do not ask exits to resolve DNS addresses in SOCKS5 requests. Tor will - connect to IPv4 addresses, IPv6 addresses (if IPv6Traffic is set) and - .onion addresses. - **NoOnionTraffic**;; - Do not connect to .onion addresses in SOCKS5 requests. - **OnionTrafficOnly**;; - Tell the tor client to only connect to .onion addresses in response to - SOCKS5 requests on this connection. This is equivalent to NoDNSRequest, - NoIPv4Traffic, NoIPv6Traffic. The corresponding NoOnionTrafficOnly - flag is not supported. - **CacheIPv4DNS**;; - Tells the client to remember IPv4 DNS answers we receive from exit - nodes via this connection. - **CacheIPv6DNS**;; - Tells the client to remember IPv6 DNS answers we receive from exit - nodes via this connection. - **GroupWritable**;; - Unix domain sockets only: makes the socket get created as - group-writable. - **WorldWritable**;; - Unix domain sockets only: makes the socket get created as - world-writable. - **CacheDNS**;; - Tells the client to remember all DNS answers we receive from exit - nodes via this connection. - **UseIPv4Cache**;; - Tells the client to use any cached IPv4 DNS answers we have when making - requests via this connection. (NOTE: This option, or UseIPv6Cache - or UseDNSCache, can harm your anonymity, and probably - won't help performance as much as you might expect. Use with care!) - **UseIPv6Cache**;; - Tells the client to use any cached IPv6 DNS answers we have when making - requests via this connection. - **UseDNSCache**;; - Tells the client to use any cached DNS answers we have when making - requests via this connection. - **NoPreferIPv6Automap**;; - When serving a hostname lookup request on this port that - should get automapped (according to AutomapHostsOnResolve), - if we could return either an IPv4 or an IPv6 answer, prefer - an IPv4 answer. (Tor prefers IPv6 by default.) - **PreferSOCKSNoAuth**;; - Ordinarily, when an application offers both "username/password - authentication" and "no authentication" to Tor via SOCKS5, Tor - selects username/password authentication so that IsolateSOCKSAuth can - work. This can confuse some applications, if they offer a - username/password combination then get confused when asked for - one. You can disable this behavior, so that Tor will select "No - authentication" when IsolateSOCKSAuth is disabled, or when this - option is set. - **ExtendedErrors**;; - Return extended error code in the SOCKS reply. So far, the possible - errors are: - - X'F0' Onion Service Descriptor Can Not be Found - - The requested onion service descriptor can't be found on the - hashring and thus not reachable by the client. (v3 only) - - X'F1' Onion Service Descriptor Is Invalid - - The requested onion service descriptor can't be parsed or - signature validation failed. (v3 only) - - X'F2' Onion Service Introduction Failed - - All introduction attempts failed either due to a combination of - NACK by the intro point or time out. (v3 only) - - X'F3' Onion Service Rendezvous Failed - - Every rendezvous circuit has timed out and thus the client is - unable to rendezvous with the service. (v3 only) - - X'F4' Onion Service Missing Client Authorization - - Client was able to download the requested onion service descriptor - but is unable to decrypt its content because it is missing client - authorization information. (v3 only) - - X'F5' Onion Service Wrong Client Authorization - - Client was able to download the requested onion service descriptor - but is unable to decrypt its content using the client - authorization information it has. This means the client access - were revoked. (v3 only) - - X'F6' Onion Service Invalid Address - - The given .onion address is invalid. In one of these cases this - error is returned: address checksum doesn't match, ed25519 public - key is invalid or the encoding is invalid. (v3 only) - - X'F7' Onion Service Introduction Timed Out - - Similar to X'F2' code but in this case, all introduction attempts - have failed due to a time out. (v3 only) - -// Anchor only for formatting, not visible in the man page. -[[SocksPortFlagsMisc]]:: - Flags are processed left to right. If flags conflict, the last flag on the - line is used, and all earlier flags are ignored. No error is issued for - conflicting flags. - -[[TokenBucketRefillInterval]] **TokenBucketRefillInterval** __NUM__ [**msec**|**second**]:: - Set the refill delay interval of Tor's token bucket to NUM milliseconds. - NUM must be between 1 and 1000, inclusive. When Tor is out of bandwidth, - on a connection or globally, it will wait up to this long before it tries - to use that connection again. - Note that bandwidth limits are still expressed in bytes per second: this - option only affects the frequency with which Tor checks to see whether - previously exhausted connections may read again. - Can not be changed while tor is running. (Default: 100 msec) - -[[TrackHostExits]] **TrackHostExits** __host__,__.domain__,__...__:: - For each value in the comma separated list, Tor will track recent - connections to hosts that match this value and attempt to reuse the same - exit node for each. If the value is prepended with a \'.\', it is treated as - matching an entire domain. If one of the values is just a \'.', it means - match everything. This option is useful if you frequently connect to sites - that will expire all your authentication cookies (i.e. log you out) if - your IP address changes. Note that this option does have the disadvantage - of making it more clear that a given history is associated with a single - user. However, most people who would wish to observe this will observe it - through cookies or other protocol-specific means anyhow. - -[[TrackHostExitsExpire]] **TrackHostExitsExpire** __NUM__:: - Since exit servers go up and down, it is desirable to expire the - association between host and exit server after NUM seconds. The default is - 1800 seconds (30 minutes). - -[[TransPort]] **TransPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: - Open this port to listen for transparent proxy connections. Set this to - 0 if you don't want to allow transparent proxy connections. Set the port - to "auto" to have Tor pick a port for you. This directive can be - specified multiple times to bind to multiple addresses/ports. If multiple - entries of this option are present in your configuration file, Tor will - perform stream isolation between listeners by default. See - <> for an explanation of isolation flags. + - + - TransPort requires OS support for transparent proxies, such as BSDs' pf or - Linux's IPTables. If you're planning to use Tor as a transparent proxy for - a network, you'll want to examine and change VirtualAddrNetwork from the - default setting. (Default: 0) - -[[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**:: - TransProxyType may only be enabled when there is transparent proxy listener - enabled. + - + - Set this to "TPROXY" if you wish to be able to use the TPROXY Linux module - to transparently proxy connections that are configured using the TransPort - option. Detailed information on how to configure the TPROXY - feature can be found in the Linux kernel source tree in the file - Documentation/networking/tproxy.txt. + - + - Set this option to "ipfw" to use the FreeBSD ipfw interface. + - + - On *BSD operating systems when using pf, set this to "pf-divert" to take - advantage of +divert-to+ rules, which do not modify the packets like - +rdr-to+ rules do. Detailed information on how to configure pf to use - +divert-to+ rules can be found in the pf.conf(5) manual page. On OpenBSD, - +divert-to+ is available to use on versions greater than or equal to - OpenBSD 4.4. + - + - Set this to "default", or leave it unconfigured, to use regular IPTables - on Linux, or to use pf +rdr-to+ rules on *BSD systems. + - + - (Default: "default") - -[[UpdateBridgesFromAuthority]] **UpdateBridgesFromAuthority** **0**|**1**:: - When set (along with UseBridges), Tor will try to fetch bridge descriptors - from the configured bridge authorities when feasible. It will fall back to - a direct request if the authority responds with a 404. (Default: 0) - -[[UseBridges]] **UseBridges** **0**|**1**:: - When set, Tor will fetch descriptors for each bridge listed in the "Bridge" - config lines, and use these relays as both entry guards and directory - guards. (Default: 0) - -[[UseEntryGuards]] **UseEntryGuards** **0**|**1**:: - If this option is set to 1, we pick a few long-term entry servers, and try - to stick with them. This is desirable because constantly changing servers - increases the odds that an adversary who owns some servers will observe a - fraction of your paths. Entry Guards can not be used by Directory - Authorities or Single Onion Services. In these cases, - this option is ignored. (Default: 1) - -[[UseGuardFraction]] **UseGuardFraction** **0**|**1**|**auto**:: - This option specifies whether clients should use the - guardfraction information found in the consensus during path - selection. If it's set to 'auto', clients will do what the - UseGuardFraction consensus parameter tells them to do. (Default: auto) - -//Out of order because it logically belongs after the UseEntryGuards option -[[GuardLifetime]] **GuardLifetime** __N__ **days**|**weeks**|**months**:: - If UseEntryGuards is set, minimum time to keep a guard on our guard list - before picking a new one. If less than one day, we use defaults from the - consensus directory. (Default: 0) - -//Out of order because it logically belongs after the UseEntryGuards option -[[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__:: - If UseEntryGuards is set to 1, we try to make sure we have at least NUM - routers to use as directory guards. If this option is set to 0, use the - value from the guard-n-primary-dir-guards-to-use consensus parameter, and - default to 3 if the consensus parameter isn't set. (Default: 0) - -//Out of order because it logically belongs after the UseEntryGuards option -[[NumEntryGuards]] **NumEntryGuards** __NUM__:: - If UseEntryGuards is set to 1, we will try to pick a total of NUM routers - as long-term entries for our circuits. If NUM is 0, we try to learn the - number from the guard-n-primary-guards-to-use consensus parameter, and - default to 1 if the consensus parameter isn't set. (Default: 0) - -//Out of order because it logically belongs after the UseEntryGuards option -[[NumPrimaryGuards]] **NumPrimaryGuards** __NUM__:: - If UseEntryGuards is set to 1, we will try to pick NUM routers for our - primary guard list, which is the set of routers we strongly prefer when - connecting to the Tor network. If NUM is 0, we try to learn the number from - the guard-n-primary-guards consensus parameter, and default to 3 if the - consensus parameter isn't set. (Default: 0) - -[[UseMicrodescriptors]] **UseMicrodescriptors** **0**|**1**|**auto**:: - Microdescriptors are a smaller version of the information that Tor needs - in order to build its circuits. Using microdescriptors makes Tor clients - download less directory information, thus saving bandwidth. Directory - caches need to fetch regular descriptors and microdescriptors, so this - option doesn't save any bandwidth for them. For legacy reasons, auto is - accepted, but it has the same effect as 1. (Default: auto) - -[[VirtualAddrNetworkIPv4]] **VirtualAddrNetworkIPv4** __IPv4Address__/__bits__ + - -[[VirtualAddrNetworkIPv6]] **VirtualAddrNetworkIPv6** [__IPv6Address__]/__bits__:: - When Tor needs to assign a virtual (unused) address because of a MAPADDRESS - command from the controller or the AutomapHostsOnResolve feature, Tor - picks an unassigned address from this range. (Defaults: - 127.192.0.0/10 and [FE80::]/10 respectively.) + - + - When providing proxy server service to a network of computers using a tool - like dns-proxy-tor, change the IPv4 network to "10.192.0.0/10" or - "172.16.0.0/12" and change the IPv6 network to "[FC00::]/7". - The default **VirtualAddrNetwork** address ranges on a - properly configured machine will route to the loopback or link-local - interface. The maximum number of bits for the network prefix is set to 104 - for IPv6 and 16 for IPv4. However, a wider network - smaller prefix length - - is preferable since it reduces the chances for an attacker to guess the - used IP. For local use, no change to the default VirtualAddrNetwork setting - is needed. - -== CIRCUIT TIMEOUT OPTIONS - -// These options are in alphabetical order, with exceptions as noted. -// Please keep them that way! - -The following options are useful for configuring timeouts related -to building Tor circuits and using them: - -[[CircuitsAvailableTimeout]] **CircuitsAvailableTimeout** __NUM__:: - Tor will attempt to keep at least one open, unused circuit available for - this amount of time. This option governs how long idle circuits are kept - open, as well as the amount of time Tor will keep a circuit open to each - of the recently used ports. This way when the Tor client is entirely - idle, it can expire all of its circuits, and then expire its TLS - connections. Note that the actual timeout value is uniformly randomized - from the specified value to twice that amount. (Default: 30 minutes; - Max: 24 hours) - -// Out of order because it logically belongs before the CircuitBuildTimeout option -[[LearnCircuitBuildTimeout]] **LearnCircuitBuildTimeout** **0**|**1**:: - If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1) - -[[CircuitBuildTimeout]] **CircuitBuildTimeout** __NUM__:: - Try for at most NUM seconds when building circuits. If the circuit isn't - open in that time, give up on it. If LearnCircuitBuildTimeout is 1, this - value serves as the initial value to use before a timeout is learned. If - LearnCircuitBuildTimeout is 0, this value is the only value used. - (Default: 60 seconds) - -[[CircuitStreamTimeout]] **CircuitStreamTimeout** __NUM__:: - If non-zero, this option overrides our internal timeout schedule for how - many seconds until we detach a stream from a circuit and try a new circuit. - If your network is particularly slow, you might want to set this to a - number like 60. (Default: 0) - -[[SocksTimeout]] **SocksTimeout** __NUM__:: - Let a socks connection wait NUM seconds handshaking, and NUM seconds - unattached waiting for an appropriate circuit, before we fail it. (Default: - 2 minutes) - -== DORMANT MODE OPTIONS - -// These options are in alphabetical order, with exceptions as noted. -// Please keep them that way! - -Tor can enter dormant mode to conserve power and network bandwidth. -The following options control when Tor enters and leaves dormant mode: - -[[DormantCanceledByStartup]] **DormantCanceledByStartup** **0**|**1**:: - By default, Tor starts in active mode if it was active the last time - it was shut down, and in dormant mode if it was dormant. But if - this option is true, Tor treats every startup event as user - activity, and Tor will never start in Dormant mode, even if it has - been unused for a long time on previous runs. (Default: 0) - + - Note: Packagers and application developers should change the value of - this option only with great caution: it has the potential to - create spurious traffic on the network. This option should only - be used if Tor is started by an affirmative user activity (like - clicking on an applcation or running a command), and not if Tor - is launched for some other reason (for example, by a startup - process, or by an application that launches itself on every login.) - -[[DormantClientTimeout]] **DormantClientTimeout** __N__ **minutes**|**hours**|**days**|**weeks**:: - If Tor spends this much time without any client activity, - enter a dormant state where automatic circuits are not built, and - directory information is not fetched. - Does not affect servers or onion services. Must be at least 10 minutes. - (Default: 24 hours) - -[[DormantOnFirstStartup]] **DormantOnFirstStartup** **0**|**1**:: - If true, then the first time Tor starts up with a fresh DataDirectory, - it starts in dormant mode, and takes no actions until the user has made - a request. (This mode is recommended if installing a Tor client for a - user who might not actually use it.) If false, Tor bootstraps the first - time it is started, whether it sees a user request or not. - + - After the first time Tor starts, it begins in dormant mode if it was - dormant before, and not otherwise. (Default: 0) - -[[DormantTimeoutDisabledByIdleStreams]] **DormantTimeoutDisabledByIdleStreams** **0**|**1**:: - If true, then any open client stream (even one not reading or writing) - counts as client activity for the purpose of DormantClientTimeout. - If false, then only network activity counts. (Default: 1) - -== NODE SELECTION OPTIONS - -// These options are in alphabetical order, with exceptions as noted. -// Please keep them that way! - -The following options restrict the nodes that a tor client -(or onion service) can use while building a circuit. -These options can weaken your anonymity by making your client behavior -different from other Tor clients: - -[[EntryNodes]] **EntryNodes** __node__,__node__,__...__:: - A list of identity fingerprints and country codes of nodes - to use for the first hop in your normal circuits. - Normal circuits include all - circuits except for direct connections to directory servers. The Bridge - option overrides this option; if you have configured bridges and - UseBridges is 1, the Bridges are used as your entry nodes. + - + - The ExcludeNodes option overrides this option: any node listed in both - EntryNodes and ExcludeNodes is treated as excluded. See - <> for more information on how to specify nodes. - -[[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__:: - A list of identity fingerprints, country codes, and address - patterns of nodes to avoid when building a circuit. Country codes are - 2-letter ISO3166 codes, and must - be wrapped in braces; fingerprints may be preceded by a dollar sign. - (Example: - ExcludeNodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + - + - By default, this option is treated as a preference that Tor is allowed - to override in order to keep working. - For example, if you try to connect to a hidden service, - but you have excluded all of the hidden service's introduction points, - Tor will connect to one of them anyway. If you do not want this - behavior, set the StrictNodes option (documented below). + - + - Note also that if you are a relay, this (and the other node selection - options below) only affects your own circuits that Tor builds for you. - Clients can still build circuits through you to any node. Controllers - can tell Tor to build circuits through any node. + - + - Country codes are case-insensitive. The code "\{??}" refers to nodes whose - country can't be identified. No country code, including \{??}, works if - no GeoIPFile can be loaded. See also the <> option below. - -// Out of order because it logically belongs after the ExcludeNodes option -[[ExcludeExitNodes]] **ExcludeExitNodes** __node__,__node__,__...__:: - A list of identity fingerprints, country codes, and address - patterns of nodes to never use when picking an exit node---that is, a - node that delivers traffic for you *outside* the Tor network. Note that any - node listed in ExcludeNodes is automatically considered to be part of this - list too. See - <> for more information on how to specify - nodes. See also the caveats on the <> option below. - -[[ExitNodes]] **ExitNodes** __node__,__node__,__...__:: - A list of identity fingerprints, country codes, and address - patterns of nodes to use as exit node---that is, a - node that delivers traffic for you *outside* the Tor network. See - <> for more information on how to specify nodes. + - + - Note that if you list too few nodes here, or if you exclude too many exit - nodes with ExcludeExitNodes, you can degrade functionality. For example, - if none of the exits you list allows traffic on port 80 or 443, you won't - be able to browse the web. + - + - Note also that not every circuit is used to deliver traffic *outside* of - the Tor network. It is normal to see non-exit circuits (such as those - used to connect to hidden services, those that do directory fetches, - those used for relay reachability self-tests, and so on) that end - at a non-exit node. To - keep a node from being used entirely, see <> and <>. + - + - The ExcludeNodes option overrides this option: any node listed in both - ExitNodes and ExcludeNodes is treated as excluded. + - + - The .exit address notation, if enabled via MapAddress, overrides - this option. - -[[GeoIPExcludeUnknown]] **GeoIPExcludeUnknown** **0**|**1**|**auto**:: - If this option is set to 'auto', then whenever any country code is set in - ExcludeNodes or ExcludeExitNodes, all nodes with unknown country (\{??} and - possibly \{A1}) are treated as excluded as well. If this option is set to - '1', then all unknown countries are treated as excluded in ExcludeNodes - and ExcludeExitNodes. This option has no effect when a GeoIP file isn't - configured or can't be found. (Default: auto) - -[[HSLayer2Nodes]] **HSLayer2Nodes** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, country codes, and - address patterns of nodes that are allowed to be used as the - second hop in all client or service-side Onion Service circuits. - This option mitigates attacks where the adversary runs middle nodes - and induces your client or service to create many circuits, in order - to discover your primary guard node. - (Default: Any node in the network may be used in the second hop.) - + - (Example: - HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + - + - When this is set, the resulting hidden service paths will - look like: - + - C - G - L2 - M - Rend + - C - G - L2 - M - HSDir + - C - G - L2 - M - Intro + - S - G - L2 - M - Rend + - S - G - L2 - M - HSDir + - S - G - L2 - M - Intro + - + - where C is this client, S is the service, G is the Guard node, - L2 is a node from this option, and M is a random middle node. - Rend, HSDir, and Intro point selection is not affected by this - option. - + - This option may be combined with HSLayer3Nodes to create - paths of the form: - + - C - G - L2 - L3 - Rend + - C - G - L2 - L3 - M - HSDir + - C - G - L2 - L3 - M - Intro + - S - G - L2 - L3 - M - Rend + - S - G - L2 - L3 - HSDir + - S - G - L2 - L3 - Intro + - + - ExcludeNodes have higher priority than HSLayer2Nodes, - which means that nodes specified in ExcludeNodes will not be - picked. - + - When either this option or HSLayer3Nodes are set, the /16 subnet - and node family restrictions are removed for hidden service - circuits. Additionally, we allow the guard node to be present - as the Rend, HSDir, and IP node, and as the hop before it. This - is done to prevent the adversary from inferring information - about our guard, layer2, and layer3 node choices at later points - in the path. - + - This option is meant to be managed by a Tor controller such as - https://github.com/mikeperry-tor/vanguards that selects and - updates this set of nodes for you. Hence it does not do load - balancing if fewer than 20 nodes are selected, and if no nodes in - HSLayer2Nodes are currently available for use, Tor will not work. - Please use extreme care if you are setting this option manually. - -[[HSLayer3Nodes]] **HSLayer3Nodes** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, country codes, and - address patterns of nodes that are allowed to be used as the - third hop in all client and service-side Onion Service circuits. - This option mitigates attacks where the adversary runs middle nodes - and induces your client or service to create many circuits, in order - to discover your primary or Layer2 guard nodes. - (Default: Any node in the network may be used in the third hop.) - + - (Example: - HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + - + - When this is set by itself, the resulting hidden service paths - will look like: + - C - G - M - L3 - Rend + - C - G - M - L3 - M - HSDir + - C - G - M - L3 - M - Intro + - S - G - M - L3 - M - Rend + - S - G - M - L3 - HSDir + - S - G - M - L3 - Intro + - where C is this client, S is the service, G is the Guard node, - L2 is a node from this option, and M is a random middle node. - Rend, HSDir, and Intro point selection is not affected by this - option. - + - While it is possible to use this option by itself, it should be - combined with HSLayer2Nodes to create paths of the form: - + - C - G - L2 - L3 - Rend + - C - G - L2 - L3 - M - HSDir + - C - G - L2 - L3 - M - Intro + - S - G - L2 - L3 - M - Rend + - S - G - L2 - L3 - HSDir + - S - G - L2 - L3 - Intro + - + - ExcludeNodes have higher priority than HSLayer3Nodes, - which means that nodes specified in ExcludeNodes will not be - picked. - + - When either this option or HSLayer2Nodes are set, the /16 subnet - and node family restrictions are removed for hidden service - circuits. Additionally, we allow the guard node to be present - as the Rend, HSDir, and IP node, and as the hop before it. This - is done to prevent the adversary from inferring information - about our guard, layer2, and layer3 node choices at later points - in the path. - + - This option is meant to be managed by a Tor controller such as - https://github.com/mikeperry-tor/vanguards that selects and - updates this set of nodes for you. Hence it does not do load - balancing if fewer than 20 nodes are selected, and if no nodes in - HSLayer3Nodes are currently available for use, Tor will not work. - Please use extreme care if you are setting this option manually. - -[[MiddleNodes]] **MiddleNodes** __node__,__node__,__...__:: - A list of identity fingerprints and country codes of nodes - to use for "middle" hops in your normal circuits. - Normal circuits include all circuits except for direct connections - to directory servers. Middle hops are all hops other than exit and entry. -+ - This is an **experimental** feature that is meant to be used by researchers - and developers to test new features in the Tor network safely. Using it - without care will strongly influence your anonymity. Other tor features may - not work with MiddleNodes. This feature might get removed in the future. -+ - The HSLayer2Node and HSLayer3Node options override this option for onion - service circuits, if they are set. The vanguards addon will read this - option, and if set, it will set HSLayer2Nodes and HSLayer3Nodes to nodes - from this set. -+ - The ExcludeNodes option overrides this option: any node listed in both - MiddleNodes and ExcludeNodes is treated as excluded. See - the <> for more information on how to specify nodes. - -[[NodeFamily]] **NodeFamily** __node__,__node__,__...__:: - The Tor servers, defined by their identity fingerprints, - constitute a "family" of similar or co-administered servers, so never use - any two of them in the same circuit. Defining a NodeFamily is only needed - when a server doesn't list the family itself (with MyFamily). This option - can be used multiple times; each instance defines a separate family. In - addition to nodes, you can also list IP address and ranges and country - codes in {curly braces}. See <> for more - information on how to specify nodes. - -[[StrictNodes]] **StrictNodes** **0**|**1**:: - If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes option - as a requirement to follow for all the circuits you generate, even if - doing so will break functionality for you (StrictNodes does not apply to - ExcludeExitNodes, ExitNodes, MiddleNodes, or MapAddress). If StrictNodes - is set to 0, Tor will still try to avoid nodes in the ExcludeNodes list, - but it will err on the side of avoiding unexpected errors. - Specifically, StrictNodes 0 tells Tor that it is okay to use an excluded - node when it is *necessary* to perform relay reachability self-tests, - connect to a hidden service, provide a hidden service to a client, - fulfill a .exit request, upload directory information, or download - directory information. (Default: 0) - -[[server-options]] -== SERVER OPTIONS - -// These options are in alphabetical order, with exceptions as noted. -// Please keep them that way! - -The following options are useful only for servers (that is, if ORPort -is non-zero): - -[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Limits the max number of bytes sent and received within a set time period - using a given calculation rule (see <> and <>). - Useful if you need to stay under a specific bandwidth. By default, the - number used for calculation is the max of either the bytes sent or - received. For example, with AccountingMax set to 1 TByte, a server - could send 900 GBytes and receive 800 GBytes and continue running. - It will only hibernate once one of the two reaches 1 TByte. This can - be changed to use the sum of the both bytes received and sent by setting - the AccountingRule option to "sum" (total bandwidth in/out). When the - number of bytes remaining gets low, Tor will stop accepting new connections - and circuits. When the number of bytes is exhausted, Tor will hibernate - until some time in the next accounting period. To prevent all servers - from waking at the same time, Tor will also wait until a random point - in each period before waking up. If you have bandwidth cost issues, - enabling hibernation is preferable to setting a low bandwidth, since - it provides users with a collection of fast servers that are up some - of the time, which is more useful than a set of slow servers that are - always "available". + - + - Note that (as also described in the Bandwidth section) Tor uses - powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not - one billion. Be careful: some internet service providers might count - GBytes differently. - -[[AccountingRule]] **AccountingRule** **sum**|**max**|**in**|**out**:: - How we determine when our AccountingMax has been reached (when we - should hibernate) during a time interval. Set to "max" to calculate - using the higher of either the sent or received bytes (this is the - default functionality). Set to "sum" to calculate using the sent - plus received bytes. Set to "in" to calculate using only the - received bytes. Set to "out" to calculate using only the sent bytes. - (Default: max) - -[[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__:: - Specify how long accounting periods last. If **month** is given, - each accounting period runs from the time __HH:MM__ on the __dayth__ day of one - month to the same day and time of the next. The relay will go at full speed, - use all the quota you specify, then hibernate for the rest of the period. (The - day must be between 1 and 28.) If **week** is given, each accounting period - runs from the time __HH:MM__ of the __dayth__ day of one week to the same day - and time of the next week, with Monday as day 1 and Sunday as day 7. If **day** - is given, each accounting period runs from the time __HH:MM__ each day to the - same time on the next day. All times are local, and given in 24-hour time. - (Default: "month 1 0:00") - -[[Address]] **Address** __address__:: - The IPv4 address of this server, or a fully qualified domain name of - this server that resolves to an IPv4 address. You can leave this - unset, and Tor will try to guess your IPv4 address. This IPv4 - address is the one used to tell clients and other servers where to - find your Tor server; it doesn't affect the address that your server - binds to. To bind to a different address, use the ORPort and - OutboundBindAddress options. - -[[AssumeReachable]] **AssumeReachable** **0**|**1**:: - This option is used when bootstrapping a new Tor network. If set to 1, - don't do self-reachability testing; just upload your server descriptor - immediately. (Default: 0) - -[[AssumeReachableIPv6]] **AssumeReachableIPv6** **0**|**1**|**auto**:: - Like **AssumeReachable**, but affects only the relay's own IPv6 ORPort. - If this value is set to "auto", then Tor will look at **AssumeReachable** - instead. (Default: auto) - -[[BridgeRelay]] **BridgeRelay** **0**|**1**:: - Sets the relay to act as a "bridge" with respect to relaying connections - from bridge users to the Tor network. It mainly causes Tor to publish a - server descriptor to the bridge database, rather than - to the public directory authorities. + - + - Note: make sure that no MyFamily lines are present in your torrc when - relay is configured in bridge mode. - -//Out of order because it logically belongs after BridgeRelay. -[[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**:: - When this option is enabled and BridgeRelay is also enabled, and we have - GeoIP data, Tor keeps a per-country count of how many client - addresses have contacted it so that it can help the bridge authority guess - which countries have blocked access to it. If ExtraInfoStatistics is - enabled, it will be published as part of the extra-info document. - (Default: 1) - -//Out of order because it logically belongs after BridgeRelay. -[[BridgeDistribution]] **BridgeDistribution** __string__:: - If set along with BridgeRelay, Tor will include a new line in its - bridge descriptor which indicates to the BridgeDB service how it - would like its bridge address to be given out. Set it to "none" if - you want BridgeDB to avoid distributing your bridge address, or "any" to - let BridgeDB decide. (Default: any) - -[[ContactInfo]] **ContactInfo** __email_address__:: - Administrative contact information for this relay or bridge. This line - can be used to contact you if your relay or bridge is misconfigured or - something else goes wrong. Note that we archive and publish all - descriptors containing these lines and that Google indexes them, so - spammers might also collect them. You may want to obscure the fact - that it's an email address and/or generate a new address for this - purpose. + - + - ContactInfo **must** be set to a working address if you run more than one - relay or bridge. (Really, everybody running a relay or bridge should set - it.) - -[[DisableOOSCheck]] **DisableOOSCheck** **0**|**1**:: - This option disables the code that closes connections when Tor notices - that it is running low on sockets. Right now, it is on by default, - since the existing out-of-sockets mechanism tends to kill OR connections - more than it should. (Default: 1) - -[[ExitPolicy]] **ExitPolicy** __policy__,__policy__,__...__:: - Set an exit policy for this server. Each policy is of the form - "**accept[6]**|**reject[6]** __ADDR__[/__MASK__][:__PORT__]". If /__MASK__ is - omitted then this policy just applies to the host given. Instead of giving - a host or network you can also use "\*" to denote the universe (0.0.0.0/0 - and ::/0), or \*4 to denote all IPv4 addresses, and \*6 to denote all IPv6 - addresses. - __PORT__ can be a single port number, an interval of ports - "__FROM_PORT__-__TO_PORT__", or "\*". If __PORT__ is omitted, that means - "\*". + - + - For example, "accept 18.7.22.69:\*,reject 18.0.0.0/8:\*,accept \*:\*" would - reject any IPv4 traffic destined for MIT except for web.mit.edu, and accept - any other IPv4 or IPv6 traffic. + - + - Tor also allows IPv6 exit policy entries. For instance, "reject6 [FC00::]/7:\*" - rejects all destinations that share 7 most significant bit prefix with - address FC00::. Respectively, "accept6 [C000::]/3:\*" accepts all destinations - that share 3 most significant bit prefix with address C000::. + - + - accept6 and reject6 only produce IPv6 exit policy entries. Using an IPv4 - address with accept6 or reject6 is ignored and generates a warning. - accept/reject allows either IPv4 or IPv6 addresses. Use \*4 as an IPv4 - wildcard address, and \*6 as an IPv6 wildcard address. accept/reject * - expands to matching IPv4 and IPv6 wildcard address rules. + - + - To specify all IPv4 and IPv6 internal and link-local networks (including - 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, - 172.16.0.0/12, [::]/8, [FC00::]/7, [FE80::]/10, [FEC0::]/10, [FF00::]/8, - and [::]/127), you can use the "private" alias instead of an address. - ("private" always produces rules for IPv4 and IPv6 addresses, even when - used with accept6/reject6.) + - + - Private addresses are rejected by default (at the beginning of your exit - policy), along with any configured primary public IPv4 and IPv6 addresses. - These private addresses are rejected unless you set the - ExitPolicyRejectPrivate config option to 0. For example, once you've done - that, you could allow HTTP to 127.0.0.1 and block all other connections to - internal networks with "accept 127.0.0.1:80,reject private:\*", though that - may also allow connections to your own computer that are addressed to its - public (external) IP address. See RFC 1918 and RFC 3330 for more details - about internal and reserved IP address space. See - <> if you want to block every address on the - relay, even those that aren't advertised in the descriptor. + - + - This directive can be specified multiple times so you don't have to put it - all on one line. + - + - Policies are considered first to last, and the first match wins. If you - want to allow the same ports on IPv4 and IPv6, write your rules using - accept/reject \*. If you want to allow different ports on IPv4 and IPv6, - write your IPv6 rules using accept6/reject6 \*6, and your IPv4 rules using - accept/reject \*4. If you want to \_replace_ the default exit policy, end - your exit policy with either a reject \*:* or an accept \*:*. Otherwise, - you're \_augmenting_ (prepending to) the default exit policy. + - + - If you want to use a reduced exit policy rather than the default exit - policy, set "ReducedExitPolicy 1". If you want to _replace_ the default - exit policy with your custom exit policy, end your exit policy with either - a reject *:* or an accept *:*. Otherwise, you're _augmenting_ (prepending - to) the default or reduced exit policy. + - + - The default exit policy is: - - reject *:25 - reject *:119 - reject *:135-139 - reject *:445 - reject *:563 - reject *:1214 - reject *:4661-4666 - reject *:6346-6429 - reject *:6699 - reject *:6881-6999 - accept *:* - -// Anchor only for formatting, not visible in the man page. -[[ExitPolicyDefault]]:: - Since the default exit policy uses accept/reject *, it applies to both - IPv4 and IPv6 addresses. - -[[ExitPolicyRejectLocalInterfaces]] **ExitPolicyRejectLocalInterfaces** **0**|**1**:: - Reject all IPv4 and IPv6 addresses that the relay knows about, at the - beginning of your exit policy. This includes any OutboundBindAddress, the - bind addresses of any port options, such as ControlPort or DNSPort, and any - public IPv4 and IPv6 addresses on any interface on the relay. (If IPv6Exit - is not set, all IPv6 addresses will be rejected anyway.) - See above entry on <>. - This option is off by default, because it lists all public relay IP - addresses in the ExitPolicy, even those relay operators might prefer not - to disclose. - (Default: 0) - -[[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**:: - Reject all private (local) networks, along with the relay's advertised - public IPv4 and IPv6 addresses, at the beginning of your exit policy. - See above entry on <>. - (Default: 1) - -[[ExitRelay]] **ExitRelay** **0**|**1**|**auto**:: - Tells Tor whether to run as an exit relay. If Tor is running as a - non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to - exit according to the ExitPolicy option, the ReducedExitPolicy option, - or the default ExitPolicy (if no other exit policy option is specified). + - + - If ExitRelay is set to 0, no traffic is allowed to exit, and the - ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored. + - + - If ExitRelay is set to "auto", then Tor checks the ExitPolicy, - ReducedExitPolicy, and IPv6Exit options. If at least one of these options - is set, Tor behaves as if ExitRelay were set to 1. If none of these exit - policy options are set, Tor behaves as if ExitRelay were set to 0. - (Default: auto) - -[[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**:: - When this option is enabled, Tor will connect to relays on localhost, - RFC1918 addresses, and so on. In particular, Tor will make direct OR - connections, and Tor routers allow EXTEND requests, to these private - addresses. (Tor will always allow connections to bridges, proxies, and - pluggable transports configured on private addresses.) Enabling this - option can create security issues; you should probably leave it off. - (Default: 0) - -[[GeoIPFile]] **GeoIPFile** __filename__:: - A filename containing IPv4 GeoIP data, for use with by-country statistics. - -[[GeoIPv6File]] **GeoIPv6File** __filename__:: - A filename containing IPv6 GeoIP data, for use with by-country statistics. - -[[HeartbeatPeriod]] **HeartbeatPeriod** __N__ **minutes**|**hours**|**days**|**weeks**:: - Log a heartbeat message every **HeartbeatPeriod** seconds. This is - a log level __notice__ message, designed to let you know your Tor - server is still alive and doing useful things. Settings this - to 0 will disable the heartbeat. Otherwise, it must be at least 30 - minutes. (Default: 6 hours) - -[[IPv6Exit]] **IPv6Exit** **0**|**1**:: - If set, and we are an exit node, allow clients to use us for IPv6 traffic. - When this option is set and ExitRelay is auto, we act as if ExitRelay - is 1. (Default: 0) - -[[KeyDirectory]] **KeyDirectory** __DIR__:: - Store secret keys in DIR. Can not be changed while tor is - running. - (Default: the "keys" subdirectory of DataDirectory.) - -[[KeyDirectoryGroupReadable]] **KeyDirectoryGroupReadable** **0**|**1**|**auto**:: - If this option is set to 0, don't allow the filesystem group to read the - KeyDirectory. If the option is set to 1, make the KeyDirectory readable - by the default GID. If the option is "auto", then we use the - setting for DataDirectoryGroupReadable when the KeyDirectory is the - same as the DataDirectory, and 0 otherwise. (Default: auto) - -[[MainloopStats]] **MainloopStats** **0**|**1**:: - Log main loop statistics every **HeartbeatPeriod** seconds. This is a log - level __notice__ message designed to help developers instrumenting Tor's - main event loop. (Default: 0) - -[[MaxMemInQueues]] **MaxMemInQueues** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: - This option configures a threshold above which Tor will assume that it - needs to stop queueing or buffering data because it's about to run out of - memory. If it hits this threshold, it will begin killing circuits until - it has recovered at least 10% of this memory. Do not set this option too - low, or your relay may be unreliable under load. This option only - affects some queues, so the actual process size will be larger than - this. If this option is set to 0, Tor will try to pick a reasonable - default based on your system's physical memory. (Default: 0) - -[[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]:: - If we have more onionskins queued for processing than we can process in - this amount of time, reject new ones. (Default: 1750 msec) - -[[MyFamily]] **MyFamily** __fingerprint__,__fingerprint__,...:: - Declare that this Tor relay is controlled or administered by a group or - organization identical or similar to that of the other relays, defined by - their (possibly $-prefixed) identity fingerprints. - This option can be repeated many times, for - convenience in defining large families: all fingerprints in all MyFamily - lines are merged into one list. - When two relays both declare that they are in the - same \'family', Tor clients will not use them in the same circuit. (Each - relay only needs to list the other servers in its family; it doesn't need to - list itself, but it won't hurt if it does.) Do not list any bridge relay as it would - compromise its concealment. + - + - If you run more than one relay, the MyFamily option on each relay - **must** list all other relays, as described above. + - + - Note: do not use MyFamily when configuring your Tor instance as a - bridge. - -[[Nickname]] **Nickname** __name__:: - Set the server's nickname to \'name'. Nicknames must be between 1 and 19 - characters inclusive, and must contain only the characters [a-zA-Z0-9]. - If not set, **Unnamed** will be used. Relays can always be uniquely identified - by their identity fingerprints. - -[[NumCPUs]] **NumCPUs** __num__:: - How many processes to use at once for decrypting onionskins and other - parallelizable operations. If this is set to 0, Tor will try to detect - how many CPUs you have, defaulting to 1 if it can't tell. (Default: 0) - -[[OfflineMasterKey]] **OfflineMasterKey** **0**|**1**:: - If non-zero, the Tor relay will never generate or load its master secret - key. Instead, you'll have to use "tor --keygen" to manage the permanent - ed25519 master identity key, as well as the corresponding temporary - signing keys and certificates. (Default: 0) - -[[ORPort]] **ORPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]:: - Advertise this port to listen for connections from Tor clients and - servers. This option is required to be a Tor server. - Set it to "auto" to have Tor pick a port for you. Set it to 0 to not - run an ORPort at all. This option can occur more than once. (Default: 0) + - + - Tor recognizes these flags on each ORPort: - **NoAdvertise**;; - By default, we bind to a port and tell our users about it. If - NoAdvertise is specified, we don't advertise, but listen anyway. This - can be useful if the port everybody will be connecting to (for - example, one that's opened on our firewall) is somewhere else. - **NoListen**;; - By default, we bind to a port and tell our users about it. If - NoListen is specified, we don't bind, but advertise anyway. This - can be useful if something else (for example, a firewall's port - forwarding configuration) is causing connections to reach us. - **IPv4Only**;; - If the address is absent, or resolves to both an IPv4 and an IPv6 - address, only listen to the IPv4 address. - **IPv6Only**;; - If the address is absent, or resolves to both an IPv4 and an IPv6 - address, only listen to the IPv6 address. - -// Anchor only for formatting, not visible in the man page. -[[ORPortFlagsExclusive]]:: - For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and - IPv4Only and IPv6Only are mutually exclusive. - -[[PublishServerDescriptor]] **PublishServerDescriptor** **0**|**1**|**v3**|**bridge**,**...**:: - This option specifies which descriptors Tor will publish when acting as - a relay. You can - choose multiple arguments, separated by commas. + - + - If this option is set to 0, Tor will not publish its - descriptors to any directories. (This is useful if you're testing - out your server, or if you're using a Tor controller that handles - directory publishing for you.) Otherwise, Tor will publish its - descriptors of all type(s) specified. The default is "1", which - means "if running as a relay or bridge, publish descriptors to the - appropriate authorities". Other possibilities are "v3", meaning - "publish as if you're a relay", and "bridge", meaning "publish as - if you're a bridge". - -[[ReducedExitPolicy]] **ReducedExitPolicy** **0**|**1**:: - If set, use a reduced exit policy rather than the default one. + - + - The reduced exit policy is an alternative to the default exit policy. It - allows as many Internet services as possible while still blocking the - majority of TCP ports. Currently, the policy allows approximately 65 ports. - This reduces the odds that your node will be used for peer-to-peer - applications. + - + - The reduced exit policy is: - - accept *:20-21 - accept *:22 - accept *:23 - accept *:43 - accept *:53 - accept *:79 - accept *:80-81 - accept *:88 - accept *:110 - accept *:143 - accept *:194 - accept *:220 - accept *:389 - accept *:443 - accept *:464 - accept *:465 - accept *:531 - accept *:543-544 - accept *:554 - accept *:563 - accept *:587 - accept *:636 - accept *:706 - accept *:749 - accept *:873 - accept *:902-904 - accept *:981 - accept *:989-990 - accept *:991 - accept *:992 - accept *:993 - accept *:994 - accept *:995 - accept *:1194 - accept *:1220 - accept *:1293 - accept *:1500 - accept *:1533 - accept *:1677 - accept *:1723 - accept *:1755 - accept *:1863 - accept *:2082 - accept *:2083 - accept *:2086-2087 - accept *:2095-2096 - accept *:2102-2104 - accept *:3128 - accept *:3389 - accept *:3690 - accept *:4321 - accept *:4643 - accept *:5050 - accept *:5190 - accept *:5222-5223 - accept *:5228 - accept *:5900 - accept *:6660-6669 - accept *:6679 - accept *:6697 - accept *:8000 - accept *:8008 - accept *:8074 - accept *:8080 - accept *:8082 - accept *:8087-8088 - accept *:8232-8233 - accept *:8332-8333 - accept *:8443 - accept *:8888 - accept *:9418 - accept *:9999 - accept *:10000 - accept *:11371 - accept *:19294 - accept *:19638 - accept *:50002 - accept *:64738 - reject *:* - - (Default: 0) - -[[RefuseUnknownExits]] **RefuseUnknownExits** **0**|**1**|**auto**:: - Prevent nodes that don't appear in the consensus from exiting using this - relay. If the option is 1, we always block exit attempts from such - nodes; if it's 0, we never do, and if the option is "auto", then we do - whatever the authorities suggest in the consensus (and block if the consensus - is quiet on the issue). (Default: auto) - -[[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**:: - If this option is false, Tor exits immediately if there are problems - parsing the system DNS configuration or connecting to nameservers. - Otherwise, Tor continues to periodically retry the system nameservers until - it eventually succeeds. (Default: 1) - -[[ServerDNSAllowNonRFC953Hostnames]] **ServerDNSAllowNonRFC953Hostnames** **0**|**1**:: - When this option is disabled, Tor does not try to resolve hostnames - containing illegal characters (like @ and :) rather than sending them to an - exit node to be resolved. This helps trap accidental attempts to resolve - URLs and so on. This option only affects name lookups that your server does - on behalf of clients. (Default: 0) - -[[ServerDNSDetectHijacking]] **ServerDNSDetectHijacking** **0**|**1**:: - When this option is set to 1, we will test periodically to determine - whether our local nameservers have been configured to hijack failing DNS - requests (usually to an advertising site). If they are, we will attempt to - correct this. This option only affects name lookups that your server does - on behalf of clients. (Default: 1) - -[[ServerDNSRandomizeCase]] **ServerDNSRandomizeCase** **0**|**1**:: - When this option is set, Tor sets the case of each character randomly in - outgoing DNS requests, and makes sure that the case matches in DNS replies. - This so-called "0x20 hack" helps resist some types of DNS poisoning attack. - For more information, see "Increased DNS Forgery Resistance through - 0x20-Bit Encoding". This option only affects name lookups that your server - does on behalf of clients. (Default: 1) - -[[ServerDNSResolvConfFile]] **ServerDNSResolvConfFile** __filename__:: - Overrides the default DNS configuration with the configuration in - __filename__. The file format is the same as the standard Unix - "**resolv.conf**" file (7). This option, like all other ServerDNS options, - only affects name lookups that your server does on behalf of clients. - (Defaults to use the system DNS configuration or a localhost DNS service - in case no nameservers are found in a given configuration.) - -[[ServerDNSSearchDomains]] **ServerDNSSearchDomains** **0**|**1**:: - If set to 1, then we will search for addresses in the local search domain. - For example, if this system is configured to believe it is in - "example.com", and a client tries to connect to "www", the client will be - connected to "www.example.com". This option only affects name lookups that - your server does on behalf of clients. (Default: 0) - -[[ServerDNSTestAddresses]] **ServerDNSTestAddresses** __hostname__,__hostname__,__...__:: - When we're detecting DNS hijacking, make sure that these __valid__ addresses - aren't getting redirected. If they are, then our DNS is completely useless, - and we'll reset our exit policy to "reject \*:*". This option only affects - name lookups that your server does on behalf of clients. (Default: - "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org") - -[[ShutdownWaitLength]] **ShutdownWaitLength** __NUM__:: - When we get a SIGINT and we're a server, we begin shutting down: - we close listeners and start refusing new circuits. After **NUM** - seconds, we exit. If we get a second SIGINT, we exit immediately. - (Default: 30 seconds) - -[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**:: - For how long should each Ed25519 signing key be valid? Tor uses a - permanent master identity key that can be kept offline, and periodically - generates new "signing" keys that it uses online. This option - configures their lifetime. - (Default: 30 days) - -[[SSLKeyLifetime]] **SSLKeyLifetime** __N__ **minutes**|**hours**|**days**|**weeks**:: - When creating a link certificate for our outermost SSL handshake, - set its lifetime to this amount of time. If set to 0, Tor will choose - some reasonable random defaults. (Default: 0) - -== STATISTICS OPTIONS - -// These options are in alphabetical order, with exceptions as noted. -// Please keep them that way! - -Relays publish most statistics in a document called the -extra-info document. The following options affect the different -types of statistics that Tor relays collect and publish: - -[[CellStatistics]] **CellStatistics** **0**|**1**:: - Relays only. - When this option is enabled, Tor collects statistics about cell - processing (i.e. mean time a cell is spending in a queue, mean - number of cells in a queue and mean number of processed cells per - circuit) and writes them into disk every 24 hours. Onion router - operators may use the statistics for performance monitoring. - If ExtraInfoStatistics is enabled, it will published as part of - the extra-info document. (Default: 0) - -[[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**:: - Relays only. - When this option is enabled, Tor writes statistics on the amounts of - traffic it passes between itself and other relays to disk every 24 - hours. Enables relay operators to monitor how much their relay is - being used as middle node in the circuit. If ExtraInfoStatistics is - enabled, it will be published as part of the extra-info document. - (Default: 0) - -[[DirReqStatistics]] **DirReqStatistics** **0**|**1**:: - Relays and bridges only. - When this option is enabled, a Tor directory writes statistics on the - number and response time of network status requests to disk every 24 - hours. Enables relay and bridge operators to monitor how much their - server is being used by clients to learn about Tor network. - If ExtraInfoStatistics is enabled, it will published as part of - the extra-info document. (Default: 1) - -[[EntryStatistics]] **EntryStatistics** **0**|**1**:: - Relays only. - When this option is enabled, Tor writes statistics on the number of - directly connecting clients to disk every 24 hours. Enables relay - operators to monitor how much inbound traffic that originates from - Tor clients passes through their server to go further down the - Tor network. If ExtraInfoStatistics is enabled, it will be published - as part of the extra-info document. (Default: 0) - -[[ExitPortStatistics]] **ExitPortStatistics** **0**|**1**:: - Exit relays only. - When this option is enabled, Tor writes statistics on the number of - relayed bytes and opened stream per exit port to disk every 24 hours. - Enables exit relay operators to measure and monitor amounts of traffic - that leaves Tor network through their exit node. If ExtraInfoStatistics - is enabled, it will be published as part of the extra-info document. - (Default: 0) - -[[ExtraInfoStatistics]] **ExtraInfoStatistics** **0**|**1**:: - When this option is enabled, Tor includes previously gathered statistics in - its extra-info documents that it uploads to the directory authorities. - Disabling this option also removes bandwidth usage statistics, and - GeoIPFile and GeoIPv6File hashes from the extra-info file. Bridge - ServerTransportPlugin lines are always included in the extra-info file, - because they are required by BridgeDB. - (Default: 1) - -[[HiddenServiceStatistics]] **HiddenServiceStatistics** **0**|**1**:: - Relays only. - When this option is enabled, a Tor relay writes obfuscated - statistics on its role as hidden-service directory, introduction - point, or rendezvous point to disk every 24 hours. If ExtraInfoStatistics - is enabled, it will be published as part of the extra-info document. - (Default: 1) - -[[PaddingStatistics]] **PaddingStatistics** **0**|**1**:: - Relays and bridges only. - When this option is enabled, Tor collects statistics for padding cells - sent and received by this relay, in addition to total cell counts. - These statistics are rounded, and omitted if traffic is low. This - information is important for load balancing decisions related to padding. - If ExtraInfoStatistics is enabled, it will be published - as a part of the extra-info document. (Default: 1) - -== DIRECTORY SERVER OPTIONS - -The following options are useful only for directory servers. (Relays with -enough bandwidth automatically become directory servers; see <> for -details.) - -[[DirCache]] **DirCache** **0**|**1**:: - When this option is set, Tor caches all current directory documents except - extra info documents, and accepts client requests for them. If - **DownloadExtraInfo** is set, cached extra info documents are also cached. - Setting **DirPort** is not required for **DirCache**, because clients - connect via the ORPort by default. Setting either DirPort or BridgeRelay - and setting DirCache to 0 is not supported. (Default: 1) - -[[DirPolicy]] **DirPolicy** __policy__,__policy__,__...__:: - Set an entrance policy for this server, to limit who can connect to the - directory ports. The policies have the same form as exit policies above, - except that port specifiers are ignored. Any address not matched by - some entry in the policy is accepted. - -[[DirPort]] **DirPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]:: - If this option is nonzero, advertise the directory service on this port. - Set it to "auto" to have Tor pick a port for you. This option can occur - more than once, but only one advertised DirPort is supported: all - but one DirPort must have the **NoAdvertise** flag set. (Default: 0) + - + - The same flags are supported here as are supported by ORPort. - -[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__:: - When this option is set, it takes an HTML file and publishes it as "/" on - the DirPort. Now relay operators can provide a disclaimer without needing - to set up a separate webserver. There's a sample disclaimer in - contrib/operator-tools/tor-exit-notice.html. - -[[MaxConsensusAgeForDiffs]] **MaxConsensusAgeForDiffs** __N__ **minutes**|**hours**|**days**|**weeks**:: - When this option is nonzero, Tor caches will not try to generate - consensus diffs for any consensus older than this amount of time. - If this option is set to zero, Tor will pick a reasonable default from - the current networkstatus document. You should not set this - option unless your cache is severely low on disk space or CPU. - If you need to set it, keeping it above 3 or 4 hours will help clients - much more than setting it to zero. - (Default: 0) - - -== DENIAL OF SERVICE MITIGATION OPTIONS - -Tor has three built-in mitigation options that can be individually -enabled/disabled and fine-tuned, but by default Tor directory authorities will -define reasonable values for relays and no explicit configuration is required -to make use of these protections. The mitigations take place at relays, -and are as follows: - - 1. If a single client address makes too many concurrent connections (this is - configurable via DoSConnectionMaxConcurrentCount), hang up on further - connections. - + - 2. If a single client IP address (v4 or v6) makes circuits too quickly - (default values are more than 3 per second, with an allowed burst of 90, - see <> and - <>) while also having - too many connections open (default is 3, see - <>), - tor will refuse any new circuit (CREATE - cells) for the next while (random value between 1 and 2 hours). - + - 3. If a client asks to establish a rendezvous point to you directly (ex: - Tor2Web client), ignore the request. - -These defenses can be manually controlled by torrc options, but relays will -also take guidance from consensus parameters using these same names, so there's -no need to configure anything manually. In doubt, do not change those values. - -The values set by the consensus, if any, can be found here: -https://consensus-health.torproject.org/#consensusparams - -If any of the DoS mitigations are enabled, a heartbeat message will appear in -your log at NOTICE level which looks like: - - DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses. - 2238 connections closed. 8052 single hop clients refused. - -The following options are useful only for a public relay. They control the -Denial of Service mitigation subsystem described above. - -//Out of order because it logically belongs before the other DoSCircuitCreation options. -[[DoSCircuitCreationEnabled]] **DoSCircuitCreationEnabled** **0**|**1**|**auto**:: - - Enable circuit creation DoS mitigation. If set to 1 (enabled), tor will - cache client IPs along with statistics in order to detect circuit DoS - attacks. If an address is positively identified, tor will activate - defenses against the address. See <> - option for more details. This is a client to relay detection only. "auto" means - use the consensus parameter. If not defined in the consensus, the value is 0. - (Default: auto) - -[[DoSCircuitCreationBurst]] **DoSCircuitCreationBurst** __NUM__:: - - The allowed circuit creation burst per client IP address. If the circuit - rate and the burst are reached, a client is marked as executing a circuit - creation DoS. "0" means use the consensus parameter. If not defined in the - consensus, the value is 90. - (Default: 0) - -[[DoSCircuitCreationDefenseTimePeriod]] **DoSCircuitCreationDefenseTimePeriod** __N__ **seconds**|**minutes**|**hours**:: - - The base time period in seconds that the DoS defense is activated for. The - actual value is selected randomly for each activation from N+1 to 3/2 * N. - "0" means use the consensus parameter. If not defined in the consensus, - the value is 3600 seconds (1 hour). - (Default: 0) - -[[DoSCircuitCreationDefenseType]] **DoSCircuitCreationDefenseType** __NUM__:: - - This is the type of defense applied to a detected client address. The - possible values are: - + - 1: No defense. - + - 2: Refuse circuit creation for the DoSCircuitCreationDefenseTimePeriod period of time. - + - "0" means use the consensus parameter. If not defined in the consensus, the value is 2. - (Default: 0) - -[[DoSCircuitCreationMinConnections]] **DoSCircuitCreationMinConnections** __NUM__:: - - Minimum threshold of concurrent connections before a client address can be - flagged as executing a circuit creation DoS. In other words, once a client - address reaches the circuit rate and has a minimum of NUM concurrent - connections, a detection is positive. "0" means use the consensus - parameter. If not defined in the consensus, the value is 3. - (Default: 0) - -[[DoSCircuitCreationRate]] **DoSCircuitCreationRate** __NUM__:: - - The allowed circuit creation rate per second applied per client IP - address. If this option is 0, it obeys a consensus parameter. If not - defined in the consensus, the value is 3. - (Default: 0) - -//out of order because it logically belongs before the other DoSConnection options. -[[DoSConnectionEnabled]] **DoSConnectionEnabled** **0**|**1**|**auto**:: - - Enable the connection DoS mitigation. If set to 1 (enabled), for client - address only, this allows tor to mitigate against large number of - concurrent connections made by a single IP address. "auto" means use the - consensus parameter. If not defined in the consensus, the value is 0. - (Default: auto) - -[[DoSConnectionDefenseType]] **DoSConnectionDefenseType** __NUM__:: - - This is the type of defense applied to a detected client address for the - connection mitigation. The possible values are: - + - 1: No defense. - + - 2: Immediately close new connections. - + - "0" means use the consensus parameter. If not defined in the consensus, the value is 2. - (Default: 0) - -[[DoSConnectionMaxConcurrentCount]] **DoSConnectionMaxConcurrentCount** __NUM__:: - - The maximum threshold of concurrent connection from a client IP address. - Above this limit, a defense selected by DoSConnectionDefenseType is - applied. "0" means use the consensus parameter. If not defined in the - consensus, the value is 100. - (Default: 0) - -[[DoSRefuseSingleHopClientRendezvous]] **DoSRefuseSingleHopClientRendezvous** **0**|**1**|**auto**:: - - Refuse establishment of rendezvous points for single hop clients. In other - words, if a client directly connects to the relay and sends an - ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto" means use the - consensus parameter. If not defined in the consensus, the value is 0. - (Default: auto) - - -== DIRECTORY AUTHORITY SERVER OPTIONS - -The following options enable operation as a directory authority, and -control how Tor behaves as a directory authority. You should not need -to adjust any of them if you're running a regular relay or exit server -on the public Tor network. - -// Out of order because it logically belongs first in this section -[[AuthoritativeDirectory]] **AuthoritativeDirectory** **0**|**1**:: - When this option is set to 1, Tor operates as an authoritative directory - server. Instead of caching the directory, it generates its own list of - good servers, signs it, and sends that to the clients. Unless the clients - already have you listed as a trusted directory, you probably do not want - to set this option. - -//Out of order because it belongs with the AuthoritativeDirectory option. -[[BridgeAuthoritativeDir]] **BridgeAuthoritativeDir** **0**|**1**:: - When this option is set in addition to **AuthoritativeDirectory**, Tor - accepts and serves server descriptors, but it caches and serves the main - networkstatus documents rather than generating its own. (Default: 0) - -//Out of order because it belongs with the AuthoritativeDirectory option. -[[V3AuthoritativeDirectory]] **V3AuthoritativeDirectory** **0**|**1**:: - When this option is set in addition to **AuthoritativeDirectory**, Tor - generates version 3 network statuses and serves descriptors, etc as - described in dir-spec.txt file of https://spec.torproject.org/[torspec] - (for Tor clients and servers running at least 0.2.0.x). - -[[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: - Authoritative directories only. A set of address patterns for servers that - will be listed as bad exits in any network status document this authority - publishes, if **AuthDirListBadExits** is set. + - + - (The address pattern syntax here and in the options below - is the same as for exit policies, except that you don't need to say - "accept" or "reject", and ports are not needed.) - -[[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Authoritative directories only. If non-zero, always vote the - Fast flag for any relay advertising this amount of capacity or - more. (Default: 100 KBytes) - -[[AuthDirGuardBWGuarantee]] **AuthDirGuardBWGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Authoritative directories only. If non-zero, this advertised capacity - or more is always sufficient to satisfy the bandwidth requirement - for the Guard flag. (Default: 2 MBytes) - -[[AuthDirHasIPv6Connectivity]] **AuthDirHasIPv6Connectivity** **0**|**1**:: - Authoritative directories only. When set to 0, OR ports with an - IPv6 address are not included in the authority's votes. When set to 1, - IPv6 OR ports are tested for reachability like IPv4 OR ports. If the - reachability test succeeds, the authority votes for the IPv6 ORPort, and - votes Running for the relay. If the reachability test fails, the authority - does not vote for the IPv6 ORPort, and does not vote Running (Default: 0) + -+ - The content of the consensus depends on the number of voting authorities - that set AuthDirHasIPv6Connectivity: - - If no authorities set AuthDirHasIPv6Connectivity 1, there will be no - IPv6 ORPorts in the consensus. - - If a minority of authorities set AuthDirHasIPv6Connectivity 1, - unreachable IPv6 ORPorts will be removed from the consensus. But the - majority of IPv4-only authorities will still vote the relay as Running. - Reachable IPv6 ORPort lines will be included in the consensus - - If a majority of voting authorities set AuthDirHasIPv6Connectivity 1, - relays with unreachable IPv6 ORPorts will not be listed as Running. - Reachable IPv6 ORPort lines will be included in the consensus - (To ensure that any valid majority will vote relays with unreachable - IPv6 ORPorts not Running, 75% of authorities must set - AuthDirHasIPv6Connectivity 1.) - -[[AuthDirInvalid]] **AuthDirInvalid** __AddressPattern...__:: - Authoritative directories only. A set of address patterns for servers that - will never be listed as "valid" in any network status document that this - authority publishes. - -[[AuthDirListBadExits]] **AuthDirListBadExits** **0**|**1**:: - Authoritative directories only. If set to 1, this directory has some - opinion about which nodes are unsuitable as exit nodes. (Do not set this to - 1 unless you plan to list non-functioning exits as bad; otherwise, you are - effectively voting in favor of every declared exit as an exit.) - -[[AuthDirMaxServersPerAddr]] **AuthDirMaxServersPerAddr** __NUM__:: - Authoritative directories only. The maximum number of servers that we will - list as acceptable on a single IP address. Set this to "0" for "no limit". - (Default: 2) - -[[AuthDirPinKeys]] **AuthDirPinKeys** **0**|**1**:: - Authoritative directories only. If non-zero, do not allow any relay to - publish a descriptor if any other relay has reserved its - identity keypair. In all cases, Tor records every keypair it accepts - in a journal if it is new, or if it differs from the most recently - accepted pinning for one of the keys it contains. (Default: 1) - -[[AuthDirReject]] **AuthDirReject** __AddressPattern__...:: - Authoritative directories only. A set of address patterns for servers that - will never be listed at all in any network status document that this - authority publishes, or accepted as an OR address in any descriptor - submitted for publication by this authority. - -//Out of order because it logically belongs with the other CCs options. -[[AuthDirBadExitCCs]] **AuthDirBadExitCCs** __CC__,... + - -//Out of order because it logically belongs with the other CCs options. -[[AuthDirInvalidCCs]] **AuthDirInvalidCCs** __CC__,... + - - -[[AuthDirRejectRequestsUnderLoad]] **AuthDirRejectRequestsUnderLoad** **0**|**1**:: - If set, the directory authority will start rejecting directory requests - from non relay connections by sending a 503 error code if it is under - bandwidth pressure (reaching the configured limit if any). Relays will - always tried to be answered even if this is on. (Default: 1) - -[[AuthDirRejectCCs]] **AuthDirRejectCCs** __CC__,...:: - Authoritative directories only. These options contain a comma-separated - list of country codes such that any server in one of those country codes - will be marked as a bad exit/invalid for use, or rejected - entirely. - -[[AuthDirSharedRandomness]] **AuthDirSharedRandomness** **0**|**1**:: - Authoritative directories only. Switch for the shared random protocol. - If zero, the authority won't participate in the protocol. If non-zero - (default), the flag "shared-rand-participate" is added to the authority - vote indicating participation in the protocol. (Default: 1) - -[[AuthDirTestEd25519LinkKeys]] **AuthDirTestEd25519LinkKeys** **0**|**1**:: - Authoritative directories only. If this option is set to 0, then we treat - relays as "Running" if their RSA key is correct when we probe them, - regardless of their Ed25519 key. We should only ever set this option to 0 - if there is some major bug in Ed25519 link authentication that causes us - to label all the relays as not Running. (Default: 1) - -[[AuthDirTestReachability]] **AuthDirTestReachability** **0**|**1**:: - Authoritative directories only. If set to 1, then we periodically - check every relay we know about to see whether it is running. - If set to 0, we vote Running for every relay, and don't perform - these tests. (Default: 1) - -[[BridgePassword]] **BridgePassword** __Password__:: - If set, contains an HTTP authenticator that tells a bridge authority to - serve all requested bridge information. Used by the (only partially - implemented) "bridge community" design, where a community of bridge - relay operators all use an alternate bridge directory authority, - and their target user audience can periodically fetch the list of - available community bridges to stay up-to-date. (Default: not set) - -[[ConsensusParams]] **ConsensusParams** __STRING__:: - STRING is a space-separated list of key=value pairs that Tor will include - in the "params" line of its networkstatus vote. - -[[DirAllowPrivateAddresses]] **DirAllowPrivateAddresses** **0**|**1**:: - If set to 1, Tor will accept server descriptors with arbitrary "Address" - elements. Otherwise, if the address is not an IP address or is a private IP - address, it will reject the server descriptor. Additionally, Tor - will allow exit policies for private networks to fulfill Exit flag - requirements. (Default: 0) - -[[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: - V3 authoritative directories only. Configures the location of the - guardfraction file which contains information about how long relays - have been guards. (Default: unset) - -[[MinMeasuredBWsForAuthToIgnoreAdvertised]] **MinMeasuredBWsForAuthToIgnoreAdvertised** __N__:: - A total value, in abstract bandwidth units, describing how much - measured total bandwidth an authority should have observed on the network - before it will treat advertised bandwidths as wholly - unreliable. (Default: 500) - -[[MinUptimeHidServDirectoryV2]] **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: - Minimum uptime of a relay to be accepted as a hidden service directory - by directory authorities. (Default: 96 hours) - -[[RecommendedClientVersions]] **RecommendedClientVersions** __STRING__:: - STRING is a comma-separated list of Tor versions currently believed to be - safe for clients to use. This information is included in version 2 - directories. If this is not set then the value of **RecommendedVersions** - is used. When this is set then **VersioningAuthoritativeDirectory** should - be set too. - -[[RecommendedServerVersions]] **RecommendedServerVersions** __STRING__:: - STRING is a comma-separated list of Tor versions currently believed to be - safe for servers to use. This information is included in version 2 - directories. If this is not set then the value of **RecommendedVersions** - is used. When this is set then **VersioningAuthoritativeDirectory** should - be set too. - -[[RecommendedVersions]] **RecommendedVersions** __STRING__:: - STRING is a comma-separated list of Tor versions currently believed to be - safe. The list is included in each directory, and nodes which pull down the - directory learn whether they need to upgrade. This option can appear - multiple times: the values from multiple lines are spliced together. When - this is set then **VersioningAuthoritativeDirectory** should be set too. - -[[V3AuthDistDelay]] **V3AuthDistDelay** __N__ **seconds**|**minutes**|**hours**:: - V3 authoritative directories only. Configures the server's preferred delay - between publishing its consensus and signature and assuming it has all the - signatures from all the other authorities. Note that the actual time used - is not the server's preferred time, but the consensus of all preferences. - (Default: 5 minutes) - -[[V3AuthNIntervalsValid]] **V3AuthNIntervalsValid** __NUM__:: - V3 authoritative directories only. Configures the number of VotingIntervals - for which each consensus should be valid for. Choosing high numbers - increases network partitioning risks; choosing low numbers increases - directory traffic. Note that the actual number of intervals used is not the - server's preferred number, but the consensus of all preferences. Must be at - least 2. (Default: 3) - -[[V3AuthUseLegacyKey]] **V3AuthUseLegacyKey** **0**|**1**:: - If set, the directory authority will sign consensuses not only with its - own signing key, but also with a "legacy" key and certificate with a - different identity. This feature is used to migrate directory authority - keys in the event of a compromise. (Default: 0) - -[[V3AuthVoteDelay]] **V3AuthVoteDelay** __N__ **seconds**|**minutes**|**hours**:: - V3 authoritative directories only. Configures the server's preferred delay - between publishing its vote and assuming it has all the votes from all the - other authorities. Note that the actual time used is not the server's - preferred time, but the consensus of all preferences. (Default: 5 - minutes) - -[[V3AuthVotingInterval]] **V3AuthVotingInterval** __N__ **minutes**|**hours**:: - V3 authoritative directories only. Configures the server's preferred voting - interval. Note that voting will __actually__ happen at an interval chosen - by consensus from all the authorities' preferred intervals. This time - SHOULD divide evenly into a day. (Default: 1 hour) - -[[V3BandwidthsFile]] **V3BandwidthsFile** __FILENAME__:: - V3 authoritative directories only. Configures the location of the - bandwidth-authority generated file storing information on relays' measured - bandwidth capacities. To avoid inconsistent reads, bandwidth data should - be written to temporary file, then renamed to the configured filename. - (Default: unset) - -[[VersioningAuthoritativeDirectory]] **VersioningAuthoritativeDirectory** **0**|**1**:: - When this option is set to 1, Tor adds information on which versions of - Tor are still believed safe for use to the published directory. Each - version 1 authority is automatically a versioning authority; version 2 - authorities provide this service optionally. See <>, - <>, and <>. - -== HIDDEN SERVICE OPTIONS - -The following options are used to configure a hidden service. Some options -apply per service and some apply for the whole tor instance. - -The next section describes the per service options that can only be set -**after** the **HiddenServiceDir** directive - -**PER SERVICE OPTIONS:** - -[[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**:: - If set to 1, then connections to unrecognized ports do not cause the - current hidden service to close rendezvous circuits. (Setting this to 0 is - not an authorization mechanism; it is instead meant to be a mild - inconvenience to port-scanners.) (Default: 0) - -[[HiddenServiceAuthorizeClient]] **HiddenServiceAuthorizeClient** __auth-type__ __client-name__,__client-name__,__...__:: - If configured, the v2 hidden service is accessible for authorized clients - only. The auth-type can either be \'basic' for a general-purpose - authorization protocol or \'stealth' for a less scalable protocol that also - hides service activity from unauthorized clients. Only clients that are - listed here are authorized to access the hidden service. Valid client names - are 1 to 16 characters long and only use characters in A-Za-z0-9+-_ (no - spaces). If this option is set, the hidden service is not accessible for - clients without authorization any more. Generated authorization data can be - found in the hostname file. Clients need to put this authorization data in - their configuration file using **HidServAuth**. This option is only for v2 - services; v3 services configure client authentication in a subdirectory of - HiddenServiceDir instead (see <>). - -[[HiddenServiceDir]] **HiddenServiceDir** __DIRECTORY__:: - Store data files for a hidden service in DIRECTORY. Every hidden service - must have a separate directory. You may use this option multiple times to - specify multiple services. If DIRECTORY does not exist, Tor will create it. - Please note that you cannot add new Onion Service to already running Tor - instance if **Sandbox** is enabled. - (Note: in current versions of Tor, if DIRECTORY is a relative path, - it will be relative to the current - working directory of Tor instance, not to its DataDirectory. Do not - rely on this behavior; it is not guaranteed to remain the same in future - versions.) - -[[HiddenServiceDirGroupReadable]] **HiddenServiceDirGroupReadable** **0**|**1**:: - If this option is set to 1, allow the filesystem group to read the - hidden service directory and hostname file. If the option is set to 0, - only owner is able to read the hidden service directory. (Default: 0) - Has no effect on Windows. - -[[HiddenServiceEnableIntroDoSDefense]] **HiddenServiceEnableIntroDoSDefense** **0**|**1**:: - Enable DoS defense at the intropoint level. When this is enabled, the - rate and burst parameter (see below) will be sent to the intro point which - will then use them to apply rate limiting for introduction request to this - service. - + - The introduction point honors the consensus parameters except if this is - specifically set by the service operator using this option. The service - never looks at the consensus parameters in order to enable or disable this - defense. (Default: 0) - -//Out of order because it logically belongs after HiddenServiceEnableIntroDoSDefense. -[[HiddenServiceEnableIntroDoSBurstPerSec]] **HiddenServiceEnableIntroDoSBurstPerSec** __NUM__:: - The allowed client introduction burst per second at the introduction - point. If this option is 0, it is considered infinite and thus if - **HiddenServiceEnableIntroDoSDefense** is set, it then effectively - disables the defenses. (Default: 200) - -[[HiddenServiceEnableIntroDoSRatePerSec]] **HiddenServiceEnableIntroDoSRatePerSec** __NUM__:: - The allowed client introduction rate per second at the introduction - point. If this option is 0, it is considered infinite and thus if - **HiddenServiceEnableIntroDoSDefense** is set, it then effectively - disables the defenses. (Default: 25) - -[[HiddenServiceExportCircuitID]] **HiddenServiceExportCircuitID** __protocol__:: - The onion service will use the given protocol to expose the global circuit - identifier of each inbound client circuit. The only - protocol supported right now \'haproxy'. This option is only for v3 - services. (Default: none) + - + - The haproxy option works in the following way: when the feature is - enabled, the Tor process will write a header line when a client is connecting - to the onion service. The header will look like this: + - + - "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n" + - + - We encode the "global circuit identifier" as the last 32-bits of the first - IPv6 address. All other values in the header can safely be ignored. You can - compute the global circuit identifier using the following formula given the - IPv6 address "fc00:dead:beef:4dad::AABB:CCDD": + - + - global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) + 0xDD; + - + - In the case above, where the last 32-bits are 0xffffffff, the global circuit - identifier would be 4294967295. You can use this value together with Tor's - control port to terminate particular circuits using their global - circuit identifiers. For more information about this see control-spec.txt. + - + - The HAProxy version 1 protocol is described in detail at - https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt - -[[HiddenServiceOnionBalanceInstance]] **HiddenServiceOnionBalanceInstance** **0**|**1**:: - - If set to 1, this onion service becomes an OnionBalance instance and will - accept client connections destined to an OnionBalance frontend. In this - case, Tor expects to find a file named "ob_config" inside the - **HiddenServiceDir** directory with content: - + - MasterOnionAddress - + - where is the onion address of the OnionBalance - frontend (e.g. wrxdvcaqpuzakbfww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion). - - -[[HiddenServiceMaxStreams]] **HiddenServiceMaxStreams** __N__:: - The maximum number of simultaneous streams (connections) per rendezvous - circuit. The maximum value allowed is 65535. (Setting this to 0 will allow - an unlimited number of simultaneous streams.) (Default: 0) - -[[HiddenServiceMaxStreamsCloseCircuit]] **HiddenServiceMaxStreamsCloseCircuit** **0**|**1**:: - If set to 1, then exceeding **HiddenServiceMaxStreams** will cause the - offending rendezvous circuit to be torn down, as opposed to stream creation - requests that exceed the limit being silently ignored. (Default: 0) - -[[HiddenServiceNumIntroductionPoints]] **HiddenServiceNumIntroductionPoints** __NUM__:: - Number of introduction points the hidden service will have. You can't - have more than 10 for v2 service and 20 for v3. (Default: 3) - -[[HiddenServicePort]] **HiddenServicePort** __VIRTPORT__ [__TARGET__]:: - Configure a virtual port VIRTPORT for a hidden service. You may use this - option multiple times; each time applies to the service using the most - recent HiddenServiceDir. By default, this option maps the virtual port to - the same port on 127.0.0.1 over TCP. You may override the target port, - address, or both by specifying a target of addr, port, addr:port, or - **unix:**__path__. (You can specify an IPv6 target as [addr]:port. Unix - paths may be quoted, and may use standard C escapes.) - You may also have multiple lines with the same VIRTPORT: when a user - connects to that VIRTPORT, one of the TARGETs from those lines will be - chosen at random. Note that address-port pairs have to be comma-separated. - -[[HiddenServiceVersion]] **HiddenServiceVersion** **2**|**3**:: - A list of rendezvous service descriptor versions to publish for the hidden - service. Currently, versions 2 and 3 are supported. (Default: 3) - -[[RendPostPeriod]] **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: - Every time the specified period elapses, Tor uploads any rendezvous - service descriptors to the directory servers. This information is also - uploaded whenever it changes. Minimum value allowed is 10 minutes and - maximum is 3.5 days. This option is only for v2 services. - (Default: 1 hour) - - - -**PER INSTANCE OPTIONS:** - -[[HiddenServiceSingleHopMode]] **HiddenServiceSingleHopMode** **0**|**1**:: - **Experimental - Non Anonymous** Hidden Services on a tor instance in - HiddenServiceSingleHopMode make one-hop (direct) circuits between the onion - service server, and the introduction and rendezvous points. (Onion service - descriptors are still posted using 3-hop paths, to avoid onion service - directories blocking the service.) - This option makes every hidden service instance hosted by a tor instance a - Single Onion Service. One-hop circuits make Single Onion servers easily - locatable, but clients remain location-anonymous. However, the fact that a - client is accessing a Single Onion rather than a Hidden Service may be - statistically distinguishable. + - + - **WARNING:** Once a hidden service directory has been used by a tor - instance in HiddenServiceSingleHopMode, it can **NEVER** be used again for - a hidden service. It is best practice to create a new hidden service - directory, key, and address for each new Single Onion Service and Hidden - Service. It is not possible to run Single Onion Services and Hidden - Services from the same tor instance: they should be run on different - servers with different IP addresses. + - + - HiddenServiceSingleHopMode requires HiddenServiceNonAnonymousMode to be set - to 1. Since a Single Onion service is non-anonymous, you can not configure - a SOCKSPort on a tor instance that is running in - **HiddenServiceSingleHopMode**. Can not be changed while tor is running. - (Default: 0) - -//Out of order because it belongs after HiddenServiceSingleHopMode. -[[HiddenServiceNonAnonymousMode]] **HiddenServiceNonAnonymousMode** **0**|**1**:: - Makes hidden services non-anonymous on this tor instance. Allows the - non-anonymous HiddenServiceSingleHopMode. Enables direct connections in the - server-side hidden service protocol. If you are using this option, - you need to disable all client-side services on your Tor instance, - including setting SOCKSPort to "0". Can not be changed while tor is - running. (Default: 0) - -[[PublishHidServDescriptors]] **PublishHidServDescriptors** **0**|**1**:: - If set to 0, Tor will run any hidden services you configure, but it won't - advertise them to the rendezvous directory. This option is only useful if - you're using a Tor controller that handles hidserv publishing for you. - (Default: 1) - -[[client-authorization]] -== CLIENT AUTHORIZATION - -(Version 3 only) - -Service side: - - To configure client authorization on the service side, the - "/authorized_clients/" directory needs to exist. Each file - in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the - file name is irrelevant) and its content format MUST be: - - :: - - The supported are: "descriptor". The supported are: - "x25519". The is the base32 representation of - the raw key bytes only (32 bytes for x25519). - - Each file MUST contain one line only. Any malformed file will be - ignored. Client authorization will only be enabled for the service if tor - successfully loads at least one authorization file. - - Note that once you've configured client authorization, anyone else with the - address won't be able to access it from this point on. If no authorization is - configured, the service will be accessible to anyone with the onion address. - - Revoking a client can be done by removing their ".auth" file, however the - revocation will be in effect only after the tor process gets restarted even if - a SIGHUP takes place. - -Client side: - - To access a v3 onion service with client authorization as a client, make sure - you have ClientOnionAuthDir set in your torrc. Then, in the - directory, create an .auth_private file for the onion - service corresponding to this key (i.e. 'bob_onion.auth_private'). The - contents of the /.auth_private file should look like: - - <56-char-onion-addr-without-.onion-part>:descriptor:x25519: - -For more information, please see https://2019.www.torproject.org/docs/tor-onion-service.html.en#ClientAuthorization . - -== TESTING NETWORK OPTIONS - -The following options are used for running a testing Tor network. - -//Out of order because it logically belongs first in this section. -[[TestingTorNetwork]] **TestingTorNetwork** **0**|**1**:: - If set to 1, Tor adjusts default values of the configuration options below, - so that it is easier to set up a testing Tor network. May only be set if - non-default set of DirAuthorities is set. Cannot be unset while Tor is - running. - (Default: 0) + - - DirAllowPrivateAddresses 1 - EnforceDistinctSubnets 0 - AuthDirMaxServersPerAddr 0 - ClientBootstrapConsensusAuthorityDownloadInitialDelay 0 - ClientBootstrapConsensusFallbackDownloadInitialDelay 0 - ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay 0 - ClientDNSRejectInternalAddresses 0 - ClientRejectInternalAddresses 0 - CountPrivateBandwidth 1 - ExitPolicyRejectPrivate 0 - ExtendAllowPrivateAddresses 1 - V3AuthVotingInterval 5 minutes - V3AuthVoteDelay 20 seconds - V3AuthDistDelay 20 seconds - TestingV3AuthInitialVotingInterval 150 seconds - TestingV3AuthInitialVoteDelay 20 seconds - TestingV3AuthInitialDistDelay 20 seconds - TestingAuthDirTimeToLearnReachability 0 minutes - MinUptimeHidServDirectoryV2 0 minutes - TestingServerDownloadInitialDelay 0 - TestingClientDownloadInitialDelay 0 - TestingServerConsensusDownloadInitialDelay 0 - TestingClientConsensusDownloadInitialDelay 0 - TestingBridgeDownloadInitialDelay 10 - TestingBridgeBootstrapDownloadInitialDelay 0 - TestingClientMaxIntervalWithoutRequest 5 seconds - TestingDirConnectionMaxStall 30 seconds - TestingEnableConnBwEvent 1 - TestingEnableCellStatsEvent 1 - RendPostPeriod 2 minutes - -[[TestingAuthDirTimeToLearnReachability]] **TestingAuthDirTimeToLearnReachability** __N__ **seconds**|**minutes**|**hours**:: - After starting as an authority, do not make claims about whether routers - are Running until this much time has passed. Changing this requires - that **TestingTorNetwork** is set. (Default: 30 minutes) - -[[TestingAuthKeyLifetime]] **TestingAuthKeyLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: - Overrides the default lifetime for a signing Ed25519 TLS Link authentication - key. - (Default: 2 days) - -[[TestingAuthKeySlop]] **TestingAuthKeySlop** __N__ **seconds**|**minutes**|**hours** + - -[[TestingBridgeBootstrapDownloadInitialDelay]] **TestingBridgeBootstrapDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download each bridge descriptor when they - have just started, or when they can not contact any of their bridges. - Changing this requires that **TestingTorNetwork** is set. (Default: 0) - -[[TestingBridgeDownloadInitialDelay]] **TestingBridgeDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download each bridge descriptor when they - know that one or more of their configured bridges are running. Changing - this requires that **TestingTorNetwork** is set. (Default: 10800) - -[[TestingClientConsensusDownloadInitialDelay]] **TestingClientConsensusDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download consensuses. Changing this - requires that **TestingTorNetwork** is set. (Default: 0) - -[[TestingClientDownloadInitialDelay]] **TestingClientDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download things in general. Changing this - requires that **TestingTorNetwork** is set. (Default: 0) - -[[TestingClientMaxIntervalWithoutRequest]] **TestingClientMaxIntervalWithoutRequest** __N__ **seconds**|**minutes**:: - When directory clients have only a few descriptors to request, they batch - them until they have more, or until this amount of time has passed. - Changing this requires that **TestingTorNetwork** is set. (Default: 10 - minutes) - -[[TestingDirAuthVoteExit]] **TestingDirAuthVoteExit** __node__,__node__,__...__:: - A list of identity fingerprints, country codes, and - address patterns of nodes to vote Exit for regardless of their - uptime, bandwidth, or exit policy. See <> - for more information on how to specify nodes. + - + - In order for this option to have any effect, **TestingTorNetwork** - has to be set. See <> for more - information on how to specify nodes. - -[[TestingDirAuthVoteExitIsStrict]] **TestingDirAuthVoteExitIsStrict** **0**|**1** :: - If True (1), a node will never receive the Exit flag unless it is specified - in the **TestingDirAuthVoteExit** list, regardless of its uptime, bandwidth, - or exit policy. + - + - In order for this option to have any effect, **TestingTorNetwork** - has to be set. - -[[TestingDirAuthVoteGuard]] **TestingDirAuthVoteGuard** __node__,__node__,__...__:: - A list of identity fingerprints and country codes and - address patterns of nodes to vote Guard for regardless of their - uptime and bandwidth. See <> for more - information on how to specify nodes. + - + - In order for this option to have any effect, **TestingTorNetwork** - has to be set. - -[[TestingDirAuthVoteGuardIsStrict]] **TestingDirAuthVoteGuardIsStrict** **0**|**1** :: - If True (1), a node will never receive the Guard flag unless it is specified - in the **TestingDirAuthVoteGuard** list, regardless of its uptime and bandwidth. + - + - In order for this option to have any effect, **TestingTorNetwork** - has to be set. - -[[TestingDirAuthVoteHSDir]] **TestingDirAuthVoteHSDir** __node__,__node__,__...__:: - A list of identity fingerprints and country codes and - address patterns of nodes to vote HSDir for regardless of their - uptime and DirPort. See <> for more - information on how to specify nodes. + - + - In order for this option to have any effect, **TestingTorNetwork** - must be set. - -[[TestingDirAuthVoteHSDirIsStrict]] **TestingDirAuthVoteHSDirIsStrict** **0**|**1** :: - If True (1), a node will never receive the HSDir flag unless it is specified - in the **TestingDirAuthVoteHSDir** list, regardless of its uptime and DirPort. + - + - In order for this option to have any effect, **TestingTorNetwork** - has to be set. - -[[TestingDirConnectionMaxStall]] **TestingDirConnectionMaxStall** __N__ **seconds**|**minutes**:: - Let a directory connection stall this long before expiring it. - Changing this requires that **TestingTorNetwork** is set. (Default: - 5 minutes) - -[[TestingEnableCellStatsEvent]] **TestingEnableCellStatsEvent** **0**|**1**:: - If this option is set, then Tor controllers may register for CELL_STATS - events. Changing this requires that **TestingTorNetwork** is set. - (Default: 0) - -[[TestingEnableConnBwEvent]] **TestingEnableConnBwEvent** **0**|**1**:: - If this option is set, then Tor controllers may register for CONN_BW - events. Changing this requires that **TestingTorNetwork** is set. - (Default: 0) - -[[TestingLinkCertLifetime]] **TestingLinkCertLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: - Overrides the default lifetime for the certificates used to authenticate - our X509 link cert with our ed25519 signing key. - (Default: 2 days) - -[[TestingLinkKeySlop]] **TestingLinkKeySlop** __N__ **seconds**|**minutes**|**hours** + - -[[TestingMinExitFlagThreshold]] **TestingMinExitFlagThreshold** __N__ **KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Sets a lower-bound for assigning an exit flag when running as an - authority on a testing network. Overrides the usual default lower bound - of 4 KBytes. (Default: 0) - -[[TestingMinFastFlagThreshold]] **TestingMinFastFlagThreshold** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Minimum value for the Fast flag. Overrides the ordinary minimum taken - from the consensus when TestingTorNetwork is set. (Default: 0.) - -[[TestingServerConsensusDownloadInitialDelay]] **TestingServerConsensusDownloadInitialDelay** __N__:: - Initial delay in seconds for when servers should download consensuses. Changing this - requires that **TestingTorNetwork** is set. (Default: 0) - -[[TestingServerDownloadInitialDelay]] **TestingServerDownloadInitialDelay** __N__:: - Initial delay in seconds for when servers should download things in general. Changing this - requires that **TestingTorNetwork** is set. (Default: 0) - -[[TestingSigningKeySlop]] **TestingSigningKeySlop** __N__ **seconds**|**minutes**|**hours**:: - How early before the official expiration of a an Ed25519 signing key do - we replace it and issue a new key? - (Default: 3 hours for link and auth; 1 day for signing.) - -[[TestingV3AuthInitialDistDelay]] **TestingV3AuthInitialDistDelay** __N__ **seconds**|**minutes**|**hours**:: - Like V3AuthDistDelay, but for initial voting interval before - the first consensus has been created. Changing this requires that - **TestingTorNetwork** is set. (Default: 5 minutes) - -[[TestingV3AuthInitialVoteDelay]] **TestingV3AuthInitialVoteDelay** __N__ **seconds**|**minutes**|**hours**:: - Like V3AuthVoteDelay, but for initial voting interval before - the first consensus has been created. Changing this requires that - **TestingTorNetwork** is set. (Default: 5 minutes) - -[[TestingV3AuthInitialVotingInterval]] **TestingV3AuthInitialVotingInterval** __N__ **seconds**|**minutes**|**hours**:: - Like V3AuthVotingInterval, but for initial voting interval before the first - consensus has been created. Changing this requires that - **TestingTorNetwork** is set. (Default: 30 minutes) - -[[TestingV3AuthVotingStartOffset]] **TestingV3AuthVotingStartOffset** __N__ **seconds**|**minutes**|**hours**:: - Directory authorities offset voting start time by this much. - Changing this requires that **TestingTorNetwork** is set. (Default: 0) - - -== NON-PERSISTENT OPTIONS - -These options are not saved to the torrc file by the "SAVECONF" controller -command. Other options of this type are documented in control-spec.txt, -section 5.4. End-users should mostly ignore them. - -[[UnderscorePorts]] **{dbl_}ControlPort**, **{dbl_}DirPort**, **{dbl_}DNSPort**, **{dbl_}ExtORPort**, **{dbl_}NATDPort**, **{dbl_}ORPort**, **{dbl_}SocksPort**, **{dbl_}TransPort**:: - These underscore-prefixed options are variants of the regular Port - options. They behave the same, except they are not saved to the - torrc file by the controller's SAVECONF command. - - -== SIGNALS - -Tor catches the following signals: - -[[SIGTERM]] **SIGTERM**:: - Tor will catch this, clean up and sync to disk if necessary, and exit. - -[[SIGINT]] **SIGINT**:: - Tor clients behave as with SIGTERM; but Tor servers will do a controlled - slow shutdown, closing listeners and waiting 30 seconds before exiting. - (The delay can be configured with the ShutdownWaitLength config option.) - -[[SIGHUP]] **SIGHUP**:: - The signal instructs Tor to reload its configuration (including closing and - reopening logs), and kill and restart its helper processes if applicable. - -[[SIGUSR1]] **SIGUSR1**:: - Log statistics about current connections, past connections, and throughput. - -[[SIGUSR2]] **SIGUSR2**:: - Switch all logs to loglevel debug. You can go back to the old loglevels by - sending a SIGHUP. - -[[SIGCHLD]] **SIGCHLD**:: - Tor receives this signal when one of its helper processes has exited, so it - can clean up. - -[[SIGPIPE]] **SIGPIPE**:: - Tor catches this signal and ignores it. - -[[SIGXFSZ]] **SIGXFSZ**:: - If this signal exists on your platform, Tor catches and ignores it. - -== FILES - -**`@CONFDIR@/torrc`**:: - Default location of the configuration file. - -**`$HOME/.torrc`**:: - Fallback location for torrc, if @CONFDIR@/torrc is not found. - -**`@LOCALSTATEDIR@/lib/tor/`**:: - The tor process stores keys and other data here. - -__CacheDirectory__/**`cached-certs`**:: - Contains downloaded directory key certificates that are used to verify - authenticity of documents generated by the Tor directory authorities. - -__CacheDirectory__/**`cached-consensus`** and/or **`cached-microdesc-consensus`**:: - The most recent consensus network status document we've downloaded. - -__CacheDirectory__/**`cached-descriptors`** and **`cached-descriptors.new`**:: - These files contain the downloaded router statuses. Some routers may appear - more than once; if so, the most recently published descriptor is - used. Lines beginning with **`@`**-signs are annotations that contain more - information about a given router. The **`.new`** file is an append-only - journal; when it gets too large, all entries are merged into a new - cached-descriptors file. - -__CacheDirectory__/**`cached-extrainfo`** and **`cached-extrainfo.new`**:: - Similar to **cached-descriptors**, but holds optionally-downloaded - "extra-info" documents. Relays use these documents to send inessential - information about statistics, bandwidth history, and network health to the - authorities. They aren't fetched by default. See <> - for more information. - -__CacheDirectory__/**`cached-microdescs`** and **`cached-microdescs.new`**:: - These files hold downloaded microdescriptors. Lines beginning with - **`@`**-signs are annotations that contain more information about a given - router. The **`.new`** file is an append-only journal; when it gets too - large, all entries are merged into a new cached-microdescs file. - -__DataDirectory__/**`state`**:: - Contains a set of persistent key-value mappings. These include: - - the current entry guards and their status. - - the current bandwidth accounting values. - - when the file was last written - - what version of Tor generated the state file - - a short history of bandwidth usage, as produced in the server - descriptors. - -__DataDirectory__/**`sr-state`**:: - _Authority only_. This file is used to record information about the current - status of the shared-random-value voting state. - -__CacheDirectory__/**`diff-cache`**:: - _Directory cache only_. Holds older consensuses and diffs from oldest to - the most recent consensus of each type compressed in various ways. Each - file contains a set of key-value arguments describing its contents, - followed by a single NUL byte, followed by the main file contents. - -__DataDirectory__/**`bw_accounting`**:: - This file is obsolete and the data is now stored in the **`state`** file - instead. Used to track bandwidth accounting values (when the current period - starts and ends; how much has been read and written so far this period). - -__DataDirectory__/**`control_auth_cookie`**:: - This file can be used only when cookie authentication is enabled. Used for - cookie authentication with the controller. Location can be overridden by - the `CookieAuthFile` configuration option. Regenerated on startup. See - control-spec.txt in https://spec.torproject.org/[torspec] for details. - -__DataDirectory__/**`lock`**:: - This file is used to prevent two Tor instances from using the same data - directory. If access to this file is locked, data directory is already in - use by Tor. - -__DataDirectory__/**`key-pinning-journal`**:: - Used by authorities. A line-based file that records mappings between - RSA1024 and Ed25519 identity keys. Authorities enforce these mappings, so - that once a relay has picked an Ed25519 key, stealing or factoring the - RSA1024 key will no longer let an attacker impersonate the relay. - -__KeyDirectory__/**`authority_identity_key`**:: - A v3 directory authority's master identity key, used to authenticate its - signing key. Tor doesn't use this while it's running. The tor-gencert - program uses this. If you're running an authority, you should keep this key - offline, and not put it in this file. - -__KeyDirectory__/**`authority_certificate`**:: - Only directory authorities use this file. A v3 directory authority's - certificate which authenticates the authority's current vote- and - consensus-signing key using its master identity key. - -__KeyDirectory__/**`authority_signing_key`**:: - Only directory authorities use this file. A v3 directory authority's - signing key that is used to sign votes and consensuses. Corresponds to the - **authority_certificate** cert. - -__KeyDirectory__/**`legacy_certificate`**:: - As authority_certificate; used only when `V3AuthUseLegacyKey` is set. See - documentation for <>. - -__KeyDirectory__/**`legacy_signing_key`**:: - As authority_signing_key: used only when `V3AuthUseLegacyKey` is set. See - documentation for <>. - -__KeyDirectory__/**`secret_id_key`**:: - A relay's RSA1024 permanent identity key, including private and public - components. Used to sign router descriptors, and to sign other keys. - -__KeyDirectory__/**`ed25519_master_id_public_key`**:: - The public part of a relay's Ed25519 permanent identity key. - -__KeyDirectory__/**`ed25519_master_id_secret_key`**:: - The private part of a relay's Ed25519 permanent identity key. This key is - used to sign the medium-term ed25519 signing key. This file can be kept - offline or encrypted. If so, Tor will not be able to generate new signing - keys automatically; you'll need to use `tor --keygen` to do so. - -__KeyDirectory__/**`ed25519_signing_secret_key`**:: - The private and public components of a relay's medium-term Ed25519 signing - key. This key is authenticated by the Ed25519 master key, which in turn - authenticates other keys (and router descriptors). - -__KeyDirectory__/**`ed25519_signing_cert`**:: - The certificate which authenticates "ed25519_signing_secret_key" as having - been signed by the Ed25519 master key. - -__KeyDirectory__/**`secret_onion_key`** and **`secret_onion_key.old`**:: - A relay's RSA1024 short-term onion key. Used to decrypt old-style ("TAP") - circuit extension requests. The **`.old`** file holds the previously - generated key, which the relay uses to handle any requests that were made - by clients that didn't have the new one. - -__KeyDirectory__/**`secret_onion_key_ntor`** and **`secret_onion_key_ntor.old`**:: - A relay's Curve25519 short-term onion key. Used to handle modern ("ntor") - circuit extension requests. The **`.old`** file holds the previously - generated key, which the relay uses to handle any requests that were made - by clients that didn't have the new one. - -__DataDirectory__/**`fingerprint`**:: - Only used by servers. Contains the fingerprint of the server's identity key. - -__DataDirectory__/**`hashed-fingerprint`**:: - Only used by bridges. Contains the hashed fingerprint of the bridge's - identity key. (That is, the hash of the hash of the identity key.) - -__DataDirectory__/**`approved-routers`**:: - Only used by authoritative directory servers. Each line lists a status and - an identity, separated by whitespace. Identities can be hex-encoded RSA - fingerprints, or base-64 encoded ed25519 public keys. See the - **fingerprint** file in a tor relay's __DataDirectory__ for an example - fingerprint line. If the status is **!reject**, then descriptors from the - given identity are rejected by this server. If it is **!invalid** then - descriptors are accepted, but marked in the directory as not valid, that - is, not recommended. In either case, the corresponding relays are not - included in the consensus. - -__DataDirectory__/**`v3-status-votes`**:: - Only for v3 authoritative directory servers. This file contains status - votes from all the authoritative directory servers. - -__CacheDirectory__/**`unverified-consensus`**:: - Contains a network consensus document that has been downloaded, but which - we didn't have the right certificates to check yet. - -__CacheDirectory__/**`unverified-microdesc-consensus`**:: - Contains a microdescriptor-flavored network consensus document that has - been downloaded, but which we didn't have the right certificates to check - yet. - -__DataDirectory__/**`unparseable-desc`**:: - Onion server descriptors that Tor was unable to parse are dumped to this - file. Only used for debugging. - -__DataDirectory__/**`router-stability`**:: - Only used by authoritative directory servers. Tracks measurements for - router mean-time-between-failures so that authorities have a fair idea of - how to set their Stable flags. - -__DataDirectory__/**`stats/dirreq-stats`**:: - Only used by directory caches and authorities. This file is used to - collect directory request statistics. - -__DataDirectory__/**`stats/entry-stats`**:: - Only used by servers. This file is used to collect incoming connection - statistics by Tor entry nodes. - -__DataDirectory__/**`stats/bridge-stats`**:: - Only used by servers. This file is used to collect incoming connection - statistics by Tor bridges. - -__DataDirectory__/**`stats/exit-stats`**:: - Only used by servers. This file is used to collect outgoing connection - statistics by Tor exit routers. - -__DataDirectory__/**`stats/buffer-stats`**:: - Only used by servers. This file is used to collect buffer usage - history. - -__DataDirectory__/**`stats/conn-stats`**:: - Only used by servers. This file is used to collect approximate connection - history (number of active connections over time). - -__DataDirectory__/**`stats/hidserv-stats`**:: - Only used by servers. This file is used to collect approximate counts - of what fraction of the traffic is hidden service rendezvous traffic, and - approximately how many hidden services the relay has seen. - -__DataDirectory__/**networkstatus-bridges`**:: - Only used by authoritative bridge directories. Contains information - about bridges that have self-reported themselves to the bridge - authority. - -__HiddenServiceDirectory__/**`hostname`**:: - The .onion domain name for this hidden service. - If the hidden service is restricted to authorized clients only, this file - also contains authorization data for all clients. -+ -[NOTE] - The clients will ignore any extra subdomains prepended to a hidden - service hostname. Supposing you have "xyz.onion" as your hostname, you - can ask your clients to connect to "www.xyz.onion" or "irc.xyz.onion" - for virtual-hosting purposes. - -__HiddenServiceDirectory__/**`private_key`**:: - Contains the private key for this hidden service. - -__HiddenServiceDirectory__/**`client_keys`**:: - Contains authorization data for a hidden service that is only accessible by - authorized clients. - -__HiddenServiceDirectory__/**`onion_service_non_anonymous`**:: - This file is present if a hidden service key was created in - **HiddenServiceNonAnonymousMode**. - -== SEE ALSO - -For more information, refer to the Tor Project website at -https://www.torproject.org/ and the Tor specifications at -https://spec.torproject.org. See also **torsocks**(1) and **torify**(1). - -== BUGS - -Because Tor is still under development, there may be plenty of bugs. Please -report them at https://trac.torproject.org/. - -== AUTHORS - -Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at alum.mit.edu]. diff --git a/doc/torify.1.txt b/doc/torify.1.txt deleted file mode 100644 index 716625f92d..0000000000 --- a/doc/torify.1.txt +++ /dev/null @@ -1,40 +0,0 @@ -// Copyright (c) The Tor Project, Inc. -// See LICENSE for licensing information -// This is an asciidoc file used to generate the manpage/html reference. -// Learn asciidoc on https://www.methods.co.nz/asciidoc/userguide.html -:man source: Tor -:man manual: Tor Manual -torify(1) -========= - -NAME ----- -torify - wrapper for torsocks and tor - -SYNOPSIS --------- -**torify** __application__ [__application's__ __arguments__] - -DESCRIPTION ------------ -**torify** is a simple wrapper that calls torsocks with a tor-specific -configuration file. - -It is provided for backward compatibility; instead you should use torsocks. - -WARNING -------- -When used with torsocks, torify should not leak DNS requests or UDP data. - -torify can leak ICMP data. - -torify will not ensure that different requests are processed on -different circuits. - -SEE ALSO --------- -**tor**(1), **torsocks**(1) - -AUTHORS -------- -Peter Palfrader and Jacob Appelbaum wrote this manual. -- cgit v1.2.3-54-g00ecf