SYNOPSIS

tor [OPTION value]…

DESCRIPTION

Tor is a connection-oriented anonymizing communication service. Users choose a source-routed path through a set of nodes, and negotiate a "virtual circuit" through the network, in which each node knows its predecessor and successor, but no others. Traffic flowing down the circuit is unwrapped by a symmetric key at each node, which reveals the downstream node.

Basically, Tor provides a distributed network of servers or relays ("onion routers"). Users bounce their TCP streams — web traffic, ftp, ssh, etc. — around the network, and recipients, observers, and even the relays themselves have difficulty tracking the source of the stream.

By default, tor will act as a client only. To help the network by providing bandwidth as a relay, change the ORPort configuration option — see below. Please also consult the documentation on the Tor Project’s website.

COMMAND-LINE OPTIONS

-h, -help

Display a short help message and exit.

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

--allow-missing-torrc

Do not require that configuration file specified by -f exist if default torrc can be accessed.

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

--ignore-missing-torrc

Specifies that Tor should treat a missing torrc file as though it were empty. Ordinarily, Tor does this for missing default torrc files, but not for those specified on the command line.

--hash-password PASSWORD

Generates a hashed password for control port access.

--list-fingerprint

Generate your keys and output your nickname and fingerprint.

--verify-config

Verify the configuration file is valid.

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

--service remove|start|stop

Remove, start, or stop a configured Tor Windows service.

--nt-service

Used internally to implement a Windows service.

--list-torrc-options

List all valid 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.)

--version

Display Tor version and exit.

--quiet|--hush

Override the default console log. By default, Tor starts out logging messages at level "notice" and higher to the console. It stops doing so after it parses its configuration, if the configuration tells it to log anywhere else. You can override this behavior with the --hush option, which tells Tor to only send warnings and errors to the console, or with the --quiet option, which tells Tor not to log to the console at all.

--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: Tor will ask you for one. If you don’t want to encrypt the master key, just don’t enter any passphrase when asked.

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.

--passphrase-fd FILEDES

Filedescriptor 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. Default: read from the terminal.

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

Other options can be specified on the command-line in the format "--option value", in the format "option value", or in a configuration file. For instance, you can tell Tor to start listening for SOCKS connections on port 9999 by passing --SocksPort 9999 or SocksPort 9999 to it on the command line, or by putting "SocksPort 9999" in the configuration file. You will need to quote options with spaces in them: if you want Tor to log all debugging messages to debug.log, you will probably need to say --Log debug file debug.log.

Options on the command line override those in configuration files. See the next section for more information.

THE CONFIGURATION FILE FORMAT

All configuration options in a configuration are written on a single line by default. They take the form of an option name and a value, or an option name and a quoted value (option value or option "value"). Anything after a # character is treated as a comment. Options are case-insensitive. C-style escaped characters are allowed inside quoted values. To split one configuration entry into multiple lines, use a single backslash character (\) before the end of the line. Comments can be used in such multiline entries, but they must start at the beginning of a line.

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.

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

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.

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

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

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.

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)

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)

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)

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)

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.

ServerTransportPlugin transport exec path-to-binary [options]

The Tor relay launches the pluggable transport proxy in path-to-binary using options as its command-line options, and expects to receive proxied client traffic from it.

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

ServerTransportOptions transport k=v k=v

When this option is set, Tor will pass the k=v parameters to any pluggable transport proxy that tries to launch transport.
(Example: ServerTransportOptions obfs45 shared-secret=bridgepasswd cache=/var/lib/tor/cache)

ExtORPort [address:]port|auto

Open this port to listen for Extended ORPort connections from your pluggable transports.

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 0|1

If this option is set to 0, don’t allow the filesystem group to read the Extended OR Port cookie file. If the option is set to 1, make the cookie file readable by the default GID. [Making the file readable by other groups is not yet implemented; let us know if you need this for some reason.] (Default: 0)

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

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)

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

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 0|1

If this option is set to 0, don’t allow the filesystem group to read and write unix sockets (e.g. ControlSocket). If the option is set to 1, make the control socket readable and writable by the default GID. (Default: 0)

HashedControlPassword hashed_password

Allow connections on the control port if they present the password whose one-way hash is hashed_password. You can compute the hash of a password by running "tor --hash-password password". You can provide several acceptable passwords by using more than one HashedControlPassword line.

CookieAuthentication 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 Path

If set, this option overrides the default location and file name for Tor’s cookie file. (See CookieAuthentication above.)

CookieAuthFileGroupReadable 0|1

If this option is set to 0, don’t allow the filesystem group to read the cookie file. If the option is set to 1, make the cookie file readable by the default GID. [Making the file readable by other groups is not yet implemented; let us know if you need this for some reason.] (Default: 0)

ControlPortWriteToFile Path

If set, Tor writes the address and port of any control port it opens to this address. Usable by controllers to learn the actual control port when ControlPort is set to "auto".

ControlPortFileGroupReadable 0|1

If this option is set to 0, don’t allow the filesystem group to read the control port file. If the option is set to 1, make the control port file readable by the default GID. (Default: 0)

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

CacheDirectory DIR

Store cached directory data in DIR. Can not be changed while tor is running. (Default: uses the value of DataDirectory.)

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)

FallbackDir ipv4address:port orport=port id=fingerprint [weight=num] [ipv6=[ipv6address]:orport]

When we’re unable to connect to any directory cache for directory info (usually because we don’t know about any yet) we try a directory authority. Clients also simultaneously try a FallbackDir, to avoid hangs on client startup if a directory authority is down. Clients retry FallbackDirs more often than directory authorities, to reduce the load on the directory authorities. By default, the directory authorities are also FallbackDirs. Specifying a FallbackDir replaces Tor’s default hard-coded FallbackDirs (if any). (See the DirAuthority entry for an explanation of each flag.)

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)

DirAuthority [nickname] [flags] ipv4address:port fingerprint

Use a nonstandard authoritative directory server at the provided address and port, with the specified key fingerprint. This option can be repeated many times, for multiple authoritative directory servers. Flags are separated by spaces, and determine what kind of an authority this directory is. By default, an authority is not authoritative for any directory style or version unless an appropriate flag is given. Tor will use this authority as a bridge authoritative directory if the "bridge" flag is set. If a flag "orport=port" is given, Tor will use the given port when opening encrypted tunnels to the dirserver. If a flag "weight=num" is given, then the directory server is chosen randomly with probability proportional to that weight (default 1.0). 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