diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING | 33 | ||||
| -rw-r--r-- | doc/TUNING | 47 | ||||
| -rw-r--r-- | doc/building-tor-msvc.txt | 122 | ||||
| -rw-r--r-- | doc/tor.1.txt | 111 |
4 files changed, 246 insertions, 67 deletions
diff --git a/doc/HACKING b/doc/HACKING index 6b21426497..5c71b74bd1 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -134,6 +134,27 @@ output directory, use `make coverage-html HTML_COVER_DIR=./funky_new_cov_dir`. Coverage diffs using lcov are not currently implemented, but are being investigated (as of July 2014). +Running the unit tests +~~~~~~~~~~~~~~~~~~~~~~ + +To quickly run all tests: +----- + make check +----- + +To run unit tests only: +----- + make test +----- + +To selectively run just some tests (the following can be combined +arbitrarily): +----- + ./src/test/test <name_of_test> [<name of test 2>] ... + ./src/test/test <prefix_of_name_of_test>.. [<prefix_of_name_of_test2>..] ... + ./src/test/test :<name_of_excluded_test> [:<name_of_excluded_test2]... +----- + Running gcov for unit test coverage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -512,7 +533,7 @@ interesting and understandable. 2.6) Clean everything one last time. - 2.7) Run it through fmt to make it pretty. + 2.7) Run ./scripts/maint/format_changelog.py to make it prettier. 3) Compose a short release blurb to highlight the user-facing changes. Insert said release blurb into the ChangeLog stanza. If it's @@ -534,10 +555,12 @@ in their approved versions list. 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" and "Makefile" to note the new version. From your -website checkout, run ./publish to build and publish the website. +8a) scp the tarball and its sig to the dist website, i.e. +/srv/dist-master.torproject.org/htdocs/ on dist-master. When you want +it to go live, you run "static-update-component dist.torproject.org" +on dist-master. + +8b) Edit "include/versions.wmi" and "Makefile" to note the new version. 9) Email the packagers (cc'ing tor-assistants) that a new tarball is up. diff --git a/doc/TUNING b/doc/TUNING new file mode 100644 index 0000000000..a4bf386dd6 --- /dev/null +++ b/doc/TUNING @@ -0,0 +1,47 @@ +Most operating systems limit an amount of TCP sockets that can be used +simultaneously. It is possible for a busy Tor relay to run into these +limits, thus being unable to fully utilize the bandwidth resources it +has at its disposal. Following system-specific tips might be helpful +to alleviate the aforementioned problem. + +Linux +----- + +Use 'ulimit -n' to raise an allowed number of file descriptors to be +opened on your host at the same time. + +FreeBSD +------- + +Tune the followind sysctl(8) variables: + * kern.maxfiles - maximum allowed file descriptors (for entire system) + * kern.maxfilesperproc - maximum file descriptors one process is allowed + to use + * kern.ipc.maxsockets - overall maximum numbers of sockets for entire + system + * kern.ipc.somaxconn - size of listen queue for incoming TCP connections + for entire system + +See also: + * https://www.freebsd.org/doc/handbook/configtuning-kernel-limits.html + * https://wiki.freebsd.org/NetworkPerformanceTuning + +Mac OS X +-------- + +Since Mac OS X is BSD-based system, most of the above hold for OS X as well. +However, launchd(8) is known to modify kern.maxfiles and kern.maxfilesperproc +when it launches tor service (see launchd.plist(5) manpage). Also, +kern.ipc.maxsockets is determined dynamically by the system and thus is +read-only on OS X. + +Disclaimer +---------- + +Do note that this document is a draft and above information may be +technically incorrect and/or incomplete. If so, please open a ticket +on https://trac.torproject.org or post to tor-relays mailing list. + +Are you running a busy Tor relay? Let us know how you are solving +the out-of-sockets problem on your system. + diff --git a/doc/building-tor-msvc.txt b/doc/building-tor-msvc.txt new file mode 100644 index 0000000000..3d3eced8af --- /dev/null +++ b/doc/building-tor-msvc.txt @@ -0,0 +1,122 @@ +Building Tor with MSVC.
+=======================
+
+NOTE: This is not the preferred method for building Tor on windows: we use
+mingw for our packages.
+
+Last updated 9 September 2014.
+
+
+Requirements:
+-------------
+
+ * Visual Studio 2010
+ http://go.microsoft.com/fwlink/?LinkId=323467
+ * CMake 2.8.12.2
+ http://www.cmake.org/download/
+ * Perl 5.16
+ http://www.activestate.com/activeperl/downloads
+ * Latest stable OpenSSL tarball
+ https://www.openssl.org/source/
+ * Latest stable zlib tarball
+ http://zlib.net/
+ * Latest stable libevent Libevent tarball
+ https://github.com/libevent/libevent/releases
+
+Make sure you check signatures for all these packages.
+
+Steps:
+------
+
+Building OpenSSL from source as a shared library:
+
+ cd <openssl source dir>
+ perl Configure VC-WIN32
+ perl util\mkfiles.pl >MINFO
+ perl util\mk1mf.pl no-asm dll VC-WIN32 >32dll.mak
+ perl util\mkdef.pl 32 libeay > ms\libeay32.def
+ perl util\mkdef.pl 32 ssleay > ms\ssleay32.def
+ nmake -f 32dll.mak
+
+Making OpenSSL final package:
+
+ Create <openssl final package dir>, I'd recommend using a name like <openssl
+ source dir>-vc10.
+
+ Copy the following directories and files to their respective locations
+ <openssl source dir>\inc32\openssl => <openssl final package dir>\include\openssl
+ <openssl source dir>\out32dll\libeay32.lib => <openssl final package dir>\lib\libeay32.lib
+ <openssl source dir>\out32dll\ssleay32.lib => <openssl final package dir>\lib\ssleay32.lib
+ <openssl source dir>\out32dll\libeay32.dll => <openssl final package dir>\bin\libeay32.dll
+ <openssl source dir>\out32dll\openssl.exe => <openssl final package dir>\bin\openssl.exe
+ <openssl source dir>\out32dll\ssleay32.dll => <openssl final package dir>\bin\ssleay32.dll
+
+Building Zlib from source:
+
+ cd <zlib source dir>
+ nmake -f win32/Makefile.msc
+
+Building libevent:
+
+ cd <libevent source dir>
+ mkdir build && cd build
+ SET OPENSSL_ROOT_DIR=<openssl final package dir>
+ cmake -G "NMake Makefiles" .. -DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo -DCMAKE_C_FLAGS_RELWITHDEBINFO:STRING="/MT /Zi /O2 /Ob1 /D NDEBUG" -DZLIB_LIBRARY:FILEPATH="<zlib source dir>\zdll.lib" -DZLIB_INCLUDE_DIR:PATH="<zlib source dir>"
+ nmake event
+
+Building Tor:
+
+ Create a dir above tor source dir named build-alpha and two subdirs include
+ and lib.
+
+ Your build tree should now be similar to this one:
+ * build-alpha
+ - include
+ - lib
+ * <libevent source dir>
+ - build
+ - cmake
+ - ...
+ * <openssl source dir>
+ - ...
+ - ms
+ - util
+ - ...
+ * <openssl final package dir>
+ - bin
+ - include
+ - lib
+ * <tor source dir>
+ - ...
+ - src
+ - ...
+ * <zlib source dir>
+ - ...
+ - win32
+ - ...
+
+ Copy the following dirs and files to the following locations:
+ <openssl final package dir>\include\openssl => build-alpha\include\openssl
+ <libevent source dir>\include => build-alpha\include
+ <libevent source dir>\WIN32-Code\nmake\event2 => build-alpha\include\event2
+ <zlib source dir>\z*.h => build-alpha\include\z*.h
+
+ Now copy the following files to the following locations and rename them
+ according new names:
+
+ <libevent source dir>\build\lib\event.lib => build-alpha\lib\libevent.lib
+ <openssl final package dir>\lib\libeay32.lib => build-alpha\lib\libcrypto.lib
+ <openssl final package dir>\lib\ssleay32.lib => build-alpha\lib\libssl.lib
+ <zlib source dir>\zdll.lib => build-alpha\lib\libz.lib
+
+ And we are now ready for the build process:
+
+ cd <tor source dir>
+ nmake -f Makefile.nmake
+
+ After the above process is completed there should be a tor.exe in <tor
+ source dir>\src\or
+
+ Copy tor.exe to desired location and also copy zlib1.dll, libeay32.dll and
+ ssleay32.dll from built zlib and openssl packages
+
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 25a602ee16..84070da8ef 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -72,7 +72,7 @@ COMMAND-LINE OPTIONS [[opt-serviceinstall]] **--service install** [**--options** __command-line options__]:: Install an instance of Tor as a Windows service, with the provided command-line options. Current instructions can be found at - https://trac.torproject.org/projects/tor/wiki/doc/TorFAQ#HowdoIrunmyTorrelayasanNTservice + https://www.torproject.org/docs/faq#NTService [[opt-service]] **--service** **remove**|**start**|**stop**:: Remove, start, or stop a configured Tor Windows service. @@ -964,10 +964,10 @@ The following options are useful only for clients (that is, if (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 + Don't share circuits with streams targeting a different destination port. **IsolateDestAddr**;; - Don't share circuits with streams targetting a different + Don't share circuits with streams targeting a different destination address. **SessionGroup=**__INT__;; If no other isolation rules would prevent it, allow streams @@ -1018,7 +1018,7 @@ The following options are useful only for clients (that is, if requests via this connection. **PreferIPv6Automap**;; When serving a hostname lookup request on this port that - should get automapped (according to AutomapHostsOnResove), + should get automapped (according to AutomapHostsOnResolve), if we could return either an IPv4 or an IPv6 answer, prefer an IPv6 answer. (On by default.) **PreferSOCKSNoAuth**;; @@ -1425,7 +1425,7 @@ The following options are useful only for clients (that is, if whose view of the current time is skewed. If this option is set to 0, we do not send this timestamp, and hidden services on obsolete Tor versions will not work. If this option is set to 1, we send the timestamp. If - this optoin is "auto", we take a recommendation from the latest consensus + this option is "auto", we take a recommendation from the latest consensus document. (Default: auto) @@ -1497,6 +1497,11 @@ is non-zero): public (external) IP address. See RFC 1918 and RFC 3330 for more details about internal and reserved IP address space. + + + Tor also allow IPv6 exit policy entries. For instance, "reject6 [FC00::]/7:*" + rejects all destinations that share 7 most significant bit prefix with + address FC00::. Respectively, "accept6 [C000::]/3:*" accepts all destinations + that share 3 most significant bit prefix with address C000::. + + + This directive can be specified multiple times so you don't have to put it all on one line. + + @@ -1630,19 +1635,31 @@ is non-zero): to 0 will disable the heartbeat. (Default: 6 hours) [[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 - receive 800 MBytes and continue running. It will only hibernate once - one of the two reaches 1 GByte. When the number of bytes gets low, - Tor will stop accepting new connections and circuits. When the - number of bytes is exhausted, Tor will hibernate until some - time in the next accounting period. To prevent all servers from waking at - the same time, Tor will also wait until a random point in each period - before waking up. If you have bandwidth cost issues, enabling hibernation - is preferable to setting a low bandwidth, since it provides users with a - collection of fast servers that are up some of the time, which is more - useful than a set of slow servers that are always "available". + 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 + number used for calculation is the max of either the bytes sent or + received. For example, with AccountingMax set to 1 GByte, a server + could send 900 MBytes and receive 800 MBytes and continue running. + It will only hibernate once one of the two reaches 1 GByte. This can + be changed to use the sum of the both bytes received and sent by setting + the AccountingRule option to "sum" (total bandwidth in/out). When the + number of bytes remaining gets low, Tor will stop accepting new connections + and circuits. When the number of bytes is exhausted, Tor will hibernate + until some time in the next accounting period. To prevent all servers + from waking at the same time, Tor will also wait until a random point + in each period before waking up. If you have bandwidth cost issues, + enabling hibernation is preferable to setting a low bandwidth, since + it provides users with a collection of fast servers that are up some + of the time, which is more useful than a set of slow servers that are + always "available". + +[[AccountingRule]] **AccountingRule** **sum**|**max**:: + How we determine when our AccountingMax has been reached (when we + should hibernate) during a time interval. Set to "max" to calculate + using the higher of either the sent or received bytes (this is the + default functionality). Set to "sum" to calculate using the sent + plus received bytes. (Default: max) [[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__:: Specify how long accounting periods last. If **month** is given, each @@ -1840,15 +1857,6 @@ on the public Tor network. authorities provide this service optionally. See **RecommendedVersions**, **RecommendedClientVersions**, and **RecommendedServerVersions**. -[[NamingAuthoritativeDirectory]] **NamingAuthoritativeDirectory** **0**|**1**:: - When this option is set to 1, then the server advertises that it has - opinions about nickname-to-fingerprint bindings. It will include these - opinions in its published network-status pages, by listing servers with - the flag "Named" if a correct binding between that nickname and fingerprint - has been registered with the dirserver. Naming dirservers will refuse to - accept or publish descriptors that contradict a registered binding. See - **approved-routers** in the **FILES** section below. - [[RecommendedVersions]] **RecommendedVersions** __STRING__:: STRING is a comma-separated list of Tor versions currently believed to be safe. The list is included in each directory, and nodes which pull down the @@ -1888,20 +1896,15 @@ on the public Tor network. elements. Otherwise, if the address is not an IP address or is a private IP address, it will reject the router descriptor. (Default: 0) -[[AuthDirBadDir]] **AuthDirBadDir** __AddressPattern...__:: +[[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that - will be listed as bad directories in any network status document this - authority publishes, if **AuthDirListBadDirs** is set. + + will be listed as bad exits in any network status document this authority + 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 "accept" or "reject", and ports are not needed.) -[[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. - [[AuthDirInvalid]] **AuthDirInvalid** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that will never be listed as "valid" in any network status document that this @@ -1913,8 +1916,6 @@ on the public Tor network. authority publishes, or accepted as an OR address in any descriptor submitted for publication by this authority. -[[AuthDirBadDirCCs]] **AuthDirBadDirCCs** __CC__,... + - [[AuthDirBadExitCCs]] **AuthDirBadExitCCs** __CC__,... + [[AuthDirInvalidCCs]] **AuthDirInvalidCCs** __CC__,... + @@ -1922,28 +1923,15 @@ on the public Tor network. [[AuthDirRejectCCs]] **AuthDirRejectCCs** __CC__,...:: Authoritative directories only. These options contain a comma-separated list of country codes such that any server in one of those country codes - will be marked as a bad directory/bad exit/invalid for use, or rejected + will be marked as a bad exit/invalid for use, or rejected entirely. -[[AuthDirListBadDirs]] **AuthDirListBadDirs** **0**|**1**:: - Authoritative directories only. If set to 1, this directory has some - opinion about which nodes are unsuitable as directory caches. (Do not set - this to 1 unless you plan to list non-functioning directories as bad; - otherwise, you are effectively voting in favor of every declared - directory.) - [[AuthDirListBadExits]] **AuthDirListBadExits** **0**|**1**:: Authoritative directories only. If set to 1, this directory has some opinion about which nodes are unsuitable as exit nodes. (Do not set this to 1 unless you plan to list non-functioning exits as bad; otherwise, you are effectively voting in favor of every declared exit as an exit.) -[[AuthDirRejectUnlisted]] **AuthDirRejectUnlisted** **0**|**1**:: - Authoritative directories only. If set to 1, the directory server rejects - all uploaded server descriptors that aren't explicitly listed in the - fingerprints file. This acts as a "panic button" if we get hit with a Sybil - attack. (Default: 0) - [[AuthDirMaxServersPerAddr]] **AuthDirMaxServersPerAddr** __NUM__:: Authoritative directories only. The maximum number of servers that we will list as acceptable on a single IP address. Set this to "0" for "no limit". @@ -2044,7 +2032,7 @@ The following options are used to configure a hidden service. [[HiddenServicePort]] **HiddenServicePort** __VIRTPORT__ [__TARGET__]:: Configure a virtual port VIRTPORT for a hidden service. You may use this option multiple times; each time applies to the service using the most - recent hiddenservicedir. By default, this option maps the virtual port to + recent HiddenServiceDir. By default, this option maps the virtual port to the same port on 127.0.0.1 over TCP. You may override the target port, address, or both by specifying a target of addr, port, or addr:port. You may also have multiple lines with the same VIRTPORT: when a user @@ -2215,6 +2203,15 @@ The following options are used for running a testing Tor network. Try this often to download a v3 authority certificate before giving up. Changing this requires that **TestingTorNetwork** is set. (Default: 8) +[[TestingDirAuthVoteExit]] **TestingDirAuthVoteExit** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, 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. + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + [[TestingDirAuthVoteGuard]] **TestingDirAuthVoteGuard** __node__,__node__,__...__:: A list of identity fingerprints, nicknames, country codes and address patterns of nodes to vote Guard for regardless of their @@ -2357,16 +2354,6 @@ __DataDirectory__**/hashed-fingerprint**:: Only used by bridges. Holds the hashed fingerprint of the bridge's identity key. (That is, the hash of the hash of the identity key.) -__DataDirectory__**/approved-routers**:: - Only for naming authoritative directory servers (see - **NamingAuthoritativeDirectory**). This file lists nickname to identity - bindings. Each line lists a nickname and a fingerprint separated by - whitespace. See your **fingerprint** file in the __DataDirectory__ for an - example line. If the nickname is **!reject** then descriptors from the - given identity (fingerprint) are rejected by this server. If it is - **!invalid** then descriptors are accepted but marked in the directory as - not valid, that is, not recommended. - __DataDirectory__**/v3-status-votes**:: Only for authoritative directory servers. This file contains status votes from all the authoritative directory servers and is used to generate the |