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 | 67 |
3 files changed, 187 insertions, 47 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 abe613e569..d6b14329d1 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -224,6 +224,13 @@ GENERAL OPTIONS for the Extended ORPort's cookie file -- the cookie file is needed for pluggable transports to communicate through the Extended ORPort. +[[ExtORPortCookieAuthFileGroupReadable]] **ExtORPortCookieAuthFileGroupReadable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read the + Extended OR Port cookie file. If the option is set to 1, make the cookie + file readable by the default GID. [Making the file readable by other + groups is not yet implemented; let us know if you need this for some + reason.] (Default: 0) + [[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 @@ -312,7 +319,7 @@ GENERAL OPTIONS If set, this option overrides the default location and file name for Tor's cookie file. (See CookieAuthentication above.) -[[CookieAuthFileGroupReadable]] **CookieAuthFileGroupReadable** **0**|**1**|__Groupname__:: +[[CookieAuthFileGroupReadable]] **CookieAuthFileGroupReadable** **0**|**1**:: If this option is set to 0, don't allow the filesystem group to read the cookie file. If the option is set to 1, make the cookie file readable by the default GID. [Making the file readable by other groups is not yet @@ -561,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 @@ -1486,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. + + @@ -1694,7 +1710,7 @@ is non-zero): [[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**:: When this option is enabled and BridgeRelay is also enabled, and we have - GeoIP data, Tor keeps a keep a per-country count of how many client + GeoIP data, Tor keeps a per-country count of how many client addresses have contacted it so that it can help the bridge authority guess which countries have blocked access to it. (Default: 1) @@ -1829,15 +1845,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 @@ -1877,20 +1884,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 @@ -1902,8 +1904,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__,... + @@ -1911,28 +1911,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". @@ -2340,16 +2327,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 |