diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING/CircuitPaddingQuickStart.md | 3 | ||||
| -rw-r--r-- | doc/HACKING/CodeStructure.md | 1 | ||||
| -rw-r--r-- | doc/HACKING/CodingStandards.md | 60 | ||||
| -rw-r--r-- | doc/HACKING/CodingStandardsRust.md | 60 | ||||
| -rw-r--r-- | doc/HACKING/EndOfLifeTor.md | 50 | ||||
| -rw-r--r-- | doc/HACKING/Fuzzing.md | 2 | ||||
| -rw-r--r-- | doc/HACKING/GettingStarted.md | 74 | ||||
| -rw-r--r-- | doc/HACKING/GettingStartedRust.md | 48 | ||||
| -rw-r--r-- | doc/HACKING/HelpfulTools.md | 61 | ||||
| -rw-r--r-- | doc/HACKING/HowToReview.md | 18 | ||||
| -rw-r--r-- | doc/HACKING/Module.md | 8 | ||||
| -rw-r--r-- | doc/HACKING/README.1st.md | 43 | ||||
| -rw-r--r-- | doc/HACKING/ReleaseSeriesLifecycle.md | 113 | ||||
| -rw-r--r-- | doc/HACKING/ReleasingTor.md | 20 | ||||
| -rw-r--r-- | doc/HACKING/Tracing.md | 12 | ||||
| -rw-r--r-- | doc/HACKING/WritingTests.md | 45 | ||||
| -rw-r--r-- | doc/HACKING/android/Simpleperf.md | 1 | ||||
| -rw-r--r-- | doc/tor.1.txt | 701 |
18 files changed, 645 insertions, 675 deletions
diff --git a/doc/HACKING/CircuitPaddingQuickStart.md b/doc/HACKING/CircuitPaddingQuickStart.md index 167ff9f292..2780b5c6ea 100644 --- a/doc/HACKING/CircuitPaddingQuickStart.md +++ b/doc/HACKING/CircuitPaddingQuickStart.md @@ -47,6 +47,7 @@ If you want to install on your localsystem, run `make install`. For our case we just want the tor binary at `src/app/tor`. ## Use tor in TB and at a relay + Download and install a fresh Tor Browser (TB) from torproject.org. Make sure it works. From the command line, relative to the folder created when you extracted TB, run `./Browser/start-tor-browser --verbose` to get some basic log output. @@ -75,6 +76,7 @@ relay. Start TB, visit a website, and manually confirm that the middle is used by looking at the circuit display. ## Add a bare-bones APE padding machine + Now the fun part. We have several resources at our disposal (mind that links might be broken in the future, just search for the headings): - The official [Circuit Padding Developer @@ -192,6 +194,7 @@ register our machines: We run `make` to get a new `tor` binary and copy it to our local TB. ## Run the machine + To be able to view circuit info events in the console as we launch TB, we add `Log [circ]info notice stdout` to `torrc` of TB. diff --git a/doc/HACKING/CodeStructure.md b/doc/HACKING/CodeStructure.md index fffafcaed1..d387018f9b 100644 --- a/doc/HACKING/CodeStructure.md +++ b/doc/HACKING/CodeStructure.md @@ -1,3 +1,4 @@ +# Code Structure TODO: revise this to talk about how things are, rather than how things have changed. diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index 7999724166..a181759d60 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -1,5 +1,4 @@ -Coding conventions for Tor -========================== +# Coding conventions for Tor tl;dr: @@ -10,8 +9,7 @@ tl;dr: - Run `make distcheck` if you have made changes to build system components - Add a file in `changes` for your branch. -Patch checklist ---------------- +## Patch checklist If possible, send your patch as one of these (in descending order of preference) @@ -34,7 +32,7 @@ Did you remember... If you are submitting a major patch or new feature, or want to in the future... - - Set up Chutney and Stem, see HACKING/WritingTests.md + - Set up Chutney and Stem, see `doc/HACKING/WritingTests.md` - Run `make test-full` to test against all unit and integration tests. If you have changed build system components: @@ -42,9 +40,7 @@ If you have changed build system components: - For example, if you have changed Makefiles, autoconf files, or anything else that affects the build system. - -License issues -============== +## License issues Tor is distributed under the license terms in the LICENSE -- in brief, the "3-clause BSD license". If you send us code to @@ -58,9 +54,7 @@ Some compatible licenses include: - 2-clause BSD - CC0 Public Domain Dedication - -How we use Git branches -======================= +## How we use Git branches Each main development series (like 0.2.1, 0.2.2, etc) has its main work applied to a single branch. At most one series can be the development series @@ -91,9 +85,7 @@ conflicts in the ChangeLog when it comes time to merge your branch into Tor. Best advice: don't try to keep an independent branch forked for more than 6 months and expect it to merge cleanly. Try to merge pieces early and often. - -How we log changes -================== +## How we log changes When you do a commit that needs a ChangeLog entry, add a new file to the `changes` toplevel subdirectory. It should have the format of a @@ -199,8 +191,7 @@ Why use changes files instead of entries in the ChangeLog? * Having every single commit touch the ChangeLog file tended to create zillions of merge conflicts. -Whitespace and C conformance ----------------------------- +## Whitespace and C conformance Invoke `make check-spaces` from time to time, so it can tell you about deviations from our C whitespace style. Generally, we use: @@ -231,8 +222,7 @@ 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 --------------------------------------- +## Functions to use; functions not to use We have some wrapper functions like `tor_malloc`, `tor_free`, `tor_strdup`, and `tor_gettimeofday;` use them instead of their generic equivalents. (They @@ -250,7 +240,6 @@ 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. - We don't use `strcat` or `strcpy` or `sprintf` of any of those notoriously broken old C functions. We also avoid `strncat` and `strncpy`. Use `strlcat`, `strlcpy`, or `tor_snprintf/tor_asprintf` instead. @@ -281,9 +270,7 @@ version prefixed with `tor_` instead: strtok_r, memmem, memstr, asprintf, localtime_r, gmtime_r, inet_aton, inet_ntop, inet_pton, getpass, ntohll, htonll. (This list is incomplete.) - -What code can use what other code? ----------------------------------- +## 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*. @@ -300,8 +287,7 @@ 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 ---------------------------- +## Floating point math is hard Floating point arithmetic as typically implemented by computers is very counterintuitive. Failure to adequately analyze floating point @@ -360,8 +346,7 @@ For more detailed (and math-intensive) background, see [What Every Computer Scientist Should Know About Floating-Point Arithmetic](https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html). -Other C conventions -------------------- +## Other C conventions The `a ? b : c` trinary operator only goes inside other expressions; don't use it as a replacement for if. (You can ignore this inside macro @@ -370,8 +355,7 @@ definitions when necessary.) Assignment operators shouldn't nest inside other expressions. (You can ignore this inside macro definitions when necessary.) -Binary data and wire formats ----------------------------- +## Binary data and wire formats Use pointer to `char` when representing NUL-terminated string. To represent arbitrary binary data, use pointer to `uint8_t`. (Many older Tor APIs ignore @@ -390,8 +374,7 @@ for more information about trunnel. For information on adding new trunnel code to Tor, see src/trunnel/README -Calling and naming conventions ------------------------------- +## Calling and naming conventions Whenever possible, functions should return -1 on error and 0 on success. @@ -414,17 +397,15 @@ probably time to create an enum. If you find that you are passing three or more flags to a function, it's probably time to create a flags argument that takes a bitfield. -What To Optimize ----------------- +## What To Optimize Don't optimize anything if it's not in the critical path. Right now, the critical path seems to be AES, logging, and the network itself. Feel free to do your own profiling to determine otherwise. -Log conventions ---------------- +## Log conventions -`https://www.torproject.org/docs/faq#LogLevel` +[FAQ - Log Levels](https://www.torproject.org/docs/faq#LogLevel) No error or warning messages should be expected during normal OR or OP operation. @@ -438,8 +419,7 @@ end-users that they aren't expected to understand the message (perhaps with a string like "internal error"). Option (A) is to be preferred to option (B). -Assertions In Tor ------------------ +## Assertions In Tor Assertions should be used for bug-detection only. Don't use assertions to detect bad user inputs, network errors, resource exhaustion, or similar @@ -458,8 +438,7 @@ macro, as in: if (BUG(ptr == NULL)) return -1; -Allocator conventions ---------------------- +## Allocator conventions By convention, any tor type with a name like `abc_t` should be allocated by a function named `abc_new()`. This function should never return @@ -500,8 +479,7 @@ to use it as a function callback), define it with a name like When deallocating, don't say e.g. `if (x) tor_free(x)`. The convention is to have deallocators do nothing when NULL pointer is passed. -Doxygen comment conventions ---------------------------- +## Doxygen comment conventions Say what functions do as a series of one or more imperative sentences, as though you were telling somebody how to be the function. In other words, DO diff --git a/doc/HACKING/CodingStandardsRust.md b/doc/HACKING/CodingStandardsRust.md index b570e10dc7..97026c9b7c 100644 --- a/doc/HACKING/CodingStandardsRust.md +++ b/doc/HACKING/CodingStandardsRust.md @@ -1,39 +1,36 @@ +# Rust Coding Standards - Rust Coding Standards -======================= - -You MUST follow the standards laid out in `.../doc/HACKING/CodingStandards.md`, +You MUST follow the standards laid out in `doc/HACKING/CodingStandards.md`, where applicable. - Module/Crate Declarations ---------------------------- +## Module/Crate Declarations Each Tor C module which is being rewritten MUST be in its own crate. -See the structure of `.../src/rust` for examples. +See the structure of `src/rust` for examples. In your crate, you MUST use `lib.rs` ONLY for pulling in external crates (e.g. `extern crate libc;`) and exporting public objects from other Rust modules (e.g. `pub use mymodule::foo;`). For example, if -you create a crate in `.../src/rust/yourcrate`, your Rust code should -live in `.../src/rust/yourcrate/yourcode.rs` and the public interface -to it should be exported in `.../src/rust/yourcrate/lib.rs`. +you create a crate in `src/rust/yourcrate`, your Rust code should +live in `src/rust/yourcrate/yourcode.rs` and the public interface +to it should be exported in `src/rust/yourcrate/lib.rs`. If your code is to be called from Tor C code, you MUST define a safe `ffi.rs`. See the "Safety" section further down for more details. For example, in a hypothetical `tor_addition` Rust module: -In `.../src/rust/tor_addition/addition.rs`: +In `src/rust/tor_addition/addition.rs`: pub fn get_sum(a: i32, b: i32) -> i32 { a + b } -In `.../src/rust/tor_addition/lib.rs`: +In `src/rust/tor_addition/lib.rs`: pub use addition::*; -In `.../src/rust/tor_addition/ffi.rs`: +In `src/rust/tor_addition/ffi.rs`: #[no_mangle] pub extern "C" fn tor_get_sum(a: c_int, b: c_int) -> c_int { @@ -42,7 +39,7 @@ In `.../src/rust/tor_addition/ffi.rs`: If your Rust code must call out to parts of Tor's C code, you must declare the functions you are calling in the `external` crate, located -at `.../src/rust/external`. +at `src/rust/external`. <!-- XXX get better examples of how to declare these externs, when/how they --> <!-- XXX are unsafe, what they are expected to do —isis --> @@ -54,8 +51,7 @@ If you have any external modules as dependencies (e.g. `extern crate libc;`), you MUST declare them in your crate's `lib.rs` and NOT in any other module. - Dependencies and versions ---------------------------- +## Dependencies and versions In general, we use modules from only the Rust standard library whenever possible. We will review including external crates on a @@ -81,8 +77,7 @@ Currently, Tor requires that you use the latest stable Rust version. At some point in the future, we will freeze on a given stable Rust version, to ensure backward compatibility with stable distributions that ship it. - Updating/Adding Dependencies ------------------------------- +## Updating/Adding Dependencies To add/remove/update dependencies, first add your dependencies, exactly specifying their versions, into the appropriate *crate-level* @@ -101,14 +96,13 @@ Next, run `/scripts/maint/updateRustDependencies.sh`. Then, go into `src/ext/rust` and commit the changes to the `tor-rust-dependencies` repo. - Documentation ---------------- +## Documentation 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 -described in `.../src/HACKING/CodingStandards.md`), then an `# Inputs` section +described in `src/HACKING/CodingStandards.md`), then an `# Inputs` section for inputs or initialisation values, a `# Returns` section for return values/types, a `# Warning` section containing warnings for unsafe behaviours or panics that could happen. For publicly accessible @@ -118,14 +112,12 @@ types/constants/objects/functions/methods, you SHOULD also include an You MUST document your module with _module docstring_ comments, i.e. `//!` at the beginning of each line. - Style -------- +## Style You SHOULD consider breaking up large literal numbers with `_` when it makes it more human readable to do so, e.g. `let x: u64 = 100_000_000_000`. - Testing ---------- +## Testing All code MUST be unittested and integration tested. @@ -134,7 +126,7 @@ describing how the function/object is expected to be used. Integration tests SHOULD go into a `tests/` directory inside your crate. Unittests SHOULD go into their own module inside the module -they are testing, e.g. in `.../src/rust/tor_addition/addition.rs` you +they are testing, e.g. in `src/rust/tor_addition/addition.rs` you should put: #[cfg(test)] @@ -148,8 +140,7 @@ should put: } } - Benchmarking --------------- +## Benchmarking The external `test` crate can be used for most benchmarking. However, using this crate requires nightly Rust. Since we may want to switch to a more @@ -173,7 +164,7 @@ for basic benchmarks, is only used when running benchmarks via `cargo bench --features bench`. Finally, to write your benchmark code, in -`.../src/rust/tor_addition/addition.rs` you SHOULD put: +`src/rust/tor_addition/addition.rs` you SHOULD put: #[cfg(all(test, features = "bench"))] mod bench { @@ -186,23 +177,20 @@ Finally, to write your benchmark code, in } } - Fuzzing ---------- +## Fuzzing If you wish to fuzz parts of your code, please see the -[`cargo fuzz`](https://github.com/rust-fuzz/cargo-fuzz) crate, which uses +[cargo fuzz](https://github.com/rust-fuzz/cargo-fuzz) crate, which uses [libfuzzer-sys](https://github.com/rust-fuzz/libfuzzer-sys). - Whitespace & Formatting -------------------------- +## Whitespace & Formatting You MUST run `rustfmt` (https://github.com/rust-lang-nursery/rustfmt) on your code before your code will be merged. You can install rustfmt by doing `cargo install rustfmt-nightly` and then run it with `cargo fmt`. - Safety --------- +## Safety You SHOULD read [the nomicon](https://doc.rust-lang.org/nomicon/) before writing Rust FFI code. It is *highly advised* that you read and write normal Rust code diff --git a/doc/HACKING/EndOfLifeTor.md b/doc/HACKING/EndOfLifeTor.md deleted file mode 100644 index 2fece2ca9d..0000000000 --- a/doc/HACKING/EndOfLifeTor.md +++ /dev/null @@ -1,50 +0,0 @@ - -End of Life on an old release series ------------------------------------- - -Here are the steps that the maintainer should take when an old Tor release -series reaches End of Life. Note that they are _only_ for entire series that -have reached their planned EOL: they do not apply to security-related -deprecations of individual versions. - -### 0. Preliminaries - -0. A few months before End of Life: - Write a deprecation announcement. - Send the announcement out with every new release announcement. - -1. A month before End of Life: - Send the announcement to tor-announce, tor-talk, tor-relays, and the - packagers. - -### 1. On the day - -1. Open tickets to remove the release from: - - the jenkins builds - - tor's Travis CI cron jobs - - chutney's Travis CI tests (#) - - stem's Travis CI tests (#) - -2. Close the milestone in Trac. To do this, go to Trac, log in, - select "Admin" near the top of the screen, then select "Milestones" from - the menu on the left. Click on the milestone for this version, and - select the "Completed" checkbox. By convention, we select the date as - the End of Life date. - -3. Replace NNN-backport with NNN-unreached-backport in all open trac tickets. - -4. If there are any remaining tickets in the milestone: - - merge_ready tickets are for backports: - - if there are no supported releases for the backport, close the ticket - - if there is an earlier (LTS) release for the backport, move the ticket - to that release - - other tickets should be closed (if we won't fix them) or moved to a - supported release (if we will fix them) - -5. Mail the end of life announcement to tor-announce, the packagers list, - and tor-relays. The current list of packagers is in ReleasingTor.md. - -6. Ask at least two of weasel/arma/Sebastian to remove the old version - number from their approved versions list. - -7. Update the CoreTorReleases wiki page. diff --git a/doc/HACKING/Fuzzing.md b/doc/HACKING/Fuzzing.md index c2db7e9853..41853a8a23 100644 --- a/doc/HACKING/Fuzzing.md +++ b/doc/HACKING/Fuzzing.md @@ -11,7 +11,6 @@ To run the fuzzing test cases in a deterministic fashion, use: This won't actually fuzz Tor! It will just run all the fuzz binaries on our existing set of testcases for the fuzzer. - ## Different kinds of fuzzing Right now we support three different kinds of fuzzer. @@ -51,7 +50,6 @@ But the fuzzing harness should crash if tor fails an assertion, triggers a bug, or accesses memory it shouldn't. This helps fuzzing frameworks detect "interesting" cases. - ## Guided Fuzzing with AFL There is no HTTPS, hash, or signature for American Fuzzy Lop's source code, so diff --git a/doc/HACKING/GettingStarted.md b/doc/HACKING/GettingStarted.md index 0c42404634..c2ca74d960 100644 --- a/doc/HACKING/GettingStarted.md +++ b/doc/HACKING/GettingStarted.md @@ -1,23 +1,19 @@ - -Getting started in Tor development -================================== +# Getting started in Tor development Congratulations! You've found this file, and you're reading it! This means that you might be interested in getting started in developing Tor. -(This guide is just about Tor itself--the small network program at the +(_This guide is just about Tor itself--the small network program at the heart of the Tor network--and not about all the other programs in the -whole Tor ecosystem.) - +whole Tor ecosystem._) If you are looking for a more bare-bones, less user-friendly information -dump of important information, you might like reading the "torguts" -documents linked to below. You should probably read it before you write +dump of important information, you might like reading the +[doxygen output](https://src-ref.docs.torproject.org/tor/index.html). +You probably should skim some of the topic headings there before you write your first patch. - -Required background -------------------- +## Required background First, I'm going to assume that you can build Tor from source, and that you know enough of the C language to read and write it. (See the README @@ -26,22 +22,20 @@ and any high-quality guide to C for information on programming.) I'm also going to assume that you know a little bit about how to use Git, or that you're able to follow one of the several excellent guides -at http://git-scm.org to learn. +at [git-scm](http://git-scm.org) to learn. -Most Tor developers develop using some Unix-based system, such as Linux, -BSD, or OSX. It's okay to develop on Windows if you want, but you're +Most Tor developers develop using some Unix-based system, such as GNU/Linux, +BSD, or macOS. It's okay to develop on Windows if you want, but you're going to have a more difficult time. - -Getting your first patch into Tor ---------------------------------- +## Getting your first patch into Tor Once you've reached this point, here's what you need to know. 1. Get the source. We keep our source under version control in Git. To get the latest - version, run + version, run: git clone https://git.torproject.org/git/tor @@ -49,20 +43,18 @@ Once you've reached this point, here's what you need to know. going to fix a bug that appears in a stable version, check out the appropriate "maint" branch, as in: - git checkout maint-0.2.7 - - 2. Find your way around the source + git checkout maint-0.4.3 - Our overall code structure is explained in the "torguts" documents, - currently at + 2. Find your way around the source. - git clone https://git.torproject.org/user/nickm/torguts.git + Our overall code structure is explained in our + [source documentation](https://src-ref.docs.torproject.org/tor/index.html). Find a part of the code that looks interesting to you, and start looking around it to see how it fits together! We do some unusual things in our codebase. Our testing-related - practices and kludges are explained in doc/WritingTests.txt. + practices and kludges are explained in `doc/HACKING/WritingTests.md`. If you see something that doesn't make sense, we love to get questions! @@ -74,10 +66,10 @@ Once you've reached this point, here's what you need to know. Many people have gotten started by looking for an area where they personally felt Tor was underperforming, and investigating ways to - fix it. If you're looking for ideas, you can head to our bug - tracker at trac.torproject.org and look for tickets that have - received the "easy" tag: these are ones that developers think would - be pretty simple for a new person to work on. For a bigger + fix it. If you're looking for ideas, you can head to + [trac](https://trac.torproject.org) our bug tracking tool and look for + tickets that have received the "easy" tag: these are ones that developers + think would be pretty simple for a new person to work on. For a bigger challenge, you might want to look for tickets with the "lorax" keyword: these are tickets that the developers think might be a good idea to build, but which we have no time to work on any time @@ -96,7 +88,7 @@ Once you've reached this point, here's what you need to know. 4. Meet the developers! - We discuss stuff on the tor-dev mailing list and on the #tor-dev + We discuss stuff on the tor-dev mailing list and on the `#tor-dev` IRC channel on OFTC. We're generally friendly and approachable, and we like to talk about how Tor fits together. If we have ideas about how something should be implemented, we'll be happy to share @@ -113,8 +105,8 @@ Once you've reached this point, here's what you need to know. protocols, there needs to be a written design proposal before it can be merged. (We use this process to manage changes in the protocols.) To write one, see the instructions at - https://gitweb.torproject.org/torspec.git/tree/proposals/001-process.txt - . If you'd like help writing a proposal, just ask! We're happy to + [the Tor proposal process](https://gitweb.torproject.org/torspec.git/plain/proposals/001-process.txt). + If you'd like help writing a proposal, just ask! We're happy to help out with good ideas. You might also like to look around the rest of that directory, to @@ -125,7 +117,7 @@ Once you've reached this point, here's what you need to know. As you write your code, you'll probably want it to fit in with the standards of the rest of the Tor codebase so it will be easy for us to review and merge. You can learn our coding standards in - doc/HACKING. + `doc/HACKING` directory. If your patch is large and/or is divided into multiple logical components, remember to divide it into a series of Git commits. A @@ -137,16 +129,16 @@ Once you've reached this point, here's what you need to know. ensure that it runs correctly. Also, all code should actually be _run_ by somebody, to make sure it works. - See doc/WritingTests.txt for more information on how we test things + See `doc/HACKING/WritingTests.md` for more information on how we test things in Tor. If you'd like any help writing tests, just ask! We're glad to help out. 8. Submitting your patch We review patches through tickets on our bugtracker at - trac.torproject.org. You can either upload your patches there, or + [trac](https://trac.torproject.org). You can either upload your patches there, or put them at a public git repository somewhere we can fetch them - (like github or bitbucket) and then paste a link on the appropriate + (like gitlab, github or bitbucket) and then paste a link on the appropriate trac ticket. Once your patches are available, write a short explanation of what @@ -163,17 +155,17 @@ Once you've reached this point, here's what you need to know. When your patch is reviewed, one of these things will happen: - * The reviewer will say "looks good to me" and your + * The reviewer will say "_looks good to me_" and your patch will get merged right into Tor. [Assuming we're not in the middle of a code-freeze window. If the codebase is frozen, your patch will go into the next release series.] - * OR the reviewer will say "looks good, just needs some small - changes!" And then the reviewer will make those changes, + * OR the reviewer will say "_looks good, just needs some small + changes!_" And then the reviewer will make those changes, and merge the modified patch into Tor. - * OR the reviewer will say "Here are some questions and - comments," followed by a bunch of stuff that the reviewer + * OR the reviewer will say "_Here are some questions and + comments,_" followed by a bunch of stuff that the reviewer thinks should change in your code, or questions that the reviewer has. diff --git a/doc/HACKING/GettingStartedRust.md b/doc/HACKING/GettingStartedRust.md index aa29c097da..247ea5c695 100644 --- a/doc/HACKING/GettingStartedRust.md +++ b/doc/HACKING/GettingStartedRust.md @@ -1,12 +1,9 @@ +# Hacking on Rust in Tor - Hacking on Rust in Tor -======================== - - Getting Started ------------------ +## Getting Started Please read or review our documentation on Rust coding standards -(`.../doc/HACKING/CodingStandardsRust.md`) before doing anything. +(`doc/HACKING/CodingStandardsRust.md`) before doing anything. Please also read [the Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html). We @@ -23,8 +20,7 @@ Please be patient with the other people who are working on getting more Rust code into Tor, because they are graciously donating their free time to contribute to this effort. - Resources for learning Rust ------------------------------ +## Resources for learning Rust **Beginning resources** @@ -49,8 +45,7 @@ is For learning more about FFI and Rust, see Jake Goulding's [Rust FFI Omnibus](http://jakegoulding.com/rust-ffi-omnibus/). - Compiling Tor with Rust enabled ---------------------------------- +## Compiling Tor with Rust enabled You will need to run the `configure` script with the `--enable-rust` flag to explicitly build with Rust. Additionally, you will need to @@ -79,7 +74,7 @@ you are in the top level of the repository) configure tor with: TOR_RUST_DEPENDENCIES='path_to_dependencies_directory' ./configure --enable-rust -(Note that TOR_RUST_DEPENDENCIES must be the full path to the directory; it +(Note that `TOR_RUST_DEPENDENCIES` must be the full path to the directory; it cannot be relative.) Assuming you used the above `git submodule` commands and you're in the @@ -87,9 +82,7 @@ topmost directory of the repository, this would be: TOR_RUST_DEPENDENCIES=`pwd`/src/ext/rust/crates ./configure --enable-rust - - Identifying which modules to rewrite -====================================== +## Identifying which modules to rewrite The places in the Tor codebase that are good candidates for porting to Rust are: @@ -117,12 +110,11 @@ interconnected your target module is. The output will tell you each module name, along with a set of every module that the module calls. Modules which call fewer other modules are better targets. - Writing your Rust module -========================== +## Writing your Rust module Strive to change the C API as little as possible. -We are currently targetting Rust stable. (See CodingStandardsRust.md for more +We are currently targetting Rust stable. (See `CodingStandardsRust.md` for more details.) It is on our TODO list to try to cultivate good @@ -134,19 +126,17 @@ If parts of your Rust code needs to stay in sync with C code (such as handling enums across the FFI boundary), annonotate these places in a comment structured as follows: - /// C_RUST_COUPLED: <path_to_file> `<name_of_c_object>` + `/// C_RUST_COUPLED: <path_to_file> <name_of_c_object>` -Where <name_of_c_object> can be an enum, struct, constant, etc. Then, +Where `<name_of_c_object>` can be an enum, struct, constant, etc. Then, do the same in the C code, to note that rust will need to be changed when the C does. - - Adding your Rust module to Tor's build system ------------------------------------------------ +## Adding your Rust module to Tor's build system 0. Your translation of the C module should live in its own crate(s) - in the `.../tor/src/rust/` directory. -1. Add your crate to `.../tor/src/rust/Cargo.toml`, in the + in the `src/rust/` directory. +1. Add your crate to `src/rust/Cargo.toml`, in the `[workspace.members]` section. 2. Add your crate's files to src/rust/include.am @@ -156,12 +146,11 @@ dependency of other Rust modules): `src/rust/tor_util/Cargo.toml` and include it in `src/rust/tor_rust/lib.rs` - How to test your Rust code ----------------------------- +## How to test your Rust code Everything should be tested full stop. Even non-public functionality. -Be sure to edit `.../tor/src/test/test_rust.sh` to add the name of your +Be sure to edit `src/test/test_rust.sh` to add the name of your crate to the `crates` variable! This will ensure that `cargo test` is run on your crate. @@ -177,7 +166,6 @@ Tor's integration tests should also pass: make test-stem - Submitting a patch -===================== +## Submitting a patch -Please follow the instructions in `.../doc/HACKING/GettingStarted.md`. +Please follow the instructions in `doc/HACKING/GettingStarted.md`. diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md index ae892c34a2..15bd153318 100644 --- a/doc/HACKING/HelpfulTools.md +++ b/doc/HACKING/HelpfulTools.md @@ -1,11 +1,10 @@ -Useful tools -============ +# Useful tools These aren't strictly necessary for hacking on Tor, but they can help track down bugs. -Travis/Appveyor CI ------------------- +## Travis/Appveyor CI + It's CI. Looks like this: @@ -29,8 +28,7 @@ for your fork to build commits outside of PRs too: 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). -Jenkins -------- +## Jenkins It's CI/builders. Looks like this: https://jenkins.torproject.org @@ -43,8 +41,7 @@ Builds Linux and Windows cross-compilation. Runs Linux tests. 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 valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/app/tor @@ -52,16 +49,14 @@ Valgrind pass `--undef-value-errors=no` to valgrind, or rebuild your openssl with `-DPURIFY`.) -Coverity --------- +## Coverity Nick regularly runs the coverity static analyzer on the Tor codebase. The preprocessor define `__COVERITY__` is used to work around instances where coverity picks up behavior that we wish to permit. -clang Static Analyzer ---------------------- +## clang Static Analyzer The clang static analyzer can be run on the Tor codebase using Xcode (WIP) or a command-line build. @@ -69,8 +64,7 @@ or a command-line build. The preprocessor define `__clang_analyzer__` is used to work around instances where clang picks up behavior that we wish to permit. -clang Runtime Sanitizers ------------------------- +## clang Runtime Sanitizers To build the Tor codebase with the clang Address and Undefined Behavior sanitizers, see the file `contrib/clang/sanitize_blacklist.txt`. @@ -78,8 +72,7 @@ sanitizers, see the file `contrib/clang/sanitize_blacklist.txt`. Preprocessor workarounds for instances where clang picks up behavior that we wish to permit are also documented in the blacklist file. -Running lcov for unit test coverage ------------------------------------ +## Running lcov for unit test coverage Lcov is a utility that generates pretty HTML reports of test code coverage. To generate such a report: @@ -96,8 +89,7 @@ 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 ----------------------- +## Running the unit tests To quickly run all the tests distributed with Tor: @@ -123,8 +115,7 @@ working connection to the internet: make test-full-online -Running gcov for unit test coverage ------------------------------------ +## Running gcov for unit test coverage ./configure --enable-coverage make @@ -164,8 +155,7 @@ lines? If you run ./scripts/test/cov-exclude, it marks excluded unreached lines with 'x', and excluded reached lines with '!!!'. -Running integration tests -------------------------- +## Running integration tests We have the beginnings of a set of scripts to run integration tests using Chutney. To try them, set CHUTNEY_PATH to your chutney source directory, and @@ -174,14 +164,12 @@ run `make test-network`. We also have scripts to run integration tests using Stem. To try them, set `STEM_SOURCE_DIR` to your Stem source directory, and run `test-stem`. -Profiling Tor -------------- +## Profiling Tor Ongoing notes about Tor profiling can be found at https://pad.riseup.net/p/profiling-tor -Profiling Tor with oprofile ---------------------------- +## Profiling Tor with oprofile The oprofile tool runs (on Linux only!) to tell you what functions Tor is spending its CPU time in, so we can identify performance bottlenecks. @@ -206,8 +194,7 @@ Here are some basic instructions * `opreport -l that_dir/*` - Profit -Profiling Tor with perf ------------------------ +## Profiling Tor with perf This works with a running Tor, and requires root. @@ -236,8 +223,7 @@ This works with a running Tor, and requires root. report -g > <FILENAME>.out`. Then you can compress that and put it somewhere public. -Profiling Tor with gperftools aka Google-performance-tools ----------------------------------------------------------- +## Profiling Tor with gperftools aka Google-performance-tools This should work on nearly any unixy system. It doesn't seem to be compatible with RunAsDaemon though. @@ -255,8 +241,7 @@ performance! See the gperftools manual for more info, but basically: 3. Run `pprof src/app/tor /tmp/profile` to start the REPL. -Generating and analyzing a callgraph ------------------------------------- +## Generating and analyzing a callgraph 0. Build Tor on linux or mac, ideally with -O0 or -fno-inline. @@ -266,8 +251,7 @@ Generating and analyzing a callgraph Note that currently the callgraph generator can't detect calls that pass through function pointers. -Getting emacs to edit Tor source properly ------------------------------------------ +## Getting emacs to edit Tor source properly Nick likes to put the following snippet in his .emacs file: @@ -315,8 +299,7 @@ If you use emacs for editing Tor and nothing else, you could always just say: There is probably a better way to do this. No, we are probably not going to clutter the files with emacs stuff. -Building a tag file (code index) --------------------------------- +## Building a tag file (code index) Many functions in tor use `MOCK_IMPL` wrappers for unit tests. Your tag-building program must be told how to handle this syntax. @@ -340,8 +323,7 @@ instead: A vim-compatible tag file will be generated by default. If you use emacs, add the `-e` flag to generate an emacs-compatible tag file. -Doxygen -------- +## Doxygen We use the 'doxygen' utility to generate documentation from our source code. Here's how to use it: @@ -396,8 +378,7 @@ source code. Here's how to use it: 6. See the Doxygen manual for more information; this summary just scratches the surface. -Style and best-practices checking --------------------------------- +## Style and best-practices checking We use scripts to check for various problems in the formatting and style of our source code. The "check-spaces" test detects a bunch of violations diff --git a/doc/HACKING/HowToReview.md b/doc/HACKING/HowToReview.md index 2325e70175..7815e76632 100644 --- a/doc/HACKING/HowToReview.md +++ b/doc/HACKING/HowToReview.md @@ -1,5 +1,4 @@ -How to review a patch -===================== +# How to review a patch Some folks have said that they'd like to review patches more often, but they don't know how. @@ -9,9 +8,7 @@ So, here are a bunch of things to check for when reviewing a patch! Note that if you can't do every one of these, that doesn't mean you can't do a good review! Just make it clear what you checked for and what you didn't. - -Top-level smell-checks ----------------------- +## Top-level smell-checks (Difficulty: easy) @@ -37,10 +34,9 @@ Top-level smell-checks - If this changes anything in the code, is there a "changes" file? -Let's look at the code! ------------------------ +## Let's look at the code! -- Does the code conform to CodingStandards.txt? +- Does the code conform to `CodingStandards.md`? - Does the code leak memory? @@ -60,8 +56,7 @@ Let's look at the code! - Is there duplicated code that could be turned into a function? -Let's look at the documentation! --------------------------------- +## Let's look at the documentation! - Does the documentation conform to CodingStandards.txt? @@ -70,8 +65,7 @@ Let's look at the documentation! - Can you predict what the function will do from its documentation? -Let's think about security! ---------------------------- +## Let's think about security! - If there are any arrays, buffers, are you 100% sure that they cannot overflow? diff --git a/doc/HACKING/Module.md b/doc/HACKING/Module.md index 781bb978f2..f8a9773d47 100644 --- a/doc/HACKING/Module.md +++ b/doc/HACKING/Module.md @@ -1,9 +1,9 @@ -# Modules in Tor # +# Modules in Tor This document describes the build system and coding standards when writing a module in Tor. -## What is a module? ## +## What is a module? In the context of the tor code base, a module is a subsystem that we can selectively enable or disable, at `configure` time. @@ -27,7 +27,7 @@ because you would actually want to run one without the other.) To disable a module, pass `--disable-module-{dirauth,relay}` at configure time. All modules are currently enabled by default. -## Build System ## +## Build System The changes to the build system are pretty straightforward. @@ -55,7 +55,7 @@ Finally, your module will automatically be included in the `TOR_MODULES_ALL_ENABLED` variable which is used to build the unit tests. They always build everything in order to test everything. -## Coding ## +## Coding As mentioned above, a module should be isolated in its own directories, suffixed with the name of the module, in `src/*/`. diff --git a/doc/HACKING/README.1st.md b/doc/HACKING/README.1st.md index 8299fe634a..2278a61d6c 100644 --- a/doc/HACKING/README.1st.md +++ b/doc/HACKING/README.1st.md @@ -1,17 +1,18 @@ +# README.1st -In this directory ------------------ +## In this directory This directory has helpful information about what you need to know to hack on Tor! -First, read `GettingStarted.md` to learn how to get a start in Tor -development. +First, read `GettingStarted.md` and `GettingStartedRust.md` +to learn how to get a start in Tor development. -If you've decided to write a patch, `CodingStandards.txt` will give -you a bunch of information about how we structure our code. +If you've decided to write a patch, `CodingStandards.md` and +`CodingStandardsRust.md` will give you a bunch of information +about how we structure our code. -It's important to get code right! Reading `WritingTests.md` will +It's important to get the code right! Reading `WritingTests.md` will tell you how to write and run tests in the Tor codebase. There are a bunch of other programs we use to help maintain and @@ -21,42 +22,26 @@ with Tor. If it's your job to put out Tor releases, see `ReleasingTor.md` so that you don't miss any steps! - ------------------------ +## Additional Information For full information on how Tor is supposed to work, look at the files in -`https://gitweb.torproject.org/torspec.git/tree`. +[Tor specification](https://gitweb.torproject.org/torspec.git/tree). For an explanation of how to change Tor's design to work differently, look at -`https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/001-process.txt`. +[the Tor proposal process](https://gitweb.torproject.org/torspec.git/plain/proposals/001-process.txt). For the latest version of the code, get a copy of git, and git clone https://git.torproject.org/git/tor +## Stay in touch + We talk about Tor on the `tor-talk` mailing list. Design proposals and discussion belong on the `tor-dev` mailing list. We hang around on -irc.oftc.net, with general discussion happening on #tor and development +irc.oftc.net, with general discussion happening on `#tor` and development happening on `#tor-dev`. The other files in this `HACKING` directory may also be useful as you get started working with Tor. Happy hacking! - - ------------------------ - -XXXXX also describe - -doc/HACKING/WritingTests.md - -torguts.git - -torspec.git - -The design paper - -freehaven.net/anonbib - -XXXX describe these and add links. diff --git a/doc/HACKING/ReleaseSeriesLifecycle.md b/doc/HACKING/ReleaseSeriesLifecycle.md new file mode 100644 index 0000000000..e4068ed806 --- /dev/null +++ b/doc/HACKING/ReleaseSeriesLifecycle.md @@ -0,0 +1,113 @@ +# Release Series Lifecycle + + +## End Of Life On An Old Release Series + +Here are the steps that the maintainer should take when an old Tor release +series reaches End of Life. + +Note that they are _only_ for an entire series that has reached its planned +EOL: they do not apply to security-related deprecations of individual +patch versions. + + +### 1. Preliminaries + +1. A few months before End of Life: + Write a deprecation announcement. + Send the announcement out with every new release announcement. + +2. A month before End of Life: + Send the announcement to tor-announce, tor-talk, tor-relays, and the + packagers. + + +### 2. On The Day + +1. Open tickets to remove the release from: + - the jenkins builds + - tor's Travis CI cron jobs + - chutney's Travis CI tests + - sbws' Travis CI tests + - stem's Travis CI tests (but see + https://github.com/torproject/stem/issues/51) + - tor's scripts/git/gist-list-tor-branches.sh script + +2. Close the milestone in Trac. To do this, go to Trac, log in, + select "Admin" near the top of the screen, then select "Milestones" from + the menu on the left. Click on the milestone for this version, and + select the "Completed" checkbox. By convention, we select the date as + the End of Life date. + +3. Replace NNN-backport with NNN-unreached-backport in all open trac tickets. + +4. If there are any remaining tickets in the milestone: + - merge_ready tickets are for backports: + - if there are no supported releases for the backport, close the ticket + - if there is an earlier (LTS) release for the backport, move the ticket + to that release + - other tickets should be closed (if we won't fix them) or moved to a + supported release (if we will fix them) + +5. Mail the end of life announcement to tor-announce, the packagers list, + and tor-relays. The current list of packagers is in ReleasingTor.md. + +6. Ask at least two of weasel/arma/Sebastian to remove the old version + number from their approved versions list. + +7. Update the CoreTorReleases wiki page. + +8. Open a ticket (if there is not one already) for authorities to + start rejecting relays that are running that release series. + This ticket should be targeted for at least a month or two + after the series is officially EOL, unless there is an important + reason to un-list relays early. + +9. (LTS end-of-life only) Open a ticket (if appropriate) for updates to the + set of required and recommended subprotocol versions. (For the process + here, see proposal 303.) + +10. (LTS end-of-life only) Open a ticket to remove no-longer-needed + consensus methods. (For the process here, see proposal 290.) + +11. (All EOL) Open a ticket to grep for obsolete series names (e.g., "0.2.9" + and "029") in tor, chutney, sbws, fallback-scripts, and so on. These + should be updated or removed. + +12. Finally, make sure this document is up to date with our latest + process. + +## Starting A New Release Series + +Here are the steps that the maintainer should take to start new maint and +release branches for a stable release. + +Note that they are _only_ for an entire series, when it first becomes stable: +they do not apply to security-related patch release versions. + +(Ideally, do this immediately after a release.) + +1. Start a new maint-x.y.z branch based on master, and a new + release-x.y.z branch based on master. They should have the same + starting point. + + Push both of these branches to the master git repository. + +2. In master, change the version to "0.x.y.0-alpha-dev". Run the + update_versions.py script, and commit this version bump. + +3. Tag the version bump with "tor-0.x.y.0-alpha-dev". Push the tag + and master. + +4. Open tickets for connecting the new branches to various other + places. See section 2 above for a list of affected locations. + +5. Stop running practracker on maintainence and release branches: + * Remove "check-best-practices" from the check-local Makefile + target in the maint-x.y.z branch only. + * Delete the file scripts/maint/practracker/.enable_practracker_in_hooks + in the maint-x.y.z branch only. + * Merge to release-x.y.z, but do not forward-port to master. + +6. Finally, make sure this document is up to date with our latest + process. diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md index 0f453ca2aa..2464d8afb4 100644 --- a/doc/HACKING/ReleasingTor.md +++ b/doc/HACKING/ReleasingTor.md @@ -1,11 +1,9 @@ - -Putting out a new release -------------------------- +# Putting out a new release Here are the steps that the maintainer should take when putting out a new Tor release: -### 0. Preliminaries +## 0. Preliminaries 1. Get at least two of weasel/arma/Sebastian to put the new version number in their approved versions list. Give them a few @@ -18,7 +16,7 @@ new Tor release: date of a TB that contains it. See note below in "commit, upload, announce". -### I. Make sure it works +## I. Make sure it works 1. Make sure that CI passes: have a look at Travis (https://travis-ci.org/torproject/tor/branches), Appveyor @@ -51,9 +49,7 @@ new Tor release: libevent and openssl, so using valgrind will sometimes find extra memory leaks.) - -### II. Write a changelog - +## II. Write a changelog 1a. (Alpha release variant) @@ -138,8 +134,7 @@ new Tor release: to start sorting and condensing entries. (Generally, we don't edit the text of existing entries, though.) - -### III. Making the source release. +## III. Making the source release. 1. In `maint-0.?.x`, bump the version number in `configure.ac` and run `make update-versions` to update version numbers in other @@ -165,7 +160,7 @@ new Tor release: If it is not, you'll need to poke Roger, Weasel, and Sebastian again: see item 0.1 at the start of this document. -### IV. Commit, upload, announce +## IV. Commit, upload, announce 1. Sign the tarball, then sign and push the git tag: @@ -215,7 +210,6 @@ new Tor release: Include a link to the changelog. - 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" @@ -241,7 +235,7 @@ new Tor release: For templates to use when announcing, see: https://trac.torproject.org/projects/tor/wiki/org/teams/NetworkTeam/AnnouncementTemplates -### V. Aftermath and cleanup +## 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` diff --git a/doc/HACKING/Tracing.md b/doc/HACKING/Tracing.md index 24fa761310..e1e97abe6d 100644 --- a/doc/HACKING/Tracing.md +++ b/doc/HACKING/Tracing.md @@ -1,16 +1,16 @@ -# Tracing # +# Tracing This document describes how the event tracing subsystem works in tor so developers can add events to the code base but also hook them to an event tracing framework. -## Basics ### +## Basics Event tracing is separated in two concepts, trace events and a tracer. The tracing subsystem can be found in `src/trace`. The `events.h` header file is the main file that maps the different tracers to trace events. -### Events ### +### Events A trace event is basically a function from which we can pass any data that we want to collect. In addition, we specify a context for the event such as @@ -39,7 +39,7 @@ How `argc` is collected or used has nothing to do with the instrumentation the trace events and collection framework (tracer) are decoupled. You _can_ have trace events without a tracer. -### Tracer ### +### Tracer In `src/trace/events.h`, we map the `tor_trace()` function to the right tracer. A tracer support is only enabled at compile time. For instance, the @@ -47,7 +47,7 @@ file `src/trace/debug.h` contains the mapping of the generic tracing function `tor_trace()` to the `log_debug()` function. More specialized function can be mapped depending on the tracepoint. -## Build System ## +## Build System This section describes how it is integrated into the build system of tor. @@ -66,7 +66,7 @@ configure option: --enable-tracing-debug -## Instrument Tor ## +## Instrument Tor This is pretty easy. Let's say you want to add a trace event in `src/feature/rend/rendcache.c`, you only have to add this include statement: diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md index 05de8e0be8..d212020525 100644 --- a/doc/HACKING/WritingTests.md +++ b/doc/HACKING/WritingTests.md @@ -1,6 +1,4 @@ - -Writing tests for Tor: an incomplete guide -========================================== +# Writing tests for Tor: an incomplete guide Tor uses a variety of testing frameworks and methodologies to try to keep from introducing bugs. The major ones are: @@ -19,8 +17,7 @@ keep from introducing bugs. The major ones are: 5. The Shadow network simulator. -How to run these tests ----------------------- +## How to run these tests ### The easy version @@ -64,7 +61,7 @@ The former are those that should finish in a few seconds; the latter tend to take more time, and may include CPU-intensive operations, deliberate delays, and stuff like that. -### Finding test coverage +## Finding test coverage Test coverage is a measurement of which lines your tests actually visit. @@ -112,7 +109,7 @@ 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 +## 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 @@ -126,9 +123,7 @@ unreached lines with 'x', and excluded reached lines with '!!!'. Note: you should never do this unless the line is meant to 100% unreachable by actual code. - -What kinds of test should I write? ----------------------------------- +## What kinds of test should I write? Integration testing and unit testing are complementary: it's probably a good idea to make sure that your code is hit by both if you can. @@ -143,8 +138,7 @@ If your code adds new externally visible functionality to Tor, it would be great to have a test for that functionality. That's where integration tests more usually come in. -Unit and regression tests: Does this function do what it's supposed to? ------------------------------------------------------------------------ +## Unit and regression tests: Does this function do what it's supposed to? Most of Tor's unit tests are made using the "tinytest" testing framework. You can see a guide to using it in the tinytest manual at @@ -165,7 +159,7 @@ If you have created a new test file, you will need to: I use the term "unit test" and "regression tests" very sloppily here. -### A simple example +## A simple example Here's an example of a test function for a simple function in util.c: @@ -207,7 +201,7 @@ Finally, remember that by convention, all `*_free()` functions that Tor defines are defined to accept NULL harmlessly. Thus, you don't need to say `if (contents)` in the cleanup block. -### Exposing static functions for testing +## Exposing static functions for testing Sometimes you need to test a function, but you don't want to expose it outside its usual module. @@ -228,7 +222,7 @@ For example, `crypto_curve25519.h` contains: The `crypto_curve25519.c` file and the `test_crypto.c` file both define `CRYPTO_CURVE25519_PRIVATE`, so they can see this declaration. -### STOP! Does this test really test? +## STOP! Does this test really test? When writing tests, it's not enough to just generate coverage on all the lines of the code that you're testing: It's important to make sure that @@ -269,8 +263,7 @@ it's supposed to do, and fail otherwise. Try to design your tests so that they check for the code's intended and documented functionality as much as possible. - -### Mock functions for testing in isolation +## Mock functions for testing in isolation Often we want to test that a function works right, but the function to be tested depends on other functions whose behavior is hard to observe, @@ -311,7 +304,7 @@ And later, you can restore the original function with: For more information, see the definitions of this mocking logic in `testsupport.h`. -### Okay but what should my tests actually do? +## Okay but what should my tests actually do? We talk above about "test coverage" -- making sure that your tests visit every line of code, or every branch of code. But visiting the code isn't @@ -382,8 +375,7 @@ Based on the implementation, we now see three more edge cases to test: * Removing an element from the end of the list * Removing an element from a position other than the end of the list. - -### What should my tests NOT do? +## What should my tests NOT do? Tests shouldn't require a network connection. @@ -401,8 +393,7 @@ When possible, tests should not be over-fit to the implementation. That is, the test should verify that the documented behavior is implemented, but should not break if other permissible behavior is later implemented. - -### Advanced techniques: Namespaces +## Advanced techniques: Namespaces Sometimes, when you're doing a lot of mocking at once, it's convenient to isolate your identifiers within a single namespace. If this were C++, we'd @@ -414,9 +405,7 @@ them, you define `NS_MODULE` to a prefix to be used for your identifiers, and then use other macros in place of identifier names. See `src/test/test.h` for more documentation. - -Integration tests: Calling Tor from the outside ------------------------------------------------ +## Integration tests: Calling Tor from the outside Some tests need to invoke Tor from the outside, and shouldn't run from the same process as the Tor test program. Reasons for doing this might include: @@ -436,8 +425,7 @@ wrapped, add a new shell script to `TESTS`, and the new program to makefile (eg `${PYTHON}` for a python interpreter), then make sure that the makefile exports them. -Writing integration tests with Stem ------------------------------------ +## Writing integration tests with Stem The 'stem' library includes extensive tests for the Tor controller protocol. You can run stem tests from tor with `make test-stem`, or see @@ -483,8 +471,7 @@ 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 ---------------------------- +## System testing with Chutney The 'chutney' program configures and launches a set of Tor relays, authorities, and clients on your local host. It has a `test network` diff --git a/doc/HACKING/android/Simpleperf.md b/doc/HACKING/android/Simpleperf.md index 25f39a3d23..c7e63a7c86 100644 --- a/doc/HACKING/android/Simpleperf.md +++ b/doc/HACKING/android/Simpleperf.md @@ -95,4 +95,3 @@ was spend on the call. Start Tor the normal way via Orbot and collect the logs from your computer using $ adb logcat - diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 62d5de4a0c..53be76f965 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -9,12 +9,12 @@ // attribute to make it easier to write names containing double underscores :dbl_: __ = TOR(1) +:toc: == NAME tor - The second-generation onion router - == SYNOPSIS **tor** [__OPTION__ __value__]... @@ -158,7 +158,7 @@ The following options in this section are only recognized on the When generating a master key, you may want to use **`--DataDirectory`** to control where the keys and certificates will be stored, and **`--SigningKeyLifetime`** to control their - lifetimes. See the server options section to learn more about the + lifetimes. See <<server-options,SERVER OPTIONS>> to learn more about the behavior of these options. You must have write access to the specified DataDirectory. + @@ -427,7 +427,7 @@ forward slash (/) in the configuration file and on the command line. [[CookieAuthFile]] **CookieAuthFile** __Path__:: If set, this option overrides the default location and file name - for Tor's cookie file. (See CookieAuthentication above.) + for Tor's cookie file. (See <<CookieAuthentication,CookieAuthentication>>.) [[CookieAuthFileGroupReadable]] **CookieAuthFileGroupReadable** **0**|**1**:: If this option is set to 0, don't allow the filesystem group to read the @@ -561,7 +561,7 @@ forward slash (/) in the configuration file and on the command line. + By default, the directory authorities are also FallbackDirs. Specifying a FallbackDir replaces Tor's default hard-coded FallbackDirs (if any). - (See the **DirAuthority** entry for an explanation of each flag.) + (See <<DirAuthority,DirAuthority>> for an explanation of each flag.) [[FetchDirInfoEarly]] **FetchDirInfoEarly** **0**|**1**:: If set to 1, Tor will always fetch directory information like other @@ -864,7 +864,7 @@ forward slash (/) in the configuration file and on the command line. **KIST**: Kernel-Informed Socket Transport. Tor will use TCP information from the kernel to make informed decisions regarding how much data to send and when to send it. KIST also handles traffic in batches (see - KISTSchedRunInterval) in order to improve traffic prioritization decisions. + <<KISTSchedRunInterval,KISTSchedRunInterval>>) in order to improve traffic prioritization decisions. As implemented, KIST will only work on Linux kernel version 2.6.39 or higher. + + @@ -1023,13 +1023,6 @@ The following options are useful only for clients (that is, if via the UI to mobile users for use where bandwidth may be expensive. (Default: 0) -[[ClientAutoIPv6ORPort]] **ClientAutoIPv6ORPort** **0**|**1**:: - If this option is set to 1, Tor clients randomly prefer a node's IPv4 or - IPv6 ORPort. The random preference is set every time a node is loaded - from a new consensus or bridge config. When this option is set to 1, - **ClientPreferIPv6ORPort** is ignored. (Default: 0) (DEPRECATED: This - option is unreliable if a connection isn't reliably dual-stack.) - [[ClientBootstrapConsensusAuthorityDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityDownloadInitialDelay** __N__:: Initial delay in seconds for when clients should download consensuses from authorities if they are bootstrapping (that is, they don't have a usable, reasonably @@ -1145,7 +1138,7 @@ The following options are useful only for clients (that is, if doesn't handle arbitrary DNS request types. Set the port to "auto" to have Tor pick a port for you. This directive can be specified multiple times to bind to multiple - addresses/ports. See SocksPort for an explanation of isolation + addresses/ports. See <<SocksPort,SocksPort>> for an explanation of isolation flags. (Default: 0) [[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**:: @@ -1161,7 +1154,7 @@ The following options are useful only for clients (that is, if [[FascistFirewall]] **FascistFirewall** **0**|**1**:: If 1, Tor will only create outgoing connections to ORs running on ports - that your firewall allows (defaults to 80 and 443; see **FirewallPorts**). + that your firewall allows (defaults to 80 and 443; see <<FirewallPorts,FirewallPorts>>). This will allow you to run Tor as a client behind a firewall with restrictive policies, but will not allow you to run as a server behind such a firewall. If you prefer more fine-grained control, use @@ -1190,7 +1183,7 @@ The following options are useful only for clients (that is, if specified multiple times to bind to multiple addresses/ports. If multiple entries of this option are present in your configuration file, Tor will perform stream isolation between listeners by default. See - SOCKSPort for an explanation of isolation flags. (Default: 0) + <<SocksPort,SocksPort>> for an explanation of isolation flags. (Default: 0) [[LongLivedPorts]] **LongLivedPorts** __PORTS__:: A list of ports for services that tend to have long-running connections @@ -1275,7 +1268,7 @@ The following options are useful only for clients (that is, if specified multiple times to bind to multiple addresses/ports. If multiple entries of this option are present in your configuration file, Tor will perform stream isolation between listeners by default. See - SocksPort for an explanation of isolation flags. + + <<SocksPort,SocksPort>> for an explanation of isolation flags. + + This option is only for people who cannot use TransPort. (Default: 0) @@ -1386,7 +1379,7 @@ The following options are useful only for clients (that is, if + The separation between **ReachableORAddresses** and **ReachableDirAddresses** is only interesting when you are connecting - through proxies (see **HTTPProxy** and **HTTPSProxy**). Most proxies limit + through proxies (see <<HTTPProxy,HTTPProxy>> and <<HTTPSProxy,HTTPSProxy>>). Most proxies limit TLS connections (which Tor uses to connect to Onion Routers) to port 443, and some limit HTTP GET requests (which Tor uses for fetching directory information) to port 80. @@ -1402,7 +1395,7 @@ The following options are useful only for clients (that is, if [[TestSocks]] **TestSocks** **0**|**1**:: When this option is enabled, Tor will make a notice-level log entry for each connection to the Socks port indicating whether the request used a - safe socks protocol or an unsafe one (see above entry on SafeSocks). This + safe socks protocol or an unsafe one (see <<SafeSocks,SafeSocks>>). This helps to determine whether an application using Tor is possibly leaking DNS requests. (Default: 0) @@ -1632,7 +1625,7 @@ The following options are useful only for clients (that is, if specified multiple times to bind to multiple addresses/ports. If multiple entries of this option are present in your configuration file, Tor will perform stream isolation between listeners by default. See - SOCKSPort for an explanation of isolation flags. + + <<SocksPort,SocksPort>> for an explanation of isolation flags. + + TransPort requires OS support for transparent proxies, such as BSDs' pf or Linux's IPTables. If you're planning to use Tor as a transparent proxy for @@ -1847,7 +1840,7 @@ different from other Tor clients: + The ExcludeNodes option overrides this option: any node listed in both EntryNodes and ExcludeNodes is treated as excluded. See - the **ExcludeNodes** option for more information on how to specify nodes. + <<ExcludeNodes,ExcludeNodes>> for more information on how to specify nodes. [[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address @@ -1871,7 +1864,7 @@ different from other Tor clients: + Country codes are case-insensitive. The code "\{??}" refers to nodes whose country can't be identified. No country code, including \{??}, works if - no GeoIPFile can be loaded. See also the GeoIPExcludeUnknown option below. + no GeoIPFile can be loaded. See also the <<GeoIPExcludeUnknown,GeoIPExcludeUnknown>> option below. // Out of order because it logically belongs after the ExcludeNodes option [[ExcludeExitNodes]] **ExcludeExitNodes** __node__,__node__,__...__:: @@ -1880,14 +1873,14 @@ different from other Tor clients: node that delivers traffic for you *outside* the Tor network. Note that any node listed in ExcludeNodes is automatically considered to be part of this list too. See - the **ExcludeNodes** option for more information on how to specify - nodes. See also the caveats on the "ExitNodes" option below. + <<ExcludeNodes,ExcludeNodes>> for more information on how to specify + nodes. See also the caveats on the <<ExitNodes,ExitNodes>> option below. [[ExitNodes]] **ExitNodes** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address patterns of nodes to use as exit node---that is, a node that delivers traffic for you *outside* the Tor network. See - the **ExcludeNodes** option for more information on how to specify nodes. + + <<ExcludeNodes,ExcludeNodes>> for more information on how to specify nodes. + + Note that if you list too few nodes here, or if you exclude too many exit nodes with ExcludeExitNodes, you can degrade functionality. For example, @@ -1899,7 +1892,7 @@ different from other Tor clients: used to connect to hidden services, those that do directory fetches, those used for relay reachability self-tests, and so on) that end at a non-exit node. To - keep a node from being used entirely, see ExcludeNodes and StrictNodes. + + keep a node from being used entirely, see <<ExcludeNodes,ExcludeNodes>> and <<StrictNodes,StrictNodes>>. + + The ExcludeNodes option overrides this option: any node listed in both ExitNodes and ExcludeNodes is treated as excluded. + @@ -2043,7 +2036,7 @@ different from other Tor clients: + The ExcludeNodes option overrides this option: any node listed in both MiddleNodes and ExcludeNodes is treated as excluded. See - the **ExcludeNodes** option for more information on how to specify nodes. + the <<ExcludeNodes,ExcludeNodes>> for more information on how to specify nodes. [[NodeFamily]] **NodeFamily** __node__,__node__,__...__:: The Tor servers, defined by their identity fingerprints, @@ -2052,7 +2045,7 @@ different from other Tor clients: when a server doesn't list the family itself (with MyFamily). This option can be used multiple times; each instance defines a separate family. In addition to nodes, you can also list IP address and ranges and country - codes in {curly braces}. See the **ExcludeNodes** option for more + codes in {curly braces}. See <<ExcludeNodes,ExcludeNodes>> for more information on how to specify nodes. [[StrictNodes]] **StrictNodes** **0**|**1**:: @@ -2068,6 +2061,7 @@ different from other Tor clients: fulfill a .exit request, upload directory information, or download directory information. (Default: 0) +[[server-options]] == SERVER OPTIONS // These options are in alphabetical order, with exceptions as noted. @@ -2078,7 +2072,7 @@ is non-zero): [[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: Limits the max number of bytes sent and received within a set time period - using a given calculation rule (see: AccountingStart, AccountingRule). + using a given calculation rule (see <<AccountingStart,AccountingStart>> and <<AccountingRule,AccountingRule>>). Useful if you need to stay under a specific bandwidth. By default, the number used for calculation is the max of either the bytes sent or received. For example, with AccountingMax set to 1 TByte, a server @@ -2225,7 +2219,7 @@ is non-zero): 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. See - ExitPolicyRejectLocalInterfaces if you want to block every address on the + <<ExitPolicyRejectLocalInterfaces,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 @@ -2270,7 +2264,7 @@ is non-zero): 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. + See above entry on <<ExitPolicy,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. @@ -2279,7 +2273,7 @@ is non-zero): [[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**:: 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. + See above entry on <<ExitPolicy,ExitPolicy>>. (Default: 1) [[ExitRelay]] **ExitRelay** **0**|**1**|**auto**:: @@ -2368,14 +2362,11 @@ is non-zero): list itself, but it won't hurt if it does.) Do not list any bridge relay as it would compromise its concealment. + + - When listing a node, it's better to list it by fingerprint than by - 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. + + Note: do not use MyFamily when configuring your Tor instance as a - brigde. + bridge. [[Nickname]] **Nickname** __name__:: Set the server's nickname to \'name'. Nicknames must be between 1 and 19 @@ -2690,7 +2681,7 @@ types of statistics that Tor relays collect and publish: == DIRECTORY SERVER OPTIONS The following options are useful only for directory servers. (Relays with -enough bandwidth automatically become directory servers; see DirCache for +enough bandwidth automatically become directory servers; see <<DirCache,DirCache>> for details.) [[DirCache]] **DirCache** **0**|**1**:: @@ -2746,9 +2737,11 @@ and are as follows: + 2. If a single client IP address (v4 or v6) makes circuits too quickly (default values are more than 3 per second, with an allowed burst of 90, - see DoSCircuitCreationRate and DoSCircuitCreationBurst) while also having + see <<DoSCircuitCreationRate,DoSCircuitCreationRate>> and + <<DoSCircuitCreationBurst,DoSCircuitCreationBurst>>) while also having too many connections open (default is 3, see - DoSCircuitCreationMinConnections), tor will refuse any new circuit (CREATE + <<DoSCircuitCreationMinConnections,DoSCircuitCreationMinConnections>>), + tor will refuse any new circuit (CREATE cells) for the next while (random value between 1 and 2 hours). + 3. If a client asks to establish a rendezvous point to you directly (ex: @@ -2770,32 +2763,17 @@ your log at NOTICE level which looks like: The following options are useful only for a public relay. They control the Denial of Service mitigation subsystem described above. +//Out of order because it logically belongs before the other DoSCircuitCreation options. [[DoSCircuitCreationEnabled]] **DoSCircuitCreationEnabled** **0**|**1**|**auto**:: Enable circuit creation DoS mitigation. If set to 1 (enabled), tor will cache client IPs along with statistics in order to detect circuit DoS attacks. If an address is positively identified, tor will activate - defenses against the address. See the DoSCircuitCreationDefenseType option - for more details. This is a client to relay detection only. "auto" means + defenses against the address. See <<DoSCircuitCreationDefenseType,DoSCircuitCreationDefenseType>> + option for more details. This is a client to relay detection only. "auto" means use the consensus parameter. If not defined in the consensus, the value is 0. (Default: auto) -[[DoSCircuitCreationMinConnections]] **DoSCircuitCreationMinConnections** __NUM__:: - - Minimum threshold of concurrent connections before a client address can be - flagged as executing a circuit creation DoS. In other words, once a client - address reaches the circuit rate and has a minimum of NUM concurrent - connections, a detection is positive. "0" means use the consensus - parameter. If not defined in the consensus, the value is 3. - (Default: 0) - -[[DoSCircuitCreationRate]] **DoSCircuitCreationRate** __NUM__:: - - The allowed circuit creation rate per second applied per client IP - address. If this option is 0, it obeys a consensus parameter. If not - defined in the consensus, the value is 3. - (Default: 0) - [[DoSCircuitCreationBurst]] **DoSCircuitCreationBurst** __NUM__:: The allowed circuit creation burst per client IP address. If the circuit @@ -2804,6 +2782,14 @@ Denial of Service mitigation subsystem described above. consensus, the value is 90. (Default: 0) +[[DoSCircuitCreationDefenseTimePeriod]] **DoSCircuitCreationDefenseTimePeriod** __N__ **seconds**|**minutes**|**hours**:: + + The base time period in seconds that the DoS defense is activated for. The + actual value is selected randomly for each activation from N+1 to 3/2 * N. + "0" means use the consensus parameter. If not defined in the consensus, + the value is 3600 seconds (1 hour). + (Default: 0) + [[DoSCircuitCreationDefenseType]] **DoSCircuitCreationDefenseType** __NUM__:: This is the type of defense applied to a detected client address. The @@ -2816,14 +2802,23 @@ Denial of Service mitigation subsystem described above. "0" means use the consensus parameter. If not defined in the consensus, the value is 2. (Default: 0) -[[DoSCircuitCreationDefenseTimePeriod]] **DoSCircuitCreationDefenseTimePeriod** __N__ **seconds**|**minutes**|**hours**:: +[[DoSCircuitCreationMinConnections]] **DoSCircuitCreationMinConnections** __NUM__:: - The base time period in seconds that the DoS defense is activated for. The - actual value is selected randomly for each activation from N+1 to 3/2 * N. - "0" means use the consensus parameter. If not defined in the consensus, - the value is 3600 seconds (1 hour). + Minimum threshold of concurrent connections before a client address can be + flagged as executing a circuit creation DoS. In other words, once a client + address reaches the circuit rate and has a minimum of NUM concurrent + connections, a detection is positive. "0" means use the consensus + parameter. If not defined in the consensus, the value is 3. (Default: 0) +[[DoSCircuitCreationRate]] **DoSCircuitCreationRate** __NUM__:: + + The allowed circuit creation rate per second applied per client IP + address. If this option is 0, it obeys a consensus parameter. If not + defined in the consensus, the value is 3. + (Default: 0) + +//out of order because it logically belongs before the other DoSConnection options. [[DoSConnectionEnabled]] **DoSConnectionEnabled** **0**|**1**|**auto**:: Enable the connection DoS mitigation. If set to 1 (enabled), for client @@ -2832,14 +2827,6 @@ Denial of Service mitigation subsystem described above. consensus parameter. If not defined in the consensus, the value is 0. (Default: auto) -[[DoSConnectionMaxConcurrentCount]] **DoSConnectionMaxConcurrentCount** __NUM__:: - - The maximum threshold of concurrent connection from a client IP address. - Above this limit, a defense selected by DoSConnectionDefenseType is - applied. "0" means use the consensus parameter. If not defined in the - consensus, the value is 100. - (Default: 0) - [[DoSConnectionDefenseType]] **DoSConnectionDefenseType** __NUM__:: This is the type of defense applied to a detected client address for the @@ -2852,6 +2839,14 @@ Denial of Service mitigation subsystem described above. "0" means use the consensus parameter. If not defined in the consensus, the value is 2. (Default: 0) +[[DoSConnectionMaxConcurrentCount]] **DoSConnectionMaxConcurrentCount** __NUM__:: + + The maximum threshold of concurrent connection from a client IP address. + Above this limit, a defense selected by DoSConnectionDefenseType is + applied. "0" means use the consensus parameter. If not defined in the + consensus, the value is 100. + (Default: 0) + [[DoSRefuseSingleHopClientRendezvous]] **DoSRefuseSingleHopClientRendezvous** **0**|**1**|**auto**:: Refuse establishment of rendezvous points for single hop clients. In other @@ -2868,6 +2863,7 @@ control how Tor behaves as a directory authority. You should not need to adjust any of them if you're running a regular relay or exit server on the public Tor network. +// Out of order because it logically belongs first in this section [[AuthoritativeDirectory]] **AuthoritativeDirectory** **0**|**1**:: When this option is set to 1, Tor operates as an authoritative directory server. Instead of caching the directory, it generates its own list of @@ -2875,59 +2871,18 @@ on the public Tor network. already have you listed as a trusted directory, you probably do not want 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 at least 0.2.0.x). - -[[VersioningAuthoritativeDirectory]] **VersioningAuthoritativeDirectory** **0**|**1**:: - When this option is set to 1, Tor adds information on which versions of - Tor are still believed safe for use to the published directory. Each - version 1 authority is automatically a versioning authority; version 2 - authorities provide this service optionally. See **RecommendedVersions**, - **RecommendedClientVersions**, and **RecommendedServerVersions**. - -[[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 - directory learn whether they need to upgrade. This option can appear - multiple times: the values from multiple lines are spliced together. When - this is set then **VersioningAuthoritativeDirectory** should be set too. - -[[RecommendedClientVersions]] **RecommendedClientVersions** __STRING__:: - STRING is a comma-separated list of Tor versions currently believed to be - safe for clients to use. This information is included in version 2 - directories. If this is not set then the value of **RecommendedVersions** - is used. When this is set then **VersioningAuthoritativeDirectory** should - be set too. - +//Out of order because it belongs with the AuthoritativeDirectory option. [[BridgeAuthoritativeDir]] **BridgeAuthoritativeDir** **0**|**1**:: When this option is set in addition to **AuthoritativeDirectory**, Tor accepts and serves server descriptors, but it caches and serves the main networkstatus documents rather than generating its own. (Default: 0) -[[MinUptimeHidServDirectoryV2]] **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: - Minimum uptime of a v2 hidden service directory to be accepted as such by - authoritative directories. (Default: 25 hours) - -[[RecommendedServerVersions]] **RecommendedServerVersions** __STRING__:: - STRING is a comma-separated list of Tor versions currently believed to be - safe for servers to use. This information is included in version 2 - directories. If this is not set then the value of **RecommendedVersions** - is used. When this is set then **VersioningAuthoritativeDirectory** should - be set too. - -[[ConsensusParams]] **ConsensusParams** __STRING__:: - STRING is a space-separated list of key=value pairs that Tor will include - in the "params" line of its networkstatus vote. - -[[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. Additionally, Tor - will allow exit policies for private networks to fulfill Exit flag - requirements. (Default: 0) +//Out of order because it belongs with the AuthoritativeDirectory 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 at least 0.2.0.x). [[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that @@ -2938,26 +2893,46 @@ on the public Tor network. is the same as for exit policies, except that you don't need to say "accept" or "reject", and ports are not needed.) -[[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 - authority publishes. +[[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Authoritative directories only. If non-zero, always vote the + Fast flag for any relay advertising this amount of capacity or + more. (Default: 100 KBytes) -[[AuthDirReject]] **AuthDirReject** __AddressPattern__...:: - Authoritative directories only. A set of address patterns for servers that - will never be listed at all in any network status document that this - authority publishes, or accepted as an OR address in any descriptor - submitted for publication by this authority. +[[AuthDirGuardBWGuarantee]] **AuthDirGuardBWGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Authoritative directories only. If non-zero, this advertised capacity + or more is always sufficient to satisfy the bandwidth requirement + for the Guard flag. (Default: 2 MBytes) -[[AuthDirBadExitCCs]] **AuthDirBadExitCCs** __CC__,... + +[[AuthDirHasIPv6Connectivity]] **AuthDirHasIPv6Connectivity** **0**|**1**:: + Authoritative directories only. When set to 0, OR ports with an + IPv6 address are not included in the authority's votes. When set to 1, + IPv6 OR ports are tested for reachability like IPv4 OR ports. If the + reachability test succeeds, the authority votes for the IPv6 ORPort, and + votes Running for the relay. If the reachability test fails, the authority + does not vote for the IPv6 ORPort, and does not vote Running (Default: 0) + ++ + The content of the consensus depends on the number of voting authorities + that set AuthDirHasIPv6Connectivity: -[[AuthDirInvalidCCs]] **AuthDirInvalidCCs** __CC__,... + + If no authorities set AuthDirHasIPv6Connectivity 1, there will be no + IPv6 ORPorts in the consensus. -[[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 exit/invalid for use, or rejected - entirely. + If a minority of authorities set AuthDirHasIPv6Connectivity 1, + unreachable IPv6 ORPorts will be removed from the consensus. But the + majority of IPv4-only authorities will still vote the relay as Running. + Reachable IPv6 ORPort lines will be included in the consensus + + If a majority of voting authorities set AuthDirHasIPv6Connectivity 1, + relays with unreachable IPv6 ORPorts will not be listed as Running. + Reachable IPv6 ORPort lines will be included in the consensus + (To ensure that any valid majority will vote relays with unreachable + IPv6 ORPorts not Running, 75% of authorities must set + AuthDirHasIPv6Connectivity 1.) + +[[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 + authority publishes. [[AuthDirListBadExits]] **AuthDirListBadExits** **0**|**1**:: Authoritative directories only. If set to 1, this directory has some @@ -2970,16 +2945,6 @@ on the public Tor network. list as acceptable on a single IP address. Set this to "0" for "no limit". (Default: 2) -[[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Authoritative directories only. If non-zero, always vote the - Fast flag for any relay advertising this amount of capacity or - more. (Default: 100 KBytes) - -[[AuthDirGuardBWGuarantee]] **AuthDirGuardBWGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Authoritative directories only. If non-zero, this advertised capacity - or more is always sufficient to satisfy the bandwidth requirement - for the Guard flag. (Default: 2 MBytes) - [[AuthDirPinKeys]] **AuthDirPinKeys** **0**|**1**:: Authoritative directories only. If non-zero, do not allow any relay to publish a descriptor if any other relay has reserved its <Ed25519,RSA> @@ -2987,6 +2952,31 @@ 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: 1) +[[AuthDirReject]] **AuthDirReject** __AddressPattern__...:: + Authoritative directories only. A set of address patterns for servers that + will never be listed at all in any network status document that this + authority publishes, or accepted as an OR address in any descriptor + submitted for publication by this authority. + +//Out of order because it logically belongs with the other CCs options. +[[AuthDirBadExitCCs]] **AuthDirBadExitCCs** __CC__,... + + +//Out of order because it logically belongs with the other CCs options. +[[AuthDirInvalidCCs]] **AuthDirInvalidCCs** __CC__,... + + + +[[AuthDirRejectRequestsUnderLoad]] **AuthDirRejectRequestsUnderLoad** **0**|**1**:: + If set, the directory authority will start rejecting directory requests + from non relay connections by sending a 503 error code if it is under + bandwidth pressure (reaching the configured limit if any). Relays will + always tried to be answered even if this is on. (Default: 1) + +[[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 exit/invalid for use, or rejected + entirely. + [[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 @@ -3008,17 +2998,52 @@ on the public Tor network. and their target user audience can periodically fetch the list of available community bridges to stay up-to-date. (Default: not set) -[[V3AuthVotingInterval]] **V3AuthVotingInterval** __N__ **minutes**|**hours**:: - V3 authoritative directories only. Configures the server's preferred voting - interval. Note that voting will __actually__ happen at an interval chosen - by consensus from all the authorities' preferred intervals. This time - SHOULD divide evenly into a day. (Default: 1 hour) +[[ConsensusParams]] **ConsensusParams** __STRING__:: + STRING is a space-separated list of key=value pairs that Tor will include + in the "params" line of its networkstatus vote. -[[V3AuthVoteDelay]] **V3AuthVoteDelay** __N__ **minutes**|**hours**:: - V3 authoritative directories only. Configures the server's preferred delay - between publishing its vote and assuming it has all the votes from all the - other authorities. Note that the actual time used is not the server's - preferred time, but the consensus of all preferences. (Default: 5 minutes) +[[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. Additionally, Tor + will allow exit policies for private networks to fulfill Exit flag + requirements. (Default: 0) + +[[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: + V3 authoritative directories only. Configures the location of the + guardfraction file which contains information about how long relays + have been guards. (Default: unset) + +[[MinMeasuredBWsForAuthToIgnoreAdvertised]] **MinMeasuredBWsForAuthToIgnoreAdvertised** __N__:: + A total value, in abstract bandwidth units, describing how much + measured total bandwidth an authority should have observed on the network + before it will treat advertised bandwidths as wholly + unreliable. (Default: 500) + +[[MinUptimeHidServDirectoryV2]] **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: + Minimum uptime of a v2 hidden service directory to be accepted as such by + authoritative directories. (Default: 25 hours) + +[[RecommendedClientVersions]] **RecommendedClientVersions** __STRING__:: + STRING is a comma-separated list of Tor versions currently believed to be + safe for clients to use. This information is included in version 2 + directories. If this is not set then the value of **RecommendedVersions** + is used. When this is set then **VersioningAuthoritativeDirectory** should + be set too. + +[[RecommendedServerVersions]] **RecommendedServerVersions** __STRING__:: + STRING is a comma-separated list of Tor versions currently believed to be + safe for servers to use. This information is included in version 2 + directories. If this is not set then the value of **RecommendedVersions** + is used. When this is set then **VersioningAuthoritativeDirectory** should + be set too. + +[[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 + directory learn whether they need to upgrade. This option can appear + multiple times: the values from multiple lines are spliced together. When + this is set then **VersioningAuthoritativeDirectory** should be set too. [[V3AuthDistDelay]] **V3AuthDistDelay** __N__ **minutes**|**hours**:: V3 authoritative directories only. Configures the server's preferred delay @@ -3035,65 +3060,40 @@ on the public Tor network. server's preferred number, but the consensus of all preferences. Must be at least 2. (Default: 3) -[[V3BandwidthsFile]] **V3BandwidthsFile** __FILENAME__:: - V3 authoritative directories only. Configures the location of the - bandwidth-authority generated file storing information on relays' measured - bandwidth capacities. To avoid inconsistent reads, bandwidth data should - be written to temporary file, then renamed to the configured filename. - (Default: unset) - -[[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: - V3 authoritative directories only. Configures the location of the - guardfraction file which contains information about how long relays - have been guards. (Default: unset) - [[V3AuthUseLegacyKey]] **V3AuthUseLegacyKey** **0**|**1**:: If set, the directory authority will sign consensuses not only with its own signing key, but also with a "legacy" key and certificate with a different identity. This feature is used to migrate directory authority keys in the event of a compromise. (Default: 0) -[[AuthDirHasIPv6Connectivity]] **AuthDirHasIPv6Connectivity** **0**|**1**:: - Authoritative directories only. When set to 0, OR ports with an - IPv6 address are not included in the authority's votes. When set to 1, - IPv6 OR ports are tested for reachability like IPv4 OR ports. If the - reachability test succeeds, the authority votes for the IPv6 ORPort, and - votes Running for the relay. If the reachability test fails, the authority - does not vote for the IPv6 ORPort, and does not vote Running (Default: 0) + -+ - The content of the consensus depends on the number of voting authorities - that set AuthDirHasIPv6Connectivity: - - If no authorities set AuthDirHasIPv6Connectivity 1, there will be no - IPv6 ORPorts in the consensus. - - If a minority of authorities set AuthDirHasIPv6Connectivity 1, - unreachable IPv6 ORPorts will be removed from the consensus. But the - majority of IPv4-only authorities will still vote the relay as Running. - Reachable IPv6 ORPort lines will be included in the consensus - - If a majority of voting authorities set AuthDirHasIPv6Connectivity 1, - relays with unreachable IPv6 ORPorts will not be listed as Running. - Reachable IPv6 ORPort lines will be included in the consensus - (To ensure that any valid majority will vote relays with unreachable - IPv6 ORPorts not Running, 75% of authorities must set - AuthDirHasIPv6Connectivity 1.) +[[V3AuthVoteDelay]] **V3AuthVoteDelay** __N__ **minutes**|**hours**:: + V3 authoritative directories only. Configures the server's preferred delay + between publishing its vote and assuming it has all the votes from all the + other authorities. Note that the actual time used is not the server's + preferred time, but the consensus of all preferences. (Default: 5 + minutes) -[[MinMeasuredBWsForAuthToIgnoreAdvertised]] **MinMeasuredBWsForAuthToIgnoreAdvertised** __N__:: - A total value, in abstract bandwidth units, describing how much - measured total bandwidth an authority should have observed on the network - before it will treat advertised bandwidths as wholly - unreliable. (Default: 500) +[[V3AuthVotingInterval]] **V3AuthVotingInterval** __N__ **minutes**|**hours**:: + V3 authoritative directories only. Configures the server's preferred voting + interval. Note that voting will __actually__ happen at an interval chosen + by consensus from all the authorities' preferred intervals. This time + SHOULD divide evenly into a day. (Default: 1 hour) -[[AuthDirRejectRequestsUnderLoad]] **AuthDirRejectRequestsUnderLoad** **0**|**1**:: - If set, the directory authority will start rejecting directory requests - from non relay connections by sending a 503 error code if it is under - bandwidth pressure (reaching the configured limit if any). Relays will - always tried to be answered even if this is on. (Default: 1) +[[V3BandwidthsFile]] **V3BandwidthsFile** __FILENAME__:: + V3 authoritative directories only. Configures the location of the + bandwidth-authority generated file storing information on relays' measured + bandwidth capacities. To avoid inconsistent reads, bandwidth data should + be written to temporary file, then renamed to the configured filename. + (Default: unset) +[[VersioningAuthoritativeDirectory]] **VersioningAuthoritativeDirectory** **0**|**1**:: + When this option is set to 1, Tor adds information on which versions of + Tor are still believed safe for use to the published directory. Each + version 1 authority is automatically a versioning authority; version 2 + authorities provide this service optionally. See <<RecommendedVersions,RecommendedVersions>>, + <<RecommendedClientVersions,RecommendedClientVersions>>, and <<RecommendedServerVersions,RecommendedServerVersions>>. -HIDDEN SERVICE OPTIONS ----------------------- +== HIDDEN SERVICE OPTIONS The following options are used to configure a hidden service. Some options apply per service and some apply for the whole tor instance. @@ -3103,6 +3103,26 @@ The next section describes the per service options that can only be set **PER SERVICE OPTIONS:** +[[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**:: + If set to 1, then connections to unrecognized ports do not cause the + current hidden service to close rendezvous circuits. (Setting this to 0 is + not an authorization mechanism; it is instead meant to be a mild + inconvenience to port-scanners.) (Default: 0) + +[[HiddenServiceAuthorizeClient]] **HiddenServiceAuthorizeClient** __auth-type__ __client-name__,__client-name__,__...__:: + If configured, the v2 hidden service is accessible for authorized clients + only. The auth-type can either be \'basic' for a general-purpose + authorization protocol or \'stealth' for a less scalable protocol that also + hides service activity from unauthorized clients. Only clients that are + listed here are authorized to access the hidden service. Valid client names + are 1 to 16 characters long and only use characters in A-Za-z0-9+-_ (no + spaces). If this option is set, the hidden service is not accessible for + 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; v3 services configure client authentication in a subdirectory of + HiddenServiceDir instead (see <<client-authorization,CLIENT AUTHORIZATION>>). + [[HiddenServiceDir]] **HiddenServiceDir** __DIRECTORY__:: Store data files for a hidden service in DIRECTORY. Every hidden service must have a separate directory. You may use this option multiple times to @@ -3115,41 +3135,35 @@ The next section describes the per service options that can only be set rely on this behavior; it is not guaranteed to remain the same in future versions.) -[[HiddenServicePort]] **HiddenServicePort** __VIRTPORT__ [__TARGET__]:: - Configure a virtual port VIRTPORT for a hidden service. You may use this - option multiple times; each time applies to the service using the most - 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 - 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. Note that address-port pairs have to be comma-separated. +[[HiddenServiceDirGroupReadable]] **HiddenServiceDirGroupReadable** **0**|**1**:: + If this option is set to 1, allow the filesystem group to read the + hidden service directory and hostname file. If the option is set to 0, + only owner is able to read the hidden service directory. (Default: 0) + Has no effect on Windows. -[[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: 3) +[[HiddenServiceEnableIntroDoSDefense]] **HiddenServiceEnableIntroDoSDefense** **0**|**1**:: + Enable DoS defense at the intropoint level. When this is enabled, the + rate and burst parameter (see below) will be sent to the intro point which + will then use them to apply rate limiting for introduction request to this + service. + + + The introduction point honors the consensus parameters except if this is + specifically set by the service operator using this option. The service + never looks at the consensus parameters in order to enable or disable this + defense. (Default: 0) -[[HiddenServiceAuthorizeClient]] **HiddenServiceAuthorizeClient** __auth-type__ __client-name__,__client-name__,__...__:: - If configured, the v2 hidden service is accessible for authorized clients - only. The auth-type can either be \'basic' for a general-purpose - authorization protocol or \'stealth' for a less scalable protocol that also - hides service activity from unauthorized clients. Only clients that are - listed here are authorized to access the hidden service. Valid client names - are 1 to 16 characters long and only use characters in A-Za-z0-9+-_ (no - spaces). If this option is set, the hidden service is not accessible for - 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; v3 services configure client authentication in a subdirectory of - HiddenServiceDir instead (see the **Client Authorization** section). +//Out of order because it logically belongs after HiddenServiceEnableIntroDoSDefense. +[[HiddenServiceEnableIntroDoSBurstPerSec]] **HiddenServiceEnableIntroDoSBurstPerSec** __NUM__:: + The allowed client introduction burst per second at the introduction + point. If this option is 0, it is considered infinite and thus if + **HiddenServiceEnableIntroDoSDefense** is set, it then effectively + disables the defenses. (Default: 200) -[[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**:: - If set to 1, then connections to unrecognized ports do not cause the - current hidden service to close rendezvous circuits. (Setting this to 0 is - not an authorization mechanism; it is instead meant to be a mild - inconvenience to port-scanners.) (Default: 0) +[[HiddenServiceEnableIntroDoSRatePerSec]] **HiddenServiceEnableIntroDoSRatePerSec** __NUM__:: + The allowed client introduction rate per second at the introduction + point. If this option is 0, it is considered infinite and thus if + **HiddenServiceEnableIntroDoSDefense** is set, it then effectively + disables the defenses. (Default: 25) [[HiddenServiceExportCircuitID]] **HiddenServiceExportCircuitID** __protocol__:: The onion service will use the given protocol to expose the global circuit @@ -3178,6 +3192,19 @@ The next section describes the per service options that can only be set The HAProxy version 1 protocol is described in detail at https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt +[[HiddenServiceOnionBalanceInstance]] **HiddenServiceOnionBalanceInstance** **0**|**1**:: + + If set to 1, this onion service becomes an OnionBalance instance and will + accept client connections destined to an OnionBalance frontend. In this + case, Tor expects to find a file named "ob_config" inside the + **HiddenServiceDir** directory with content: + + + MasterOnionAddress <frontend_onion_address> + + + where <frontend_onion_address> is the onion address of the OnionBalance + frontend (e.g. wrxdvcaqpuzakbfww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.onion). + + [[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 @@ -3188,6 +3215,26 @@ The next section describes the per service options that can only be set offending rendezvous circuit to be torn down, as opposed to stream creation requests that exceed the limit being silently ignored. (Default: 0) +[[HiddenServiceNumIntroductionPoints]] **HiddenServiceNumIntroductionPoints** __NUM__:: + Number of introduction points the hidden service will have. You can't + have more than 10 for v2 service and 20 for v3. (Default: 3) + +[[HiddenServicePort]] **HiddenServicePort** __VIRTPORT__ [__TARGET__]:: + Configure a virtual port VIRTPORT for a hidden service. You may use this + option multiple times; each time applies to the service using the most + 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 + 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. Note that address-port pairs have to be comma-separated. + +[[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: 3) + [[RendPostPeriod]] **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: Every time the specified period elapses, Tor uploads any rendezvous service descriptors to the directory servers. This information is also @@ -3195,48 +3242,10 @@ The next section describes the per service options that can only be set maximum is 3.5 days. This option is only for v2 services. (Default: 1 hour) -[[HiddenServiceDirGroupReadable]] **HiddenServiceDirGroupReadable** **0**|**1**:: - If this option is set to 1, allow the filesystem group to read the - hidden service directory and hostname file. If the option is set to 0, - only owner is able to read the hidden service directory. (Default: 0) - Has no effect on Windows. - -[[HiddenServiceNumIntroductionPoints]] **HiddenServiceNumIntroductionPoints** __NUM__:: - Number of introduction points the hidden service will have. You can't - have more than 10 for v2 service and 20 for v3. (Default: 3) - -[[HiddenServiceEnableIntroDoSDefense]] **HiddenServiceEnableIntroDoSDefense** **0**|**1**:: - Enable DoS defense at the intropoint level. When this is enabled, the - rate and burst parameter (see below) will be sent to the intro point which - will then use them to apply rate limiting for introduction request to this - service. - + - The introduction point honors the consensus parameters except if this is - specifically set by the service operator using this option. The service - never looks at the consensus parameters in order to enable or disable this - defense. (Default: 0) - -[[HiddenServiceEnableIntroDoSRatePerSec]] **HiddenServiceEnableIntroDoSRatePerSec** __NUM__:: - The allowed client introduction rate per second at the introduction - point. If this option is 0, it is considered infinite and thus if - **HiddenServiceEnableIntroDoSDefense** is set, it then effectively - disables the defenses. (Default: 25) - -[[HiddenServiceEnableIntroDoSBurstPerSec]] **HiddenServiceEnableIntroDoSBurstPerSec** __NUM__:: - The allowed client introduction burst per second at the introduction - point. If this option is 0, it is considered infinite and thus if - **HiddenServiceEnableIntroDoSDefense** is set, it then effectively - disables the defenses. (Default: 200) **PER INSTANCE OPTIONS:** -[[PublishHidServDescriptors]] **PublishHidServDescriptors** **0**|**1**:: - If set to 0, Tor will run any hidden services you configure, but it won't - advertise them to the rendezvous directory. This option is only useful if - you're using a Tor controller that handles hidserv publishing for you. - (Default: 1) - [[HiddenServiceSingleHopMode]] **HiddenServiceSingleHopMode** **0**|**1**:: **Experimental - Non Anonymous** Hidden Services on a tor instance in HiddenServiceSingleHopMode make one-hop (direct) circuits between the onion @@ -3263,6 +3272,7 @@ The next section describes the per service options that can only be set **HiddenServiceSingleHopMode**. Can not be changed while tor is running. (Default: 0) +//Out of order because it belongs after HiddenServiceSingleHopMode. [[HiddenServiceNonAnonymousMode]] **HiddenServiceNonAnonymousMode** **0**|**1**:: Makes hidden services non-anonymous on this tor instance. Allows the non-anonymous HiddenServiceSingleHopMode. Enables direct connections in the @@ -3271,7 +3281,14 @@ The next section describes the per service options that can only be set including setting SOCKSPort to "0". Can not be changed while tor is running. (Default: 0) -== Client Authorization +[[PublishHidServDescriptors]] **PublishHidServDescriptors** **0**|**1**:: + If set to 0, Tor will run any hidden services you configure, but it won't + advertise them to the rendezvous directory. This option is only useful if + you're using a Tor controller that handles hidserv publishing for you. + (Default: 1) + +[[client-authorization]] +== CLIENT AUTHORIZATION (Version 3 only) @@ -3316,6 +3333,7 @@ For more information, please see https://2019.www.torproject.org/docs/tor-onion- The following options are used for running a testing Tor network. +//Out of order because it logically belongs first in this section. [[TestingTorNetwork]] **TestingTorNetwork** **0**|**1**:: If set to 1, Tor adjusts default values of the configuration options below, so that it is easier to set up a testing Tor network. May only be set if @@ -3356,59 +3374,35 @@ The following options are used for running a testing Tor network. TestingEnableConnBwEvent 1 TestingEnableCellStatsEvent 1 -[[TestingV3AuthInitialVotingInterval]] **TestingV3AuthInitialVotingInterval** __N__ **minutes**|**hours**:: - Like V3AuthVotingInterval, but for initial voting interval before the first - consensus has been created. Changing this requires that - **TestingTorNetwork** is set. (Default: 30 minutes) - -[[TestingV3AuthInitialVoteDelay]] **TestingV3AuthInitialVoteDelay** __N__ **minutes**|**hours**:: - Like V3AuthVoteDelay, but for initial voting interval before - the first consensus has been created. Changing this requires that - **TestingTorNetwork** is set. (Default: 5 minutes) - -[[TestingV3AuthInitialDistDelay]] **TestingV3AuthInitialDistDelay** __N__ **minutes**|**hours**:: - Like V3AuthDistDelay, but for initial voting interval before - the first consensus has been created. Changing this requires that - **TestingTorNetwork** is set. (Default: 5 minutes) - -[[TestingV3AuthVotingStartOffset]] **TestingV3AuthVotingStartOffset** __N__ **seconds**|**minutes**|**hours**:: - Directory authorities offset voting start time by this much. - Changing this requires that **TestingTorNetwork** is set. (Default: 0) - [[TestingAuthDirTimeToLearnReachability]] **TestingAuthDirTimeToLearnReachability** __N__ **minutes**|**hours**:: After starting as an authority, do not make claims about whether routers are Running until this much time has passed. Changing this requires that **TestingTorNetwork** is set. (Default: 30 minutes) -[[TestingMinFastFlagThreshold]] **TestingMinFastFlagThreshold** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Minimum value for the Fast flag. Overrides the ordinary minimum taken - from the consensus when TestingTorNetwork is set. (Default: 0.) - -[[TestingServerDownloadInitialDelay]] **TestingServerDownloadInitialDelay** __N__:: - Initial delay in seconds for when servers should download things in general. Changing this - requires that **TestingTorNetwork** is set. (Default: 0) - -[[TestingClientDownloadInitialDelay]] **TestingClientDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download things in general. Changing this - requires that **TestingTorNetwork** is set. (Default: 0) +[[TestingAuthKeyLifetime]] **TestingAuthKeyLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: + Overrides the default lifetime for a signing Ed25519 TLS Link authentication + key. + (Default: 2 days) -[[TestingServerConsensusDownloadInitialDelay]] **TestingServerConsensusDownloadInitialDelay** __N__:: - Initial delay in seconds for when servers should download consensuses. Changing this - requires that **TestingTorNetwork** is set. (Default: 0) +[[TestingAuthKeySlop]] **TestingAuthKeySlop** __N__ **seconds**|**minutes**|**hours** + -[[TestingClientConsensusDownloadInitialDelay]] **TestingClientConsensusDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download consensuses. Changing this - requires that **TestingTorNetwork** is set. (Default: 0) +[[TestingBridgeBootstrapDownloadInitialDelay]] **TestingBridgeBootstrapDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download each bridge descriptor when they + have just started, or when they can not contact any of their bridges. + Changing this requires that **TestingTorNetwork** is set. (Default: 0) [[TestingBridgeDownloadInitialDelay]] **TestingBridgeDownloadInitialDelay** __N__:: Initial delay in seconds for when clients should download each bridge descriptor when they know that one or more of their configured bridges are running. Changing this requires that **TestingTorNetwork** is set. (Default: 10800) -[[TestingBridgeBootstrapDownloadInitialDelay]] **TestingBridgeBootstrapDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download each bridge descriptor when they - have just started, or when they can not contact any of their bridges. - Changing this requires that **TestingTorNetwork** is set. (Default: 0) +[[TestingClientConsensusDownloadInitialDelay]] **TestingClientConsensusDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) + +[[TestingClientDownloadInitialDelay]] **TestingClientDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download things in general. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) [[TestingClientMaxIntervalWithoutRequest]] **TestingClientMaxIntervalWithoutRequest** __N__ **seconds**|**minutes**:: When directory clients have only a few descriptors to request, they batch @@ -3416,19 +3410,14 @@ The following options are used for running a testing Tor network. Changing this requires that **TestingTorNetwork** is set. (Default: 10 minutes) -[[TestingDirConnectionMaxStall]] **TestingDirConnectionMaxStall** __N__ **seconds**|**minutes**:: - Let a directory connection stall this long before expiring it. - Changing this requires that **TestingTorNetwork** is set. (Default: - 5 minutes) - [[TestingDirAuthVoteExit]] **TestingDirAuthVoteExit** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address patterns of nodes to vote Exit for regardless of their - uptime, bandwidth, or exit policy. See the **ExcludeNodes** - option for more information on how to specify nodes. + + uptime, bandwidth, or exit policy. See <<ExcludeNodes,ExcludeNodes>> + for more information on how to specify nodes. + + In order for this option to have any effect, **TestingTorNetwork** - has to be set. See the **ExcludeNodes** option for more + has to be set. See <<ExcludeNodes,ExcludeNodes>> for more information on how to specify nodes. [[TestingDirAuthVoteExitIsStrict]] **TestingDirAuthVoteExitIsStrict** **0**|**1** :: @@ -3442,7 +3431,7 @@ The following options are used for running a testing Tor network. [[TestingDirAuthVoteGuard]] **TestingDirAuthVoteGuard** __node__,__node__,__...__:: A list of identity fingerprints and country codes and address patterns of nodes to vote Guard for regardless of their - uptime and bandwidth. See the **ExcludeNodes** option for more + uptime and bandwidth. See <<ExcludeNodes,ExcludeNodes>> for more information on how to specify nodes. + + In order for this option to have any effect, **TestingTorNetwork** @@ -3458,7 +3447,7 @@ The following options are used for running a testing Tor network. [[TestingDirAuthVoteHSDir]] **TestingDirAuthVoteHSDir** __node__,__node__,__...__:: A list of identity fingerprints and country codes and address patterns of nodes to vote HSDir for regardless of their - uptime and DirPort. See the **ExcludeNodes** option for more + uptime and DirPort. See <<ExcludeNodes,ExcludeNodes>> for more information on how to specify nodes. + + In order for this option to have any effect, **TestingTorNetwork** @@ -3471,40 +3460,70 @@ The following options are used for running a testing Tor network. In order for this option to have any effect, **TestingTorNetwork** has to be set. -[[TestingEnableConnBwEvent]] **TestingEnableConnBwEvent** **0**|**1**:: - If this option is set, then Tor controllers may register for CONN_BW - events. Changing this requires that **TestingTorNetwork** is set. - (Default: 0) +[[TestingDirConnectionMaxStall]] **TestingDirConnectionMaxStall** __N__ **seconds**|**minutes**:: + Let a directory connection stall this long before expiring it. + Changing this requires that **TestingTorNetwork** is set. (Default: + 5 minutes) [[TestingEnableCellStatsEvent]] **TestingEnableCellStatsEvent** **0**|**1**:: If this option is set, then Tor controllers may register for CELL_STATS events. Changing this requires that **TestingTorNetwork** is set. (Default: 0) -[[TestingMinExitFlagThreshold]] **TestingMinExitFlagThreshold** __N__ **KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Sets a lower-bound for assigning an exit flag when running as an - authority on a testing network. Overrides the usual default lower bound - of 4 KBytes. (Default: 0) +[[TestingEnableConnBwEvent]] **TestingEnableConnBwEvent** **0**|**1**:: + If this option is set, then Tor controllers may register for CONN_BW + events. Changing this requires that **TestingTorNetwork** is set. + (Default: 0) [[TestingLinkCertLifetime]] **TestingLinkCertLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: Overrides the default lifetime for the certificates used to authenticate our X509 link cert with our ed25519 signing key. (Default: 2 days) -[[TestingAuthKeyLifetime]] **TestingAuthKeyLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: - Overrides the default lifetime for a signing Ed25519 TLS Link authentication - key. - (Default: 2 days) - [[TestingLinkKeySlop]] **TestingLinkKeySlop** __N__ **seconds**|**minutes**|**hours** + -[[TestingAuthKeySlop]] **TestingAuthKeySlop** __N__ **seconds**|**minutes**|**hours** + +[[TestingMinExitFlagThreshold]] **TestingMinExitFlagThreshold** __N__ **KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Sets a lower-bound for assigning an exit flag when running as an + authority on a testing network. Overrides the usual default lower bound + of 4 KBytes. (Default: 0) + +[[TestingMinFastFlagThreshold]] **TestingMinFastFlagThreshold** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Minimum value for the Fast flag. Overrides the ordinary minimum taken + from the consensus when TestingTorNetwork is set. (Default: 0.) + +[[TestingServerConsensusDownloadInitialDelay]] **TestingServerConsensusDownloadInitialDelay** __N__:: + Initial delay in seconds for when servers should download consensuses. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) + +[[TestingServerDownloadInitialDelay]] **TestingServerDownloadInitialDelay** __N__:: + Initial delay in seconds for when servers should download things in general. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) [[TestingSigningKeySlop]] **TestingSigningKeySlop** __N__ **seconds**|**minutes**|**hours**:: How early before the official expiration of a an Ed25519 signing key do we replace it and issue a new key? (Default: 3 hours for link and auth; 1 day for signing.) +[[TestingV3AuthInitialDistDelay]] **TestingV3AuthInitialDistDelay** __N__ **minutes**|**hours**:: + Like V3AuthDistDelay, but for initial voting interval before + the first consensus has been created. Changing this requires that + **TestingTorNetwork** is set. (Default: 5 minutes) + +[[TestingV3AuthInitialVoteDelay]] **TestingV3AuthInitialVoteDelay** __N__ **minutes**|**hours**:: + Like V3AuthVoteDelay, but for initial voting interval before + the first consensus has been created. Changing this requires that + **TestingTorNetwork** is set. (Default: 5 minutes) + +[[TestingV3AuthInitialVotingInterval]] **TestingV3AuthInitialVotingInterval** __N__ **minutes**|**hours**:: + Like V3AuthVotingInterval, but for initial voting interval before the first + consensus has been created. Changing this requires that + **TestingTorNetwork** is set. (Default: 30 minutes) + +[[TestingV3AuthVotingStartOffset]] **TestingV3AuthVotingStartOffset** __N__ **seconds**|**minutes**|**hours**:: + Directory authorities offset voting start time by this much. + Changing this requires that **TestingTorNetwork** is set. (Default: 0) + + == NON-PERSISTENT OPTIONS These options are not saved to the torrc file by the "SAVECONF" controller @@ -3580,8 +3599,8 @@ __CacheDirectory__/**`cached-extrainfo`** and **`cached-extrainfo.new`**:: Similar to **cached-descriptors**, but holds optionally-downloaded "extra-info" documents. Relays use these documents to send inessential information about statistics, bandwidth history, and network health to the - authorities. They aren't fetched by default. See the DownloadExtraInfo - option for more information. + authorities. They aren't fetched by default. See <<DownloadExtraInfo,DownloadExtraInfo>> + for more information. __CacheDirectory__/**`cached-microdescs`** and **`cached-microdescs.new`**:: These files hold downloaded microdescriptors. Lines beginning with @@ -3648,11 +3667,11 @@ __KeyDirectory__/**`authority_signing_key`**:: __KeyDirectory__/**`legacy_certificate`**:: As authority_certificate; used only when `V3AuthUseLegacyKey` is set. See - documentation for V3AuthUseLegacyKey. + documentation for <<V3AuthUseLegacyKey,V3AuthUseLegacyKey>>. __KeyDirectory__/**`legacy_signing_key`**:: As authority_signing_key: used only when `V3AuthUseLegacyKey` is set. See - documentation for V3AuthUseLegacyKey. + documentation for <<V3AuthUseLegacyKey,V3AuthUseLegacyKey>>. __KeyDirectory__/**`secret_id_key`**:: A relay's RSA1024 permanent identity key, including private and public |