diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/man/tor-gencert.1.txt | 7 | ||||
| -rw-r--r-- | doc/man/tor-print-ed-signing-cert.1.txt | 4 | ||||
| -rw-r--r-- | doc/man/tor-resolve.1.txt | 4 | ||||
| -rw-r--r-- | doc/man/tor.1.txt | 37 | ||||
| -rw-r--r-- | doc/man/torify.1.txt | 4 | ||||
| -rw-r--r-- | doc/state-contents.txt | 225 | ||||
| -rw-r--r-- | doc/ticket40136 | 3 |
7 files changed, 200 insertions, 84 deletions
diff --git a/doc/man/tor-gencert.1.txt b/doc/man/tor-gencert.1.txt index 26f68b29c0..9262c4a39a 100644 --- a/doc/man/tor-gencert.1.txt +++ b/doc/man/tor-gencert.1.txt @@ -6,7 +6,6 @@ :man manual: Tor Manual tor-gencert(1) ============== -Nick Mathewson NAME ---- @@ -14,7 +13,7 @@ tor-gencert - Generate certs and keys for Tor directory authorities SYNOPSIS -------- -**tor-gencert** [-h|--help] [-v] [-r|--reuse] [--create-identity-key] [-i __id_file__] [-c +**tor-gencert** [-h|--help] [-v] [-r|--reuse] [--create-identity-key] [-i __id_file__] [-c __cert_file__] [-m __num__] [-a __address__:__port__] DESCRIPTION @@ -86,7 +85,3 @@ SEE ALSO **tor**(1) + See also the "dir-spec.txt" file, distributed with Tor. - -AUTHORS -------- - Roger Dingledine <arma@mit.edu>, Nick Mathewson <nickm@alum.mit.edu>. diff --git a/doc/man/tor-print-ed-signing-cert.1.txt b/doc/man/tor-print-ed-signing-cert.1.txt index 71c8b67ec4..2ce10d7cbd 100644 --- a/doc/man/tor-print-ed-signing-cert.1.txt +++ b/doc/man/tor-print-ed-signing-cert.1.txt @@ -32,7 +32,3 @@ SEE ALSO **tor**(1) + https://spec.torproject.org/cert-spec - -AUTHORS -------- -Roger Dingledine <arma@mit.edu>, Nick Mathewson <nickm@alum.mit.edu>. diff --git a/doc/man/tor-resolve.1.txt b/doc/man/tor-resolve.1.txt index 17a77e482f..c944d75650 100644 --- a/doc/man/tor-resolve.1.txt +++ b/doc/man/tor-resolve.1.txt @@ -48,7 +48,3 @@ SEE ALSO **tor**(1), **torify**(1). + For protocol details, see: https://spec.torproject.org/socks-extensions - -AUTHORS -------- -Roger Dingledine <arma@mit.edu>, Nick Mathewson <nickm@alum.mit.edu>. diff --git a/doc/man/tor.1.txt b/doc/man/tor.1.txt index 4b37548b07..860e1db33a 100644 --- a/doc/man/tor.1.txt +++ b/doc/man/tor.1.txt @@ -150,7 +150,7 @@ The following options in this section are only recognized on the + Use the **`--newpass`** option with **`--keygen`** only when you need to add, change, or remove a passphrase on an existing ed25519 - master identity key. You will be prompted for the old passphase + master identity key. You will be prompted for the old passphrase (if any), and the new passphrase (if any). + [NOTE] @@ -276,11 +276,6 @@ forward slash (/) in the configuration file and on the command line. AlternateBridgeAuthority replaces the default bridge authority, but leaves the directory authorities alone. -[[AndroidIdentityTag]] **AndroidIdentityTag** __tag__:: - When logging to Android's logging subsystem, adds a tag to the log identity - such that log entries are marked with "Tor-__tag__". Can not be changed while - tor is running. (Default: none) - [[AvoidDiskWrites]] **AvoidDiskWrites** **0**|**1**:: If non-zero, try to write to disk less frequently than we would otherwise. This is useful when running on flash memory or other media that support @@ -621,7 +616,7 @@ forward slash (/) in the configuration file and on the command line. **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 + flavor of consensuses and descriptors that is fetched and used for building circuits. (Default: 0) [[HardwareAccel]] **HardwareAccel** **0**|**1**:: @@ -688,7 +683,7 @@ forward slash (/) in the configuration file and on the command line. Signal-safe logs are always sent to stderr or stdout. They are also sent to a limited number of log files that are configured to log messages at error severity from the bug or general domains. They are never sent as syslogs, - android logs, control port log events, or to any API-based log + control port log events, or to any API-based log destinations. [[Log2]] **Log** __minSeverity__[-__maxSeverity__] **file** __FILENAME__:: @@ -797,6 +792,17 @@ forward slash (/) in the configuration file and on the command line. field, Tor will use it for separate rate limiting for each connection from a non-relay. (Default: 0) +[[OutboundBindAddressPT]] **OutboundBindAddressPT** __IP__:: + Request that pluggable transports makes all outbound connections + originate from the IP address specified. Because outgoing connections + are handled by the pluggable transport itself, it is not possible for + Tor to enforce whether the pluggable transport honors this option. 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. IPv6 addresses should be wrapped in square brackets. This + setting will be ignored for connections to the loopback addresses + (127.0.0.0/8 and ::1). + [[PidFile]] **PidFile** __FILE__:: On startup, write our PID to FILE. On clean shutdown, remove FILE. Can not be changed while tor is running. @@ -1303,15 +1309,6 @@ The following options are useful only for clients (that is, if Every NUM seconds consider whether to build a new circuit. (Default: 30 seconds) -[[OptimisticData]] **OptimisticData** **0**|**1**|**auto**:: - When this option is set, and Tor is using an exit node that supports - the feature, it will try optimistically to send data to the exit node - without waiting for the exit node to report whether the connection - succeeded. This can save a round-trip time for protocols like HTTP - where the client talks first. If OptimisticData is set to **auto**, - Tor will look at the UseOptimisticData parameter in the networkstatus. - (Default: auto) - // These are out of order because they logically belong together [[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ + @@ -1822,7 +1819,7 @@ The following options control when Tor enters and leaves dormant mode: this option only with great caution: it has the potential to create spurious traffic on the network. This option should only be used if Tor is started by an affirmative user activity (like - clicking on an applcation or running a command), and not if Tor + clicking on an application or running a command), and not if Tor is launched for some other reason (for example, by a startup process, or by an application that launches itself on every login.) @@ -3855,7 +3852,3 @@ https://spec.torproject.org. See also **torsocks**(1) and **torify**(1). Because Tor is still under development, there may be plenty of bugs. Please report them at https://bugs.torproject.org/. - -== AUTHORS - -Roger Dingledine [arma at mit.edu], Nick Mathewson [nickm at alum.mit.edu]. diff --git a/doc/man/torify.1.txt b/doc/man/torify.1.txt index 716625f92d..46b13e18e5 100644 --- a/doc/man/torify.1.txt +++ b/doc/man/torify.1.txt @@ -34,7 +34,3 @@ different circuits. SEE ALSO -------- **tor**(1), **torsocks**(1) - -AUTHORS -------- -Peter Palfrader and Jacob Appelbaum wrote this manual. diff --git a/doc/state-contents.txt b/doc/state-contents.txt index 44716efc0c..772e108377 100644 --- a/doc/state-contents.txt +++ b/doc/state-contents.txt @@ -14,6 +14,21 @@ Recognized fields are: Time when this state file was written. Given in ISO format (YYYY-MM-DD HH:MM:SS) + + MinutesSinceUserActivity (integer) + Dormant (0, 1, or "auto") + + These values are used to keep track of how long Tor has been idle, + for the purpose of becoming 'dormant' after a long period without + any user-initiated requests. + + "MinutesSinceUserActivity" is the number of minutes since the last + time the user asked us to do something. It is set to zero if we're + dormant. + + "Dormant" is 1 if Tor was dormant when it wrote its state file, 0 if + Tor was active, and "auto" if Tor was starting for the first time. + AccountingBytesReadInInterval (memory unit) AccountingBytesWrittenInInterval (memory unit) AccountingExpectedUsage (memory unit) @@ -36,26 +51,6 @@ Recognized fields are: BytesAtSoftLimit. If we hit the soft limit already, we did so at SoftLimitHitAt. - EntryGuard - EntryGuardDownSince - EntryGuardUnlistedSince - EntryGuardAddedBy - - These lines form sections related to entry guards. Each section - starts with a single EntryGuard line, and is then followed by - information on the state of the Entry guard. - - The EntryGuard line contains a nickname, then an identity digest, of - the guard. - - The EntryGuardDownSince and EntryGuardUnlistedSince lines are present - if the entry guard is believed to be non-running or non-listed. If - present, they contain a line in ISO format (YYYY-MM-DD HH:MM:SS). - - The EntryGuardAddedBy line is optional. It contains three - space-separated fields: the identity of the entry guard, the version of - Tor that added it, and the ISO time at which it was added. - TransportProxy One or more of these may be present. @@ -65,41 +60,183 @@ Recognized fields are: this information to spawn pluggable transport listeners in the same IP address and TCP port even after tor client restarts. - BWHistoryReadEnds (ISO time) - BWHistoryReadInterval (integer, number of seconds) - BWHistoryReadValues (comma-separated list of integer) - BWHistoryReadMaxima (comma-separated list of integer) - BWHistoryWriteEnds - BWHistoryWriteInterval - BWHistoryWriteValues - BWHistoryWriteMaxima - BWHistoryDirReadEnds - BWHistoryDirReadInterval - BWHistoryDirReadValues - BWHistoryDirReadMaxima - BWHistoryDirWriteEnds - BWHistoryDirWriteInterval - BWHistoryDirWriteValues - BWHistoryDirWriteMaxima - - These values record bandwidth history. The "Values" fields are a list, for - some number of "Intervals", of the total amount read/written during that - integer. The "Maxima" are the highest burst for each interval. + BWHistory___Ends (ISO time) + BWHistory___Interval (integer, number of seconds) + BWHistory___Values (comma-separated list of integer) + BWHistory___Maxima (comma-separated list of integer) + + These values record bandwidth history. The "Values" fields are a list, + for some number of "Intervals", of the total amount read/written during + that integer. The "Maxima" are the highest burst for each interval. Interval duration is set by the "Interval" field, in seconds. The "Ends" field is the ending time of the last interval in each list. - The *Read* and *Write* fields are the total amount read and - written; the *DirRead* and *DirWrite* variants are for directory - traffic only. + Recognized values for "___" are: + Read -- total bytes read + Write -- total bytes written + DirRead -- total bytes read for directory connections. + DirWrite -- total bytes written for directory connections. + IPv6Read -- total bytes read on IPv6 connections + IPv6Write -- total bytes written on IPv6 connections LastRotatedOnionKey The last time that we changed our onion key for a new one. Given in ISO format (YYYY-MM-DD HH:MM:SS) + This field is used to ensure that onion key rotations happen with the + appropriate frequency. + TotalBuildTimes CircuitBuildAbandonedCount CircuitBuildTimeBin - XXXX writeme. + These fields are used by the Circuit Build Timeout code, which + tries to learn what times are reasonable for circuit construction, + so that it can reject circuits that take too long to build. + + CircuitBuildTimeBin is a count of circuits that were build + successfully in some timeframe. This entry can repeat; each of + these represents some bar on a histogram. The first integer is a + number of milliseconds; it tells the position of the center of the + histogram bin on the time axis. The second number is a count of + circuits in that bin. + + CircuitBuildTimeAbandonedCount is a count of circuits that we + simply gave up on building because they were taking far too long. + + TotalBuildTimes is the number of circuit build times that we + observed in order to build the above measurements fields. If it + reaches a cap, then older measurements get thrown away. + + Guard [key=value] [key=value]... + + Describes a single entry guard used by the client. Key=value + entries with unrecognized keys are persisted. Order is not + significant. For more information about terminology used here, + system, see guard-spec.txt in the tor specifications repository. + + Recognized keys are: + + in (string) + + The name of a guard selection that this guard is in. + + rsa_id (string) + + RSA fingerprint of this guard, without spaces. + + nickname (string) + + Declared nickname of this guard. + + sampled_on (Time in ISO YYYY-MM-DDTHH:MM:SS format) + + When was this guard added to the Guard sample? + + sampled_by (tor version) + + Which version of Tor added this Guard to the sample? + (Used to help with debugging.) + + sampled_idx (integer) + + Index of this guard among sampled guards. + + listed (boolean) + + Did this guard appear in the most recent consensus? + + unlisted_since (Time in ISO YYYY-MM-DDTHH:MM:SS format) + + If this guard is not listed, when is the earliest + consensus in which we found it unlisted? + + confirmed_on (Time in ISO YYYY-MM-DDTHH:MM:SS format) + + When did this guard become confirmed? + + confirmed_idx (integer) + + Index of this guard among confirmed guards. + + bridge_addr (address) + + If this guard is a bridge, its current address. + + pb_use_attempts + pb_use_successes + pb_circ_attempts + pb_successful_circuits_closed + pb_collapsed_circuits + pb_unusable_circuits + pb_timeouts + + Used by the pathbias subsystem to keep a record of the + behavior of circuits built through this guard, in hopes of + detecting guards try to that interfere with traffic. + + All of these fields are floating-point integers which + represent a count of circuits that have been trated in + various ways. These counts decay with time. + + "use_attempts" is a count of the circuits that we've built + and tried to use for traffic. + + "successful_circuits_closed" is a count of circuits that + have closed "naturally" without timeout or error. + + "use_successes" is a count of circuits that we've sent + traffic on, and which closed "naturally" without timeout + or error. + + "circ_attempts" is a count of circuits we've tried to + build through this guard. + + "collapsed_circuits" is a count of circuits that failed + after having been built, but before sending traffic. + + "unusable_circuits" is a count of circuits that we + built, but where streams or probes but which failed, + or which encountered questionable errors. + + "timeouts" is a count of circuits that encountered a + timeout while we were building them. + +Obsolete fields include: + + EntryGuard + EntryGuardDownSince + EntryGuardUnlistedSince + EntryGuardAddedBy + + These lines formed sections related to entry guards. Each section + starts with a single EntryGuard line, and is then followed by + information on the state of the Entry guard. + + The EntryGuard line contains a nickname, then an identity digest, of + the guard. + + The EntryGuardDownSince and EntryGuardUnlistedSince lines are present + if the entry guard is believed to be non-running or non-listed. If + present, they contain a line in ISO format (YYYY-MM-DD HH:MM:SS). + + The EntryGuardAddedBy line is optional. It contains three + space-separated fields: the identity of the entry guard, the version of + Tor that added it, and the ISO time at which it was added. + + EntryGuardPathBias and EntryGuardPathUseBias are superseded by + the `pb_...` elements in the Guard flag, and served a similar purpose. + + These entries have all been superseded by the Guard line type, + since Tor 0.3.0.1-alpha. + + HidServRevCounter + + It was once used to ensure that v3 onion service directory revision + numbers were strictly increasing; we now use an order-preserving + encryption scheme for that purpose. + + This option could appear multiple times; each time it does, it + applies to a different hidden service. diff --git a/doc/ticket40136 b/doc/ticket40136 new file mode 100644 index 0000000000..cd1c0682f6 --- /dev/null +++ b/doc/ticket40136 @@ -0,0 +1,3 @@ + o Documentation: + - Update doc/state-contents.txt to more accurately explain the + current contents of a Tor state file. Closes ticket 40136. |