diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING/CodingStandards.md | 12 | ||||
| -rw-r--r-- | doc/HACKING/WritingTests.md | 12 | ||||
| -rw-r--r-- | doc/HACKING/tracing/EventsCircuit.md | 139 | ||||
| -rw-r--r-- | doc/HACKING/tracing/README.md (renamed from doc/HACKING/Tracing.md) | 0 | ||||
| -rw-r--r-- | doc/include.am | 3 | ||||
| -rw-r--r-- | doc/man/tor.1.txt | 30 |
6 files changed, 187 insertions, 9 deletions
diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index e9bb75b986..cd3417d0b5 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -145,6 +145,10 @@ tor-0.3.1.10 ... ``` +If a bug was introduced before the oldest currently supported release series +of Tor, and it's hard to track down where it was introduced, you may say +"bugfix on all supported versions of Tor." + If at all possible, try to create the changes file in the same commit where you are making the change. Please give it a distinctive name that no other branch will use for the lifetime of your change. We usually use "ticketNNNNN" @@ -185,6 +189,14 @@ What needs a changes file? What does not need a changes file? * Bugfixes for code that hasn't shipped in any released version of Tor + * Any change to a file that is not distributed in the tarball. This + includes: + * Any change to our CI configuration that does not affect the distributed + source. + * Any change to developer-only tools, unless those tools are distributed + in the tarball. + * Non-functional code movement. + * Identifier re-namings, comment edits, spelling fixes, and so on. Why use changes files instead of Git commit messages? diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md index 01e80f3f66..e1497a77c2 100644 --- a/doc/HACKING/WritingTests.md +++ b/doc/HACKING/WritingTests.md @@ -504,3 +504,15 @@ targets in `Makefile.am`. (Adding new kinds of program to chutney will still require hacking the code.) + +## Other integration tests + +It's fine to write tests that use a POSIX shell to invoke Tor or test other +aspects of the system. When you do this, have a look at our existing tests +of this kind in `src/test/` to make sure that you haven't forgotten anything +important. For example: it can be tricky to make sure you're invoking Tor at +the right path in various build scenarios. + +We use a POSIX shell whenever possible here, and we use the shellcheck tool +to make sure that our scripts portable. We should only require bash for +scripts that are developer-only. diff --git a/doc/HACKING/tracing/EventsCircuit.md b/doc/HACKING/tracing/EventsCircuit.md new file mode 100644 index 0000000000..42abdda856 --- /dev/null +++ b/doc/HACKING/tracing/EventsCircuit.md @@ -0,0 +1,139 @@ +# Circuit Subsystem Trace Events + +The circuit subsystem emits a series of tracing events related to a circuit +object life cycle and its state change. + +This document describes each event as in what data they record and what they +represent. + +## Background + +There are two types of circuits: origin and OR (onion router). Both of them +are derived from a base object called a general circuit. + +- Origin circuits are the ones initiated by tor itself so client or onion + service circuits for instance. + +- OR circuits are the ones going through us that we have not initiated and + thus only seen by relays. + +Many operations are done on the base (general) circuit, and some are specific +to an origin or OR. The following section describes each of them by circuit +type. + +## Trace Events + +For the LTTng tracer, the subsystem name of these events is: `tor_circuit`. + +Also, unless specified otherwise, every event emits a common set of parameters +thus they should always be expected in the following order: + +- `circ_id`: For an origin circuit, this is the global circuit identifier used + in a cell. For an OR circuit, the value is 0. + +- `purpose`: Purpose of the circuit as in what it is used for. Note that this + can change during the lifetime of a circuit. See `CIRCUIT_PURPOSE_*` in + `core/or/circuitlist.h` for an exhaustive list of the possible values. + +- `state`: State of a circuit. This changes during the lifetime of a circuit. + See `CIRCUIT_STATE_*` in `core/or/circuitlist.h` for an exhaustive list of + the possible values. + +Now, the tracing events. + +### General Circuit (`circuit_t`) + +The following events are triggered for the base circuit object and thus apply +to all types of circuits. + + * `free`: A circuit object is freed that is memory is released and not + usable anymore. After this event, no more events will be emitted for the + specific circuit object. + + * `mark_for_close`: A circuit object is marked for close that is scheduled + to be closed in a later mainloop periodic event. + + Extra parameters: + + - `end_reason`: Reason why the circuit is closed. Tor often changes that + reason to something generic sometimes in order to avoid leaking internal + reasons to the end point. Thus, this value can be different from + orig_close_reason. + + - `orig_close_reason`: Original reason why the circuit is closed. That + value never changes and contains the internal reason why we close it. It + is **never** this reason that is sent back on the circuit. + + * `change_purpose`: Purpose change. + + Extra parameters: + + (`purpose` parameter is not present) + + - `old_purpose`: Previous purpose that is no longer. + + - `new_purpose`: New purpose assigned to the circuit. + + * `change_state`: State change. + + Extra parameters: + + (`state` parameter is not present) + + - `old_state`: Previous state that is no longer. + + - `new_state`: New state assigned to the circuit. + +### Origin Circuit (`origin_circuit_t`) + +The following events are triggered only for origin circuits. + + * `new_origin`: New origin circuit has been created meaning it has been + newly allocated, initialized and added to the global list. + + * `establish`: Circuit is being established. This is the initial first step + where the path was selected and a connection to the first hop has been + launched. + + * `cannibalized`: Circuit has been cannibalized. This happens when we have + an already opened unused circuit (preemptive circuits) and it was picked. + + * `first_onion_skin`: First onion skin was sent that is the handshake with + the first hop. + + Extra parameters: + + - `fingerprint`: Identity digest (RSA) of the first hop. + + * `intermediate_onion_skin`: An intermediate onion skin was sent which can + be why any hops after the first one. There is thus `N - 1` of these events + where `N` is the total number of hops in the path. + + Extra parameters: + + - `fingerprint`: Identity digest (RSA) of the next hop. + + * `opened`: Circuit just became opened which means that all hops down the + path have negotiated the handshake between them and us and the circuit is + now ready to send cells. + + * `timeout`: Circuit has timed out that is we waited too long for the + circuit to be built. + + * `idle_timeout`: Circuit has timed out due to idleness. This is controlled + by the MaxCircuitDirtiness parameter which is 10 min by default. + +For the common use case of a 3-hop circuit, the following events should be +seen in this order: + + `new_origin` -> `establish` -> `first_onion_skin` -> + `intermediate_onion_skin` -> `intermediate_onion_skin` -> `opened` + +### OR Circuit (`or_circuit_t`) + +The following events are triggered only for OR circuits. For each of them, the +`circ_id` parameter is not present since it would always be 0. The `purpose` +and `state` remain. + + * `new_or`: New OR circuit has been created meaning it has been newly + allocated, initialized and added to the global list. diff --git a/doc/HACKING/Tracing.md b/doc/HACKING/tracing/README.md index d9fb2e5341..d9fb2e5341 100644 --- a/doc/HACKING/Tracing.md +++ b/doc/HACKING/tracing/README.md diff --git a/doc/include.am b/doc/include.am index d3e757f3bb..7a8a64ed16 100644 --- a/doc/include.am +++ b/doc/include.am @@ -59,8 +59,9 @@ EXTRA_DIST+= doc/asciidoc-helper.sh \ doc/HACKING/HowToReview.md \ doc/HACKING/Module.md \ doc/HACKING/ReleasingTor.md \ - doc/HACKING/Tracing.md \ doc/HACKING/WritingTests.md + doc/HACKING/tracing/Tracing.md \ + doc/HACKING/tracing/EventsCircuit.md docdir = @docdir@ diff --git a/doc/man/tor.1.txt b/doc/man/tor.1.txt index 3febf43513..e8dcc7b236 100644 --- a/doc/man/tor.1.txt +++ b/doc/man/tor.1.txt @@ -174,16 +174,22 @@ The following options in this section are only recognized on the If the file descriptor is not specified, the passphrase is read from the terminal by default. -[[opt-key-expiration]] **`--key-expiration`** [__purpose__]:: +[[opt-key-expiration]] **`--key-expiration`** [__purpose__] [**`--format`** **`iso8601`**|**`timestamp`**]:: The __purpose__ specifies which type of key certificate to determine the expiration of. The only currently recognised __purpose__ is "sign". + + Running **`tor --key-expiration sign`** will attempt to find your signing key certificate and will output, both in the logs as well - as to stdout, the signing key certificate's expiration time in - ISO-8601 format. For example, the output sent to stdout will be - of the form: "signing-cert-expiry: 2017-07-25 08:30:15 UTC" + as to stdout. The optional **`--format`** argument lets you specify + the time format. Currently, **`iso8601`** and **`timestamp`** are + supported. If **`--format`** is not specified, the signing key + certificate's expiration time will be in ISO-8601 format. For example, + the output sent to stdout will be of the form: + "signing-cert-expiry: 2017-07-25 08:30:15 UTC". If **`--format`** **`timestamp`** + is specified, the signing key certificate's expiration time will be in + Unix timestamp format. For example, the output sent to stdout will be of the form: + "signing-cert-expiry: 1500971415". [[opt-dbg]] **--dbg-**...:: Tor may support other options beginning with the string "dbg". These @@ -841,10 +847,11 @@ forward slash (/) in the configuration file and on the command line. [[Sandbox]] **Sandbox** **0**|**1**:: If set to 1, Tor will run securely through the use of a syscall sandbox. - Otherwise the sandbox will be disabled. The option is currently an - experimental feature. It only works on Linux-based operating systems, - and only when Tor has been built with the libseccomp library. This option - can not be changed while tor is running. + + Otherwise the sandbox will be disabled. The option only works on + Linux-based operating systems, and only when Tor has been built with the + libseccomp library. Note that this option may be incompatible with some + versions of libc, and some kernel versions. This option can not be + changed while tor is running. + + When the **Sandbox** is 1, the following options can not be changed when tor is running: @@ -2146,6 +2153,13 @@ is non-zero): binds to. To bind to a different address, use the ORPort and OutboundBindAddress options. +[[AddressDisableIPv6]] **AddressDisableIPv6** **0**|**1**:: + By default, Tor will attempt to find the IPv6 of the relay if there is no + IPv4Only ORPort. If set, this option disables IPv6 auto discovery. This + disables IPv6 address resolution, IPv6 ORPorts, and IPv6 reachability + checks. Also, the relay won't publish an IPv6 ORPort in its + descriptor. (Default: 0) + [[AssumeReachable]] **AssumeReachable** **0**|**1**:: This option is used when bootstrapping a new Tor network. If set to 1, don't do self-reachability testing; just upload your server descriptor |