diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING/Module.md | 111 | ||||
| -rw-r--r-- | doc/include.am | 5 | ||||
| -rw-r--r-- | doc/tor.1.txt | 141 |
3 files changed, 191 insertions, 66 deletions
diff --git a/doc/HACKING/Module.md b/doc/HACKING/Module.md new file mode 100644 index 0000000000..1028a029d9 --- /dev/null +++ b/doc/HACKING/Module.md @@ -0,0 +1,111 @@ +# Modules in Tor # + +This document describes the build system and coding standards when writing a +module in Tor. + +## 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. + +Currently, there is only one module: + + - Directory Authority subsystem (dirauth) + +It is located in its own directory in `src/or/dirauth/`. To disable it, one +need to pass `--disable-module-dirauth` at configure time. All modules are +currently enabled by default. + +## Build System ## + +The changes to the build system are pretty straightforward. + +1. Locate in the `configure.ac` file this define: `m4_define(MODULES`. It + contains a list (white-space separated) of the module in tor. Add yours to + the list. + +2. Use the `AC_ARG_ENABLE([module-dirauth]` template for your new module. We + use the "disable module" approach instead of enabling them one by one. So, + by default, tor will build all the modules. + + This will define the `HAVE_MODULE_<name>` statement which can be used in + the C code to conditionally compile things for your module. And the + `BUILD_MODULE_<name>` is also defined for automake files (e.g: include.am). + +3. In the `src/or/include.am` file, locate the `MODULE_DIRAUTH_SOURCES` value. + You need to create your own `_SOURCES` variable for your module and then + conditionally add the it to `LIBTOR_A_SOURCES` if you should build the + module. + + It is then **very** important to add your SOURCES variable to + `src_or_libtor_testing_a_SOURCES` so the tests can build it. + +4. Do the same for header files, locate `ORHEADERS +=` which always add all + headers of all modules so the symbol can be found for the module entry + points. + +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 tests everything. + +## Coding ## + +As mentioned above, a module must be isolated in its own directory (name of +the module) in `src/or/`. + +There are couples of "rules" you want to follow: + +* Minimize as much as you can the number of entry points into your module. + Less is always better but of course that doesn't work out for every use + case. However, it is a good thing to always keep that in mind. + +* Do **not** use the `HAVE_MODULE_<name>` define outside of the module code + base. Every entry point should have a second definition if the module is + disabled. For instance: + + ``` + #ifdef HAVE_MODULE_DIRAUTH + + int sr_init(int save_to_disk); + + #else /* HAVE_MODULE_DIRAUTH */ + + static inline int + sr_init(int save_to_disk) + { + (void) save_to_disk; + return 0; + } + + #endif /* HAVE_MODULE_DIRAUTH */ + + ``` + + The main reason for this approach is to avoid having conditional code + everywhere in the code base. It should be centralized as much as possible + which helps maintainability but also avoids conditional spaghetti code + making the code much more difficult to follow/understand. + +* It is possible that you end up with code that needs to be used by the rest + of the code base but is still part of your module. As a good example, if you + look at `src/or/shared_random_client.c`: it contains code needed by the hidden + service subsystem but mainly related to the shared random subsystem very + specific to the dirauth module. + + This is fine but try to keep it as lean as possible and never use the same + filename as the one in the module. For example, this is a bad idea and + should never be done: + + - `src/or/shared_random.c` + - `src/or/dirauth/shared_random.c` + +* When you include headers from the module, **always** use the full module + path in your statement. Example: + + `#include "dirauth/dirvote.h"` + + The main reason is that we do **not** add the module include path by default + so it needs to be specified. But also, it helps our human brain understand + which part comes from a module or not. + + Even **in** the module itself, use the full include path like above. diff --git a/doc/include.am b/doc/include.am index 0e8de231e1..7942188eaf 100644 --- a/doc/include.am +++ b/doc/include.am @@ -35,10 +35,15 @@ EXTRA_DIST+= doc/asciidoc-helper.sh \ doc/TUNING \ doc/HACKING/README.1st.md \ doc/HACKING/CodingStandards.md \ + doc/HACKING/CodingStandardsRust.md \ + doc/HACKING/Fuzzing.md \ doc/HACKING/GettingStarted.md \ + doc/HACKING/GettingStartedRust.md \ doc/HACKING/HelpfulTools.md \ doc/HACKING/HowToReview.md \ + doc/HACKING/Module.md \ doc/HACKING/ReleasingTor.md \ + doc/HACKING/Tracing.md \ doc/HACKING/WritingTests.md docdir = @docdir@ diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 2f74d567e5..f42ad0dd3c 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -368,7 +368,8 @@ GENERAL OPTIONS [[ControlSocket]] **ControlSocket** __Path__:: Like ControlPort, but listens on a Unix domain socket, rather than a TCP - socket. '0' disables ControlSocket (Unix and Unix-like systems only.) + socket. '0' disables ControlSocket. (Unix and Unix-like systems only.) + (Default: 0) [[ControlSocketsGroupWritable]] **ControlSocketsGroupWritable** **0**|**1**:: If this option is set to 0, don't allow the filesystem group to read and @@ -542,13 +543,21 @@ GENERAL OPTIONS (Default: 1) [[FetchUselessDescriptors]] **FetchUselessDescriptors** **0**|**1**:: - If set to 1, Tor will fetch every consensus flavor, descriptor, and - certificate that it hears about. Otherwise, it will avoid fetching useless - descriptors: flavors that it is not using to build circuits, and authority - certificates it does not trust. This option is useful if you're using a + If set to 1, Tor will fetch every consensus flavor, and all server + descriptors and authority certificates referenced by those consensuses, + except for extra info descriptors. When this option is 1, Tor will also + keep fetching descriptors, even when idle. + If set to 0, Tor will avoid fetching useless descriptors: flavors that it + is not using to build circuits, and authority certificates it does not + trust. When Tor hasn't built any application circuits, it will go idle, + and stop fetching descriptors. This option is useful if you're using a tor client with an external parser that uses a full consensus. - This option fetches all documents, **DirCache** fetches and serves - all documents. (Default: 0) + This option fetches all documents except extrainfo descriptors, + **DirCache** fetches and serves all documents except extrainfo + descriptors, **DownloadExtraInfo*** fetches extrainfo documents, and serves + them if **DirCache** is on, and **UseMicrodescriptors** changes the + flavour of consensues and descriptors that is fetched and used for + building circuits. (Default: 0) [[HTTPProxy]] **HTTPProxy** __host__[:__port__]:: Tor will make all its directory requests through this host:port (or host:80 @@ -1228,7 +1237,7 @@ The following options are useful only for clients (that is, if flag is not supported. **CacheIPv4DNS**;; Tells the client to remember IPv4 DNS answers we receive from exit - nodes via this connection. (On by default.) + nodes via this connection. **CacheIPv6DNS**;; Tells the client to remember IPv6 DNS answers we receive from exit nodes via this connection. @@ -1285,9 +1294,11 @@ The following options are useful only for clients (that is, if 2 minutes) [[TokenBucketRefillInterval]] **TokenBucketRefillInterval** __NUM__ [**msec**|**second**]:: - Set the refill interval of Tor's token bucket to NUM milliseconds. - NUM must be between 1 and 1000, inclusive. Note that the configured - bandwidth limits are still expressed in bytes per second: this + Set the refill delay interval of Tor's token bucket to NUM milliseconds. + NUM must be between 1 and 1000, inclusive. When Tor is out of bandwidth, + on a connection or globally, it will wait up to this long before it tries + to use that connection again. + Note that bandwidth limits are still expressed in bytes per second: this option only affects the frequency with which Tor checks to see whether previously exhausted connections may read again. Can not be changed while tor is running. (Default: 100 msec) @@ -1344,6 +1355,13 @@ The following options are useful only for clients (that is, if number from the guard-n-primary-guards-to-use consensus parameter, and default to 1 if the consensus parameter isn't set. (Default: 0) +[[NumPrimaryGuards]] **NumPrimaryGuards** __NUM__:: + If UseEntryGuards is set to 1, we will try to pick NUM routers for our + primary guard list, which is the set of routers we strongly prefer when + connecting to the Tor network. If NUM is 0, we try to learn the number from + the guard-n-primary-guards consensus parameter, and default to 3 if the + consensus parameter isn't set. (Default: 0) + [[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__:: If UseEntryGuards is set to 1, 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 @@ -1648,9 +1666,8 @@ The following options are useful only for clients (that is, if in order to build its circuits. Using microdescriptors makes Tor clients download less directory information, thus saving bandwidth. Directory caches need to fetch regular descriptors and microdescriptors, so this - option doesn't save any bandwidth for them. If this option is set to - "auto" (recommended) then it is on for all clients that do not set - FetchUselessDescriptors. (Default: auto) + option doesn't save any bandwidth for them. For legacy reasons, auto is + accepted, but it has the same effect as 1. (Default: auto) [[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ + @@ -1748,32 +1765,29 @@ The following options are useful only for clients (that is, if directory authorities do not choose a value, Tor will default to 0.6. (Default: -1) -[[ClientBootstrapConsensusAuthorityDownloadSchedule]] **ClientBootstrapConsensusAuthorityDownloadSchedule** __N__,__N__,__...__:: - Schedule for when clients should download consensuses from authorities +[[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 live consensus). Only used by clients fetching from a list of fallback directory mirrors. This schedule is advanced by (potentially concurrent) connection attempts, unlike other schedules, which are advanced by - connection failures. (Default: 6, 11, 3600, 10800, 25200, 54000, 111600, - 262800) + connection failures. (Default: 6) -[[ClientBootstrapConsensusFallbackDownloadSchedule]] **ClientBootstrapConsensusFallbackDownloadSchedule** __N__,__N__,__...__:: - Schedule for when clients should download consensuses from fallback +[[ClientBootstrapConsensusFallbackDownloadInitialDelay]] **ClientBootstrapConsensusFallbackDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses from fallback directory mirrors if they are bootstrapping (that is, they don't have a usable, reasonably live consensus). Only used by clients fetching from a list of fallback directory mirrors. This schedule is advanced by (potentially concurrent) connection attempts, unlike other schedules, - which are advanced by connection failures. (Default: 0, 1, 4, 11, 3600, - 10800, 25200, 54000, 111600, 262800) + which are advanced by connection failures. (Default: 0) -[[ClientBootstrapConsensusAuthorityOnlyDownloadSchedule]] **ClientBootstrapConsensusAuthorityOnlyDownloadSchedule** __N__,__N__,__...__:: - Schedule for when clients should download consensuses from authorities +[[ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay** __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 live consensus). Only used by clients which don't have or won't fetch from a list of fallback directory mirrors. This schedule is advanced by (potentially concurrent) connection attempts, unlike other schedules, - which are advanced by connection failures. (Default: 0, 3, 7, 3600, - 10800, 25200, 54000, 111600, 262800) + which are advanced by connection failures. (Default: 0) [[ClientBootstrapConsensusMaxInProgressTries]] **ClientBootstrapConsensusMaxInProgressTries** __NUM__:: Try this many simultaneous connections to download a consensus before @@ -2067,6 +2081,8 @@ is non-zero): [[Nickname]] **Nickname** __name__:: Set the server's nickname to \'name'. Nicknames must be between 1 and 19 characters inclusive, and must contain only the characters [a-zA-Z0-9]. + If not set, **Unnamed** will be used. Relays can always be uniquely identified + by their identity fingerprints. [[NumCPUs]] **NumCPUs** __num__:: How many processes to use at once for decrypting onionskins and other @@ -2399,10 +2415,12 @@ details.) some entry in the policy is accepted. [[DirCache]] **DirCache** **0**|**1**:: - When this option is set, Tor caches all current directory documents and - accepts client requests for them. Setting DirPort is not required for this, - because clients connect via the ORPort by default. Setting either DirPort - or BridgeRelay and setting DirCache to 0 is not supported. (Default: 1) + When this option is set, Tor caches all current directory documents except + extra info documents, and accepts client requests for them. If + **DownloadExtraInfo** is set, cached extra info documents are also cached. + Setting **DirPort** is not required for **DirCache**, because clients + connect via the ORPort by default. Setting either DirPort or BridgeRelay + and setting DirCache to 0 is not supported. (Default: 1) [[MaxConsensusAgeForDiffs]] **MaxConsensusAgeForDiffs** __N__ **minutes**|**hours**|**days**|**weeks**:: When this option is nonzero, Tor caches will not try to generate @@ -2904,12 +2922,9 @@ The following options are used for running a testing Tor network. AssumeReachable 1 AuthDirMaxServersPerAddr 0 AuthDirMaxServersPerAuthAddr 0 - ClientBootstrapConsensusAuthorityDownloadSchedule 0, 2, - 4 (for 40 seconds), 8, 16, 32, 60 - ClientBootstrapConsensusFallbackDownloadSchedule 0, 1, - 4 (for 40 seconds), 8, 16, 32, 60 - ClientBootstrapConsensusAuthorityOnlyDownloadSchedule 0, 1, - 4 (for 40 seconds), 8, 16, 32, 60 + ClientBootstrapConsensusAuthorityDownloadInitialDelay 0 + ClientBootstrapConsensusFallbackDownloadInitialDelay 0 + ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay 0 ClientDNSRejectInternalAddresses 0 ClientRejectInternalAddresses 0 CountPrivateBandwidth 1 @@ -2924,12 +2939,12 @@ The following options are used for running a testing Tor network. TestingV3AuthInitialDistDelay 20 seconds TestingAuthDirTimeToLearnReachability 0 minutes TestingEstimatedDescriptorPropagationTime 0 minutes - TestingServerDownloadSchedule 0, 0, 0, 5, 10, 15, 20, 30, 60 - TestingClientDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60 - TestingServerConsensusDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60 - TestingClientConsensusDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60 - TestingBridgeDownloadSchedule 10, 30, 60 - TestingBridgeBootstrapDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60 + TestingServerDownloadInitialDelay 0 + TestingClientDownloadInitialDelay 0 + TestingServerConsensusDownloadInitialDelay 0 + TestingClientConsensusDownloadInitialDelay 0 + TestingBridgeDownloadInitialDelay 10 + TestingBridgeBootstrapDownloadInitialDelay 0 TestingClientMaxIntervalWithoutRequest 5 seconds TestingDirConnectionMaxStall 30 seconds TestingEnableConnBwEvent 1 @@ -2968,37 +2983,31 @@ The following options are used for running a testing Tor network. Minimum value for the Fast flag. Overrides the ordinary minimum taken from the consensus when TestingTorNetwork is set. (Default: 0.) -[[TestingServerDownloadSchedule]] **TestingServerDownloadSchedule** __N__,__N__,__...__:: - Schedule for when servers should download things in general. Changing this - requires that **TestingTorNetwork** is set. (Default: 0, 0, 0, 60, 60, 120, - 300, 900, 2147483647) +[[TestingServerDownloadInitialDelay]] **TestingServerDownloadInitialDelay** __N__:: + Initial delay in seconds for when servers should download things in general. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) -[[TestingClientDownloadSchedule]] **TestingClientDownloadSchedule** __N__,__N__,__...__:: - Schedule for when clients should download things in general. Changing this - requires that **TestingTorNetwork** is set. (Default: 0, 0, 60, 300, 600, - 2147483647) +[[TestingClientDownloadInitialDelay]] **TestingClientDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download things in general. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) -[[TestingServerConsensusDownloadSchedule]] **TestingServerConsensusDownloadSchedule** __N__,__N__,__...__:: - Schedule for when servers should download consensuses. Changing this - requires that **TestingTorNetwork** is set. (Default: 0, 0, 60, 300, 600, - 1800, 1800, 1800, 1800, 1800, 3600, 7200) +[[TestingServerConsensusDownloadInitialDelay]] **TestingServerConsensusDownloadInitialDelay** __N__:: + Initial delay in seconds for when servers should download consensuses. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) -[[TestingClientConsensusDownloadSchedule]] **TestingClientConsensusDownloadSchedule** __N__,__N__,__...__:: - Schedule for when clients should download consensuses. Changing this - requires that **TestingTorNetwork** is set. (Default: 0, 0, 60, 300, 600, - 1800, 3600, 3600, 3600, 10800, 21600, 43200) +[[TestingClientConsensusDownloadInitialDelay]] **TestingClientConsensusDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses. Changing this + requires that **TestingTorNetwork** is set. (Default: 0) -[[TestingBridgeDownloadSchedule]] **TestingBridgeDownloadSchedule** __N__,__N__,__...__:: - Schedule for when clients should download each bridge descriptor when they +[[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, 25200, - 54000, 111600, 262800) + this requires that **TestingTorNetwork** is set. (Default: 10800) -[[TestingBridgeBootstrapDownloadSchedule]] **TestingBridgeBootstrapDownloadSchedule** __N__,__N__,__...__:: - Schedule for when clients should download each bridge descriptor when they +[[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, 30, - 90, 600, 3600, 10800, 25200, 54000, 111600, 262800) + 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 |