diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING | 39 | ||||
| -rw-r--r-- | doc/Makefile.am | 18 | ||||
| -rw-r--r-- | doc/nodefamily_routerset | 4 | ||||
| -rw-r--r-- | doc/tor.1.txt | 189 |
4 files changed, 179 insertions, 71 deletions
diff --git a/doc/HACKING b/doc/HACKING index 7ff9c5f3c2..bc409dc0d0 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -426,10 +426,10 @@ interesting and understandable. first entry or two and the last entry most interesting: they're the ones that skimmers tend to read. - 2.4) Clean them up + 2.4) Clean them up: Standard idioms: - "Fixes bug 9999; Bugfix on 0.3.3.3-alpha." + "Fixes bug 9999; bugfix on 0.3.3.3-alpha." One period after a space. @@ -446,6 +446,11 @@ interesting and understandable. Present and imperative tense: not past. + Try not to let any given section be longer than about a page. Break up + long sections into subsections by some sort of common subtopic. This + guideline is especially important when organizing Release Notes for + new stable releases. + If a given changes stanza showed up in a different release (e.g. maint-0.2.1), be sure to make the stanzas identical (so people can distinguish if these are the same change). @@ -456,7 +461,6 @@ interesting and understandable. 2.7) Run it through fmt to make it pretty. - 3) Compose a short release blurb to highlight the user-facing changes. Insert said release blurb into the ChangeLog stanza. If it's a stable release, add it to the ReleaseNotes file too. If we're adding @@ -469,18 +473,22 @@ git branches too. a while to see if anybody has problems building it. Try to get Sebastian or somebody to try building it on Windows. -6) Get at least two of weasel/arma/karsten to put the new version number +6) Get at least two of weasel/arma/sebastian to put the new version number in their approved versions list. -7) Sign and push the tarball to the website in the dist/ directory. Sign -and push the git tag. - (That's either "git tag -u <keyid> tor-0.2.x.y-status", then - "git push origin tag tor-0.2.x.y-status". To sign the - tarball, "gpg -ba <the_tarball>". Put the files in - /srv/www-master.torproject.org/htdocs/dist/ on vescum.) +7) Sign the tarball, then sign and push the git tag: + gpg -ba <the_tarball> + git tag -u <keyid> tor-0.2.x.y-status + git push origin tag tor-0.2.x.y-status + +8) scp the tarball and its sig to the website in the dist/ directory +(i.e. /srv/www-master.torproject.org/htdocs/dist/ on vescum). Edit +include/versions.wmi to note the new version. From your website checkout, +run ./publish to build and publish the website. -8) Edit include/versions.wmi to note the new version. From your website -checkout, run ./publish to build and publish the website. +Try not to delay too much between scp'ing the tarball and running +./publish -- the website has multiple A records and your scp only sent +it to one of them. 9) Email Erinn and weasel (cc'ing tor-assistants) that a new tarball is up. This step should probably change to mailing more packagers. @@ -492,9 +500,14 @@ box. By convention, we enter the version in the form "Tor: 0.2.2.23-alpha" (or whatever the version is), and we select the date as the date in the ChangeLog. -11) Wait up to a day or two (for a development release), or until most +11) Forward-port the ChangeLog. + +12) Update the topic in #tor to reflect the new version. + +12) Wait up to a day or two (for a development release), or until most packages are up (for a stable release), and mail the release blurb and changelog to tor-talk or tor-announce. (We might be moving to faster announcements, but don't announce until the website is at least updated.) + diff --git a/doc/Makefile.am b/doc/Makefile.am index 6cc0ea99fb..d8d9fbefc2 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -12,19 +12,21 @@ # part of the source distribution, so that people without asciidoc can # just use the .1 and .html files. +regular_mans = tor tor-gencert tor-resolve torify +all_mans = $(regular_mans) tor-fw-helper + if USE_ASCIIDOC if USE_FW_HELPER -asciidoc_files = tor tor-gencert tor-resolve torify tor-fw-helper +nodist_man_MANS = $(all_mans:=.1) +doc_DATA = $(all_mans:=.html) else -asciidoc_files = tor tor-gencert tor-resolve torify +nodist_man_MANS = $(regular_mans:=.1) +doc_DATA = $(regular_mans:=.html) endif -html_in = $(asciidoc_files:=.html.in) -man_in = $(asciidoc_files:=.1.in) -txt_in = $(asciidoc_files:=.1.txt) -nodist_man_MANS = $(asciidoc_files:=.1) -doc_DATA = $(asciidoc_files:=.html) +html_in = $(all_mans:=.html.in) +man_in = $(all_mans:=.1.in) +txt_in = $(all_mans:=.1.txt) else -asciidoc_files = html_in = man_in = txt_in = diff --git a/doc/nodefamily_routerset b/doc/nodefamily_routerset deleted file mode 100644 index 0af62e11f6..0000000000 --- a/doc/nodefamily_routerset +++ /dev/null @@ -1,4 +0,0 @@ - o Minor features - - The NodeFamily option -- which let you declare that you want to - consider nodes to be part of a family whether they list themselves - that way or not -- now allows IP address ranges and country codes. diff --git a/doc/tor.1.txt b/doc/tor.1.txt index c37c44c7bf..7f9bfbbf9a 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -110,6 +110,12 @@ Other options can be specified either on the command-line (--option 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) +**ClientTransportPlugin** __transport__ socks4|socks5 __IP__:__PORT__:: + When set along with a corresponding Bridge line, the Tor client + forwards its traffic to a SOCKS-speaking proxy on "IP:PORT". It's + the duty of that proxy to properly forward the traffic to the + bridge. + **ConnLimit** __NUM__:: The minimum number of file descriptors that must be available to the Tor process before it will start. Tor will ask the OS for as many file @@ -148,10 +154,11 @@ Other options can be specified either on the command-line (--option **ControlPort** __PORT__|**auto**:: If set, Tor will accept connections on this port and allow those connections to control the Tor process using the Tor Control Protocol - (described in control-spec.txt). Note: unless you also specify one of - **HashedControlPassword** or **CookieAuthentication**, setting this - option will - cause Tor to allow any process on the local host to control it. This + (described in control-spec.txt). Note: unless you also specify one or + more of **HashedControlPassword** or **CookieAuthentication**, + setting this option will cause Tor to allow any process on the local + host to control it. (Setting both authentication methods means either + method is sufficient to authenticate to Tor.) This option is required for many Tor controllers; most use the value of 9051. Set it to "auto" to have Tor pick a port for you. (Default: 0). @@ -173,15 +180,15 @@ Other options can be specified either on the command-line (--option the control socket readable and writable by the default GID. (Default: 0) **HashedControlPassword** __hashed_password__:: - Don't allow any connections on the control port except when the other - process knows the password whose one-way hash is __hashed_password__. You + Allow connections on the control port if they present + the password whose one-way hash is __hashed_password__. You can compute the hash of a password by running "tor --hash-password __password__". You can provide several acceptable passwords by using more than one HashedControlPassword line. **CookieAuthentication** **0**|**1**:: - If this option is set to 1, don't allow any connections on the control port - except when the connecting process knows the contents of a file named + If this option is set to 1, allow connections on the control port + when the connecting process knows the contents of a file named "control_auth_cookie", which Tor will create in its data directory. This authentication method should only be used on systems with good filesystem security. (Default: 0) @@ -478,7 +485,7 @@ CLIENT OPTIONS -------------- The following options are useful only for clients (that is, if -**SocksPort** is non-zero): +**SocksPort**, **TransPort**, **DNSPort**, or **NATDPort** is non-zero): **AllowInvalidNodes** **entry**|**exit**|**middle**|**introduction**|**rendezvous**|**...**:: If some Tor servers are obviously not working right, the directory @@ -496,13 +503,17 @@ The following options are useful only for clients (that is, if so using these relays might make your client stand out. (Default: 1) -**Bridge** __IP__:__ORPort__ [fingerprint]:: +**Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]:: When set along with UseBridges, instructs Tor to use the relay at "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint" is provided (using the same format as for DirServer), we will verify that 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 - it's provided and if UpdateBridgesFromAuthority is set too. + it's provided and if UpdateBridgesFromAuthority is set too. + + + + If "transport" is provided, and matches to a ClientTransportPlugin + line, we use that pluggable transports proxy to transfer data to + the bridge. **LearnCircuitBuildTimeout** **0**|**1**:: If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1) @@ -540,15 +551,15 @@ The following options are useful only for clients (that is, if A list of identity fingerprints, nicknames, country codes and address patterns of nodes to avoid when building a circuit. (Example: - ExcludeNodes SlowServer, $ EFFFFFFFFFFFFFFF, \{cc}, 255.254.0.0/8) + -+ + ExcludeNodes SlowServer, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + + By default, this option is treated as a preference that Tor is allowed to override in order to keep working. For example, if you try to connect to a hidden service, but you have excluded all of the hidden service's introduction points, Tor will connect to one of them anyway. If you do not want this behavior, set the StrictNodes option (documented below). + -+ + + Note also that if you are a relay, this (and the other node selection options below) only affects your own circuits that Tor builds for you. Clients can still build circuits through you to any node. Controllers @@ -566,22 +577,22 @@ The following options are useful only for clients (that is, if A list of identity fingerprints, nicknames, 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. + -+ + + Note that if you list too few nodes here, or if you exclude too many exit nodes with ExcludeExitNodes, you can degrade functionality. For example, if none of the exits you list allows traffic on port 80 or 443, you won't be able to browse the web. + -+ + + Note also that not every circuit is used to deliver traffic outside of the Tor network. It is normal to see non-exit circuits (such as those used to connect to hidden services, those that do directory fetches, those used for relay reachability self-tests, and so on) that end at a non-exit node. To keep a node from being used entirely, see ExcludeNodes and StrictNodes. + -+ + + The ExcludeNodes option overrides this option: any node listed in both ExitNodes and ExcludeNodes is treated as excluded. + -+ + + The .exit address notation, if enabled via AllowDotExit, overrides this option. @@ -592,7 +603,7 @@ The following options are useful only for clients (that is, if circuits except for direct connections to directory servers. The Bridge option overrides this option; if you have configured bridges and UseBridges is 1, the Bridges are used as your entry nodes. + -+ + + The ExcludeNodes option overrides this option: any node listed in both EntryNodes and ExcludeNodes is treated as excluded. @@ -665,7 +676,7 @@ The following options are useful only for clients (that is, if (e.g. chat and interactive shells). Circuits for streams that use these ports will contain only high-uptime nodes, to reduce the chance that a node will go down before the stream is finished. (Default: 21, 22, 706, 1863, - 5050, 5190, 5222, 5223, 6667, 6697, 8300) + 5050, 5190, 5222, 5223, 6523, 6667, 6697, 8300) **MapAddress** __address__ __newaddress__:: When a request for address arrives to Tor, it will rewrite it to newaddress @@ -696,17 +707,49 @@ The following options are useful only for clients (that is, if the same circuit. Currently, two addresses are "too close" if they lie in the same /16 range. (Default: 1) -**SocksPort** __PORT__|**auto**:: - Advertise this port to listen for connections from Socks-speaking +**SOCKSPort** \['address':]__port__|**auto** [_isolation flags_]:: + Open this port to listen for connections from SOCKS-speaking applications. Set this to 0 if you don't want to allow application connections via SOCKS. Set it to "auto" to have Tor pick a port for - you. (Default: 9050) - -**SocksListenAddress** __IP__[:__PORT__]:: + you. This directive can be specified multiple times to bind + to multiple addresses/ports. (Default: 9050) + + + + The _isolation flags_ arguments give Tor rules for which streams + received on this SOCKSPort are allowed to share circuits with one + another. Recognized isolation flags are: + **IsolateClientAddr**;; + Don't share circuits with streams from a different + client address. (On by default and strongly recommended; + you can disable it with **NoIsolateClientAddr**.) + **IsolateSOCKSAuth**;; + Don't share circuits with streams for which different + SOCKS authentication was provided. (On by default; + you can disable it with **NoIsolateSOCKSAuth**.) + **IsolateClientProtocol**;; + Don't share circuits with streams using a different protocol. + (SOCKS 4, SOCKS 5, TransPort connections, NATDPort connections, + and DNSPort requests are all considered to be different protocols.) + **IsolateDestPort**;; + Don't share circuits with streams targetting a different + destination port. + **IsolateDestAddr**;; + Don't share circuits with streams targetting a different + destination address. + **SessionGroup=**__INT__;; + If no other isolation rules would prevent it, allow streams + on this port to share circuits with streams from every other + port with the same session group. (By default, streams received + on different ports are always isolated from one another.) + +**SOCKSListenAddress** __IP__[:__PORT__]:: Bind to this address to listen for connections from Socks-speaking applications. (Default: 127.0.0.1) You can also specify a port (e.g. 192.168.0.1:9100). This directive can be specified multiple times to bind - to multiple addresses/ports. + to multiple addresses/ports. (DEPRECATED: As of 0.2.3.x-alpha, you can + now use multiple SOCKSPort entries, and provide addresses for SOCKSPort + entries, so SOCKSListenAddress no longer has a purpose. For backward + compatibility, SOCKSListenAddress is only allowed when SOCKSPort is just + a port number.) **SocksPolicy** __policy__,__policy__,__...__:: Set an entrance policy for this server, to limit who can connect to the @@ -718,6 +761,13 @@ The following options are useful only for clients (that is, if unattached waiting for an appropriate circuit, before we fail it. (Default: 2 minutes.) +**TokenBucketRefillInterval** __NUM__ [**msec**|**second**]:: + Set the refill interval of Tor's token bucket to NUM milliseconds. + 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.) + **TrackHostExits** __host__,__.domain__,__...__:: For each value in the comma separated list, Tor will track recent connections to hosts that match this value and attempt to reuse the same @@ -809,28 +859,44 @@ The following options are useful only for clients (that is, if operating as a relay, and it will never use the public key step if it doesn't yet know the onion key of the first hop. (Default: 1) -**TransPort** __PORT__|**auto**:: - If non-zero, enables transparent proxy support on __PORT__ (by convention, - 9040). Requires OS support for transparent proxies, such as BSDs' pf or +**TransPort** \['address':]__port__|**auto** [_isolation flags_]:: + Open this port to listen for transparent proxy connections. Set this to + 0 if you don't want to allow transparent proxy connections. Set the port + to "auto" to have Tor pick a port for you. This directive can be + specified multiple times to bind to multiple addresses/ports. See + SOCKSPort for an explanation of isolation flags. + + + + TransPort requires OS support for transparent proxies, such as BSDs' pf or Linux's IPTables. If you're planning to use Tor as a transparent proxy for a network, you'll want to examine and change VirtualAddrNetwork from the default setting. You'll also want to set the TransListenAddress option for - the network you'd like to proxy. Set it to "auto" to have Tor pick a - port for you. (Default: 0). + the network you'd like to proxy. (Default: 0). **TransListenAddress** __IP__[:__PORT__]:: Bind to this address to listen for transparent proxy connections. (Default: 127.0.0.1). This is useful for exporting a transparent proxy server to an - entire network. - -**NATDPort** __PORT__|**auto**:: - Allow old versions of ipfw (as included in old versions of FreeBSD, etc.) - to send connections through Tor using the NATD protocol. This option is - only for people who cannot use TransPort. Set it to "auto" to have Tor - pick a port for you. (Default: 0) + entire network. (DEPRECATED: As of 0.2.3.x-alpha, you can + now use multiple TransPort entries, and provide addresses for TransPort + entries, so TransListenAddress no longer has a purpose. For backward + compatibility, TransListenAddress is only allowed when TransPort is just + a port number.) + +**NATDPort** \['address':]__port__|**auto** [_isolation flags_]:: + Open this port to listen for connections from old versions of ipfw (as + included in old versions of FreeBSD, etc) using the NATD protocol. + Use 0 if you don't want to allow NATD connections. Set the port + to "auto" to have Tor pick a port for you. This directive can be + specified multiple times to bind to multiple addresses/ports. See + SOCKSPort for an explanation of isolation flags. + + + + This option is only for people who cannot use TransPort. (Default: 0) **NATDListenAddress** __IP__[:__PORT__]:: - Bind to this address to listen for NATD connections. (Default: 127.0.0.1). + Bind to this address to listen for NATD connections. (DEPRECATED: As of + 0.2.3.x-alpha, you can now use multiple NATDPort entries, and provide + addresses for NATDPort entries, so NATDListenAddress no longer has a + purpose. For backward compatibility, NATDListenAddress is only allowed + when NATDPort is just a port number.) **AutomapHostsOnResolve** **0**|**1**:: When this option is enabled, and we get a request to resolve an address @@ -843,13 +909,19 @@ The following options are useful only for clients (that is, if A comma-separated list of suffixes to use with **AutomapHostsOnResolve**. The "." suffix is equivalent to "all addresses." (Default: .exit,.onion). -**DNSPort** __PORT__|**auto**:: - If non-zero, Tor listens for UDP DNS requests on this port and resolves - them anonymously. Set it to "auto" to have Tor pick a port for - you. (Default: 0). +**DNSPort** \['address':]__port__|**auto** [_isolation flags_]:: + If non-zero, open this port to listen for UDP DNS requests, and resolve + them anonymously. Set the port to "auto" to have Tor pick a port for + you. This directive can be specified multiple times to bind to multiple + addresses/ports. See SOCKSPort for an explanation of isolation + flags. (Default: 0). **DNSListenAddress** __IP__[:__PORT__]:: - Bind to this address to listen for DNS connections. (Default: 127.0.0.1). + Bind to this address to listen for DNS connections. (DEPRECATED: As of + 0.2.3.x-alpha, you can now use multiple DNSPort entries, and provide + addresses for DNSPort entries, so DNSListenAddress no longer has a + purpose. For backward compatibility, DNSListenAddress is only allowed + when DNSPort is just a port number.) **ClientDNSRejectInternalAddresses** **0**|**1**:: If true, Tor does not believe any anonymously retrieved DNS answer that @@ -890,6 +962,16 @@ The following options are useful only for clients (that is, if that have the **AllowSingleHopExits** option turned on to build one-hop Tor connections. (Default: 0) +**OptimisticData** **0**|**1**|**auto**:: + When this option is set, and Tor is using an exit node that supports + the feature, it will try optimistically to send data to the exit node + without waiting for the exit node to report whether the connection + succeeded. This can save a round-trip time for protocols like HTTP + where the client talks first. If OptimisticData is set to **auto**, + Tor will look at the UseOptimisticData parameter in the networkstatus. + (Default: auto) + + SERVER OPTIONS -------------- @@ -1234,7 +1316,7 @@ if DirPort is non-zero): **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: Minimum uptime of a v2 hidden service directory to be accepted as such by - authoritative directories. (Default: 24 hours) + authoritative directories. (Default: 25 hours) **DirPort** __PORT__|**auto**:: If this option is nonzero, advertise the directory service on this port. @@ -1338,6 +1420,16 @@ DIRECTORY AUTHORITY SERVER OPTIONS Authoritative directories only. Like AuthDirMaxServersPerAddr, but applies to addresses shared with directory authorities. (Default: 5) +**AuthDirFastGuarantee** __N__ **bytes**|**KB**|**MB**|**GB**:: + Authoritative directories only. If non-zero, always vote the + Fast flag for any relay advertising this amount of capacity or + more. (Default: 100 KB) + +**AuthDirGuardBWGuarantee** __N__ **bytes**|**KB**|**MB**|**GB**:: + 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 KB) + **BridgePassword** __Password__:: If set, contains an HTTP authenticator that tells a bridge authority to serve all requested bridge information. Used for debugging. (Default: @@ -1386,6 +1478,11 @@ DIRECTORY AUTHORITY SERVER OPTIONS that fine-grained information about nodes can be discarded when it hasn't changed for a given amount of time. (Default: 24 hours) +**VoteOnHidServDirectoriesV2** **0**|**1**:: + When this option is set in addition to **AuthoritativeDirectory**, Tor + votes on whether to accept relays as hidden service directories. + (Default: 1) + HIDDEN SERVICE OPTIONS ---------------------- @@ -1394,7 +1491,7 @@ The following options are used to configure a hidden service. **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. + specify multiple services. DIRECTORY must be an existing directory. **HiddenServicePort** __VIRTPORT__ [__TARGET__]:: Configure a virtual port VIRTPORT for a hidden service. You may use this |