diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING | 45 | ||||
| -rw-r--r-- | doc/building-tor-msvc.txt | 122 | ||||
| -rw-r--r-- | doc/tor.1.txt | 89 |
3 files changed, 198 insertions, 58 deletions
diff --git a/doc/HACKING b/doc/HACKING index c69b2a6fee..2052a9d492 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -114,6 +114,47 @@ valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/or/tor pass --undef-value-errors=no to valgrind, or rebuild your openssl with -DPURIFY.) +Running lcov for unit test coverage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lcov is a utility that generates pretty HTML reports of test code coverage. +To generate such a report: + +----- + ./configure --enable-coverage + make + make coverage-html + $BROWSER ./coverage_html/index.html +----- + +This will run the tor unit test suite `./src/test/test` and generate the HTML +coverage code report under the directory ./coverage_html/. To change the +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -460,7 +501,7 @@ interesting and understandable. Standard idioms: "Fixes bug 9999; bugfix on 0.3.3.3-alpha." - One period after a space. + One space after a period. Make stuff very terse @@ -492,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 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 8d51f6e3c2..c9172b85be 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -568,6 +568,10 @@ GENERAL OPTIONS messages to affect times logged by a controller, times attached to syslog messages, or the mtime fields on log files. (Default: 1 second) +[[TruncateLogFile]] **TruncateLogFile** **0**|**1**:: + If 1, Tor will overwrite logs at startup and in response to a HUP signal, + instead of appending to them. (Default: 0) + [[SafeLogging]] **SafeLogging** **0**|**1**|**relay**:: Tor can scrub potentially sensitive strings from log messages (e.g. addresses) by replacing them with the string [scrubbed]. This way logs can @@ -1631,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. [[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__:: Specify how long accounting periods last. If **month** is given, each @@ -1841,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 @@ -1889,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 @@ -1914,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__,... + @@ -1923,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". @@ -2352,16 +2339,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 |