diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING/ReleasingTor.md | 34 | ||||
| -rw-r--r-- | doc/HACKING/WritingTests.md | 2 | ||||
| -rwxr-xr-x | doc/asciidoc-helper.sh | 2 | ||||
| -rw-r--r-- | doc/building-tor-msvc.txt | 122 | ||||
| -rw-r--r-- | doc/include.am | 8 | ||||
| -rw-r--r-- | doc/man/tor.1.txt | 81 |
6 files changed, 102 insertions, 147 deletions
diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md index a32bb10dad..af3805f38e 100644 --- a/doc/HACKING/ReleasingTor.md +++ b/doc/HACKING/ReleasingTor.md @@ -53,6 +53,12 @@ been merged upstream. (Version bumps apply to `maint`; anything touching the changelog should apply only to `main` or `release`.) + When updating the version, it will be on `maint` branches and so to + merge-forward, use `git merge -s ours`. For instance, if merging the + version change of `maint-0.4.5` into `maint-0.4.6`, do on `maint-0.4.6` + this command: `git merge -s ours maint-0.4.5`. And then you can proceed + with a git-merge-forward. + 2. For the ChangeLog and ReleaseNotes, you need to write a blurb at the top explaining a bit the release. @@ -70,7 +76,7 @@ Steps are: 1. Run `./build.sh` which will download everything you need, including the latest tarballs from the release CI, and auto-commit the signatures if - the checksum match. You will need to confim the commits. + the checksum match. You will need to confirm the commits. 2. If all is good, `git push origin main` your signatures. @@ -120,26 +126,38 @@ do the following: 2. Merge upstream the artifacts from the `patches` job in the `Post-process` stage of the CI release pipeline. + Like step (2.1) above, the `-dev` version bump need to be done manually + with a `git merge -s ours`. + 3. Write and post the release announcement for the `forum.torproject.net` in the `News -> Tor Release Announcement` category. If possible, mention in which Tor Browser version (with dates) the release will be in. This usually only applies to the latest stable. - 4. Inform `tor-talk@lists.torproject.org` with the releasing pointing to + 4. Inform `tor-announce@lists.torproject.org` with the releasing pointing to the Forum. Append the ChangeLog there. We do this until we can automate such post from the forum directly. -### New Stable + 5. Update torproject.org website by submitting a MR to + https://gitlab.torproject.org/tpo/web/tpo - 1. Create the `maint-x.y.z` and `release-x.y.z` branches and update the - `./scripts/git/git-list-tor-branches.sh` with the new version. + The `databags/versions.ini` file is the one to change with the newly + released version(s). + +### New Stable - 2. Add the new version in `./scripts/ci/ci-driver.sh`. + 1. Create the `maint-x.y.z` and `release-x.y.z` branches at the version + tag. Then update the `./scripts/git/git-list-tor-branches.sh` with the + new version. - 3. Forward port the ChangeLog and ReleaseNotes into main branch. Remove any - change logs of stable releases in ReleaseNotes. + 2. Update `./scripts/git/git-list-tor-branches.sh` and + `./scripts/ci/ci-driver.sh` with the new version in `maint-x.y.z` and + then merge forward into main. (If you haven't pushed remotely the new + branches, merge the local branch). + 3. In `main`, bump version to the next series: `tor-x.y.0-alpha-dev` and + then tag it: `git tag -s tor-x.y.0-alpha-dev` ## Appendix: An alternative means to notify packagers diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md index 129b79a854..463a4ad4af 100644 --- a/doc/HACKING/WritingTests.md +++ b/doc/HACKING/WritingTests.md @@ -336,7 +336,7 @@ glass-box one is one you implement while looking at how the function is implemented. In either case, make sure to consider common cases *and* edge cases; success -cases and failure csaes. +cases and failure cases. For example, consider testing this function: diff --git a/doc/asciidoc-helper.sh b/doc/asciidoc-helper.sh index 98e216e68a..a3e2f8f9bf 100755 --- a/doc/asciidoc-helper.sh +++ b/doc/asciidoc-helper.sh @@ -12,7 +12,7 @@ if [ $# != 3 ]; then exit 1 fi -SOURCE_DATE_EPOCH="$(git show --no-patch --format='%ct')" +SOURCE_DATE_EPOCH="$(git -C "$(dirname "$0")" show --no-patch --format='%ct')" export SOURCE_DATE_EPOCH output=$3 diff --git a/doc/building-tor-msvc.txt b/doc/building-tor-msvc.txt deleted file mode 100644 index dbc644d172..0000000000 --- a/doc/building-tor-msvc.txt +++ /dev/null @@ -1,122 +0,0 @@ -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
- https://go.microsoft.com/fwlink/?LinkId=323467
- * CMake 2.8.12.2
- https://www.cmake.org/download/
- * Perl 5.16
- https://www.activestate.com/activeperl/downloads
- * Latest stable OpenSSL tarball
- https://www.openssl.org/source/
- * Latest stable zlib tarball
- https://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/include.am b/doc/include.am index d10f380e7f..7570978ddb 100644 --- a/doc/include.am +++ b/doc/include.am @@ -56,10 +56,10 @@ EXTRA_DIST+= doc/asciidoc-helper.sh \ doc/HACKING/HelpfulTools.md \ doc/HACKING/HowToReview.md \ doc/HACKING/Module.md \ - doc/HACKING/ReleasingTor.md \ - doc/HACKING/WritingTests.md - doc/HACKING/tracing/Tracing.md \ - doc/HACKING/tracing/EventsCircuit.md + doc/HACKING/ReleasingTor.md \ + doc/HACKING/WritingTests.md \ + doc/HACKING/tracing/EventsCircuit.md \ + doc/HACKING/tracing/README.md docdir = @docdir@ diff --git a/doc/man/tor.1.txt b/doc/man/tor.1.txt index 3672444c5d..1589809b1a 100644 --- a/doc/man/tor.1.txt +++ b/doc/man/tor.1.txt @@ -335,7 +335,7 @@ forward slash (/) in the configuration file and on the command line. to mess with it. (Default: -1) [[ClientTransportPlugin]] **ClientTransportPlugin** __transport__ socks4|socks5 __IP__:__PORT__:: -**ClientTransportPlugin** __transport__ exec __path-to-binary__ [options]:: +[[ClientTransportPlugin-2]] **ClientTransportPlugin** __transport__ exec __path-to-binary__ [options]:: In its first form, when set along with a corresponding Bridge line, the Tor client forwards its traffic to a SOCKS-speaking proxy on "IP:PORT". (IPv4 addresses should written as-is; IPv6 addresses should be wrapped in @@ -348,6 +348,19 @@ forward slash (/) in the configuration file and on the command line. forwards its traffic to it. It's the duty of that proxy to properly forward the traffic to the bridge. (Default: none) +[[ConfluxEnabled]] **ConfluxEnabled** **0**|**1**|**auto**:: + If this option is set to 1, general purpose traffic will use Conflux which + is traffic splitting among multiple legs (circuits). Onion services are not + supported at the moment. Default value is set to "auto" meaning the + consensus is used to decide unless set. (Default: auto) + +[[ConfluxClientUX]] **ConfluxClientUX** **throughput**|**latency**|**throughput_lowmem**|**latency_lowmem**:: + This option configures the user experience that the client requests from + the exit, for data that the exit sends to the client. The default is + "throughput", which maximizes throughput. "Latency" will tell the exit to + only use the circuit with lower latency for all data. The lowmem versions + minimize queue usage memory at the client. (Default: "throughput") + [[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 @@ -860,6 +873,7 @@ forward slash (/) in the configuration file and on the command line. \_relayed traffic_ to the given number of bytes in each direction. They do not include directory fetches by the relay (from authority or other relays), because that is considered "client" activity. (Default: 0) + RelayBandwidthBurst defaults to the value of RelayBandwidthRate if unset. [[RelayBandwidthRate]] **RelayBandwidthRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: If not 0, a separate token bucket limits the average incoming bandwidth @@ -869,6 +883,7 @@ forward slash (/) in the configuration file and on the command line. requests, but that may change in future versions. They do not include directory fetches by the relay (from authority or other relays), because that is considered "client" activity. (Default: 0) + RelayBandwidthRate defaults to the value of RelayBandwidthBurst if unset. [[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: Tells an authority, or other node tracking node reliability and history, @@ -1172,7 +1187,7 @@ The following options are useful only for clients (that is, if entry nodes over IPv6. For IPv6 only hosts, you need to also set **ClientUseIPv4** to 0 to disable IPv4. Note that clients configured with an IPv6 address in a **Bridge**, proxy, or pluggable transportline will - try connecting over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0) + try connecting over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 1) [[ConnectionPadding]] **ConnectionPadding** **0**|**1**|**auto**:: This option governs Tor's use of padding to defend against some forms of @@ -3013,14 +3028,14 @@ Denial of Service mitigation subsystem described above. (Default: auto) -As for onion services, only one possible mitigation exists. It was intended to -protect the network first and thus do not help the service availability or -reachability. +For onion services, mitigations are a work in progress and multiple options +are currently available. -The mitigation we put in place is a rate limit of the amount of introduction -that happens at the introduction point for a service. In other words, it rates -limit the number of clients that are attempting to reach the service at the -introduction point instead of at the service itself. +The introduction point defense is a rate limit on the number of introduction +requests that will be forwarded to a service by each of its honest +introduction point routers. This can prevent some types of overwhelming floods +from reaching the service, but it will also prevent legitimate clients from +establishing new connections. The following options are per onion service: @@ -3074,6 +3089,51 @@ The bottom line is that this protects the network by preventing an onion service to flood the network with new rendezvous circuits that is reducing load on the network. +A secondary mitigation is available, based on prioritized dispatch of rendezvous +circuits for new connections. The queue is ordered based on effort a client +chooses to spend at computing a proof-of-work function. + +The following options are per onion service: + +[[HiddenServicePoWDefensesEnabled]] **HiddenServicePoWDefensesEnabled** **0**|**1**:: + + Enable proof-of-work based service DoS mitigation. If set to 1 (enabled), + tor will include parameters for an optional client puzzle in the encrypted + portion of this hidden service's descriptor. Incoming rendezvous requests + will be prioritized based on the amount of effort a client chooses to make + when computing a solution to the puzzle. The service will periodically update + a suggested amount of effort, based on attack load, and disable the puzzle + entirely when the service is not overloaded. + (Default: 0) + +[[HiddenServicePoWQueueRate]] **HiddenServicePoWQueueRate** __NUM__:: + + The sustained rate of rendezvous requests to dispatch per second from + the priority queue. Has no effect when proof-of-work is disabled. + If this is set to 0 there's no explicit limit and we will process + requests as quickly as possible. + (Default: 250) + +[[HiddenServicePoWQueueBurst]] **HiddenServicePoWQueueBurst** __NUM__:: + + The maximum burst size for rendezvous requests handled from the + priority queue at once. (Default: 2500) + +These options are applicable to both onion services and their clients: + +[[CompiledProofOfWorkHash]] **CompiledProofOfWorkHash** **0**|**1**|**auto**:: + When proof-of-work DoS mitigation is active, both the services themselves + and the clients which connect will use a dynamically generated hash + function as part of the puzzle computation. + + + If this option is set to 1, puzzles will only be solved and verified using + the compiled implementation (about 20x faster) and we choose to fail rather + than using a slower fallback. If it's 0, the compiler will never be used. + By default, the compiler is always tried if possible but the interpreter is + available as a fallback. (Default: auto) + +See also <<opt-list-modules,`--list-modules`>>, these proof of work options +have no effect unless the "`pow`" module is enabled at compile time. == DIRECTORY AUTHORITY SERVER OPTIONS @@ -3532,7 +3592,7 @@ Service side: configured, the service will be accessible to anyone with the onion address. Revoking a client can be done by removing their ".auth" file, however the - revocation will be in effect only after the tor process gets restarted even if + revocation will be in effect only after the tor process gets restarted or if a SIGHUP takes place. Client side: @@ -3588,7 +3648,6 @@ The following options are used for running a testing Tor network. TestingDirConnectionMaxStall 30 seconds TestingEnableConnBwEvent 1 TestingEnableCellStatsEvent 1 - RendPostPeriod 2 minutes [[TestingAuthDirTimeToLearnReachability]] **TestingAuthDirTimeToLearnReachability** __N__ **seconds**|**minutes**|**hours**:: After starting as an authority, do not make claims about whether routers |