diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING | 40 | ||||
| -rw-r--r-- | doc/include.am | 10 | ||||
| -rw-r--r-- | doc/tor.1.txt | 156 |
3 files changed, 161 insertions, 45 deletions
diff --git a/doc/HACKING b/doc/HACKING index b7cd8952d..a0072ec53 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -118,25 +118,29 @@ Running gcov for unit test coverage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----- - make clean - make CFLAGS='-g -fprofile-arcs -ftest-coverage' - ./src/test/test - gcov -o src/common src/common/*.[ch] - gcov -o src/or src/or/*.[ch] - cd ../or; gcov *.[ch] + ./configure --enable-coverage + make + ./src/test/test + mkdir coverage-output + ./contrib/coverage coverage-output ----- -Then, look at the .gcov files. '-' before a line means that the -compiler generated no code for that line. '######' means that the -line was never reached. Lines with numbers were called that number -of times. +(On OSX, you'll need to start with "--enable-coverage CC=clang".) + +Then, look at the .gcov files in coverage-output. '-' before a line means +that the compiler generated no code for that line. '######' means that the +line was never reached. Lines with numbers were called that number of times. If that doesn't work: * Try configuring Tor with --disable-gcc-hardening - * On recent OSX versions, you might need to add CC=clang to your - build line, as in: - make CFLAGS='-g -fprofile-arcs -ftest-coverage' CC=clang - Their llvm-gcc doesn't work so great for me. + * You might need to run 'make clean' after you run './configure'. + +Running integration tests +~~~~~~~~~~~~~~~~~~~~~~~~~ + +We have the beginnings of a set of scripts to run integration tests using +Chutney. To try them, set CHUTNEY_PATH to your chutney source directory, and +run "make test-network". Profiling Tor with oprofile ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -493,12 +497,8 @@ in their approved versions list. 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. - -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. +"include/versions.wmi" and "Makefile" to note the new version. From your +website checkout, run ./publish to build and publish the website. 9) Email Erinn and weasel (cc'ing tor-assistants) that a new tarball is up. This step should probably change to mailing more packagers. diff --git a/doc/include.am b/doc/include.am index 9695292bd..37c0237a0 100644 --- a/doc/include.am +++ b/doc/include.am @@ -12,8 +12,8 @@ # part of the source distribution, so that people without asciidoc can # just use the .1 and .html files. -regular_mans = doc/tor doc/tor-gencert doc/tor-resolve doc/torify -all_mans = $(regular_mans) doc/tor-fw-helper +regular_mans = doc/tor doc/tor-gencert doc/tor-resolve +all_mans = $(regular_mans) doc/torify doc/tor-fw-helper if USE_ASCIIDOC if USE_FW_HELPER @@ -55,13 +55,11 @@ $(man_in) : doc/tor.1.in: doc/tor.1.txt doc/tor-gencert.1.in: doc/tor-gencert.1.txt doc/tor-resolve.1.in: doc/tor-resolve.1.txt -doc/torify.1.in: doc/torify.1.txt doc/tor-fw-helper.1.in: doc/tor-fw-helper.1.txt doc/tor.html.in: doc/tor.1.txt doc/tor-gencert.html.in: doc/tor-gencert.1.txt doc/tor-resolve.html.in: doc/tor-resolve.1.txt -doc/torify.html.in: doc/torify.1.txt doc/tor-fw-helper.html.in: doc/tor-fw-helper.1.txt # use ../config.status to swap all machine-specific magic strings @@ -76,13 +74,13 @@ $(asciidoc_product) : doc/tor.html: doc/tor.html.in doc/tor-gencert.html: doc/tor-gencert.html.in doc/tor-resolve.html: doc/tor-resolve.html.in -doc/torify.html: doc/torify.html.in +doc/torify.html: doc/torify.1.txt doc/tor-fw-helper.html: doc/tor-fw-helper.html.in doc/tor.1: doc/tor.1.in doc/tor-gencert.1: doc/tor-gencert.1.in doc/tor-resolve.1: doc/tor-resolve.1.in -doc/torify.1: doc/torify.1.in +doc/torify.1: doc/torify.1.txt doc/tor-fw-helper.1: doc/tor-fw-helper.1.in CLEANFILES+= $(asciidoc_product) config.log diff --git a/doc/tor.1.txt b/doc/tor.1.txt index b9ee29614..5dc17b5f3 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -18,18 +18,23 @@ SYNOPSIS DESCRIPTION ----------- -__tor__ is a connection-oriented anonymizing communication +Tor is a connection-oriented anonymizing communication service. Users choose a source-routed path through a set of nodes, and negotiate a "virtual circuit" through the network, in which each node knows its predecessor and successor, but no others. Traffic flowing down the circuit is unwrapped by a symmetric key at each node, which reveals the downstream node. + -Basically __tor__ provides a distributed network of servers ("onion routers"). -Users bounce their TCP streams -- web traffic, ftp, ssh, etc -- around the -routers, and recipients, observers, and even the routers themselves have +Basically, Tor provides a distributed network of servers or relays ("onion routers"). +Users bounce their TCP streams -- web traffic, ftp, ssh, etc. -- around the +network, and recipients, observers, and even the relays themselves have difficulty tracking the source of the stream. +By default, **tor** will only act as a client only. To help the network +by providing bandwidth as a relay, change the **ORPort** configuration +option -- see below. Please also consult the documentation on the Tor +Project's website. + COMMAND-LINE OPTIONS -------------------- [[opt-h]] **-h**, **-help**:: @@ -46,7 +51,7 @@ COMMAND-LINE OPTIONS configuration file, and by those on the command line. (Default: @CONFDIR@/torrc-defaults.) -[[opt-hash-password]] **--hash-password**:: +[[opt-hash-password]] **--hash-password** __PASSWORD__:: Generates a hashed password for control port access. [[opt-list-fingerprint]] **--list-fingerprint**:: @@ -124,42 +129,42 @@ option name with a forward slash. GENERAL OPTIONS --------------- -[[BandwidthRate]] **BandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: +[[BandwidthRate]] **BandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: A token bucket limits the average incoming bandwidth usage on this node to the specified number of bytes per second, and the average outgoing bandwidth usage to that same value. If you want to run a relay in the public network, this needs to be _at the very least_ 30 KBytes (that is, 30720 bytes). (Default: 1 GByte) -[[BandwidthBurst]] **BandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: +[[BandwidthBurst]] **BandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: 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**:: +[[MaxAdvertisedBandwidth]] **MaxAdvertisedBandwidth** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: 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**:: +[[RelayBandwidthRate]] **RelayBandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: 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**:: +[[RelayBandwidthBurst]] **RelayBandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: 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**:: +[[PerConnBWRate]] **PerConnBWRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: 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**:: +[[PerConnBWBurst]] **PerConnBWBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: 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) @@ -186,6 +191,20 @@ GENERAL OPTIONS listening address of any pluggable transport proxy that tries to launch __transport__. +[[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) + +[[ExtORPort]] **ExtORPort** \['address':]__port__|**auto** + Open this port to listen for Extended ORPort connections from your + pluggable transports. + +[[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. + [[ConnLimit]] **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 @@ -197,7 +216,8 @@ GENERAL OPTIONS [[DisableNetwork]] **DisableNetwork** **0**|**1**:: When this option is set, we don't listen for or accept any connections - other than controller connections, and we don't make any outbound + 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. (Default: 0) @@ -424,6 +444,11 @@ GENERAL OPTIONS proxy authentication that Tor supports; feel free to submit a patch if you want it to support others. +[[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) + [[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). @@ -1256,9 +1281,9 @@ The following options are useful only for clients (that is, if it too early might make your client stand out. If this option is 0, your Tor client won't use the ntor handshake. If it's 1, your Tor client will use the ntor handshake to extend circuits through servers that - support it. If this option is "auto" (recommended), then your client + support it. If this option is "auto", then your client will use the ntor handshake once enough directory authorities recommend - it. (Default: auto) + it. (Default: 1) [[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ + @@ -1548,7 +1573,7 @@ is non-zero): server is still alive and doing useful things. Settings this to 0 will disable the heartbeat. (Default: 6 hours) -[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**:: +[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**|**TBytes**:: Never send more than the specified number of bytes in a given accounting period, or receive more than that number in the period. For example, with AccountingMax set to 1 GByte, a server could send 900 MBytes and @@ -1880,12 +1905,12 @@ DIRECTORY AUTHORITY SERVER OPTIONS Authoritative directories only. Like AuthDirMaxServersPerAddr, but applies to addresses shared with directory authorities. (Default: 5) -[[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: +[[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: 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**:: +[[AuthDirGuardBWGuarantee]] **AuthDirGuardBWGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: 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) @@ -2030,6 +2055,20 @@ The following options are used for running a testing Tor network. TestingV3AuthInitialDistDelay 20 seconds TestingAuthDirTimeToLearnReachability 0 minutes TestingEstimatedDescriptorPropagationTime 0 minutes + TestingServerDownloadSchedule 0, 0, 0, 5, 10, 15, 20, 30, 60 + TestingClientDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60 + TestingServerConsensusDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60 + TestingClientConsensusDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60 + TestingBridgeDownloadSchedule 60, 30, 30, 60 + TestingClientMaxIntervalWithoutRequest 5 seconds + TestingDirConnectionMaxStall 30 seconds + TestingConsensusMaxDownloadTries 80 + TestingDescriptorMaxDownloadTries 80 + TestingMicrodescMaxDownloadTries 80 + TestingCertMaxDownloadTries 80 + TestingEnableConnBwEvent 1 + TestingEnableCellStatsEvent 1 + TestingEnableTbEmptyEvent 1 [[TestingV3AuthInitialVotingInterval]] **TestingV3AuthInitialVotingInterval** __N__ **minutes**|**hours**:: Like V3AuthVotingInterval, but for initial voting interval before the first @@ -2046,6 +2085,10 @@ The following options are used for running a testing Tor network. the first consensus has been created. Changing this requires that **TestingTorNetwork** is set. (Default: 5 minutes) +[[TestingV3AuthVotingStartOffset]] **TestingV3AuthVotingStartOffset** __N__ **seconds**|**minutes**|**hours**:: + Directory authorities offset voting start time by this much. + Changing this requires that **TestingTorNetwork** is set. (Default: 0) + [[TestingAuthDirTimeToLearnReachability]] **TestingAuthDirTimeToLearnReachability** __N__ **minutes**|**hours**:: After starting as an authority, do not make claims about whether routers are Running until this much time has passed. Changing this requires @@ -2056,10 +2099,85 @@ 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**:: +[[TestingMinFastFlagThreshold]] **TestingMinFastFlagThreshold** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**KBits**|**MBits**|**GBits**:: Minimum value for the Fast flag. Overrides the ordinary minimum taken from the consensus when TestingTorNetwork is set. (Default: 0.) +[[TestingServerDownloadSchedule]] **TestingServerDownloadSchedule** __N__,__N__,__...__:: + Schedule for when servers should download things in general. Changing this + requires that **TestingTorNetwork** is set. (Default: 0, 0, 0, 60, 60, 120, + 300, 900, 2147483647) + +[[TestingClientDownloadSchedule]] **TestingClientDownloadSchedule** __N__,__N__,__...__:: + Schedule for when clients should download things in general. Changing this + requires that **TestingTorNetwork** is set. (Default: 0, 0, 60, 300, 600, + 2147483647) + +[[TestingServerConsensusDownloadSchedule]] **TestingServerConsensusDownloadSchedule** __N__,__N__,__...__:: + Schedule for when servers should download consensuses. Changing this + requires that **TestingTorNetwork** is set. (Default: 0, 0, 60, 300, 600, + 1800, 1800, 1800, 1800, 1800, 3600, 7200) + +[[TestingClientConsensusDownloadSchedule]] **TestingClientConsensusDownloadSchedule** __N__,__N__,__...__:: + Schedule for when clients should download consensuses. Changing this + requires that **TestingTorNetwork** is set. (Default: 0, 0, 60, 300, 600, + 1800, 3600, 3600, 3600, 10800, 21600, 43200) + +[[TestingBridgeDownloadSchedule]] **TestingBridgeDownloadSchedule** __N__,__N__,__...__:: + Schedule for when clients should download bridge descriptors. Changing this + requires that **TestingTorNetwork** is set. (Default: 3600, 900, 900, 3600) + +[[TestingClientMaxIntervalWithoutRequest]] **TestingClientMaxIntervalWithoutRequest** __N__ **seconds**|**minutes**:: + When directory clients have only a few descriptors to request, they batch + them until they have more, or until this amount of time has passed. + Changing this requires that **TestingTorNetwork** is set. (Default: 10 + minutes) + +[[TestingDirConnectionMaxStall]] **TestingDirConnectionMaxStall** __N__ **seconds**|**minutes**:: + Let a directory connection stall this long before expiring it. + Changing this requires that **TestingTorNetwork** is set. (Default: + 5 minutes) + +[[TestingConsensusMaxDownloadTries]] **TestingConsensusMaxDownloadTries** __NUM__:: + Try this often to download a consensus before giving up. Changing + this requires that **TestingTorNetwork** is set. (Default: 8) + +[[TestingDescriptorMaxDownloadTries]] **TestingDescriptorMaxDownloadTries** __NUM__:: + Try this often to download a router descriptor before giving up. + Changing this requires that **TestingTorNetwork** is set. (Default: 8) + +[[TestingMicrodescMaxDownloadTries]] **TestingMicrodescMaxDownloadTries** __NUM__:: + Try this often to download a microdesc descriptor before giving up. + Changing this requires that **TestingTorNetwork** is set. (Default: 8) + +[[TestingCertMaxDownloadTries]] **TestingCertMaxDownloadTries** __NUM__:: + Try this often to download a v3 authority certificate before giving up. + Changing this requires that **TestingTorNetwork** is set. (Default: 8) + +**TestingDirAuthVoteGuard** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, 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. + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + +[[TestingEnableConnBwEvent]] **TestingEnableConnBwEvent** **0**|**1**:: + If this option is set, then Tor controllers may register for CONN_BW + events. Changing this requires that **TestingTorNetwork** is set. + (Default: 0) + +[[TestingEnableCellStatsEvent]] **TestingEnableCellStatsEvent** **0**|**1**:: + If this option is set, then Tor controllers may register for CELL_STATS + events. Changing this requires that **TestingTorNetwork** is set. + (Default: 0) + +[[TestingEnableTbEmptyEvent]] **TestingEnableTbEmptyEvent** **0**|**1**:: + If this option is set, then Tor controllers may register for TB_EMPTY + events. Changing this requires that **TestingTorNetwork** is set. + (Default: 0) + SIGNALS ------- |