diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING/CodingStandards.md | 12 | ||||
| -rw-r--r-- | doc/HACKING/HowToReview.md | 2 | ||||
| -rw-r--r-- | doc/HACKING/ReleasingTor.md | 78 | ||||
| -rw-r--r-- | doc/HACKING/WritingTests.md | 68 | ||||
| -rw-r--r-- | doc/tor-gencert.1.txt | 2 | ||||
| -rw-r--r-- | doc/tor.1.txt | 194 |
6 files changed, 262 insertions, 94 deletions
diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index 4aafa5ddd4..f1c65850a4 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -3,7 +3,7 @@ Coding conventions for Tor tl;dr: - - Run configure with `--enable-gcc-warnings` + - Run configure with `--enable-fatal-warnings` - Run `make check-spaces` to catch whitespace errors - Document your functions - Write unit tests @@ -21,7 +21,7 @@ preference) Did you remember... - - To build your code while configured with `--enable-gcc-warnings`? + - To build your code while configured with `--enable-fatal-warnings`? - To run `make check-spaces` on your code? - To run `make check-docs` to see whether all new options are on the manpage? @@ -125,10 +125,10 @@ deviations from our C whitespace style. Generally, we use: `puts (x)`. - Function declarations at the start of the line. -We try hard to build without warnings everywhere. In particular, if you're -using gcc, you should invoke the configure script with the option -`--enable-gcc-warnings`. This will give a bunch of extra warning flags to -the compiler, and help us find divergences from our preferred C style. +We try hard to build without warnings everywhere. In particular, if +you're using gcc, you should invoke the configure script with the +option `--enable-fatal-warnings`. This will tell the compiler +to make all warnings into errors. Functions to use; functions not to use -------------------------------------- diff --git a/doc/HACKING/HowToReview.md b/doc/HACKING/HowToReview.md index de7891c923..d53318942f 100644 --- a/doc/HACKING/HowToReview.md +++ b/doc/HACKING/HowToReview.md @@ -15,7 +15,7 @@ Top-level smell-checks (Difficulty: easy) -- Does it compile with `--enable-gcc-warnings`? +- Does it compile with `--enable-fatal-warnings`? - Does `make check-spaces` pass? diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md index 2378aef568..7595398241 100644 --- a/doc/HACKING/ReleasingTor.md +++ b/doc/HACKING/ReleasingTor.md @@ -2,7 +2,16 @@ Putting out a new release ------------------------- -Here are the steps Roger takes when putting out a new Tor release: +Here are the steps that the maintainer should take when putting out a +new Tor release: + +=== 0. Preliminaries + +1. Get at least three of weasel/arma/Sebastian/Sina to put the new + version number in their approved versions list. + + +=== I. Make sure it works 1. Use it for a while, as a client, as a relay, as a hidden service, and as a directory authority. See if it has any obvious bugs, and @@ -10,7 +19,28 @@ Here are the steps Roger takes when putting out a new Tor release: As applicable, merge the `maint-X` branch into the `release-X` branch. -2. Gather the `changes/*` files into a changelog entry, rewriting many +2. Are all of the jenkins builders happy? See jenkins.torproject.org. + + What about the bsd buildbots? + See http://buildbot.pixelminers.net/builders/ + + What about Coverity Scan? + + Is make check-spaces happy? + + Does 'make distcheck' compain? + + How about 'make test-stem' and 'make test-network'? + + - Are all those tests still happy with --enable-expensive-hardening ? + + Any memory leaks? + + +=== II. Write a changelog. + + +1. Gather the `changes/*` files into a changelog entry, rewriting many of them and reordering to focus on what users and funders would find interesting and understandable. @@ -62,13 +92,13 @@ Here are the steps Roger takes when putting out a new Tor release: 7. Run `./scripts/maint/format_changelog.py` to make it prettier. -3. Compose a short release blurb to highlight the user-facing +2. 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 to a release-0.2.x branch, manually commit the changelogs to the later git branches too. - If you're doing the first stable release in a series, you need to +3. If you're doing the first stable release in a series, you need to create a ReleaseNotes for the series as a whole. To get started there, copy all of the Changelog entries from the series into a new file, and run `./scripts/maint/sortChanges.py` on it. That will @@ -78,7 +108,10 @@ Here are the steps Roger takes when putting out a new Tor release: to start sorting and condensing entries. (Generally, we don't edit the text of existing entries, though.) -4. In `maint-0.2.x`, bump the version number in `configure.ac` and run + +=== III. Making the source release. + +1. In `maint-0.2.x`, bump the version number in `configure.ac` and run `scripts/maint/updateVersions.pl` to update version numbers in other places, and commit. Then merge `maint-0.2.x` into `release-0.2.x`. @@ -86,20 +119,19 @@ Here are the steps Roger takes when putting out a new Tor release: either `make`, or `perl scripts/maint/updateVersions.pl`, depending on your version.) -5. Make distcheck, put the tarball up somewhere, and tell `#tor` about +2. Make distcheck, put the tarball up somewhere, and tell `#tor` about it. Wait 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/Sebastian to put the new version number - in their approved versions list. +=== IV. Commit, upload, announce -7. Sign the tarball, then sign and push the git tag: +1. 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 dist website, i.e. +2. 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. @@ -110,34 +142,44 @@ Here are the steps Roger takes when putting out a new Tor release: once. Nonetheless, do not call your version "alpha" if it is stable, or people will get confused.) -9. Email the packagers (cc'ing tor-assistants) that a new tarball is up. +3. Email the packagers (cc'ing tor-assistants) that a new tarball is up. The current list of packagers is: - {weasel,gk,mikeperry} at torproject dot org - {blueness} at gentoo dot org - {paul} at invizbox dot io - - {ondrej.mikle} at gmail dot com - {lfleischer} at archlinux dot org - - {tails-dev} at boum dot org + - {Nathan} at freitas dot net + - {mike} at tig dot as + - {tails-rm} at boum dot org (for pre-release announcments) + + + - {tails-dev} at boum dot org (for at-release announcements) + -10. Add the version number to Trac. To do this, go to Trac, log in, +4. Add the version number to Trac. To do this, go to Trac, log in, select "Admin" near the top of the screen, then select "Versions" from the menu on the left. At the right, there will be an "Add version" 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. Forward-port the ChangeLog (and ReleaseNotes if appropriate). - -12. Wait up to a day or two (for a development release), or until most +5. 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.) -13. If it's a stable release, bump the version number in the `maint-x.y.z` + +=== V. Aftermath and cleanup + +1. If it's a stable release, bump the version number in the `maint-x.y.z` branch to "newversion-dev", and do a `merge -s ours` merge to avoid taking that change into master. Do a similar `merge -s theirs` merge to get the change (and only that change) into release. (Some of the build scripts require that maint merge cleanly into release.) + +2. Forward-port the ChangeLog (and ReleaseNotes if appropriate). + + diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md index 4e98d3d645..de80bbdef2 100644 --- a/doc/HACKING/WritingTests.md +++ b/doc/HACKING/WritingTests.md @@ -109,6 +109,19 @@ To count new or modified uncovered lines in D2, you can run: ./scripts/test/cov-diff ${D1} ${D2}" | grep '^+ *\#' | wc -l +### Marking lines as unreachable by tests + +You can mark a specific line as unreachable by using the special +string LCOV_EXCL_LINE. You can mark a range of lines as unreachable +with LCOV_EXCL_START... LCOV_EXCL_STOP. Note that older versions of +lcov don't understand these lines. + +You can post-process .gcov files to make these lines 'unreached' by +running ./scripts/test/cov-exclude on them. + +Note: you should never do this unless the line is meant to 100% +unreachable by actual code. + What kinds of test should I write? ---------------------------------- @@ -139,6 +152,11 @@ or create a new C file there. Each test is a single function that must be indexed in the table at the end of the file. We use the label "done:" as a cleanup point for all test functions. +If you have created a new test file, you will need to: +1. Add the new test file to include.am +2. In `test.h`, include the new test cases (testcase_t) +3. In `test.c`, add the new test cases to testgroup_t testgroups + (Make sure you read `tinytest-manual.md` before proceeding.) I use the term "unit test" and "regression tests" very sloppily here. @@ -417,18 +435,50 @@ makefile exports them. Writing integration tests with Stem ----------------------------------- -The 'stem' library includes extensive unit tests for the Tor controller -protocol. - -For more information on writing new tests for stem, have a look around -the `test/*` directory in stem, and find a good example to emulate. You -might want to start with -`https://gitweb.torproject.org/stem.git/tree/test/integ/control/controller.py` -to improve Tor's test coverage. - +The 'stem' library includes extensive tests for the Tor controller protocol. You can run stem tests from tor with `make test-stem`, or see `https://stem.torproject.org/faq.html#how-do-i-run-the-tests`. +To see what tests are available, have a look around the `test/*` directory in +stem. The first thing you'll notice is that there are both `unit` and `integ` +tests. The former are for tests of the facilities provided by stem itself that +can be tested on their own, without the need to hook up a tor process. These +are less relevant, unless you want to develop a new stem feature. The latter, +however, are a very useful tool to write tests for controller features. They +provide a default environment with a connected tor instance that can be +modified and queried. Adding more integration tests is a great way to increase +the test coverage inside Tor, especially for controller features. + +Let's assume you actually want to write a test for a previously untested +controller feature. I'm picking the `exit-policy/*` GETINFO queries. Since +these are a controller feature that we want to write an integration test for, +the right file to modify is +`https://gitweb.torproject.org/stem.git/tree/test/integ/control/controller.py`. + +First off we notice that there is an integration test called +`test_get_exit_policy()` that's already written. This exercises the interaction +of stem's `Controller.get_exit_policy()` method, and is not relevant for our +test since there are no stem methods to make use of all `exit-policy/*` +queries (if there were, likely they'd be tested already. Maybe you want to +write a stem feature, but I chose to just add tests). + +Our test requires a tor controller connection, so we'll use the +`@require_controller` annotation for our `test_exit_policy()` method. We need a +controller instance, which we get from +`test.runner.get_runner().get_tor_controller()`. The attached Tor instance is +configured as a client, but the exit-policy GETINFO queries need a relay to +work, so we have to change the config (using `controller.set_options()`). This +is OK for us to do, we just have to remember to set DisableNetwork so we don't +actually start an exit relay and also to undo the changes we made (by calling +`controller.reset_conf()` at the end of our test). Additionally, we have to +configure a static Address for Tor to use, because it refuses to build a +descriptor when it can't guess a suitable IP address. Unfortunately, these +kinds of tripwires are everywhere. Don't forget to file appropriate tickets if +you notice any strange behaviour that seems totally unreasonable. + +Check out the `test_exit_policy()` function in abovementioned file to see the +final implementation for this test. + System testing with Chutney --------------------------- diff --git a/doc/tor-gencert.1.txt b/doc/tor-gencert.1.txt index aa61ec3ec6..6bba548b87 100644 --- a/doc/tor-gencert.1.txt +++ b/doc/tor-gencert.1.txt @@ -68,7 +68,7 @@ OPTIONS Number of months that the certificate should be valid. Default: 12. **--passphrase-fd** __FILEDES__:: - Filedescriptor to read the file descriptor from. Ends at the first NUL or + Filedescriptor to read the passphrase from. Ends at the first NUL or newline. Default: read from the terminal. **-a** __address__:__port__:: diff --git a/doc/tor.1.txt b/doc/tor.1.txt index b286a06563..4c5d5359af 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -84,6 +84,10 @@ COMMAND-LINE OPTIONS [[opt-list-torrc-options]] **--list-torrc-options**:: List all valid options. +[[opt-list-deprecated-options]] **--list-deprecated-options**:: + List all valid options that are scheduled to become obsolete in a + future version. (This is a warning, not a promise.) + [[opt-version]] **--version**:: Display Tor version and exit. @@ -118,6 +122,13 @@ COMMAND-LINE OPTIONS directory of your Tor daemon, and make sure that they are owned by the user actually running the Tor daemon on your system. +**--passphrase-fd** __FILEDES__:: + Filedescriptor to read the passphrase from. Note that unlike with the + tor-gencert program, the entire file contents are read and used as + the passphrase, including any trailing newlines. + Default: read from the terminal. + + Other options can be specified on the command-line in the format "--option value", in the format "option value", or in a configuration file. For instance, you can tell Tor to start listening for SOCKS connections on port @@ -310,8 +321,10 @@ GENERAL OPTIONS 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 eithermethod is sufficient to authenticate to Tor.) This + methods means either method is sufficient to authenticate to Tor.) This option is required for many Tor controllers; most use the value of 9051. + If a unix domain socket is used, you may quote the path using standard + C escape sequences. Set it to "auto" to have Tor pick a port for you. (Default: 0) + + Recognized flags are... @@ -596,6 +609,13 @@ GENERAL OPTIONS message currently has at least one domain; most currently have exactly one. This doesn't affect controller log messages. (Default: 0) +[[MaxUnparseableDescSizeToLog]] **MaxUnparseableDescSizeToLog** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: + Unparseable descriptors (e.g. for votes, consensuses, routers) are logged + in separate files by hash, up to the specified size in total. Note that + only files logged during the lifetime of this Tor process count toward the + total; this is intended to be used to debug problems without opening live + servers to resource exhaustion attacks. (Default: 10 MB) + [[OutboundBindAddress]] **OutboundBindAddress** __IP__:: Make all outbound connections originate from the IP address specified. This is only useful when you have multiple network interfaces, and you want all @@ -651,7 +671,7 @@ GENERAL OPTIONS relay, all log messages generated when acting as a relay are sanitized, but all messages generated when acting as a client are not. (Default: 1) -[[User]] **User** __UID__:: +[[User]] **User** __Username__:: On startup, setuid to this user and setgid to their primary group. [[KeepBindCapabilities]] **KeepBindCapabilities** **0**|**1**|**auto**:: @@ -692,26 +712,6 @@ GENERAL OPTIONS networkstatus. This is an advanced option; you generally shouldn't have to mess with it. (Default: not set) -[[DisableIOCP]] **DisableIOCP** **0**|**1**:: - If Tor was built to use the Libevent's "bufferevents" networking code - and you're running on Windows, setting this option to 1 will tell Libevent - not to use the Windows IOCP networking API. (Default: 1) - -[[UserspaceIOCPBuffers]] **UserspaceIOCPBuffers** **0**|**1**:: - If IOCP is enabled (see DisableIOCP above), setting this option to 1 - will tell Tor to disable kernel-space TCP buffers, in order to avoid - needless copy operations and try not to run out of non-paged RAM. - This feature is experimental; don't use it yet unless you're eager to - help tracking down bugs. (Default: 0) - -[[UseFilteringSSLBufferevents]] **UseFilteringSSLBufferevents** **0**|**1**:: - Tells Tor to do its SSL communication using a chain of - bufferevents: one for SSL and one for networking. This option has no - effect if bufferevents are disabled (in which case it can't turn on), or - if IOCP bufferevents are enabled (in which case it can't turn off). This - option is useful for debugging only; most users shouldn't touch it. - (Default: 0) - [[CountPrivateBandwidth]] **CountPrivateBandwidth** **0**|**1**:: If this option is set, then Tor's rate-limiting applies not only to remote connections, but also to connections to private addresses like @@ -1035,7 +1035,9 @@ The following options are useful only for clients (that is, if 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. This directive can be specified multiple times to bind - to multiple addresses/ports. (Default: 9050) + + to multiple addresses/ports. If a unix domain socket is used, you may + quote the path using standard C escape sequences. + (Default: 9050) + + NOTE: Although this option allows you to specify an IP address other than localhost, you should do so only with extreme caution. @@ -1049,8 +1051,9 @@ The following options are useful only for clients (that is, if 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**.) + client address. (On by default and strongly recommended when + supported; you can disable it with **NoIsolateClientAddr**. + Unsupported and force-disabled when using Unix domain sockets.) **IsolateSOCKSAuth**;; Don't share circuits with streams for which different SOCKS authentication was provided. (On by default; @@ -1086,7 +1089,18 @@ The following options are useful only for clients (that is, if IPv6.) **PreferIPv6**;; Tells exits that, if a host has both an IPv4 and an IPv6 address, - we would prefer to connect to it via IPv6. (IPv4 is the default.) + + we would prefer to connect to it via IPv6. (IPv4 is the default.) + **NoDNSRequest**;; + Do not ask exits to resolve DNS addresses in SOCKS5 requests. Tor will + connect to IPv4 addresses, IPv6 addresses (if IPv6Traffic is set) and + .onion addresses. + **NoOnionTraffic**;; + Do not connect to .onion addresses in SOCKS5 requests. + **OnionTrafficOnly**;; + Tell the tor client to only connect to .onion addresses in response to + SOCKS5 requests on this connection. This is equivalent to NoDNSRequest, + NoIPv4Traffic, NoIPv6Traffic. The corresponding NoOnionTrafficOnly + flag is not supported. **CacheIPv4DNS**;; Tells the client to remember IPv4 DNS answers we receive from exit nodes via this connection. (On by default.) @@ -1128,6 +1142,10 @@ The following options are useful only for clients (that is, if authentication" when IsolateSOCKSAuth is disabled, or when this option is set. + Flags are processed left to right. If flags conflict, the last flag on the + line is used, and all earlier flags are ignored. No error is issued for + conflicting flags. + [[SocksListenAddress]] **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. @@ -1187,7 +1205,9 @@ The following options are useful only for clients (that is, if If this option is set to 1, we pick a few long-term entry servers, and try to stick with them. This is desirable because constantly changing servers increases the odds that an adversary who owns some servers will observe a - fraction of your paths. (Default: 1) + fraction of your paths. Entry Guards can not be used by Directory + Authorities, Single Onion Services, and Tor2web clients. In these cases, + the this option is ignored. (Default: 1) [[UseEntryGuardsAsDirGuards]] **UseEntryGuardsAsDirGuards** **0**|**1**:: If this option is set to 1, and UseEntryGuards is also set to 1, @@ -1258,11 +1278,14 @@ The following options are useful only for clients (that is, if + When providing proxy server service to a network of computers using a tool like dns-proxy-tor, change the IPv4 network to "10.192.0.0/10" or - "172.16.0.0/12" and change the IPv6 network to "[FC00]/7". + "172.16.0.0/12" and change the IPv6 network to "[FC00::]/7". The default **VirtualAddrNetwork** address ranges on a properly configured machine will route to the loopback or link-local - interface. For - local use, no change to the default VirtualAddrNetwork setting is needed. + interface. The maximum number of bits for the network prefix is set to 104 + for IPv6 and 16 for IPv4. However, a wider network - smaller prefix length + - is preferable since it reduces the chances for an attacker to guess the + used IP. For local use, no change to the default VirtualAddrNetwork setting + is needed. [[AllowNonRFC953Hostnames]] **AllowNonRFC953Hostnames** **0**|**1**:: When this option is disabled, Tor blocks hostnames containing illegal @@ -1427,8 +1450,10 @@ The following options are useful only for clients (that is, if **non-anonymously**. This option also disables client connections to non-hidden-service hostnames through Tor. It **must only** be used when running a tor2web Hidden Service web proxy. - To enable this option the compile time flag --enable-tor2webmode must be - specified. (Default: 0) + To enable this option the compile time flag --enable-tor2web-mode must be + specified. Since Tor2webMode is non-anonymous, you can not run an + anonymous Hidden Service on a tor version compiled with Tor2webMode. + (Default: 0) [[Tor2webRendezvousPoints]] **Tor2webRendezvousPoints** __node__,__node__,__...__:: A list of identity fingerprints, nicknames, country codes and @@ -1455,16 +1480,6 @@ The following options are useful only for clients (that is, if "auto" (recommended) then it is on for all clients that do not set FetchUselessDescriptors. (Default: auto) -[[UseNTorHandshake]] **UseNTorHandshake** **0**|**1**|**auto**:: - The "ntor" circuit-creation handshake is faster and (we think) more - secure than the original ("TAP") circuit handshake, but starting to use - 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", then your client - will use the ntor handshake once enough directory authorities recommend - it. (Default: 1) - [[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ + [[PathBiasNoticeRate]] **PathBiasNoticeRate** __NUM__ + @@ -1556,8 +1571,9 @@ The following options are useful only for clients (that is, if that fraction of possible paths. Note that setting this option too low can make your Tor client less anonymous, and setting it too high can prevent your Tor client from bootstrapping. If this option is negative, - Tor will use a default value chosen by the directory - authorities. (Default: -1.) + Tor will use a default value chosen by the directory authorities. If the + directory authorities do not choose a value, Tor will default to 0.6. + (Default: -1.) [[ClientBootstrapConsensusAuthorityDownloadSchedule]] **ClientBootstrapConsensusAuthorityDownloadSchedule** __N__,__N__,__...__:: Schedule for when clients should download consensuses from authorities @@ -1688,15 +1704,16 @@ is non-zero): used with accept6/reject6.) + + Private addresses are rejected by default (at the beginning of your exit - policy), along with any configured primary public IPv4 and IPv6 addresses, - and any public IPv4 and IPv6 addresses on any interface on the relay. + policy), along with any configured primary public IPv4 and IPv6 addresses. These private addresses are rejected unless you set the ExitPolicyRejectPrivate config option to 0. For example, once you've done that, you could allow HTTP to 127.0.0.1 and block all other connections to internal networks with "accept 127.0.0.1:80,reject private:\*", though that may also allow connections to your own computer that are addressed to its public (external) IP address. See RFC 1918 and RFC 3330 for more details - about internal and reserved IP address space. + + about internal and reserved IP address space. See + ExitPolicyRejectLocalInterfaces if you want to block every address on the + relay, even those that aren't advertised in the descriptor. + + This directive can be specified multiple times so you don't have to put it all on one line. + @@ -1726,16 +1743,23 @@ is non-zero): IPv4 and IPv6 addresses. [[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**:: - Reject all private (local) networks, along with any configured public - IPv4 and IPv6 addresses, at the beginning of your exit policy. (This - includes the IPv4 and IPv6 addresses advertised by the relay, any - OutboundBindAddress, and the bind addresses of any port options, such as - ORPort and DirPort.) This also rejects any public IPv4 and IPv6 addresses - on any interface on the relay. (If IPv6Exit is not set, all IPv6 addresses - will be rejected anyway.) + Reject all private (local) networks, along with the relay's advertised + public IPv4 and IPv6 addresses, at the beginning of your exit policy. See above entry on ExitPolicy. (Default: 1) +[[ExitPolicyRejectLocalInterfaces]] **ExitPolicyRejectLocalInterfaces** **0**|**1**:: + Reject all IPv4 and IPv6 addresses that the relay knows about, at the + beginning of your exit policy. This includes any OutboundBindAddress, the + bind addresses of any port options, such as ControlPort or DNSPort, and any + public IPv4 and IPv6 addresses on any interface on the relay. (If IPv6Exit + is not set, all IPv6 addresses will be rejected anyway.) + See above entry on ExitPolicy. + This option is off by default, because it lists all public relay IP + addresses in the ExitPolicy, even those relay operators might prefer not + to disclose. + (Default: 0) + [[IPv6Exit]] **IPv6Exit** **0**|**1**:: If set, and we are an exit node, allow clients to use us for IPv6 traffic. (Default: 0) @@ -2036,6 +2060,12 @@ is non-zero): this. If this option is set to 0, Tor will try to pick a reasonable default based on your system's physical memory. (Default: 0) +[[DisableOOSCheck]] **DisableOOSCheck** **0**|**1**:: + This option disables the code that closes connections when Tor notices + that it is running low on sockets. Right now, it is on by default, + since the existing out-of-sockets mechanism tends to kill OR connections + more than it should. (Default: 1) + [[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**:: For how long should each Ed25519 signing key be valid? Tor uses a permanent master identity key that can be kept offline, and periodically @@ -2104,14 +2134,13 @@ on the public Tor network. server. Instead of caching the directory, it generates its own list of good servers, signs it, and sends that to the clients. Unless the clients already have you listed as a trusted directory, you probably do not want - to set this option. Please coordinate with the other admins at - tor-ops@torproject.org if you think you should be a directory. + to set this option. [[V3AuthoritativeDirectory]] **V3AuthoritativeDirectory** **0**|**1**:: When this option is set in addition to **AuthoritativeDirectory**, Tor generates version 3 network statuses and serves descriptors, etc as described in dir-spec.txt file of https://spec.torproject.org/[torspec] - (for Tor clients and servers running atleast 0.2.0.x). + (for Tor clients and servers running at least 0.2.0.x). [[VersioningAuthoritativeDirectory]] **VersioningAuthoritativeDirectory** **0**|**1**:: When this option is set to 1, Tor adds information on which versions of @@ -2163,7 +2192,9 @@ on the public Tor network. [[DirAllowPrivateAddresses]] **DirAllowPrivateAddresses** **0**|**1**:: If set to 1, Tor will accept server descriptors with arbitrary "Address" elements. Otherwise, if the address is not an IP address or is a private IP - address, it will reject the server descriptor. (Default: 0) + address, it will reject the server descriptor. Additionally, Tor + will allow exit policies for private networks to fulfill Exit flag + requirements. (Default: 0) [[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that @@ -2227,6 +2258,12 @@ on the public Tor network. in a journal if it is new, or if it differs from the most recently accepted pinning for one of the keys it contains. (Default: 0) +[[AuthDirSharedRandomness]] **AuthDirSharedRandomness** **0**|**1**:: + Authoritative directories only. Switch for the shared random protocol. + If zero, the authority won't participate in the protocol. If non-zero + (default), the flag "shared-rand-participate" is added to the authority + vote indicating participation in the protocol. (Default: 1) + [[BridgePassword]] **BridgePassword** __Password__:: If set, contains an HTTP authenticator that tells a bridge authority to serve all requested bridge information. Used by the (only partially @@ -2311,7 +2348,8 @@ The following options are used to configure a hidden service. 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, addr:port, or - **unix:**__path__. (You can specify an IPv6 target as [addr]:port.) + **unix:**__path__. (You can specify an IPv6 target as [addr]:port. Unix + paths may be quoted, and may use standard C escapes.) You may also have multiple lines with the same VIRTPORT: when a user connects to that VIRTPORT, one of the TARGETs from those lines will be chosen at random. @@ -2369,6 +2407,40 @@ The following options are used to configure a hidden service. Number of introduction points the hidden service will have. You can't have more than 10. (Default: 3) +[[HiddenServiceSingleHopMode]] **HiddenServiceSingleHopMode** **0**|**1**:: + **Experimental - Non Anonymous** Hidden Services on a tor instance in + HiddenServiceSingleHopMode make one-hop (direct) circuits between the onion + service server, and the introduction and rendezvous points. (Onion service + descriptors are still posted using 3-hop paths, to avoid onion service + directories blocking the service.) + This option makes every hidden service instance hosted by a tor instance a + Single Onion Service. One-hop circuits make Single Onion servers easily + locatable, but clients remain location-anonymous. However, the fact that a + client is accessing a Single Onion rather than a Hidden Service may be + statistically distinguishable. + + **WARNING:** Once a hidden service directory has been used by a tor + instance in HiddenServiceSingleHopMode, it can **NEVER** be used again for + a hidden service. It is best practice to create a new hidden service + directory, key, and address for each new Single Onion Service and Hidden + Service. It is not possible to run Single Onion Services and Hidden + Services from the same tor instance: they should be run on different + servers with different IP addresses. + + HiddenServiceSingleHopMode requires HiddenServiceNonAnonymousMode to be set + to 1. Since a Single Onion service is non-anonymous, you can not configure + a SOCKSPort on a tor instance that is running in + **HiddenServiceSingleHopMode**. + (Default: 0) + +[[HiddenServiceNonAnonymousMode]] **HiddenServiceNonAnonymousMode** **0**|**1**:: + Makes hidden services non-anonymous on this tor instance. Allows the + non-anonymous HiddenServiceSingleHopMode. Enables direct connections in the + server-side hidden service protocol. If you are using this option, + you need to disable all client-side services on your Tor instance, + including setting SOCKSPort to "0". + (Default: 0) + TESTING NETWORK OPTIONS ----------------------- @@ -2828,6 +2900,10 @@ __HiddenServiceDirectory__**/client_keys**:: Authorization data for a hidden service that is only accessible by authorized clients. +__HiddenServiceDirectory__**/onion_service_non_anonymous**:: + This file is present if a hidden service key was created in + **HiddenServiceNonAnonymousMode**. + SEE ALSO -------- **torsocks**(1), **torify**(1) + |