summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/HACKING/CodingStandards.md7
-rw-r--r--doc/HACKING/Fuzzing.md12
-rw-r--r--doc/HACKING/ReleasingTor.md7
-rw-r--r--doc/HACKING/Tracing.md91
-rw-r--r--doc/tor.1.txt47
-rw-r--r--doc/torrc_format.txt4
6 files changed, 140 insertions, 28 deletions
diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md
index 01212a9919..c7787a72cc 100644
--- a/doc/HACKING/CodingStandards.md
+++ b/doc/HACKING/CodingStandards.md
@@ -4,9 +4,10 @@ Coding conventions for Tor
tl;dr:
- Run configure with `--enable-fatal-warnings`
- - Run `make check-spaces` to catch whitespace errors
- Document your functions
- Write unit tests
+ - Run `make test-full` to test against all unit and integration tests.
+ - Run `make distcheck` to ensure the distribution works
- Add a file in `changes` for your branch.
Patch checklist
@@ -22,10 +23,12 @@ preference)
Did you remember...
- To build your code while configured with `--enable-fatal-warnings`?
- - To run `make check-spaces` on your code?
- To run `make check-docs` to see whether all new options are on
the manpage?
- To write unit tests, as possible?
+ - To run `make test-full` to test against all unit and integration tests (or
+ `make test-full-online` if you have a working connection to the internet)?
+ - To test that the distribution will actually work via `make distcheck`?
- To base your code on the appropriate branch?
- To include a file in the `changes` directory as appropriate?
diff --git a/doc/HACKING/Fuzzing.md b/doc/HACKING/Fuzzing.md
index 16b0b6b000..2039d6a4c0 100644
--- a/doc/HACKING/Fuzzing.md
+++ b/doc/HACKING/Fuzzing.md
@@ -64,14 +64,14 @@ To Build:
make
cd ../tor
PATH=$PATH:../afl/ CC="../afl/afl-gcc" ./configure --enable-expensive-hardening
- AFL_HARDEN=1 make clean fuzz
+ AFL_HARDEN=1 make clean fuzzers
To Find The ASAN Memory Limit: (64-bit only)
-On 64-bit platforms, afl needs to know how much memory ASAN uses.
-Or, you can configure tor without --enable-expensive-hardening, then use
- make fuzz
-to run the generated test cases through an ASAN-enabled fuzz-http.
+On 64-bit platforms, afl needs to know how much memory ASAN uses,
+because ASAN tends to allocate a ridiculous amount of virtual memory,
+and then not actually use it.
+
Read afl/docs/notes_for_asan.txt for more details.
Download recidivm from http://jwilk.net/software/recidivm
@@ -80,7 +80,7 @@ Read afl/docs/notes_for_asan.txt for more details.
tar xvzf recidivm*.tar.gz
cd recidivm*
make
- /path/to/recidivm -v src/test/fuzz_dir
+ /path/to/recidivm -v src/test/fuzz/fuzz-http
Use the final "ok" figure as the input to -m when calling afl-fuzz
(Normally, recidivm would output a figure automatically, but in some cases,
the fuzzing harness will hang when the memory limit is too small.)
diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md
index 4761ca9a37..809cd03bf3 100644
--- a/doc/HACKING/ReleasingTor.md
+++ b/doc/HACKING/ReleasingTor.md
@@ -98,7 +98,12 @@ new Tor release:
to a release-0.2.x branch, manually commit the changelogs to the later
git branches too.
-3. If you're doing the first stable release in a series, you need to
+3. If there are changes that require or suggest operator intervention
+ before or during the update, mail operators (either dirauth or relays
+ list) with a headline that indicates that an action is required or
+ appreciated.
+
+4. If you're doing the first stable release in a series, you need to
create a ReleaseNotes for the series as a whole. To get started
there, copy all of the Changelog entries from the series into a new
file, and run `./scripts/maint/sortChanges.py` on it. That will
diff --git a/doc/HACKING/Tracing.md b/doc/HACKING/Tracing.md
new file mode 100644
index 0000000000..a5fb5165e2
--- /dev/null
+++ b/doc/HACKING/Tracing.md
@@ -0,0 +1,91 @@
+# 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 ###
+
+Event tracing is seperated 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 ###
+
+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
+a subsystem and an event name.
+
+A trace event in tor has the following standard format:
+
+ tor_trace(subsystem, event\_name, args...)
+
+The `subsystem` parameter is the name of the subsytem the trace event is in.
+For example that could be "scheduler" or "vote" or "hs". The idea is to add
+some context to the event so when we collect them we know where it's coming
+from. The `event_name` is the name of the event which helps a lot with
+adding some semantic to the event. Finally, `args` is any number of
+arguments we want to collect.
+
+Here is an example of a possible tracepoint in main():
+
+ tor_trace(main, init_phase, argc)
+
+The above is a tracepoint in the `main` subsystem with `init_phase` as the
+event name and the `int argc` is passed to the event as well.
+
+How `argc` is collected or used has nothing to do with the instrumentation
+(adding trace events to the code). It is the work of the tracer so this is why
+the trace events and collection framework (tracer) are decoupled. You _can_
+have trace events without a 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
+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 ##
+
+This section describes how it is integrated into the build system of tor.
+
+By default, every tracing events are disabled in tor that is `tor_trace()`
+is a NOP.
+
+To enable a tracer, there is a configure option on the form of:
+
+ --enable-tracing-<tracer>
+
+We have an option that will send every trace events to a `log_debug()` (as
+mentionned above) which will print you the subsystem and name of the event but
+not the arguments for technical reasons. This is useful if you want to quickly
+see if your trace event is being hit or well written. To do so, use this
+configure option:
+
+ --enable-tracing-debug
+
+## Instrument Tor ##
+
+This is pretty easy. Let's say you want to add a trace event in
+`src/or/rendcache.c`, you only have to add this include statement:
+
+ #include "trace/events.h"
+
+Once done, you can add as many as you want `tor_trace()` that you need.
+Please use the right subsystem (here it would be `hs`) and a unique name that
+tells what the event is for. For example:
+
+ tor_trace(hs, store_desc_as_client, desc, desc_id);
+
+If you look in `src/trace/events.h`, you'll see that if tracing is enabled it
+will be mapped to a function called:
+
+ tor_trace_hs_store_desc_as_client(desc, desc_id)
+
+And the point of all this is for that function to be defined in a new file
+that you might want to add named `src/trace/hs.{c|h}` which would defined how
+to collect the data for the `tor_trace_hs_store_desc_as_client()` function
+like for instance sending it to a `log_debug()` or do more complex operations
+or use a userspace tracer like LTTng (https://lttng.org).
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 109efa7da9..1de01162a4 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -185,6 +185,9 @@ GENERAL OPTIONS
course, more is better; we recommend at least 250 KBytes (2 mbits) if
possible. (Default: 1 GByte) +
+
+ Note that this option, and other bandwidth-limiting options, apply to TCP
+ data only: They do not count TCP headers or DNS traffic. +
+ +
With this option, and in other options that take arguments in bytes,
KBytes, and so on, other formats are also supported. Notably, "KBytes" can
also be written as "kilobytes" or "kb"; "MBytes" can be written as
@@ -391,7 +394,9 @@ GENERAL OPTIONS
[[DataDirectory]] **DataDirectory** __DIR__::
Store working data in DIR. Can not be changed while tor is running.
- (Default: @LOCALSTATEDIR@/lib/tor)
+ (Default: ~/.tor if your home directory is not /; otherwise,
+ @LOCALSTATEDIR@/lib/tor. On Windows, the default is
+ your ApplicationData folder.)
[[DataDirectoryGroupReadable]] **DataDirectoryGroupReadable** **0**|**1**::
If this option is set to 0, don't allow the filesystem group to read the
@@ -641,7 +646,7 @@ GENERAL OPTIONS
(127.0.0.0/8 and ::1).
[[OutboundBindAddressOR]] **OutboundBindAddressOR** __IP__::
- Make all outbound non-exit (=relay and other) connections originate from the IP
+ Make all outbound non-exit (=relay and other) connections originate from the IP
address specified. This option overrides **OutboundBindAddress** for the same
IP version. This option may be used twice, once with an IPv4 address and once
with an IPv6 address. This setting will be ignored for connections to the
@@ -783,7 +788,7 @@ The following options are useful only for clients (that is, if
so using these relays might make your client stand out.
(Default: 1)
-[[Bridge]] **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]::
+[[Bridge]] **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__] [__key__=__val__...]::
When set along with UseBridges, instructs Tor to use the relay at
"IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint"
is provided (using the same format as for DirAuthority), we will verify that
@@ -796,7 +801,12 @@ The following options are useful only for clients (that is, if
rather than connecting to the bridge directly. Some transports use a
transport-specific method to work out the remote address to connect to.
These transports typically ignore the "IP:ORPort" specified in the bridge
- line.
+ line. +
+ +
+ Tor passes any "key=val" settings to the pluggable transport proxy as
+ per-connection arguments when connecting to the bridge. Consult
+ the documentation of the pluggable transport for details of what
+ arguments it supports.
[[LearnCircuitBuildTimeout]] **LearnCircuitBuildTimeout** **0**|**1**::
If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1)
@@ -1072,7 +1082,8 @@ The following options are useful only for clients (that is, if
but never attach a new stream to a circuit that is too old. For hidden
services, this applies to the __last__ time a circuit was used, not the
first. Circuits with streams constructed with SOCKS authentication via
- SocksPorts that have **KeepAliveIsolateSOCKSAuth** ignore this value.
+ SocksPorts that have **KeepAliveIsolateSOCKSAuth** also remain alive
+ for MaxCircuitDirtiness seconds after carrying the last such stream.
(Default: 10 minutes)
[[MaxClientCircuitsPending]] **MaxClientCircuitsPending** __NUM__::
@@ -1134,8 +1145,9 @@ The following options are useful only for clients (that is, if
Don't share circuits with streams targeting a different
destination address.
**KeepAliveIsolateSOCKSAuth**;;
- If **IsolateSOCKSAuth** is enabled, keep alive circuits that have
- streams with SOCKS authentication set indefinitely.
+ If **IsolateSOCKSAuth** is enabled, keep alive circuits while they have
+ at least one stream with SOCKS authentication active. After such a circuit
+ is idle for more than MaxCircuitDirtiness seconds, it can be closed.
**SessionGroup=**__INT__;;
If no other isolation rules would prevent it, allow streams
on this port to share circuits with streams from every other
@@ -1289,16 +1301,16 @@ The following options are useful only for clients (that is, if
[[NumEntryGuards]] **NumEntryGuards** __NUM__::
If UseEntryGuards is set to 1, we will try to pick a total of NUM routers
- as long-term entries for our circuits. If NUM is 0, we try to learn
- the number from the NumEntryGuards consensus parameter, and default
- to 3 if the consensus parameter isn't set. (Default: 0)
+ as long-term entries for our circuits. If NUM is 0, we try to learn the
+ number from the guard-n-primary-guards-to-use consensus parameter, and
+ default to 1 if the consensus parameter isn't set. (Default: 0)
[[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__::
- If UseEntryGuardsAsDirectoryGuards is enabled, we try to make sure we
- have at least NUM routers to use as directory guards. If this option
- is set to 0, use the value from the NumDirectoryGuards consensus
- parameter, falling back to the value from NumEntryGuards if the
- consensus parameter is 0 or isn't set. (Default: 0)
+ If UseEntryGuardsAsDirectoryGuards is enabled, we try to make sure we have
+ at least NUM routers to use as directory guards. If this option is set to
+ 0, use the value from the guard-n-primary-dir-guards-to-use consensus
+ parameter, and default to 3 if the consensus parameter isn't set.
+ (Default: 0)
[[GuardLifetime]] **GuardLifetime** __N__ **days**|**weeks**|**months**::
If nonzero, and UseEntryGuards is set, minimum time to keep a guard before
@@ -2151,8 +2163,9 @@ is non-zero):
DIRECTORY SERVER OPTIONS
------------------------
-The following options are useful only for directory servers (that is,
-if DirPort is non-zero):
+The following options are useful only for directory servers. (Relays with
+enough bandwidth automatically become directory servers; see DirCache for
+details.)
[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__::
When this option is set, it takes an HTML file and publishes it as "/" on
diff --git a/doc/torrc_format.txt b/doc/torrc_format.txt
index 7a809901d9..b175b9fb15 100644
--- a/doc/torrc_format.txt
+++ b/doc/torrc_format.txt
@@ -175,7 +175,7 @@ and\
friends
# Backslashes in the middle of a line are included as-is. The key of
-# this one is "Too" and the value is "Many\\Backsl\ashes here" (with
+# this one is "Too" and the value is "Many\\Backsl\ashes \here" (with
# backslashes in that last string as-is)
Too \
Many\\\
@@ -185,7 +185,7 @@ here
# And here's the really yucky part. If a comment appears in a multi-line
# entry, the entry is still able to continue on the next line, as in the
# following, where the key is "This" and the value is
-# "entry and some are silly"
+# "entry and some are silly"
This entry \
# has comments \
and some \
7apu2bq3rhoylwmucxizk54afw5jyda7pho4j5zdcqpwkufke7zdzwad.onion