The --newpass option should be used 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).

When generating a master key, you will probably want to use --DataDirectory to control where the keys and certificates will be stored, and --SigningKeyLifetime to control their lifetimes. Their behavior is as documented in the server options section below. (You must have write access to the specified DataDirectory.)

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.

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"

Note that this option, and other bandwidth-limiting options, apply to TCP data only: They do not count TCP headers or DNS traffic.

With this option, and in other options that take arguments in bytes, KBytes, and so on, other formats are also supported. Notably, "KBytes" can also be written as "kilobytes" or "kb"; "MBytes" can be written as "megabytes" or "MB"; "kbits" can be written as "kilobits"; and so forth. Tor also accepts "byte" and "bit" in the singular. The prefixes "tera" and "T" are also recognized. If no units are given, we default to bytes. To avoid confusion, we recommend writing "bytes" or "bits" explicitly, since it’s easy to forget that "B" means bytes, not bits.

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.

(Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd cache=/var/lib/tor/cache)

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)

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)

Recognized flags are...

GroupWritable

WorldWritable

RelaxDirModeCheck

Tor will contact the authority at ipv4address to download directory documents. The provided port value is a dirport; clients ignore this in favor of the specified "orport=" value. If an IPv6 ORPort is supplied, Tor will also download directory documents at the IPv6 ORPort.

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.

When the Sandbox is 1, the following options can not be changed when tor is running: Address ConnLimit CookieAuthFile DirPortFrontPage ExtORPortCookieAuthFile Logs ServerDNSResolvConfFile Tor must remain in client or server mode (some changes to ClientOnly and ORPort are not allowed). ClientOnionAuthDir and any files in it won’t reload on HUP signal. (Default: 0)

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, and dos. 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.

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)

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 KISTSchedRunInterval) 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.

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.

By default, this option is treated as a preference that Tor is allowed to override in order to keep working. For example, if you try to connect to a hidden service, but you have excluded all of the hidden service’s introduction points, Tor will connect to one of them anyway. If you do not want this behavior, set the StrictNodes option (documented below).

Note also that if you are a relay, this (and the other node selection options below) only affects your own circuits that Tor builds for you. Clients can still build circuits through you to any node. Controllers can tell Tor to build circuits through any node.

Country codes are case-insensitive. The code "{??}" refers to nodes whose country can’t be identified. No country code, including {??}, works if no GeoIPFile can be loaded. See also the GeoIPExcludeUnknown option below.

Note that if you list too few nodes here, or if you exclude too many exit nodes with ExcludeExitNodes, you can degrade functionality. For example, if none of the exits you list allows traffic on port 80 or 443, you won’t be able to browse the web.

Note also that not every circuit is used to deliver traffic outside of the Tor network. It is normal to see non-exit circuits (such as those used to connect to hidden services, those that do directory fetches, those used for relay reachability self-tests, and so on) that end at a non-exit node. To keep a node from being used entirely, see ExcludeNodes and StrictNodes.

The ExcludeNodes option overrides this option: any node listed in both ExitNodes and ExcludeNodes is treated as excluded.

The .exit address notation, if enabled via MapAddress, overrides this option.

The ExcludeNodes option overrides this option: any node listed in both EntryNodes and ExcludeNodes is treated as excluded. See the ExcludeNodes option for more information on how to specify nodes.

The separation between ReachableORAddresses and ReachableDirAddresses is only interesting when you are connecting through proxies (see HTTPProxy and HTTPSProxy). Most proxies limit TLS connections (which Tor uses to connect to Onion Routers) to port 443, and some limit HTTP GET requests (which Tor uses for fetching directory information) to port 80.

<onion-address>:descriptor:x25519:<base32-encoded-privkey>

The <onion-address> MUST NOT have the ".onion" suffix. The <base32-encoded-privkey> 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 torspec for more information.

NOTES:

MapAddress www.torproject.org 2.2.2.2
MapAddress www.torproject.org 1.1.1.1

MapAddress 1.1.1.1 2.2.2.2
MapAddress www.torproject.org 1.1.1.1

MapAddress www.torproject.org *.torproject.org.torserver.exit

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.

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

IsolateSOCKSAuth

IsolateClientProtocol

IsolateDestPort

IsolateDestAddr

KeepAliveIsolateSOCKSAuth

SessionGroup=INT

NoIPv4Traffic

IPv6Traffic

PreferIPv6

NoDNSRequest

NoOnionTraffic

OnionTrafficOnly

CacheIPv4DNS

CacheIPv6DNS

GroupWritable

WorldWritable

CacheDNS

UseIPv4Cache

UseIPv6Cache

UseDNSCache

PreferIPv6Automap

PreferSOCKSNoAuth

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

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)

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")

This option is only for people who cannot use TransPort. (Default: 0)

(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.

(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.

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.

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.

Note: make sure that no MyFamily lines are present in your torrc when relay is configured in bridge mode.

Note: as of Oct 2017, the BridgeDB part of this option is not yet implemented. Until BridgeDB is updated to obey this option, your bridge will make this request, but it will not (yet) be obeyed.

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.)

If ExitRelay is set to 0, no traffic is allowed to exit, and the ExitPolicy and ReducedExitPolicy options are ignored.

If ExitRelay is set to "auto", then Tor checks the ExitPolicy and ReducedExitPolicy options. If either is set, Tor behaves as if ExitRelay were set to 1. If neither exit policy option is set, Tor behaves as if ExitRelay were set to 0. (Default: auto)

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 ExitPolicyRejectLocalInterfaces 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 *:*

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)

When listing a node, it’s better to list it by fingerprint than by nickname: fingerprints are more reliable.

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 brigde.

Tor recognizes these flags on each ORPort:

NoAdvertise

NoListen

IPv4Only

IPv6Only

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".

The same flags are supported here as are supported by ORPort.

DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses.
2238 connections closed. 8052 single hop clients refused.

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)

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)

(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.)

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-bit is 0xffffffff, the global circuit identifier would be 4294967295. You can use this value together with Tor’s control port where it is possible to terminate a circuit given the global circuit identifier. For more information about this see controls-spec.txt.

The HAProxy version 1 proxy protocol is described in detail at https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt

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)

<auth-type>:<key-type>:<base32-encoded-public-key>

In order for this option to have any effect, TestingTorNetwork has to be set. See the ExcludeNodes option for more information on how to specify nodes.

In order for this option to have any effect, TestingTorNetwork has to be set.

In order for this option to have any effect, TestingTorNetwork has to be set.

In order for this option to have any effect, TestingTorNetwork has to be set.

In order for this option to have any effect, TestingTorNetwork must be set.

In order for this option to have any effect, TestingTorNetwork has to be set.

Note that clients will ignore any extra subdomains prepended to a hidden service hostname. So if you have "xyz.onion" as your hostname, you can tell clients to connect to "www.xyz.onion" or "irc.xyz.onion" for virtual-hosting purposes.