diff options
Diffstat (limited to 'doc/tor.1.txt')
| -rw-r--r-- | doc/tor.1.txt | 262 |
1 files changed, 160 insertions, 102 deletions
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 4c5d5359af..7ef8920858 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -176,7 +176,7 @@ forward slash (/) in the configuration file and on the command line. GENERAL OPTIONS --------------- -[[BandwidthRate]] **BandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[BandwidthRate]] **BandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: A token bucket limits the average incoming bandwidth usage on this node to the specified number of bytes per second, and the average outgoing bandwidth usage to that same value. If you want to run a relay in the @@ -195,35 +195,35 @@ GENERAL OPTIONS To avoid confusion, we recommend writing "bytes" or "bits" explicitly, since it's easy to forget that "B" means bytes, not bits. -[[BandwidthBurst]] **BandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[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) -[[MaxAdvertisedBandwidth]] **MaxAdvertisedBandwidth** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[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. -[[RelayBandwidthRate]] **RelayBandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[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. (Default: 0) -[[RelayBandwidthBurst]] **RelayBandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[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. (Default: 0) -[[PerConnBWRate]] **PerConnBWRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[PerConnBWRate]] **PerConnBWRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: If set, do separate rate limiting for each connection from a non-relay. You should never need to change this value, since a network-wide value is published in the consensus and your relay will use that value. (Default: 0) -[[PerConnBWBurst]] **PerConnBWBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[PerConnBWBurst]] **PerConnBWBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: If set, do separate rate limiting for each connection from a non-relay. You should never need to change this value, since a network-wide value is published in the consensus and your relay will use that value. (Default: 0) @@ -390,7 +390,8 @@ GENERAL OPTIONS file readable by the default GID. (Default: 0) [[DataDirectory]] **DataDirectory** __DIR__:: - Store working data in DIR (Default: @LOCALSTATEDIR@/lib/tor) + Store working data in DIR. Can not be changed while tor is running. + (Default: @LOCALSTATEDIR@/lib/tor) [[DataDirectoryGroupReadable]] **DataDirectoryGroupReadable** **0**|**1**:: If this option is set to 0, don't allow the filesystem group to read the @@ -465,7 +466,8 @@ GENERAL OPTIONS not supported. We believe that this feature works on modern Gnu/Linux distributions, and that it should work on *BSD systems (untested). This option requires that you start your Tor as root, and you should use the - **User** option to properly reduce Tor's privileges. (Default: 0) + **User** option to properly reduce Tor's privileges. + Can not be changed while tor is running. (Default: 0) [[DisableDebuggerAttachment]] **DisableDebuggerAttachment** **0**|**1**:: If set to 1, Tor will attempt to prevent basic debugging attachment attempts @@ -505,11 +507,13 @@ GENERAL OPTIONS (Default: 1) [[FetchUselessDescriptors]] **FetchUselessDescriptors** **0**|**1**:: - If set to 1, Tor will fetch every non-obsolete descriptor from the - authorities that it hears about. Otherwise, it will avoid fetching useless - descriptors, for example for routers that are not running. This option is - useful if you're using the contributed "exitlist" script to enumerate Tor - nodes that exit to certain addresses. (Default: 0) + If set to 1, Tor will fetch every consensus flavor, descriptor, and + certificate that it hears about. Otherwise, it will avoid fetching useless + descriptors: flavors that it is not using to build circuits, and authority + certificates it does not trust. This option is useful if you're using a + tor client with an external parser that uses a full consensus. + This option fetches all documents, **DirCache** fetches and serves + all documents. (Default: 0) [[HTTPProxy]] **HTTPProxy** __host__[:__port__]:: Tor will make all its directory requests through this host:port (or host:80 @@ -538,7 +542,20 @@ GENERAL OPTIONS [[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. (Default: 0) + experimental feature. Can not be changed while tor is running. + + When the Sandbox is 1, the following options can not be changed when tor + is running: + Address + ConnLimit + CookieAuthFile + DirPortFrontPage + ExtORPortCookieAuthFile + Logs + ServerDNSResolvConfFile + Tor must remain in client or server mode (some changes to ClientOnly and + ORPort are not allowed). + (Default: 0) [[Socks4Proxy]] **Socks4Proxy** __host__[:__port__]:: Tor will make all OR connections through the SOCKS 4 proxy at host:port @@ -609,7 +626,7 @@ GENERAL OPTIONS message currently has at least one domain; most currently have exactly one. This doesn't affect controller log messages. (Default: 0) -[[MaxUnparseableDescSizeToLog]] **MaxUnparseableDescSizeToLog** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: +[[MaxUnparseableDescSizeToLog]] **MaxUnparseableDescSizeToLog** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**:: Unparseable descriptors (e.g. for votes, consensuses, routers) are logged in separate files by hash, up to the specified size in total. Note that only files logged during the lifetime of this Tor process count toward the @@ -624,9 +641,23 @@ GENERAL OPTIONS This setting will be ignored for connections to the loopback addresses (127.0.0.0/8 and ::1). +[[OutboundBindAddressOR]] **OutboundBindAddressOR** __IP__:: + Make all outbound non-exit (=relay and other) connections originate from the IP + address specified. This option overrides **OutboundBindAddress** for the same + IP version. This option may be used twice, once with an IPv4 address and once + with an IPv6 address. This setting will be ignored for connections to the + loopback addresses (127.0.0.0/8 and ::1). + +[[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. This + setting will be ignored for connections to the loopback addresses (127.0.0.0/8 + and ::1). + [[PidFile]] **PidFile** __FILE__:: On startup, write our PID to FILE. On clean shutdown, remove - FILE. + FILE. Can not be changed while tor is running. [[ProtocolWarnings]] **ProtocolWarnings** **0**|**1**:: If 1, Tor will log with severity \'warn' various cases of other parties not @@ -642,6 +673,7 @@ GENERAL OPTIONS [[RunAsDaemon]] **RunAsDaemon** **0**|**1**:: If 1, Tor forks and daemonizes to the background. This option has no effect on Windows; instead you should use the --service command-line option. + Can not be changed while tor is running. (Default: 0) [[LogTimeGranularity]] **LogTimeGranularity** __NUM__:: @@ -658,7 +690,8 @@ GENERAL OPTIONS [[SyslogIdentityTag]] **SyslogIdentityTag** __tag__:: When logging to syslog, adds a tag to the syslog identity such that - log entries are marked with "Tor-__tag__". (Default: none) + log entries are marked with "Tor-__tag__". Can not be changed while tor is + running. (Default: none) [[SafeLogging]] **SafeLogging** **0**|**1**|**relay**:: Tor can scrub potentially sensitive strings from log messages (e.g. @@ -673,6 +706,7 @@ GENERAL OPTIONS [[User]] **User** __Username__:: On startup, setuid to this user and setgid to their primary group. + Can not be changed while tor is running. [[KeepBindCapabilities]] **KeepBindCapabilities** **0**|**1**|**auto**:: On Linux, when we are started as root and we switch our identity using @@ -680,20 +714,23 @@ GENERAL OPTIONS 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.) [[HardwareAccel]] **HardwareAccel** **0**|**1**:: If non-zero, try to use built-in (static) crypto hardware acceleration when - available. (Default: 0) + available. Can not be changed while tor is running. (Default: 0) [[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. + Names can be verified with the openssl engine command. Can not be changed + while tor is running. [[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. [[AvoidDiskWrites]] **AvoidDiskWrites** **0**|**1**:: If non-zero, try to write to disk less frequently than we would otherwise. @@ -718,6 +755,13 @@ GENERAL OPTIONS 127.0.0.1 or 10.0.0.1. This is mostly useful for debugging rate-limiting. (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) + CLIENT OPTIONS -------------- @@ -817,7 +861,7 @@ The following options are useful only for clients (that is, if [[ExcludeExitNodes]] **ExcludeExitNodes** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address patterns of nodes to never use when picking an exit node---that is, a - node that delivers traffic for you outside the Tor network. Note that any + node that delivers traffic for you *outside* the Tor network. Note that any node listed in ExcludeNodes is automatically considered to be part of this list too. See the **ExcludeNodes** option for more information on how to specify @@ -834,7 +878,7 @@ The following options are useful only for clients (that is, if [[ExitNodes]] **ExitNodes** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address patterns of nodes to use as exit node---that is, a - node that delivers traffic for you outside the Tor network. See + node that delivers traffic for you *outside* the Tor network. See the **ExcludeNodes** option for more information on how to specify nodes. + + Note that if you list too few nodes here, or if you exclude too many exit @@ -842,7 +886,7 @@ The following options are useful only for clients (that is, if 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 + 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 @@ -868,16 +912,16 @@ The following options are useful only for clients (that is, if the **ExcludeNodes** option for more information on how to specify nodes. [[StrictNodes]] **StrictNodes** **0**|**1**:: - If StrictNodes is set to 1, Tor will treat the ExcludeNodes option as a - requirement to follow for all the circuits you generate, even if doing so - will break functionality for you. If StrictNodes is set to 0, Tor will + If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes option + as a requirement to follow for all the circuits you generate, even if + doing so will break functionality for you (StrictNodes applies to neither + ExcludeExitNodes nor to ExitNodes). If StrictNodes is set to 0, Tor will still try to avoid nodes in the ExcludeNodes list, but it will err on the - side of avoiding unexpected errors. Specifically, StrictNodes 0 tells - Tor that it is okay to use an excluded node when it is *necessary* to - perform relay reachability self-tests, connect to - a hidden service, provide a hidden service to a client, fulfill a .exit - request, upload directory information, or download directory information. - (Default: 0) + side of avoiding unexpected errors. Specifically, StrictNodes 0 tells Tor + that it is okay to use an excluded node when it is *necessary* to perform + relay reachability self-tests, connect to a hidden service, provide a + hidden service to a client, fulfill a .exit request, upload directory + information, or download directory information. (Default: 0) [[FascistFirewall]] **FascistFirewall** **0**|**1**:: If 1, Tor will only create outgoing connections to ORs running on ports @@ -1142,6 +1186,7 @@ The following options are useful only for clients (that is, if authentication" when IsolateSOCKSAuth is disabled, or when this option is set. +[[SocksPortFlagsMisc]]:: Flags are processed left to right. If flags conflict, the last flag on the line is used, and all earlier flags are ignored. No error is issued for conflicting flags. @@ -1172,7 +1217,8 @@ The following options are useful only for clients (that is, if NUM must be between 1 and 1000, inclusive. Note that the configured bandwidth limits are still expressed in bytes per second: this option only affects the frequency with which Tor checks to see whether - previously exhausted connections may read again. (Default: 100 msec) + previously exhausted connections may read again. + Can not be changed while tor is running. (Default: 100 msec) [[TrackHostExits]] **TrackHostExits** __host__,__.domain__,__...__:: For each value in the comma separated list, Tor will track recent @@ -1209,15 +1255,6 @@ The following options are useful only for clients (that is, if Authorities, Single Onion Services, and Tor2web clients. In these cases, the this option is ignored. (Default: 1) -[[UseEntryGuardsAsDirGuards]] **UseEntryGuardsAsDirGuards** **0**|**1**:: - If this option is set to 1, and UseEntryGuards is also set to 1, - we try to use our entry guards as directory - guards, and failing that, pick more nodes to act as our directory guards. - This helps prevent an adversary from enumerating clients. It's only - available for clients (non-relay, non-bridge) that aren't configured to - download any non-default directory material. It doesn't currently - do anything when we lack a live consensus. (Default: 1) - [[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: V3 authoritative directories only. Configures the location of the guardfraction file which contains information about how long relays @@ -1335,7 +1372,7 @@ The following options are useful only for clients (that is, if [[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**:: TransProxyType may only be enabled when there is transparent proxy listener - enabled. + enabled. + + Set this to "TPROXY" if you wish to be able to use the TPROXY Linux module to transparently proxy connections that are configured using the TransPort @@ -1343,19 +1380,19 @@ The following options are useful only for clients (that is, if for all addresses, even when the TransListenAddress is configured for an internal address. 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. + Documentation/networking/tproxy.txt. + + - Set this option to "ipfw" to use the FreeBSD ipfw interface. + 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. + 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. + on Linux, or to use pf +rdr-to+ rules on *BSD systems. + + (Default: "default".) @@ -1413,7 +1450,8 @@ The following options are useful only for clients (that is, if If true, Tor does not try to fulfill requests to connect to an internal address (like 127.0.0.1 or 192.168.0.1) __unless a exit node is specifically requested__ (for example, via a .exit hostname, or a - controller request). (Default: 1) + controller request). If true, multicast DNS hostnames for machines on the + local network (of the form *.local) are also rejected. (Default: 1) [[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**:: If true, Tor downloads and caches "extra-info" documents. These documents @@ -1462,11 +1500,11 @@ The following options are useful only for clients (that is, if (Example: Tor2webRendezvousPoints Fastyfasty, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + - This feature can only be used if Tor2webMode is also enabled. + This feature can only be used if Tor2webMode is also enabled. + + ExcludeNodes have higher priority than Tor2webRendezvousPoints, which means that nodes specified in ExcludeNodes will not be - picked as RPs. + picked as RPs. + + If no nodes in Tor2webRendezvousPoints are currently available for use, Tor will choose a random node when building HS circuits. @@ -1494,7 +1532,7 @@ The following options are useful only for clients (that is, if These options override the default behavior of Tor's (**currently experimental**) path bias detection algorithm. To try to find broken or misbehaving guard nodes, Tor looks for nodes where more than a certain - fraction of circuits through that guard fail to get built. + fraction of circuits through that guard fail to get built. + + The PathBiasCircThreshold option controls how many circuits we need to build through a guard before we make these checks. The PathBiasNoticeRate, @@ -1520,14 +1558,14 @@ The following options are useful only for clients (that is, if [[PathBiasScaleUseThreshold]] **PathBiasScaleUseThreshold** __NUM__:: Similar to the above options, these options override the default behavior - of Tor's (**currently experimental**) path use bias detection algorithm. + of Tor's (**currently experimental**) path use bias detection algorithm. + + Where as the path bias parameters govern thresholds for successfully building circuits, these four path use bias parameters govern thresholds only for circuit usage. Circuits which receive no stream usage are not counted by this detection algorithm. A used circuit is considered successful if it is capable of carrying streams or otherwise receiving - well-formed responses to RELAY cells. + 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. @@ -1661,7 +1699,7 @@ is non-zero): Tells Tor whether to run as an exit relay. If Tor is running as a non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to exit according to the ExitPolicy option (or the default ExitPolicy if - none is specified). + none is specified). + + If ExitRelay is set to 0, no traffic is allowed to exit, and the ExitPolicy option is ignored. + @@ -1739,6 +1777,7 @@ is non-zero): reject *:6881-6999 accept *:* +[[ExitPolicyDefault]]:: Since the default exit policy uses accept/reject *, it applies to both IPv4 and IPv6 addresses. @@ -1775,7 +1814,7 @@ is non-zero): that they are in the same \'family', Tor clients will not use them in the same circuit. (Each server only needs to list the other servers in its family; it doesn't need to list itself, but it won't hurt.) Do not list - any bridge relay as it would compromise its concealment. + any bridge relay as it would compromise its concealment. + + When listing a node, it's better to list it by fingerprint than by nickname: fingerprints are more reliable. @@ -1793,26 +1832,27 @@ is non-zero): Advertise this port to listen for connections from Tor clients and servers. This option is required to be a Tor server. Set it to "auto" to have Tor pick a port for you. Set it to 0 to not - run an ORPort at all. This option can occur more than once. (Default: 0) -+ + run an ORPort at all. This option can occur more than once. (Default: 0) + + + Tor recognizes these flags on each ORPort: - **NoAdvertise**:: + **NoAdvertise**;; By default, we bind to a port and tell our users about it. If NoAdvertise is specified, we don't advertise, but listen anyway. This can be useful if the port everybody will be connecting to (for example, one that's opened on our firewall) is somewhere else. - **NoListen**:: + **NoListen**;; By default, we bind to a port and tell our users about it. If NoListen is specified, we don't bind, but advertise anyway. This can be useful if something else (for example, a firewall's port forwarding configuration) is causing connections to reach us. - **IPv4Only**:: + **IPv4Only**;; If the address is absent, or resolves to both an IPv4 and an IPv6 address, only listen to the IPv4 address. - **IPv6Only**:: + **IPv6Only**;; If the address is absent, or resolves to both an IPv4 and an IPv6 address, only listen to the IPv6 address. -+ + +[[ORPortFlagsExclusive]]:: For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and IPv4Only and IPv6Only are mutually exclusive. @@ -1820,8 +1860,8 @@ is non-zero): Bind to this IP address to listen for connections from Tor clients and servers. If you specify a port, bind to this port rather than the one specified in ORPort. (Default: 0.0.0.0) This directive can be specified - multiple times to bind to multiple addresses/ports. -+ + multiple times to bind to multiple addresses/ports. + + + This option is deprecated; you can get the same behavior with ORPort now that it supports NoAdvertise and explicit addresses. @@ -1840,7 +1880,7 @@ is non-zero): [[PublishServerDescriptor]] **PublishServerDescriptor** **0**|**1**|**v3**|**bridge**,**...**:: This option specifies which descriptors Tor will publish when acting as a relay. You can - choose multiple arguments, separated by commas. + choose multiple arguments, separated by commas. + + If this option is set to 0, Tor will not publish its descriptors to any directories. (This is useful if you're testing @@ -1868,7 +1908,7 @@ is non-zero): to 0 will disable the heartbeat. Otherwise, it must be at least 30 minutes. (Default: 6 hours) -[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**|**TBytes**:: +[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: Limits the max number of bytes sent and received within a set time period using a given calculation rule (see: AccountingStart, AccountingRule). Useful if you need to stay under a specific bandwidth. By default, the @@ -2082,8 +2122,9 @@ is non-zero): DIRECTORY SERVER OPTIONS ------------------------ -The following options are useful only for directory servers (that is, -if DirPort is non-zero): +The following options are useful only for directory servers. (Relays with +enough bandwidth automatically become directory servers; see DirCache for +details.) [[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__:: When this option is set, it takes an HTML file and publishes it as "/" on @@ -2095,16 +2136,16 @@ if DirPort is non-zero): If this option is nonzero, advertise the directory service on this port. Set it to "auto" to have Tor pick a port for you. This option can occur more than once, but only one advertised DirPort is supported: all - but one DirPort must have the **NoAdvertise** flag set. (Default: 0) -+ + but one DirPort must have the **NoAdvertise** flag set. (Default: 0) + + + The same flags are supported here as are supported by ORPort. [[DirListenAddress]] **DirListenAddress** __IP__[:__PORT__]:: Bind the directory service to this address. If you specify a port, bind to this port rather than the one specified in DirPort. (Default: 0.0.0.0) This directive can be specified multiple times to bind to multiple - addresses/ports. -+ + addresses/ports. + + + This option is deprecated; you can get the same behavior with DirPort now that it supports NoAdvertise and explicit addresses. @@ -2199,7 +2240,7 @@ on the public Tor network. [[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that will be listed as bad exits in any network status document this authority - publishes, if **AuthDirListBadExits** is set. + publishes, if **AuthDirListBadExits** is set. + + (The address pattern syntax here and in the options below is the same as for exit policies, except that you don't need to say @@ -2237,26 +2278,22 @@ on the public Tor network. list as acceptable on a single IP address. Set this to "0" for "no limit". (Default: 2) -[[AuthDirMaxServersPerAuthAddr]] **AuthDirMaxServersPerAuthAddr** __NUM__:: - Authoritative directories only. Like AuthDirMaxServersPerAddr, but applies - to addresses shared with directory authorities. (Default: 5) - -[[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: Authoritative directories only. If non-zero, always vote the Fast flag for any relay advertising this amount of capacity or more. (Default: 100 KBytes) -[[AuthDirGuardBWGuarantee]] **AuthDirGuardBWGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[AuthDirGuardBWGuarantee]] **AuthDirGuardBWGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: Authoritative directories only. If non-zero, this advertised capacity or more is always sufficient to satisfy the bandwidth requirement - for the Guard flag. (Default: 250 KBytes) + for the Guard flag. (Default: 2 MBytes) [[AuthDirPinKeys]] **AuthDirPinKeys** **0**|**1**:: Authoritative directories only. If non-zero, do not allow any relay to publish a descriptor if any other relay has reserved its <Ed25519,RSA> identity keypair. In all cases, Tor records every keypair it accepts in a journal if it is new, or if it differs from the most recently - accepted pinning for one of the keys it contains. (Default: 0) + accepted pinning for one of the keys it contains. (Default: 1) [[AuthDirSharedRandomness]] **AuthDirSharedRandomness** **0**|**1**:: Authoritative directories only. Switch for the shared random protocol. @@ -2264,6 +2301,13 @@ on the public Tor network. (default), the flag "shared-rand-participate" is added to the authority vote indicating participation in the protocol. (Default: 1) +[[AuthDirTestEd25519LinkKeys]] **AuthDirTestEd25519LinkKeys** **0**|**1**:: + Authoritative directories only. If this option is set to 0, then we treat + relays as "Running" if their RSA key is correct when we probe them, + regardless of their Ed25519 key. We should only ever set this option to 0 + if there is some major bug in Ed25519 link authentication that causes us + to label all the relays as not Running. (Default: 1) + [[BridgePassword]] **BridgePassword** __Password__:: If set, contains an HTTP authenticator that tells a bridge authority to serve all requested bridge information. Used by the (only partially @@ -2335,9 +2379,9 @@ The following options are used to configure a hidden service. [[HiddenServiceDir]] **HiddenServiceDir** __DIRECTORY__:: Store data files for a hidden service in DIRECTORY. Every hidden service must have a separate directory. You may use this option multiple times to - specify multiple services. DIRECTORY must be an existing directory. + specify multiple services. If DIRECTORY does not exist, Tor will create it. (Note: in current versions of Tor, if DIRECTORY is a relative path, - it will be relative to current + it will be relative to the current working directory of Tor instance, not to its DataDirectory. Do not rely on this behavior; it is not guaranteed to remain the same in future versions.) @@ -2384,8 +2428,8 @@ The following options are used to configure a hidden service. [[HiddenServiceMaxStreams]] **HiddenServiceMaxStreams** __N__:: The maximum number of simultaneous streams (connections) per rendezvous - circuit. (Setting this to 0 will allow an unlimited number of simultanous - streams.) (Default: 0) + circuit. The maximum value allowed is 65535. (Setting this to 0 will allow + an unlimited number of simultanous streams.) (Default: 0) [[HiddenServiceMaxStreamsCloseCircuit]] **HiddenServiceMaxStreamsCloseCircuit** **0**|**1**:: If set to 1, then exceeding **HiddenServiceMaxStreams** will cause the @@ -2394,8 +2438,9 @@ The following options are used to configure a hidden service. [[RendPostPeriod]] **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: Every time the specified period elapses, Tor uploads any rendezvous - service descriptors to the directory servers. This information is also - uploaded whenever it changes. (Default: 1 hour) + service descriptors to the directory servers. This information is also + uploaded whenever it changes. Minimum value allowed is 10 minutes and + maximum is 3.5 days. (Default: 1 hour) [[HiddenServiceDirGroupReadable]] **HiddenServiceDirGroupReadable** **0**|**1**:: If this option is set to 1, allow the filesystem group to read the @@ -2417,20 +2462,20 @@ The following options are used to configure a hidden service. Single Onion Service. One-hop circuits make Single Onion servers easily locatable, but clients remain location-anonymous. However, the fact that a client is accessing a Single Onion rather than a Hidden Service may be - statistically distinguishable. - + statistically distinguishable. + + + **WARNING:** Once a hidden service directory has been used by a tor instance in HiddenServiceSingleHopMode, it can **NEVER** be used again for a hidden service. It is best practice to create a new hidden service directory, key, and address for each new Single Onion Service and Hidden Service. It is not possible to run Single Onion Services and Hidden Services from the same tor instance: they should be run on different - servers with different IP addresses. - + 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**. + **HiddenServiceSingleHopMode**. Can not be changed while tor is running. (Default: 0) [[HiddenServiceNonAnonymousMode]] **HiddenServiceNonAnonymousMode** **0**|**1**:: @@ -2438,8 +2483,8 @@ The following options are used to configure a hidden service. non-anonymous HiddenServiceSingleHopMode. Enables direct connections in the server-side hidden service protocol. If you are using this option, you need to disable all client-side services on your Tor instance, - including setting SOCKSPort to "0". - (Default: 0) + including setting SOCKSPort to "0". Can not be changed while tor is + running. (Default: 0) TESTING NETWORK OPTIONS ----------------------- @@ -2525,7 +2570,7 @@ The following options are used for running a testing Tor network. time. Changing this requires that **TestingTorNetwork** is set. (Default: 10 minutes) -[[TestingMinFastFlagThreshold]] **TestingMinFastFlagThreshold** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[TestingMinFastFlagThreshold]] **TestingMinFastFlagThreshold** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: Minimum value for the Fast flag. Overrides the ordinary minimum taken from the consensus when TestingTorNetwork is set. (Default: 0.) @@ -2584,7 +2629,7 @@ The following options are used for running a testing Tor network. A list of identity fingerprints, country codes, and address patterns of nodes to vote Exit for regardless of their uptime, bandwidth, or exit policy. See the **ExcludeNodes** - option for more information on how to specify nodes. + option for more information on how to specify nodes. + + In order for this option to have any effect, **TestingTorNetwork** has to be set. See the **ExcludeNodes** option for more @@ -2593,7 +2638,7 @@ The following options are used for running a testing Tor network. [[TestingDirAuthVoteExitIsStrict]] **TestingDirAuthVoteExitIsStrict** **0**|**1** :: If True (1), a node will never receive the Exit flag unless it is specified in the **TestingDirAuthVoteExit** list, regardless of its uptime, bandwidth, - or exit policy. + or exit policy. + + In order for this option to have any effect, **TestingTorNetwork** has to be set. @@ -2602,14 +2647,14 @@ The following options are used for running a testing Tor network. A list of identity fingerprints and country codes and address patterns of nodes to vote Guard for regardless of their uptime and bandwidth. See the **ExcludeNodes** option for more - information on how to specify nodes. + information on how to specify nodes. + + In order for this option to have any effect, **TestingTorNetwork** has to be set. [[TestingDirAuthVoteGuardIsStrict]] **TestingDirAuthVoteGuardIsStrict** **0**|**1** :: If True (1), a node will never receive the Guard flag unless it is specified - in the **TestingDirAuthVoteGuard** list, regardless of its uptime and bandwidth. + in the **TestingDirAuthVoteGuard** list, regardless of its uptime and bandwidth. + + In order for this option to have any effect, **TestingTorNetwork** has to be set. @@ -2618,14 +2663,14 @@ The following options are used for running a testing Tor network. A list of identity fingerprints and country codes and address patterns of nodes to vote HSDir for regardless of their uptime and DirPort. See the **ExcludeNodes** option for more - information on how to specify nodes. + information on how to specify nodes. + + In order for this option to have any effect, **TestingTorNetwork** must be set. [[TestingDirAuthVoteHSDirIsStrict]] **TestingDirAuthVoteHSDirIsStrict** **0**|**1** :: If True (1), a node will never receive the HSDir flag unless it is specified - in the **TestingDirAuthVoteHSDir** list, regardless of its uptime and DirPort. + in the **TestingDirAuthVoteHSDir** list, regardless of its uptime and DirPort. + + In order for this option to have any effect, **TestingTorNetwork** has to be set. @@ -2645,7 +2690,7 @@ The following options are used for running a testing Tor network. events. Changing this requires that **TestingTorNetwork** is set. (Default: 0) -[[TestingMinExitFlagThreshold]] **TestingMinExitFlagThreshold** __N__ **KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: +[[TestingMinExitFlagThreshold]] **TestingMinExitFlagThreshold** __N__ **KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: Sets a lower-bound for assigning an exit flag when running as an authority on a testing network. Overrides the usual default lower bound of 4 KB. (Default: 0) @@ -2669,6 +2714,19 @@ The following options are used for running a testing Tor network. we replace it and issue a new key? (Default: 3 hours for link and auth; 1 day for signing.) +NON-PERSISTENT OPTIONS +---------------------- + +These options are not saved to the torrc file by the "SAVECONF" controller +command. Other options of this type are documented in control-spec.txt, +section 5.4. End-users should mostly ignore them. + +[[UnderscorePorts]] **\_\_ControlPort**, **\_\_DirPort**, **\_\_DNSPort**, **\_\_ExtORPort**, **\_\_NATDPort**, **\_\_ORPort**, **\_\_SocksPort**, **\_\_TransPort**:: + These underscore-prefixed options are variants of the regular Port + options. They behave the same, except they are not saved to the + torrc file by the controller's SAVECONF command. + + SIGNALS ------- |