diff options
Diffstat (limited to 'doc/tor.1.txt')
| -rw-r--r-- | doc/tor.1.txt | 150 |
1 files changed, 106 insertions, 44 deletions
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 6dd1b60b23..581783dd65 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -303,8 +303,15 @@ GENERAL OPTIONS 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. + + - You probably don't need to adjust this. It has no effect on Windows - since that platform lacks getrlimit(). (Default: 1000) + Tor relays need thousands of sockets, to connect to every other relay. + If you are running a private bridge, you can reduce the number of sockets + that Tor uses. For example, to limit Tor to 500 sockets, run + "ulimit -n 500" in a shell. Then start tor in the same shell, with + **ConnLimit 500**. You may also need to set **DisableOOSCheck 0**. + + + + Unless you have severely limited sockets, you probably don't need to + adjust **ConnLimit** itself. It has no effect on Windows, since that + platform lacks getrlimit(). (Default: 1000) [[DisableNetwork]] **DisableNetwork** **0**|**1**:: When this option is set, we don't listen for or accept any connections @@ -604,6 +611,7 @@ GENERAL OPTIONS ServerDNSResolvConfFile Tor must remain in client or server mode (some changes to ClientOnly and ORPort are not allowed). + ClientOnionAuthDir and any files in it won't reload on HUP signal. (Default: 0) [[Socks4Proxy]] **Socks4Proxy** __host__[:__port__]:: @@ -628,9 +636,7 @@ GENERAL OPTIONS [[KeepalivePeriod]] **KeepalivePeriod** __NUM__:: To keep firewalls from expiring connections, send a padding keepalive cell - every NUM seconds on open connections that are in use. If the connection - has no open circuits, it will instead be closed after NUM seconds of - idleness. (Default: 5 minutes) + every NUM seconds on open connections that are in use. (Default: 5 minutes) [[Log]] **Log** __minSeverity__[-__maxSeverity__] **stderr**|**stdout**|**syslog**:: Send all messages between __minSeverity__ and __maxSeverity__ to the standard @@ -756,7 +762,9 @@ GENERAL OPTIONS If this option is set to 0, Tor will not perform any scrubbing, if it is set to 1, all potentially sensitive strings are replaced. If it is set to relay, all log messages generated when acting as a relay are sanitized, but - all messages generated when acting as a client are not. (Default: 1) + 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) [[User]] **User** __Username__:: On startup, setuid to this user and setgid to their primary group. @@ -1080,6 +1088,18 @@ The following options are useful only for clients (that is, if services can be configured to require authorization using the **HiddenServiceAuthorizeClient** option. +[[ClientOnionAuthDir]] **ClientOnionAuthDir** __path__:: + Path to the directory containing v3 hidden service authorization files. + Each file is for a single onion address, and the files MUST have the suffix + ".auth_private" (i.e. "bob_onion.auth_private"). The content format MUST be: + + + <onion-address>:descriptor:x25519:<base32-encoded-privkey> + + + The <onion-address> MUST NOT have the ".onion" suffix. The + <base32-encoded-privkey> is the base32 representation of the raw key bytes + only (32 bytes for x25519). See Appendix G in the rend-spec-v3.txt file of + https://spec.torproject.org/[torspec] for more information. + [[LongLivedPorts]] **LongLivedPorts** __PORTS__:: A list of ports for services that tend to have long-running connections (e.g. chat and interactive shells). Circuits for streams that use these @@ -1337,8 +1357,8 @@ The following options are useful only for clients (that is, if to stick with them. This is desirable because constantly changing servers increases the odds that an adversary who owns some servers will observe a fraction of your paths. Entry Guards can not be used by Directory - Authorities, Single Onion Services, and Tor2web clients. In these cases, - the this option is ignored. (Default: 1) + Authorities or Single Onion Services. In these cases, + this option is ignored. (Default: 1) [[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: V3 authoritative directories only. Configures the location of the @@ -1346,7 +1366,7 @@ The following options are useful only for clients (that is, if have been guards. (Default: unset) [[UseGuardFraction]] **UseGuardFraction** **0**|**1**|**auto**:: - This torrc option specifies whether clients should use the + This option specifies whether clients should use the guardfraction information found in the consensus during path selection. If it's set to 'auto', clients will do what the UseGuardFraction consensus parameter tells them to do. (Default: auto) @@ -1527,32 +1547,6 @@ The following options are useful only for clients (that is, if Tor will look at the UseOptimisticData parameter in the networkstatus. (Default: auto) -[[Tor2webMode]] **Tor2webMode** **0**|**1**:: - When this option is set, Tor connects to hidden services - **non-anonymously**. This option also disables client connections to - non-hidden-service hostnames through Tor. It **must only** be used when - running a tor2web Hidden Service web proxy. - To enable this option the compile time flag --enable-tor2web-mode must be - specified. Since Tor2webMode is non-anonymous, you can not run an - anonymous Hidden Service on a tor version compiled with Tor2webMode. - (Default: 0) - -[[Tor2webRendezvousPoints]] **Tor2webRendezvousPoints** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, country codes and - address patterns of nodes that are allowed to be used as RPs - in HS circuits; any other nodes will not be used as RPs. - (Example: - Tor2webRendezvousPoints Fastyfasty, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + - + - 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. + - + - If no nodes in Tor2webRendezvousPoints are currently available for - use, Tor will choose a random node when building HS circuits. - [[HSLayer2Nodes]] **HSLayer2Nodes** __node__,__node__,__...__:: A list of identity fingerprints, nicknames, country codes, and address patterns of nodes that are allowed to be used as the @@ -1733,9 +1727,10 @@ The following options are useful only for clients (that is, if [[ClientUseIPv6]] **ClientUseIPv6** **0**|**1**:: If this option is set to 1, Tor might connect to directory servers or - entry nodes over IPv6. Note that clients configured with an IPv6 address - in a **Bridge**, proxy, or pluggable transport line will try connecting - over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0) + entry nodes over IPv6. For IPv6 only hosts, you need to also set + **ClientUseIPv4** to 0 to disable IPv4. Note that clients configured with + an IPv6 address in a **Bridge**, proxy, or pluggable transportline will + try connecting over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0) [[ClientPreferIPv6DirPort]] **ClientPreferIPv6DirPort** **0**|**1**|**auto**:: If this option is set to 1, Tor prefers a directory port with an IPv6 @@ -1821,7 +1816,10 @@ is non-zero): Sets the relay to act as a "bridge" with respect to relaying connections from bridge users to the Tor network. It mainly causes Tor to publish a server descriptor to the bridge database, rather than - to the public directory authorities. + to the public directory authorities. + + + + Note: make sure that no MyFamily lines are present in your torrc when + relay is configured in bridge mode. [[BridgeDistribution]] **BridgeDistribution** __string__:: If set along with BridgeRelay, Tor will include a new line in its @@ -2078,7 +2076,10 @@ is non-zero): nickname: fingerprints are more reliable. + + If you run more than one relay, the MyFamily option on each relay - **must** list all other relays, as described above. + **must** list all other relays, as described above. + + + + Note: do not use MyFamily when configuring your Tor instance as a + brigde. [[Nickname]] **Nickname** __name__:: Set the server's nickname to \'name'. Nicknames must be between 1 and 19 @@ -2749,7 +2750,9 @@ on the public Tor network. [[V3BandwidthsFile]] **V3BandwidthsFile** __FILENAME__:: V3 authoritative directories only. Configures the location of the bandwidth-authority generated file storing information on relays' measured - bandwidth capacities. (Default: unset) + bandwidth capacities. To avoid inconsistent reads, bandwidth data should + be written to temporary file, then renamed to the configured filename. + (Default: unset) [[V3AuthUseLegacyKey]] **V3AuthUseLegacyKey** **0**|**1**:: If set, the directory authority will sign consensuses not only with its @@ -2814,7 +2817,7 @@ The following options are used to configure a hidden service. paths may be quoted, and may use standard C escapes.) You may also have multiple lines with the same VIRTPORT: when a user connects to that VIRTPORT, one of the TARGETs from those lines will be - chosen at random. + chosen at random. Note that address-port pairs have to be comma-separated. [[PublishHidServDescriptors]] **PublishHidServDescriptors** **0**|**1**:: If set to 0, Tor will run any hidden services you configure, but it won't @@ -2824,7 +2827,7 @@ The following options are used to configure a hidden service. [[HiddenServiceVersion]] **HiddenServiceVersion** **2**|**3**:: A list of rendezvous service descriptor versions to publish for the hidden - service. Currently, versions 2 and 3 are supported. (Default: 2) + service. Currently, versions 2 and 3 are supported. (Default: 3) [[HiddenServiceAuthorizeClient]] **HiddenServiceAuthorizeClient** __auth-type__ __client-name__,__client-name__,__...__:: If configured, the hidden service is accessible for authorized clients @@ -2837,7 +2840,8 @@ The following options are used to configure a hidden service. clients without authorization any more. Generated authorization data can be found in the hostname file. Clients need to put this authorization data in their configuration file using **HidServAuth**. This option is only for v2 - services. + services; v3 services configure client authentication in a subdirectory of + HiddenServiceDir instead (see the **Client Authorization** section). [[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**:: If set to 1, then connections to unrecognized ports do not cause the @@ -2845,6 +2849,33 @@ The following options are used to configure a hidden service. not an authorization mechanism; it is instead meant to be a mild inconvenience to port-scanners.) (Default: 0) +[[HiddenServiceExportCircuitID]] **HiddenServiceExportCircuitID** __protocol__:: + The onion service will use the given protocol to expose the global circuit + identifier of each inbound client circuit via the selected protocol. The only + protocol supported right now \'haproxy'. This option is only for v3 + services. (Default: none) + + + + The haproxy option works in the following way: when the feature is + enabled, the Tor process will write a header line when a client is connecting + to the onion service. The header will look like this: + + + + "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n" + + + + We encode the "global circuit identifier" as the last 32-bits of the first + IPv6 address. All other values in the header can safely be ignored. You can + compute the global circuit identifier using the following formula given the + IPv6 address "fc00:dead:beef:4dad::AABB:CCDD": + + + + global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) + 0xDD; + + + + In the case above, where the last 32-bit is 0xffffffff, the global circuit + identifier would be 4294967295. You can use this value together with Tor's + control port where it is possible to terminate a circuit given the global + circuit identifier. For more information about this see controls-spec.txt. + + + + The HAProxy version 1 proxy protocol is described in detail at + https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt + [[HiddenServiceMaxStreams]] **HiddenServiceMaxStreams** __N__:: The maximum number of simultaneous streams (connections) per rendezvous circuit. The maximum value allowed is 65535. (Setting this to 0 will allow @@ -2906,6 +2937,37 @@ The following options are used to configure a hidden service. including setting SOCKSPort to "0". Can not be changed while tor is running. (Default: 0) +Client Authorization +-------------------- + +(Version 3 only) + +To configure client authorization on the service side, the +"<HiddenServiceDir>/authorized_clients/" directory needs to exist. Each file +in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the +file name is irrelevant) and its content format MUST be: + + <auth-type>:<key-type>:<base32-encoded-public-key> + +The supported <auth-type> are: "descriptor". The supported <key-type> are: +"x25519". The <base32-encoded-privkey> is the base32 representation of the raw +key bytes only (32 bytes for x25519). + +Each file MUST contain one line only. Any malformed file will be +ignored. Client authorization will only be enabled for the service if tor +successfully loads at least one authorization file. + +Note that once you've configured client authorization, anyone else with the +address won't be able to access it from this point on. If no authorization is +configured, the service will be accessible to anyone with the onion address. + +Revoking a client can be done by removing their ".auth" file, however the +revocation will be in effect only after the tor process gets restarted even if +a SIGHUP takes place. + +See the Appendix G in the rend-spec-v3.txt file of +https://spec.torproject.org/[torspec] for more information. + TESTING NETWORK OPTIONS ----------------------- |