tor.1.txt 195 KB
Newer Older
1
2
3
4
// Copyright (c) The Tor Project, Inc.
// See LICENSE for licensing information
// This is an asciidoc file used to generate the manpage/html reference.
// Learn asciidoc on http://www.methods.co.nz/asciidoc/userguide.html
5
6
:man source:   Tor
:man manual:   Tor Manual
Taylor Yu's avatar
Taylor Yu committed
7
8
// compat-mode tells Asciidoctor tools to process this as legacy AsciiDoc
:compat-mode:
Taylor Yu's avatar
Taylor Yu committed
9
10
// attribute to make it easier to write names containing double underscores
:dbl_: __
Taylor Yu's avatar
Taylor Yu committed
11
12
13
= TOR(1)

== NAME
14
15
16
17

tor - The second-generation onion router


Taylor Yu's avatar
Taylor Yu committed
18
19
== SYNOPSIS

20
21
**tor** [__OPTION__ __value__]...

Taylor Yu's avatar
Taylor Yu committed
22
== DESCRIPTION
Taylor Yu's avatar
Taylor Yu committed
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

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

Taylor Yu's avatar
Taylor Yu committed
43
== COMMAND-LINE OPTIONS
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

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 **<<conf-format,THE CONFIGURATION FILE
FORMAT>>** for more information.

The following options in this section are only recognized on the
**`tor`** command line, not in a configuration file.

Taylor Yu's avatar
Taylor Yu committed
67
[[opt-h]] **`-h`**, **`--help`**::
68
69
    Display a short help message and exit.

Taylor Yu's avatar
Taylor Yu committed
70
[[opt-f]] **`-f`** __FILE__::
71
    Specify a new configuration file to contain further Tor configuration
72
    options, or pass *-* to make Tor read its configuration from standard
Taylor Yu's avatar
Taylor Yu committed
73
74
    input. (Default: **`@CONFDIR@/torrc`**, or **`$HOME/.torrc`** if
    that file is not found)
75

Taylor Yu's avatar
Taylor Yu committed
76
77
78
[[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.
79

Taylor Yu's avatar
Taylor Yu committed
80
[[opt-defaults-torrc]] **`--defaults-torrc`** __FILE__::
81
82
83
    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:
Taylor Yu's avatar
Taylor Yu committed
84
    **`@CONFDIR@/torrc-defaults`**.)
85

Taylor Yu's avatar
Taylor Yu committed
86
[[opt-ignore-missing-torrc]] **`--ignore-missing-torrc`**::
87
    Specify that Tor should treat a missing torrc file as though it
88
89
90
    were empty. Ordinarily, Tor does this for missing default torrc files,
    but not for those specified on the command line.

Taylor Yu's avatar
Taylor Yu committed
91
[[opt-hash-password]] **`--hash-password`** __PASSWORD__::
92
    Generate a hashed password for control port access.
93

Taylor Yu's avatar
Taylor Yu committed
94
[[opt-list-fingerprint]] **`--list-fingerprint`**::
95
96
    Generate your keys and output your nickname and fingerprint.

Taylor Yu's avatar
Taylor Yu committed
97
[[opt-verify-config]] **`--verify-config`**::
98
    Verify whether the configuration file is valid.
99

Nick Mathewson's avatar
Nick Mathewson committed
100
101
102
103
104
105
106
[[opt-dump-config]] **`--dump-config`** **`short`**|**`full`**|**`non-builtin`**::
    Write a complete 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 `non-builtin` is selected,
    write options that are not zero or the empty string.
    When `full` is selected, write every option.

Taylor Yu's avatar
Taylor Yu committed
107
[[opt-serviceinstall]] **`--service install`** [**`--options`** __command-line options__]::
108
109
    Install an instance of Tor as a Windows service, with the provided
    command-line options. Current instructions can be found at
Roger Dingledine's avatar
Roger Dingledine committed
110
    https://www.torproject.org/docs/faq#NTService
111

Taylor Yu's avatar
Taylor Yu committed
112
[[opt-service]] **`--service`** **`remove`**|**`start`**|**`stop`**::
113
114
    Remove, start, or stop a configured Tor Windows service.

Taylor Yu's avatar
Taylor Yu committed
115
[[opt-nt-service]] **`--nt-service`**::
116
    Used internally to implement a Windows service.
117

Taylor Yu's avatar
Taylor Yu committed
118
[[opt-list-torrc-options]] **`--list-torrc-options`**::
119
120
    List all valid options.

Taylor Yu's avatar
Taylor Yu committed
121
[[opt-list-deprecated-options]] **`--list-deprecated-options`**::
122
123
124
    List all valid options that are scheduled to become obsolete in a
    future version. (This is a warning, not a promise.)

Taylor Yu's avatar
Taylor Yu committed
125
[[opt-list-modules]] **`--list-modules`**::
126
127
    List whether each optional module has been compiled into Tor.
    (Any module not listed is not optional in this version of Tor.)
128

Taylor Yu's avatar
Taylor Yu committed
129
[[opt-version]] **`--version`**::
130
131
132
    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.)
133

Taylor Yu's avatar
Taylor Yu committed
134
[[opt-quiet]] **`--quiet`**|**`--hush`**::
135
136
137
138
    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
Taylor Yu's avatar
Taylor Yu committed
139
140
141
142
    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.
143

Taylor Yu's avatar
Taylor Yu committed
144
145
[[opt-keygen]] **`--keygen`** [**`--newpass`**]::
    Running **`tor --keygen`** creates a new ed25519 master identity key
146
147
148
149
150
    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. +
Taylor Yu's avatar
Taylor Yu committed
151
     +
Taylor Yu's avatar
Taylor Yu committed
152
153
154
155
    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).
156
157
+
[NOTE]
Taylor Yu's avatar
Taylor Yu committed
158
159
160
161
162
163
    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 the server options section to learn more about the
    behavior of these options.  You must have write access to the
    specified DataDirectory.
164
+
Taylor Yu's avatar
Taylor Yu committed
165
166
167
168
169
[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.
170

Taylor Yu's avatar
Taylor Yu committed
171
**`--passphrase-fd`** __FILEDES__::
172
    File descriptor to read the passphrase from.  Note that unlike with the
173
174
    tor-gencert program, the entire file contents are read and used as
    the passphrase, including any trailing newlines.
175
176
    If the file descriptor is not specified, the passphrase is read
    from the terminal by default.
177

Taylor Yu's avatar
Taylor Yu committed
178
179
180
[[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
181
    "sign". +
Taylor Yu's avatar
Taylor Yu committed
182
     +
Taylor Yu's avatar
Taylor Yu committed
183
184
185
186
187
    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"
188

189
[[conf-format]]
Taylor Yu's avatar
Taylor Yu committed
190
== THE CONFIGURATION FILE FORMAT
191
192
193
194
195
196
197
198
199
200

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.

201
202
203
204
205
206
207
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.

208
209
210
211
212
213
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
214
specify four SocksPorts in your configuration file, and one more SocksPort on
215
the command line, the option on the command line will replace __all__ of the
216
SocksPorts in the configuration file.  If this isn't what you want, prefix
217
the option name with a plus sign (+), and it will be appended to the previous
218
219
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
220
this is the default).
221
222
223

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
224
command line that you want no SocksPorts at all.  To do that, prefix the
225
226
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.
227

Taylor Yu's avatar
Taylor Yu committed
228
229
== GENERAL OPTIONS

230
231
232
// These options are in alphabetical order, with exceptions as noted.
// Please keep them that way!

233
234
235
236
237
238
239
240
241
[[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
Taylor Yu's avatar
Taylor Yu committed
242
    while tor is running. +
Taylor Yu's avatar
Taylor Yu committed
243
     +
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
    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)
270

271
[[BandwidthRate]] **BandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**::
272
273
    A token bucket limits the average incoming bandwidth usage on this node
    to the specified number of bytes per second, and the average outgoing
274
    bandwidth usage to that same value.  If you want to run a relay in the
275
276
277
278
    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) +
Taylor Yu's avatar
Taylor Yu committed
279
     +
280
281
    Note that this option, and other bandwidth-limiting options, apply to TCP
    data only: They do not count TCP headers or DNS traffic. +
Taylor Yu's avatar
Taylor Yu committed
282
     +
283
284
    Tor uses powers of two, not powers of ten, so 1 GByte is
    1024*1024*1024 bytes as opposed to 1 billion bytes. +
Taylor Yu's avatar
Taylor Yu committed
285
     +
286
287
288
289
    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.
290
    Case doesn't matter.
291
292
293
294
295
    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.
296

297
298
299
300
[[CacheDirectory]] **CacheDirectory** __DIR__::
    Store cached directory data in DIR. Can not be changed while tor is
    running.
    (Default: uses the value of DataDirectory.)
301

302
303
304
305
306
307
[[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)
308

309
310
311
312
313
314
315
316
317
[[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)
318

319
[[ClientTransportPlugin]] **ClientTransportPlugin** __transport__ socks4|socks5 __IP__:__PORT__::
320
321
**ClientTransportPlugin** __transport__ exec __path-to-binary__ [options]::
    In its first form, when set along with a corresponding Bridge line, the Tor
322
323
324
    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
325
    duty of that proxy to properly forward the traffic to the bridge. +
Taylor Yu's avatar
Taylor Yu committed
326
     +
327
    In its second form, when set along with a corresponding Bridge line, the Tor
Nick Mathewson's avatar
Nick Mathewson committed
328
    client launches the pluggable transport proxy executable in
329
330
    __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
331
    the traffic to the bridge. (Default: none)
332

333
[[ConnLimit]] **ConnLimit** __NUM__::
334
335
336
337
    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. +
Taylor Yu's avatar
Taylor Yu committed
338
     +
339
340
341
342
343
    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**. +
Taylor Yu's avatar
Taylor Yu committed
344
     +
345
346
347
    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)
348

349
[[ConstrainedSockets]] **ConstrainedSockets** **0**|**1**::
350
351
352
353
354
355
    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. +
Taylor Yu's avatar
Taylor Yu committed
356
     +
357
358
359
    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. +
Taylor Yu's avatar
Taylor Yu committed
360
     +
361
362
363
    The DirPort option should also not be used if TCP buffers are scarce. The
    cached directory requests consume additional sockets which exacerbates
    the problem. +
Taylor Yu's avatar
Taylor Yu committed
364
     +
365
366
367
    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
368
    time on long paths. (Default: 0)
369

370
[[ConstrainedSockSize]] **ConstrainedSockSize** __N__ **bytes**|**KBytes**::
371
372
373
374
    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.

Taylor Yu's avatar
Taylor Yu committed
375
[[ControlPort]] **ControlPort** ['address'**:**]{empty}__port__|**unix:**__path__|**auto** [__flags__]::
376
377
    If set, Tor will accept connections on this port and allow those
    connections to control the Tor process using the Tor Control Protocol
rl1987's avatar
rl1987 committed
378
379
380
381
382
    (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
383
    methods means either method is sufficient to authenticate to Tor.) This
384
    option is required for many Tor controllers; most use the value of 9051.
385
    If a unix domain socket is used, you may quote the path using standard
386
387
    C escape sequences. You can specify this directive multiple times, to
    bind to multiple address/port pairs.
388
    Set it to "auto" to have Tor pick a port for you. (Default: 0) +
Taylor Yu's avatar
Taylor Yu committed
389
     +
Taylor Yu's avatar
Taylor Yu committed
390
    Recognized flags are:
391
392
393
394
395
396
    **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.
397
398
399
    **RelaxDirModeCheck**;;
        Unix domain sockets only: Do not insist that the directory
        that holds the socket be read-restricted.
400

401
402
403
404
405
406
407
408
409
410
[[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".

411
[[ControlSocket]] **ControlSocket** __Path__::
412
    Like ControlPort, but listens on a Unix domain socket, rather than a TCP
413
414
    socket. '0' disables ControlSocket. (Unix and Unix-like systems only.)
    (Default: 0)
415

416
[[ControlSocketsGroupWritable]] **ControlSocketsGroupWritable** **0**|**1**::
417
418
419
420
    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)

421
[[CookieAuthentication]] **CookieAuthentication** **0**|**1**::
422
423
    If this option is set to 1, allow connections on the control port
    when the connecting process knows the contents of a file named
424
425
426
427
    "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)

428
[[CookieAuthFile]] **CookieAuthFile** __Path__::
429
430
431
    If set, this option overrides the default location and file name
    for Tor's cookie file. (See CookieAuthentication above.)

432
[[CookieAuthFileGroupReadable]] **CookieAuthFileGroupReadable** **0**|**1**::
433
434
435
    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
436
    implemented; let us know if you need this for some reason.] (Default: 0)
437

438
439
440
441
442
[[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)
443

444
[[DataDirectory]] **DataDirectory** __DIR__::
445
    Store working data in DIR. Can not be changed while tor is running.
446
447
448
    (Default: ~/.tor if your home directory is not /; otherwise,
    @LOCALSTATEDIR@/lib/tor.  On Windows, the default is
    your ApplicationData folder.)
449

450
451
452
453
454
[[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)

455
[[DirAuthority]] **DirAuthority** [__nickname__] [**flags**] __ipv4address__:__dirport__ __fingerprint__::
456
457
458
459
    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
460
    is. By default, an authority is not authoritative for any directory style
461
    or version unless an appropriate flag is given. +
Taylor Yu's avatar
Taylor Yu committed
462
     +
463
    Tor will use this authority as a bridge authoritative directory if the
464
465
466
467
    "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
468
    flag "v3ident=**fp**" is given, the dirserver is a v3 directory authority
469
    whose v3 long-term signing key has the fingerprint **fp**. Lastly,
470
    if an "ipv6=**[**__ipv6address__**]**:__orport__" flag is present, then
471
472
    the directory authority is listening for IPv6 connections on the
    indicated IPv6 address and OR Port. +
Taylor Yu's avatar
Taylor Yu committed
473
     +
474
    Tor will contact the authority at __ipv4address__ to
475
476
477
478
    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. +
Taylor Yu's avatar
Taylor Yu committed
479
     +
480
481
    If no **DirAuthority** line is given, Tor will use the default directory
    authorities. NOTE: this option is intended for setting up a private Tor
482
483
484
485
    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.

486
[[DirAuthorityFallbackRate]] **DirAuthorityFallbackRate** __NUM__::
487
488
489
    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
490
491
    should be 1.0 or less. The default is less than 1, to reduce load on
    authorities. (Default: 0.1)
492

493
[[DisableAllSwap]] **DisableAllSwap** **0**|**1**::
494
495
496
497
498
    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
499
500
    **User** option to properly reduce Tor's privileges.
    Can not be changed while tor is running. (Default: 0)
501

502
[[DisableDebuggerAttachment]] **DisableDebuggerAttachment** **0**|**1**::
503
   If set to 1, Tor will attempt to prevent basic debugging attachment attempts
504
505
   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
506
507
508
509
510
511
512
513
514
   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
515
516
   on. Disabling this option while Tor is running is prohibited. (Default: 1)

517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
[[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 proceeding 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 "default", we obey a
    parameter in the consensus document. (Default: auto)

Taylor Yu's avatar
Taylor Yu committed
533
[[ExtORPort]] **ExtORPort** ['address'**:**]{empty}__port__|**auto**::
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
    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.  +
Taylor Yu's avatar
Taylor Yu committed
558
     +
559
560
    FallbackDirs should be stable relays with stable IP addresses, ports,
    and identity keys. They must have a DirPort. +
Taylor Yu's avatar
Taylor Yu committed
561
     +
562
563
564
565
    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.)

566
[[FetchDirInfoEarly]] **FetchDirInfoEarly** **0**|**1**::
567
568
569
570
    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)

571
[[FetchDirInfoExtraEarly]] **FetchDirInfoExtraEarly** **0**|**1**::
572
573
574
575
576
    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)

577
[[FetchHidServDescriptors]] **FetchHidServDescriptors** **0**|**1**::
578
579
580
581
    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)

582
[[FetchServerDescriptors]] **FetchServerDescriptors** **0**|**1**::
583
584
585
586
587
    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)

588
[[FetchUselessDescriptors]] **FetchUselessDescriptors** **0**|**1**::
589
590
591
592
593
594
595
596
    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
597
    tor client with an external parser that uses a full consensus.
598
599
600
601
602
603
    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)
604

605
606
607
608
609
610
611
612
613
614
615
616
617
618
[[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
619
    servers. (DEPRECATED: As of 0.3.1.0-alpha you should use HTTPSProxy.)
620

621
[[HTTPProxyAuthenticator]] **HTTPProxyAuthenticator** __username:password__::
622
623
624
    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
625
626
    want it to support others. (DEPRECATED: As of 0.3.1.0-alpha you should use
    HTTPSProxyAuthenticator.)
627

628
[[HTTPSProxy]] **HTTPSProxy** __host__[:__port__]::
629
630
631
632
633
634
    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.

635
[[HTTPSProxyAuthenticator]] **HTTPSProxyAuthenticator** __username:password__::
636
637
638
639
640
    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.

641
[[KeepalivePeriod]] **KeepalivePeriod** __NUM__::
642
    To keep firewalls from expiring connections, send a padding keepalive cell
643
    every NUM seconds on open connections that are in use. (Default: 5 minutes)
644

645
646
647
648
649
650
651
652
653
[[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.)

654
[[Log]] **Log** __minSeverity__[-__maxSeverity__] **stderr**|**stdout**|**syslog**::
655
656
657
658
659
660
    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
661
    messages of that level or higher will be sent to the listed destination. +
Taylor Yu's avatar
Taylor Yu committed
662
     +
663
664
665
666
667
668
669
670
    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.
671

Nick Mathewson's avatar
Nick Mathewson committed
672
[[Log2]] **Log** __minSeverity__[-__maxSeverity__] **file** __FILENAME__::
673
674
675
676
677
    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.

Nick Mathewson's avatar
Nick Mathewson committed
678
[[Log3]] **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **file** __FILENAME__ +
679

Nick Mathewson's avatar
Nick Mathewson committed
680
[[Log4]] **Log** **[**__domain__,...**]**__minSeverity__[-__maxSeverity__] ... **stderr**|**stdout**|**syslog**::
681
682
683
684
    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
685
    list of logging domains.  You can prefix a domain with $$~$$ to indicate
686
687
    negation, and use * to indicate "all domains".  If you specify a severity
    range without a list of domains, it matches all domains. +
Taylor Yu's avatar
Taylor Yu committed
688
     +
689
690
    This is an advanced feature which is most useful for debugging one or two
    of Tor's subsystems at a time. +
Taylor Yu's avatar
Taylor Yu committed
691
     +
692
693
    The currently recognized domains are: general, crypto, net, config, fs,
    protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge,
Alexander Færøy's avatar
Alexander Færøy committed
694
    acct, hist, handshake, heartbeat, channel, sched, guard, consdiff, dos,
Nick Mathewson's avatar
Nick Mathewson committed
695
    process, pt, btrack, and mesg.
696
    Domain names are case-insensitive. +
Taylor Yu's avatar
Taylor Yu committed
697
     +
698
    For example, "`Log [handshake]debug [~net,~mm]info notice stdout`" sends
699
700
701
702
    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.

703
704
705
706
707
[[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)

708
709
710
711
712
713
714
715
716
717
718
719
720
721
[[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.
722

723
[[MaxUnparseableDescSizeToLog]] **MaxUnparseableDescSizeToLog** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**::
724
725
726
727
    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
Roger Dingledine's avatar
Roger Dingledine committed
728
    servers to resource exhaustion attacks. (Default: 10 MBytes)
729

730
731
732
733
734
735
[[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)

736
[[OutboundBindAddress]] **OutboundBindAddress** __IP__::
737
738
    Make all outbound connections originate from the IP address specified. This
    is only useful when you have multiple network interfaces, and you want all
739
740
    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.
741
    IPv6 addresses should be wrapped in square brackets.
742
    This setting will be ignored for connections to the loopback addresses
743
    (127.0.0.0/8 and ::1), and is not used for DNS requests as well.
744

745
746
747
748
749
750
751
752
753
[[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).

754
[[OutboundBindAddressOR]] **OutboundBindAddressOR** __IP__::
Roger Dingledine's avatar
Roger Dingledine committed
755
756
757
758
    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
759
760
    address. IPv6 addresses should be wrapped in square brackets.
    This setting will be ignored for connections to the loopback
Roger Dingledine's avatar
Roger Dingledine committed
761
    addresses (127.0.0.0/8 and ::1).
762

rl1987's avatar
rl1987 committed
763
[[OwningControllerProcess]] **{dbl_}OwningControllerProcess** __PID__::
764
765
766
767
    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.

768
769
770
771
772
773
774
775
776
[[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)
777

778
[[PidFile]] **PidFile** __FILE__::
779
    On startup, write our PID to FILE. On clean shutdown, remove
780
    FILE. Can not be changed while tor is running.
781

782
[[ProtocolWarnings]] **ProtocolWarnings** **0**|**1**::
783
784
785
786
    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)

787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
[[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)

802
803
804
805
806
[[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)

807
[[RunAsDaemon]] **RunAsDaemon** **0**|**1**::
808
809
    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.
810
    Can not be changed while tor is running.
811
812
    (Default: 0)

813
[[SafeLogging]] **SafeLogging** **0**|**1**|**relay**::
814
815
816
817
    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. +
Taylor Yu's avatar
Taylor Yu committed
818
     +
819
820
821
    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
822
823
824
    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)
825

826
827
828
829
830
831
[[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. +
Taylor Yu's avatar
Taylor Yu committed
832
     +
833
834
835
836
837
838
839
840
841
    When the **Sandbox** is 1, the following options can not be changed when tor
    is running:
    **Address**,
    **ConnLimit**,
    **CookieAuthFile**,
    **DirPortFrontPage**,
    **ExtORPortCookieAuthFile**,
    **Logs**,
    **ServerDNSResolvConfFile**,
Taylor Yu's avatar
Taylor Yu committed
842
    **ClientOnionAuthDir** (and any files in it won't reload on HUP signal). +
Taylor Yu's avatar
Taylor Yu committed
843
     +
844
    Launching new Onion Services through the control port is not supported
Taylor Yu's avatar
Taylor Yu committed
845
    with current syscall sandboxing implementation. +
Taylor Yu's avatar
Taylor Yu committed
846
     +
847
848
    Tor must remain in client or server mode (some changes to **ClientOnly**
    and **ORPort** are not allowed). Currently, if **Sandbox** is 1,
Taylor Yu's avatar
Taylor Yu committed
849
    **ControlPort** command "GETINFO address" will not work. +
Taylor Yu's avatar
Taylor Yu committed
850
     +
851
    (Default: 0)
852

David Goulet's avatar
David Goulet committed
853
[[Schedulers]] **Schedulers** **KIST**|**KISTLite**|**Vanilla**::
854
855
856
857
858
859
    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.
Taylor Yu's avatar
Taylor Yu committed
860
    (Default: KIST,KISTLite,Vanilla) +
Taylor Yu's avatar
Taylor Yu committed
861
     +
David Goulet's avatar
David Goulet committed
862
    The possible scheduler types are:
Taylor Yu's avatar
Taylor Yu committed
863
     +
864
865
866
867
868
    **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
Taylor Yu's avatar
Taylor Yu committed
869
    higher. +
Taylor Yu's avatar
Taylor Yu committed
870
     +
871
872
873
874
    **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
Taylor Yu's avatar
Taylor Yu committed
875
    are still realized with KISTLite. +
Taylor Yu's avatar
Taylor Yu committed
876
     +
877
878
879
    **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.
David Goulet's avatar
David Goulet committed
880

881
// Out of order because it logically belongs near the Schedulers option
David Goulet's avatar
David Goulet committed
882
[[KISTSchedRunInterval]] **KISTSchedRunInterval** __NUM__ **msec**::
883
    If KIST or KISTLite is used in the Schedulers option, this controls at which
David Goulet's avatar
David Goulet committed
884
885
886
887
    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)

888
// Out of order because it logically belongs near the Schedulers option
David Goulet's avatar
David Goulet committed
889
890
891
892
[[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)

893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917

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

918
// Out of order because Username logically precedes Password
919
920
921
922
923
924
925
926
927
928
929
930
[[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)

931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
[[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.

947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
[[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.

Taylor Yu's avatar
Taylor Yu committed
965
== CLIENT OPTIONS
966

967
968
969
// These options are in alphabetical order, with exceptions as noted.
// Please keep them that way!

970
The following options are useful only for clients (that is, if
971
972
**SocksPort**, **HTTPTunnelPort**, **TransPort**, **DNSPort**, or
**NATDPort** is non-zero):
973

974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
[[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).

991
[[Bridge]] **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]::
992
993
    When set along with UseBridges, instructs Tor to use the relay at
    "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint"
994
    is provided (using the same format as for DirAuthority), we will verify that
995
996
    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
997
    it's provided and if UpdateBridgesFromAuthority is set too.  +
Taylor Yu's avatar
Taylor Yu committed
998
     +
999
1000
    If "transport" is provided, it must match a ClientTransportPlugin line. We
    then use that pluggable transport's proxy to transfer data to the bridge,