diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING/CodingStandardsRust.md | 22 | ||||
| -rw-r--r-- | doc/HACKING/ReleasingTor.md | 2 | ||||
| -rw-r--r-- | doc/tor.1.txt | 62 |
3 files changed, 44 insertions, 42 deletions
diff --git a/doc/HACKING/CodingStandardsRust.md b/doc/HACKING/CodingStandardsRust.md index 7c6405e624..d9496c08f7 100644 --- a/doc/HACKING/CodingStandardsRust.md +++ b/doc/HACKING/CodingStandardsRust.md @@ -324,12 +324,26 @@ Here are some additional bits of advice and rules: } } -3. Pass only integer types and bytes over the boundary +3. Pass only C-compatible primitive types and bytes over the boundary - The only non-integer type which may cross the FFI boundary is + Rust's C-compatible primitive types are integers and floats. + These types are declared in the [libc crate](https://doc.rust-lang.org/libc/x86_64-unknown-linux-gnu/libc/index.html#types). + Most Rust objects have different [representations](https://doc.rust-lang.org/libc/x86_64-unknown-linux-gnu/libc/index.html#types) + in C and Rust, so they can't be passed using FFI. + + Tor currently uses the following Rust primitive types from libc for FFI: + * defined-size integers: `uint32_t` + * native-sized integers: `c_int` + * native-sized floats: `c_double` + * native-sized raw pointers: `* c_void`, `* c_char`, `** c_char` + + TODO: C smartlist to Stringlist conversion using FFI + + The only non-primitive type which may cross the FFI boundary is bytes, e.g. `&[u8]`. This SHOULD be done on the Rust side by - passing a pointer (`*mut libc::c_char`) and a length - (`libc::size_t`). + passing a pointer (`*mut libc::c_char`). The length can be passed + explicitly (`libc::size_t`), or the string can be NUL-byte terminated + C string. One might be tempted to do this via doing `CString::new("blah").unwrap().into_raw()`. This has several problems: diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md index 6c8fa1331f..e70416c354 100644 --- a/doc/HACKING/ReleasingTor.md +++ b/doc/HACKING/ReleasingTor.md @@ -34,7 +34,7 @@ new Tor release: What about Coverity Scan? - What about clan scan-build? + What about clang scan-build? Does 'make distcheck' complain? diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 9aad3af98d..c3493f7181 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -311,7 +311,9 @@ GENERAL OPTIONS other than controller connections, and we close (and don't reattempt) any outbound connections. Controllers sometimes use this option to avoid using - the network until Tor is fully configured. (Default: 0) + the network until Tor is fully configured. Tor will make still certain + network-related calls (like DNS lookups) as a part of its configuration + process, even if DisableNetwork is set. (Default: 0) [[ConstrainedSockets]] **ConstrainedSockets** **0**|**1**:: If set, Tor will tell the kernel to attempt to shrink the buffers for all @@ -778,17 +780,15 @@ GENERAL OPTIONS This is useful when running on flash memory or other media that support only a limited number of writes. (Default: 0) -[[CircuitPriorityHalflife]] **CircuitPriorityHalflife** __NUM1__:: +[[CircuitPriorityHalflife]] **CircuitPriorityHalflife** __NUM__:: If this value is set, we override the default algorithm for choosing which - circuit's cell to deliver or relay next. When the value is 0, we - round-robin between the active circuits on a connection, delivering one - cell from each in turn. When the value is positive, we prefer delivering - cells from whichever connection has the lowest weighted cell count, where - cells are weighted exponentially according to the supplied - CircuitPriorityHalflife value (in seconds). If this option is not set at - all, we use the behavior recommended in the current consensus - networkstatus. This is an advanced option; you generally shouldn't have - to mess with it. (Default: not set) + circuit's cell to deliver or relay next. It is delivered first to the + circuit that has the lowest weighted cell count, where cells are weighted + exponentially according to this value (in seconds). If the value is -1, it + is taken from the consensus if possible else it will fallback to the + default value of 30. Minimum: 1, Maximum: 2147483647. This can be defined + as a float value. This is an advanced option; you generally shouldn't have + to mess with it. (Default: -1) [[CountPrivateBandwidth]] **CountPrivateBandwidth** **0**|**1**:: If this option is set, then Tor's rate-limiting applies not only to @@ -805,10 +805,9 @@ GENERAL OPTIONS [[NoExec]] **NoExec** **0**|**1**:: If this option is set to 1, then Tor will never launch another - executable, regardless of the settings of PortForwardingHelper, - ClientTransportPlugin, or ServerTransportPlugin. Once this - option has been set to 1, it cannot be set back to 0 without - restarting Tor. (Default: 0) + executable, regardless of the settings of ClientTransportPlugin + or ServerTransportPlugin. Once this option has been set to 1, + it cannot be set back to 0 without restarting Tor. (Default: 0) [[Schedulers]] **Schedulers** **KIST**|**KISTLite**|**Vanilla**:: Specify the scheduler type that tor should use. The scheduler is @@ -1398,7 +1397,7 @@ The following options are useful only for clients (that is, if [[HTTPTunnelPort]] **HTTPTunnelPort** \['address':]__port__|**auto** [_isolation flags_]:: Open this port to listen for proxy connections using the "HTTP CONNECT" - protocol instead of SOCKS. Set this to 0 + protocol instead of SOCKS. Set this to 0 if you don't want to allow "HTTP CONNECT" connections. 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 @@ -1438,7 +1437,7 @@ The following options are useful only for clients (that is, if Set this to "default", or leave it unconfigured, to use regular IPTables on Linux, or to use pf +rdr-to+ rules on *BSD systems. + + - (Default: "default".) + (Default: "default") [[NATDPort]] **NATDPort** \['address':]__port__|**auto** [_isolation flags_]:: Open this port to listen for connections from old versions of ipfw (as @@ -1731,7 +1730,7 @@ The following options are useful only for clients (that is, if prevent your Tor client from bootstrapping. If this option is negative, Tor will use a default value chosen by the directory authorities. If the directory authorities do not choose a value, Tor will default to 0.6. - (Default: -1.) + (Default: -1) [[ClientBootstrapConsensusAuthorityDownloadSchedule]] **ClientBootstrapConsensusAuthorityDownloadSchedule** __N__,__N__,__...__:: Schedule for when clients should download consensuses from authorities @@ -1889,7 +1888,7 @@ is non-zero): If you want to use a reduced exit policy rather than the default exit policy, set "ReducedExitPolicy 1". If you want to _replace_ the default exit policy with your custom exit policy, end your exit policy with either - a reject *:* or an accept *:*. Otherwise, you’re _augmenting_ (prepending + a reject *:* or an accept *:*. Otherwise, you're _augmenting_ (prepending to) the default or reduced exit policy. + + The default exit policy is: @@ -2087,18 +2086,6 @@ is non-zero): For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and IPv4Only and IPv6Only are mutually exclusive. -[[PortForwarding]] **PortForwarding** **0**|**1**:: - Attempt to automatically forward the DirPort and ORPort on a NAT router - connecting this Tor server to the Internet. If set, Tor will try both - NAT-PMP (common on Apple routers) and UPnP (common on routers from other - manufacturers). (Default: 0) - -[[PortForwardingHelper]] **PortForwardingHelper** __filename__|__pathname__:: - If PortForwarding is set, use this executable to configure the forwarding. - If set to a filename, the system path will be searched for the executable. - If set to a path, only the specified path will be executed. - (Default: tor-fw-helper) - [[PublishServerDescriptor]] **PublishServerDescriptor** **0**|**1**|**v3**|**bridge**,**...**:: This option specifies which descriptors Tor will publish when acting as a relay. You can @@ -2262,7 +2249,8 @@ is non-zero): sent and received by this relay, in addition to total cell counts. These statistics are rounded, and omitted if traffic is low. This information is important for load balancing decisions related to padding. - (Default: 1) + If ExtraInfoStatistics is enabled, it will be published + as a part of extra-info document. (Default: 1) [[DirReqStatistics]] **DirReqStatistics** **0**|**1**:: Relays and bridges only. @@ -2361,6 +2349,11 @@ is non-zero): KeywDirectory. If the option is set to 1, make the KeyDirectory readable by the default GID. (Default: 0) +[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: + Tells an authority, or other node tracking node reliability and history, + that fine-grained information about nodes can be discarded when it hasn't + changed for a given amount of time. (Default: 24 hours) + DIRECTORY SERVER OPTIONS ------------------------ @@ -2598,11 +2591,6 @@ on the public Tor network. different identity. This feature is used to migrate directory authority keys in the event of a compromise. (Default: 0) -[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: - Tells an authority, or other node tracking node reliability and history, - that fine-grained information about nodes can be discarded when it hasn't - changed for a given amount of time. (Default: 24 hours) - [[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, |