diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING/CodeStructure.md | 129 | ||||
| -rw-r--r-- | doc/HACKING/CodingStandards.md | 27 | ||||
| -rw-r--r-- | doc/HACKING/CodingStandardsRust.md | 2 | ||||
| -rw-r--r-- | doc/HACKING/HelpfulTools.md | 36 | ||||
| -rw-r--r-- | doc/HACKING/Module.md | 30 | ||||
| -rw-r--r-- | doc/HACKING/ReleasingTor.md | 2 | ||||
| -rw-r--r-- | doc/HACKING/Tracing.md | 2 | ||||
| -rw-r--r-- | doc/HACKING/WritingTests.md | 4 | ||||
| -rw-r--r-- | doc/include.am | 13 | ||||
| -rw-r--r-- | doc/tor-print-ed-signing-cert.1.txt | 32 | ||||
| -rw-r--r-- | doc/tor-resolve.1.txt | 2 | ||||
| -rw-r--r-- | doc/tor.1.txt | 150 |
12 files changed, 342 insertions, 87 deletions
diff --git a/doc/HACKING/CodeStructure.md b/doc/HACKING/CodeStructure.md new file mode 100644 index 0000000000..736d6cd484 --- /dev/null +++ b/doc/HACKING/CodeStructure.md @@ -0,0 +1,129 @@ + +TODO: revise this to talk about how things are, rather than how things +have changed. + +TODO: Make this into good markdown. + + + +For quite a while now, the program "tor" has been built from source +code in just two directories: src/common and src/or. + +This has become more-or-less untenable, for a few reasons -- most +notably of which is that it has led our code to become more +spaghetti-ish than I can endorse with a clean conscience. + +So to fix that, we've gone and done a huge code movement in our git +master branch, which will land in a release once Tor 0.3.5.1-alpha is +out. + +Here's what we did: + + * src/common has been turned into a set of static libraries. These +all live in the "src/lib/*" directories. The dependencies between +these libraries should have no cycles. The libraries are: + + arch -- Headers to handle architectural differences + cc -- headers to handle differences among compilers + compress -- wraps zlib, zstd, lzma + container -- high-level container types + crypt_ops -- Cryptographic operations. Planning to split this into +a higher and lower level library + ctime -- Operations that need to run in constant-time. (Properly, +data-invariant time) + defs -- miscelaneous definitions needed throughout Tor. + encoding -- transforming one data type into another, and various +data types into strings. + err -- lowest-level error handling, in cases where we can't use +the logs because something that the logging system needs has broken. + evloop -- Generic event-loop handling logic + fdio -- Low-level IO wrapper functions for file descriptors. + fs -- Operations on the filesystem + intmath -- low-level integer math and misc bit-twiddling hacks + lock -- low-level locking code + log -- Tor's logging module. This library sits roughly halfway up +the library dependency diagram, since everything it depends on has to +be carefully crafted to *not* log. + malloc -- Low-level wrappers for the platform memory allocation functions. + math -- Higher-level mathematical functions, and floating-point math + memarea -- An arena allocator + meminfo -- Functions for querying the current process's memory +status and resources + net -- Networking compatibility and convenience code + osinfo -- Querying information about the operating system + process -- Launching and querying the status of other processes + sandbox -- Backend for the linux seccomp2 sandbox + smartlist_core -- The lowest-level of the smartlist_t data type. +Separated from the rest of the containers library because the logging +subsystem depends on it. + string -- Compatibility and convenience functions for manipulating +C strings. + term -- Terminal-related functions (currently limited to a getpass +function). + testsupport -- Macros for mocking, unit tests, etc. + thread -- Higher-level thread compatibility code + time -- Higher-level time management code, including format +conversions and monotonic time + tls -- Our wrapper around our TLS library + trace -- Formerly src/trace -- a generic event tracing API + wallclock -- Low-level time code, used by the log module. + + * To ensure that the dependency graph in src/common remains under +control, there is a tool that you can run called "make +check-includes". It verifies that each module in Tor only includes +the headers that it is permitted to include, using a per-directory +".may_include" file. + + * The src/or/or.h header has been split into numerous smaller +headers. Notably, many important structures are now declared in a +header called foo_st.h, where "foo" is the name of the structure. + + * The src/or directory, which had most of Tor's code, had been split +up into several directories. This is still a work in progress: This +code has not itself been refactored, and its dependency graph is still +a tangled web. I hope we'll be working on that over the coming +releases, but it will take a while to do. + + The new top-level source directories are: + + src/core -- Code necessary to actually perform or use onion routing. + src/feature -- Code used only by some onion routing +configurations, or only for a special purpose. + src/app -- Top-level code to run, invoke, and configure the +lower-level code + + The new second-level source directories are: + src/core/crypto -- High-level cryptographic protocols used in Tor + src/core/mainloop -- Tor's event loop, connection-handling, and +traffic-routing code. + src/core/or -- Parts related to handling onion routing itself + src/core/proto -- support for encoding and decoding different +wire protocols + + src/feature/api -- Support for making Tor embeddable + src/feature/client -- Functionality which only Tor clients need + src/feature/control -- Controller implementation + src/feature/dirauth -- Directory authority + src/feature/dircache -- Directory cache + src/feature/dirclient -- Directory client + src/feature/dircommon -- Shared code between the other directory modules + src/feature/hibernate -- Hibernating when Tor is out of bandwidth +or shutting down + src/feature/hs -- v3 onion service implementation + src/feature/hs_common -- shared code between both onion service +implementations + src/feature/nodelist -- storing and accessing the list of relays on +the network. + src/feature/relay -- code that only relay servers and exit servers need. + src/feature/rend -- v2 onion service implementation + src/feature/stats -- statistics and history + + src/app/config -- configuration and state for Tor + src/app/main -- Top-level functions to invoke the rest or Tor. + + * The "tor" executable is now built in src/app/tor rather than src/or/tor. + + * There are more static libraries than before that you need to build +into your application if you want to embed Tor. Rather than +maintaining this list yourself, I recommend that you run "make +show-libs" to have Tor emit a list of what you need to link. diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index 3711f70198..4f229348e4 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -172,7 +172,6 @@ deviations from our C whitespace style. Generally, we use: - Unix-style line endings - K&R-style indentation - No space before newlines - - A blank line at the end of each file - Never more than one blank line in a row - Always spaces, never tabs - No more than 79-columns per line. @@ -185,6 +184,9 @@ deviations from our C whitespace style. Generally, we use: `puts (x)`. - Function declarations at the start of the line. +If you use an editor that has plugins for editorconfig.org, the file +`.editorconfig` will help you to conform this coding 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 @@ -198,8 +200,8 @@ We have some wrapper functions like `tor_malloc`, `tor_free`, `tor_strdup`, and always succeed or exit.) You can get a full list of the compatibility functions that Tor provides by -looking through `src/common/util*.h` and `src/common/compat*.h`. You can see the -available containers in `src/common/containers*.h`. You should probably +looking through `src/lib/*/*.h`. You can see the +available containers in `src/lib/containers/*.h`. You should probably familiarize yourself with these modules before you write too much code, or else you'll wind up reinventing the wheel. @@ -212,6 +214,24 @@ We don't call `memcmp()` directly. Use `fast_memeq()`, `fast_memneq()`, Also see a longer list of functions to avoid in: https://people.torproject.org/~nickm/tor-auto/internal/this-not-that.html +What code can use what other code? +---------------------------------- + +We're trying to simplify Tor's structure over time. In the long run, we want +Tor to be structured as a set of modules with *no circular dependencies*. + +This property is currently provided by the modules in src/lib, but not +throughout the rest of Tor. In general, higher-level libraries may use +lower-level libraries, but never the reverse. + +To prevent new circular dependencies from landing, we have a tool that +you can invoke with `make check-includes`, and which is run +automatically as part of `make check`. This tool will verify that, for +every source directory with a `.may_include` file, no local headers are +included except those specifically permitted by the `.may_include` file. +When editing one of these files, please make sure that you are not +introducing any cycles into Tor's dependency graph. + Floating point math is hard --------------------------- @@ -434,4 +454,3 @@ the functions that call your function rely on it doing something, then your function should mention that it does that something in the documentation. If you rely on a function doing something beyond what is in its documentation, then you should watch out, or it might do something else later. - diff --git a/doc/HACKING/CodingStandardsRust.md b/doc/HACKING/CodingStandardsRust.md index d9496c08f7..fc562816db 100644 --- a/doc/HACKING/CodingStandardsRust.md +++ b/doc/HACKING/CodingStandardsRust.md @@ -104,7 +104,7 @@ repo. Documentation --------------- -You MUST include `#[deny(missing_docs)]` in your crate. +You MUST include `#![deny(missing_docs)]` in your crate. For function/method comments, you SHOULD include a one-sentence, "first person" description of function behaviour (see requirements for documentation as diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md index a0795076e0..d499238526 100644 --- a/doc/HACKING/HelpfulTools.md +++ b/doc/HACKING/HelpfulTools.md @@ -4,9 +4,16 @@ Useful tools These aren't strictly necessary for hacking on Tor, but they can help track down bugs. -Travis CI ---------- -It's CI. Looks like this: https://travis-ci.org/torproject/tor. +Travis/Appveyor CI +------------------ +It's CI. + +Looks like this: +* https://travis-ci.org/torproject/tor +* https://ci.appveyor.com/project/torproject/tor + +Travis builds and runs tests on Linux, and eventually macOS (#24629). +Appveyor builds and runs tests on Windows (using Windows Services for Linux). Runs automatically on Pull Requests sent to torproject/tor. You can set it up for your fork to build commits outside of PRs too: @@ -16,6 +23,8 @@ for your fork to build commits outside of PRs too: https://help.github.com/articles/fork-a-repo/ 3. follow https://docs.travis-ci.com/user/getting-started/#To-get-started-with-Travis-CI. skip steps involving `.travis.yml` (we already have one). +4. go to https://ci.appveyor.com/login , log in with github, and select + "NEW PROJECT" Builds should show up on the web at travis-ci.com and on IRC at #tor-ci on OFTC. If they don't, ask #tor-dev (also on OFTC). @@ -23,22 +32,21 @@ OFTC. If they don't, ask #tor-dev (also on OFTC). Jenkins ------- - https://jenkins.torproject.org +It's CI/builders. Looks like this: https://jenkins.torproject.org -Dmalloc -------- +Runs automatically on commits merged to git.torproject.org. We CI the +master branch and all supported tor versions. We also build nightly debian +packages from master. -The dmalloc library will keep track of memory allocation, so you can find out -if we're leaking memory, doing any double-frees, or so on. +Builds Linux and Windows cross-compilation. Runs Linux tests. - dmalloc -l -/dmalloc.log - (run the commands it tells you) - ./configure --with-dmalloc +Builds should show up on the web at jenkins.torproject.org and on IRC at +#tor-bots on OFTC. If they don't, ask #tor-dev (also on OFTC). Valgrind -------- - valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/or/tor + valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/app/tor (Note that if you get a zillion openssl warnings, you will also need to pass `--undef-value-errors=no` to valgrind, or rebuild your openssl @@ -242,10 +250,10 @@ Beforehand, install google-perftools. Now you can run Tor with profiling enabled, and use the pprof utility to look at performance! See the gperftools manual for more info, but basically: -2. Run `env CPUPROFILE=/tmp/profile src/or/tor -f <path/torrc>`. The profile file +2. Run `env CPUPROFILE=/tmp/profile src/app/tor -f <path/torrc>`. The profile file is not written to until Tor finishes execuction. -3. Run `pprof src/or/tor /tm/profile` to start the REPL. +3. Run `pprof src/app/tor /tm/profile` to start the REPL. Generating and analyzing a callgraph ------------------------------------ diff --git a/doc/HACKING/Module.md b/doc/HACKING/Module.md index 1028a029d9..9cf36090b4 100644 --- a/doc/HACKING/Module.md +++ b/doc/HACKING/Module.md @@ -12,9 +12,9 @@ Currently, there is only one module: - Directory Authority subsystem (dirauth) -It is located in its own directory in `src/or/dirauth/`. To disable it, one -need to pass `--disable-module-dirauth` at configure time. All modules are -currently enabled by default. +It is located in its own directory in `src/feature/dirauth/`. To disable it, +one need to pass `--disable-module-dirauth` at configure time. All modules +are currently enabled by default. ## Build System ## @@ -32,10 +32,10 @@ The changes to the build system are pretty straightforward. the C code to conditionally compile things for your module. And the `BUILD_MODULE_<name>` is also defined for automake files (e.g: include.am). -3. In the `src/or/include.am` file, locate the `MODULE_DIRAUTH_SOURCES` value. - You need to create your own `_SOURCES` variable for your module and then - conditionally add the it to `LIBTOR_A_SOURCES` if you should build the - module. +3. In the `src/core/include.am` file, locate the `MODULE_DIRAUTH_SOURCES` + value. You need to create your own `_SOURCES` variable for your module + and then conditionally add the it to `LIBTOR_A_SOURCES` if you should + build the module. It is then **very** important to add your SOURCES variable to `src_or_libtor_testing_a_SOURCES` so the tests can build it. @@ -51,7 +51,7 @@ always build everything in order to tests everything. ## Coding ## As mentioned above, a module must be isolated in its own directory (name of -the module) in `src/or/`. +the module) in `src/feature/`. There are couples of "rules" you want to follow: @@ -87,22 +87,22 @@ There are couples of "rules" you want to follow: making the code much more difficult to follow/understand. * It is possible that you end up with code that needs to be used by the rest - of the code base but is still part of your module. As a good example, if you - look at `src/or/shared_random_client.c`: it contains code needed by the hidden - service subsystem but mainly related to the shared random subsystem very - specific to the dirauth module. + of the code base but is still part of your module. As a good example, if + you look at `src/feature/shared_random_client.c`: it contains code needed + by the hidden service subsystem but mainly related to the shared random + subsystem very specific to the dirauth module. This is fine but try to keep it as lean as possible and never use the same filename as the one in the module. For example, this is a bad idea and should never be done: - - `src/or/shared_random.c` - - `src/or/dirauth/shared_random.c` + - `src/feature/dirclient/shared_random.c` + - `src/feature/dirauth/shared_random.c` * When you include headers from the module, **always** use the full module path in your statement. Example: - `#include "dirauth/dirvote.h"` + `#include "feature/dirauth/dirvote.h"` The main reason is that we do **not** add the module include path by default so it needs to be specified. But also, it helps our human brain understand diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md index e70416c354..55a40fc89b 100644 --- a/doc/HACKING/ReleasingTor.md +++ b/doc/HACKING/ReleasingTor.md @@ -7,7 +7,7 @@ new Tor release: === 0. Preliminaries -1. Get at least three of weasel/arma/Sebastian/Sina to put the new +1. Get at least two of weasel/arma/Sebastian to put the new version number in their approved versions list. Give them a few days to do this if you can. diff --git a/doc/HACKING/Tracing.md b/doc/HACKING/Tracing.md index 349aade23a..24fa761310 100644 --- a/doc/HACKING/Tracing.md +++ b/doc/HACKING/Tracing.md @@ -69,7 +69,7 @@ configure option: ## Instrument Tor ## This is pretty easy. Let's say you want to add a trace event in -`src/or/rendcache.c`, you only have to add this include statement: +`src/feature/rend/rendcache.c`, you only have to add this include statement: #include "trace/events.h" diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md index cc393494ec..05de8e0be8 100644 --- a/doc/HACKING/WritingTests.md +++ b/doc/HACKING/WritingTests.md @@ -7,8 +7,8 @@ keep from introducing bugs. The major ones are: 1. Unit tests written in C and shipped with the Tor distribution. - 2. Integration tests written in Python and shipped with the Tor - distribution. + 2. Integration tests written in Python 2 (>= 2.7) or Python 3 + (>= 3.1) and shipped with the Tor distribution. 3. Integration tests written in Python and shipped with the Stem library. Some of these use the Tor controller protocol. diff --git a/doc/include.am b/doc/include.am index 7942188eaf..0a123aae11 100644 --- a/doc/include.am +++ b/doc/include.am @@ -12,7 +12,7 @@ # part of the source distribution, so that people without asciidoc can # just use the .1 and .html files. -all_mans = doc/tor doc/tor-gencert doc/tor-resolve doc/torify +all_mans = doc/tor doc/tor-gencert doc/tor-resolve doc/torify doc/tor-print-ed-signing-cert if USE_ASCIIDOC nodist_man1_MANS = $(all_mans:=.1) @@ -29,13 +29,14 @@ doc_DATA = endif EXTRA_DIST+= doc/asciidoc-helper.sh \ - $(html_in) $(man_in) $(txt_in) \ - doc/state-contents.txt \ - doc/torrc_format.txt \ + $(html_in) $(man_in) $(txt_in) \ + doc/state-contents.txt \ + doc/torrc_format.txt \ doc/TUNING \ doc/HACKING/README.1st.md \ doc/HACKING/CodingStandards.md \ doc/HACKING/CodingStandardsRust.md \ + doc/HACKING/CodeStructure.md \ doc/HACKING/Fuzzing.md \ doc/HACKING/GettingStarted.md \ doc/HACKING/GettingStartedRust.md \ @@ -64,11 +65,13 @@ doc/tor.1.in: doc/tor.1.txt doc/torify.1.in: doc/torify.1.txt doc/tor-gencert.1.in: doc/tor-gencert.1.txt doc/tor-resolve.1.in: doc/tor-resolve.1.txt +doc/tor-print-ed-signing-cert.1.in: doc/tor-print-ed-signing-cert.1.txt doc/tor.html.in: doc/tor.1.txt doc/torify.html.in: doc/torify.1.txt doc/tor-gencert.html.in: doc/tor-gencert.1.txt doc/tor-resolve.html.in: doc/tor-resolve.1.txt +doc/tor-print-ed-signing-cert.html.in: doc/tor-print-ed-signing-cert.1.txt # use config.status to swap all machine-specific magic strings # in the asciidoc with their replacements. @@ -82,11 +85,13 @@ $(asciidoc_product) : doc/tor.html: doc/tor.html.in doc/tor-gencert.html: doc/tor-gencert.html.in doc/tor-resolve.html: doc/tor-resolve.html.in +doc/tor-print-ed-signing-cert.html: doc/tor-print-ed-signing-cert.html.in doc/torify.html: doc/torify.html.in doc/tor.1: doc/tor.1.in doc/tor-gencert.1: doc/tor-gencert.1.in doc/tor-resolve.1: doc/tor-resolve.1.in +doc/tor-print-ed-signing-cert.1: doc/tor-print-ed-signing-cert.1.in doc/torify.1: doc/torify.1.in CLEANFILES+= $(asciidoc_product) diff --git a/doc/tor-print-ed-signing-cert.1.txt b/doc/tor-print-ed-signing-cert.1.txt new file mode 100644 index 0000000000..1a3109df95 --- /dev/null +++ b/doc/tor-print-ed-signing-cert.1.txt @@ -0,0 +1,32 @@ +// Copyright (c) The Tor Project, Inc. +// See LICENSE for licensing information +// This is an asciidoc file used to generate the manpage/html reference. +// Learn asciidoc on http://www.methods.co.nz/asciidoc/userguide.html +:man source: Tor +:man manual: Tor Manual +tor-print-ed-signing-cert(1) +============================ +Tor Project, Inc. + +NAME +---- +tor-print-ed-signing-cert - print expiration date of ed25519 signing certificate + +SYNOPSIS +-------- +**tor-print-ed-signing-cert** __<path to ed25519_signing_cert file>__ + +DESCRIPTION +----------- +**tor-print-ed-signing-cert** is utility program for Tor relay operators to +check expiration date of ed25519 signing certificate. + +SEE ALSO +-------- +**tor**(1) + + +https://spec.torproject.org/cert-spec + +AUTHORS +------- +Roger Dingledine <arma@mit.edu>, Nick Mathewson <nickm@alum.mit.edu>. diff --git a/doc/tor-resolve.1.txt b/doc/tor-resolve.1.txt index 30e16d5daa..f1f8f77a42 100644 --- a/doc/tor-resolve.1.txt +++ b/doc/tor-resolve.1.txt @@ -47,7 +47,7 @@ SEE ALSO -------- **tor**(1), **torify**(1). + -See doc/socks-extensions.txt in the Tor package for protocol details. +For protocol details, see: https://spec.torproject.org/socks-extensions AUTHORS ------- diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 3f7a8c39af..975a198182 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -303,8 +303,15 @@ GENERAL OPTIONS descriptors as the OS will allow (you can find this by "ulimit -H -n"). If this number is less than ConnLimit, then Tor will refuse to start. + + - You probably don't need to adjust this. It has no effect on Windows - since that platform lacks getrlimit(). (Default: 1000) + Tor relays need thousands of sockets, to connect to every other relay. + If you are running a private bridge, you can reduce the number of sockets + that Tor uses. For example, to limit Tor to 500 sockets, run + "ulimit -n 500" in a shell. Then start tor in the same shell, with + **ConnLimit 500**. You may also need to set **DisableOOSCheck 0**. + + + + Unless you have severely limited sockets, you probably don't need to + adjust **ConnLimit** itself. It has no effect on Windows, since that + platform lacks getrlimit(). (Default: 1000) [[DisableNetwork]] **DisableNetwork** **0**|**1**:: When this option is set, we don't listen for or accept any connections @@ -604,6 +611,7 @@ GENERAL OPTIONS ServerDNSResolvConfFile Tor must remain in client or server mode (some changes to ClientOnly and ORPort are not allowed). + ClientOnionAuthDir and any files in it won't reload on HUP signal. (Default: 0) [[Socks4Proxy]] **Socks4Proxy** __host__[:__port__]:: @@ -628,9 +636,7 @@ GENERAL OPTIONS [[KeepalivePeriod]] **KeepalivePeriod** __NUM__:: To keep firewalls from expiring connections, send a padding keepalive cell - every NUM seconds on open connections that are in use. If the connection - has no open circuits, it will instead be closed after NUM seconds of - idleness. (Default: 5 minutes) + every NUM seconds on open connections that are in use. (Default: 5 minutes) [[Log]] **Log** __minSeverity__[-__maxSeverity__] **stderr**|**stdout**|**syslog**:: Send all messages between __minSeverity__ and __maxSeverity__ to the standard @@ -756,7 +762,9 @@ GENERAL OPTIONS If this option is set to 0, Tor will not perform any scrubbing, if it is set to 1, all potentially sensitive strings are replaced. If it is set to 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) + all messages generated when acting as a client are not. + Note: Tor may not heed this option when logging at log levels below Notice. + (Default: 1) [[User]] **User** __Username__:: On startup, setuid to this user and setgid to their primary group. @@ -1080,6 +1088,18 @@ The following options are useful only for clients (that is, if services can be configured to require authorization using the **HiddenServiceAuthorizeClient** option. +[[ClientOnionAuthDir]] **ClientOnionAuthDir** __path__:: + Path to the directory containing v3 hidden service authorization files. + Each file is for a single onion address, and the files MUST have the suffix + ".auth_private" (i.e. "bob_onion.auth_private"). The content format MUST be: + + + <onion-address>:descriptor:x25519:<base32-encoded-privkey> + + + The <onion-address> MUST NOT have the ".onion" suffix. The + <base32-encoded-privkey> is the base32 representation of the raw key bytes + only (32 bytes for x25519). See Appendix G in the rend-spec-v3.txt file of + https://spec.torproject.org/[torspec] for more information. + [[LongLivedPorts]] **LongLivedPorts** __PORTS__:: A list of ports for services that tend to have long-running connections (e.g. chat and interactive shells). Circuits for streams that use these @@ -1337,8 +1357,8 @@ The following options are useful only for clients (that is, if 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. 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) + Authorities or Single Onion Services. In these cases, + this option is ignored. (Default: 1) [[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: V3 authoritative directories only. Configures the location of the @@ -1346,7 +1366,7 @@ The following options are useful only for clients (that is, if have been guards. (Default: unset) [[UseGuardFraction]] **UseGuardFraction** **0**|**1**|**auto**:: - This torrc option specifies whether clients should use the + This option specifies whether clients should use the guardfraction information found in the consensus during path selection. If it's set to 'auto', clients will do what the UseGuardFraction consensus parameter tells them to do. (Default: auto) @@ -1527,32 +1547,6 @@ The following options are useful only for clients (that is, if Tor will look at the UseOptimisticData parameter in the networkstatus. (Default: auto) -[[Tor2webMode]] **Tor2webMode** **0**|**1**:: - When this option is set, Tor connects to hidden services - **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-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 - address patterns of nodes that are allowed to be used as RPs - in HS circuits; any other nodes will not be used as RPs. - (Example: - Tor2webRendezvousPoints Fastyfasty, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + - + - This feature can only be used if Tor2webMode is also enabled. + - + - ExcludeNodes have higher priority than Tor2webRendezvousPoints, - which means that nodes specified in ExcludeNodes will not be - picked as RPs. + - + - If no nodes in Tor2webRendezvousPoints are currently available for - use, Tor will choose a random node when building HS circuits. - [[HSLayer2Nodes]] **HSLayer2Nodes** __node__,__node__,__...__:: A list of identity fingerprints, nicknames, country codes, and address patterns of nodes that are allowed to be used as the @@ -1733,9 +1727,10 @@ The following options are useful only for clients (that is, if [[ClientUseIPv6]] **ClientUseIPv6** **0**|**1**:: If this option is set to 1, Tor might connect to directory servers or - entry nodes over IPv6. Note that clients configured with an IPv6 address - in a **Bridge**, proxy, or pluggable transport line will try connecting - over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0) + 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) [[ClientPreferIPv6DirPort]] **ClientPreferIPv6DirPort** **0**|**1**|**auto**:: If this option is set to 1, Tor prefers a directory port with an IPv6 @@ -1821,7 +1816,10 @@ is non-zero): Sets the relay to act as a "bridge" with respect to relaying connections from bridge users to the Tor network. It mainly causes Tor to publish a server descriptor to the bridge database, rather than - to the public directory authorities. + to the public directory authorities. + + + + Note: make sure that no MyFamily lines are present in your torrc when + relay is configured in bridge mode. [[BridgeDistribution]] **BridgeDistribution** __string__:: If set along with BridgeRelay, Tor will include a new line in its @@ -2078,7 +2076,10 @@ is non-zero): nickname: fingerprints are more reliable. + + If you run more than one relay, the MyFamily option on each relay - **must** list all other relays, as described above. + **must** list all other relays, as described above. + + + + Note: do not use MyFamily when configuring your Tor instance as a + brigde. [[Nickname]] **Nickname** __name__:: Set the server's nickname to \'name'. Nicknames must be between 1 and 19 @@ -2749,7 +2750,9 @@ on the public Tor network. [[V3BandwidthsFile]] **V3BandwidthsFile** __FILENAME__:: V3 authoritative directories only. Configures the location of the bandwidth-authority generated file storing information on relays' measured - bandwidth capacities. (Default: unset) + bandwidth capacities. To avoid inconsistent reads, bandwidth data should + be written to temporary file, then renamed to the configured filename. + (Default: unset) [[V3AuthUseLegacyKey]] **V3AuthUseLegacyKey** **0**|**1**:: If set, the directory authority will sign consensuses not only with its @@ -2814,7 +2817,7 @@ The following options are used to configure a hidden service. 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. + chosen at random. Note that address-port pairs have to be comma-separated. [[PublishHidServDescriptors]] **PublishHidServDescriptors** **0**|**1**:: If set to 0, Tor will run any hidden services you configure, but it won't @@ -2824,7 +2827,7 @@ The following options are used to configure a hidden service. [[HiddenServiceVersion]] **HiddenServiceVersion** **2**|**3**:: A list of rendezvous service descriptor versions to publish for the hidden - service. Currently, versions 2 and 3 are supported. (Default: 2) + service. Currently, versions 2 and 3 are supported. (Default: 3) [[HiddenServiceAuthorizeClient]] **HiddenServiceAuthorizeClient** __auth-type__ __client-name__,__client-name__,__...__:: If configured, the hidden service is accessible for authorized clients @@ -2837,7 +2840,8 @@ The following options are used to configure a hidden service. clients without authorization any more. Generated authorization data can be found in the hostname file. Clients need to put this authorization data in their configuration file using **HidServAuth**. This option is only for v2 - services. + services; v3 services configure client authentication in a subdirectory of + HiddenServiceDir instead (see the **Client Authorization** section). [[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**:: If set to 1, then connections to unrecognized ports do not cause the @@ -2845,6 +2849,33 @@ The following options are used to configure a hidden service. not an authorization mechanism; it is instead meant to be a mild inconvenience to port-scanners.) (Default: 0) +[[HiddenServiceExportCircuitID]] **HiddenServiceExportCircuitID** __protocol__:: + The onion service will use the given protocol to expose the global circuit + identifier of each inbound client circuit via the selected protocol. The only + protocol supported right now \'haproxy'. This option is only for v3 + services. (Default: none) + + + + The haproxy option works in the following way: when the feature is + enabled, the Tor process will write a header line when a client is connecting + to the onion service. The header will look like this: + + + + "PROXY TCP6 fc00:dead:beef:4dad::ffff:ffff ::1 65535 42\r\n" + + + + We encode the "global circuit identifier" as the last 32-bits of the first + IPv6 address. All other values in the header can safely be ignored. You can + compute the global circuit identifier using the following formula given the + IPv6 address "fc00:dead:beef:4dad::AABB:CCDD": + + + + global_circuit_id = (0xAA << 24) + (0xBB << 16) + (0xCC << 8) + 0xDD; + + + + In the case above, where the last 32-bit is 0xffffffff, the global circuit + identifier would be 4294967295. You can use this value together with Tor's + control port where it is possible to terminate a circuit given the global + circuit identifier. For more information about this see controls-spec.txt. + + + + The HAProxy version 1 proxy protocol is described in detail at + https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt + [[HiddenServiceMaxStreams]] **HiddenServiceMaxStreams** __N__:: The maximum number of simultaneous streams (connections) per rendezvous circuit. The maximum value allowed is 65535. (Setting this to 0 will allow @@ -2906,6 +2937,37 @@ The following options are used to configure a hidden service. including setting SOCKSPort to "0". Can not be changed while tor is running. (Default: 0) +Client Authorization +-------------------- + +(Version 3 only) + +To configure client authorization on the service side, the +"<HiddenServiceDir>/authorized_clients/" directory needs to exist. Each file +in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the +file name is irrelevant) and its content format MUST be: + + <auth-type>:<key-type>:<base32-encoded-public-key> + +The supported <auth-type> are: "descriptor". The supported <key-type> are: +"x25519". The <base32-encoded-public-key> is the base32 representation of +the raw key bytes only (32 bytes for x25519). + +Each file MUST contain one line only. Any malformed file will be +ignored. Client authorization will only be enabled for the service if tor +successfully loads at least one authorization file. + +Note that once you've configured client authorization, anyone else with the +address won't be able to access it from this point on. If no authorization is +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 +a SIGHUP takes place. + +See the Appendix G in the rend-spec-v3.txt file of +https://spec.torproject.org/[torspec] for more information. + TESTING NETWORK OPTIONS ----------------------- |