state-contents.txt (9038B)
1 Contents of the Tor state file 2 ============================== 3 4 The state file is structured with more or less the same rules as torrc. 5 Recognized fields are: 6 7 TorVersion 8 9 The version of Tor that wrote this file 10 11 LastWritten 12 13 Time when this state file was written. 14 Given in ISO format (YYYY-MM-DD HH:MM:SS) 15 16 17 MinutesSinceUserActivity (integer) 18 Dormant (0, 1, or "auto") 19 20 These values are used to keep track of how long Tor has been idle, 21 for the purpose of becoming 'dormant' after a long period without 22 any user-initiated requests. 23 24 "MinutesSinceUserActivity" is the number of minutes since the last 25 time the user asked us to do something. It is set to zero if we're 26 dormant. 27 28 "Dormant" is 1 if Tor was dormant when it wrote its state file, 0 if 29 Tor was active, and "auto" if Tor was starting for the first time. 30 31 AccountingBytesReadInInterval (memory unit) 32 AccountingBytesWrittenInInterval (memory unit) 33 AccountingExpectedUsage (memory unit) 34 AccountingIntervalStart (ISO time) 35 AccountingSecondsActive (time interval) 36 AccountingSecondsToReachSoftLimit (time interval) 37 AccountingSoftLimitHitAt (ISO time) 38 AccountingBytesAtSoftLimit (memory unit) 39 40 These fields describe the state of the accounting subsystem. 41 42 The IntervalStart is the time at which the current accounting 43 interval began. We were expecting to use ExpectedUsage over the 44 course of the interval. BytesRead/BytesWritten are the total 45 number of bytes transferred over the whole interval. If Tor has 46 been active during the interval, then AccountingSecondsActive is 47 the amount of time for which it has been active. We were expecting 48 to hit the bandwidth soft limit in SecondsToReachSoftLimit after we 49 became active. When we hit the soft limit, we record 50 BytesAtSoftLimit. If we hit the soft limit already, we did so at 51 SoftLimitHitAt. 52 53 TransportProxy 54 55 One or more of these may be present. 56 57 The format is "transportname addr:port", to remember the address 58 at which a pluggable transport was listening. Tor bridges use 59 this information to spawn pluggable transport listeners in the 60 same IP address and TCP port even after tor client restarts. 61 62 BWHistory___Ends (ISO time) 63 BWHistory___Interval (integer, number of seconds) 64 BWHistory___Values (comma-separated list of integer) 65 BWHistory___Maxima (comma-separated list of integer) 66 67 These values record bandwidth history. The "Values" fields are a list, 68 for some number of "Intervals", of the total amount read/written during 69 that integer. The "Maxima" are the highest burst for each interval. 70 71 Interval duration is set by the "Interval" field, in seconds. The 72 "Ends" field is the ending time of the last interval in each list. 73 74 Recognized values for "___" are: 75 Read -- total bytes read 76 Write -- total bytes written 77 DirRead -- total bytes read for directory connections. 78 DirWrite -- total bytes written for directory connections. 79 IPv6Read -- total bytes read on IPv6 connections 80 IPv6Write -- total bytes written on IPv6 connections 81 82 LastRotatedOnionKey 83 84 The last time that we changed our onion key for a new one. 85 Given in ISO format (YYYY-MM-DD HH:MM:SS) 86 87 This field is used to ensure that onion key rotations happen with the 88 appropriate frequency. 89 90 TotalBuildTimes 91 CircuitBuildAbandonedCount 92 CircuitBuildTimeBin 93 94 These fields are used by the Circuit Build Timeout code, which 95 tries to learn what times are reasonable for circuit construction, 96 so that it can reject circuits that take too long to build. 97 98 CircuitBuildTimeBin is a count of circuits that were build 99 successfully in some timeframe. This entry can repeat; each of 100 these represents some bar on a histogram. The first integer is a 101 number of milliseconds; it tells the position of the center of the 102 histogram bin on the time axis. The second number is a count of 103 circuits in that bin. 104 105 CircuitBuildTimeAbandonedCount is a count of circuits that we 106 simply gave up on building because they were taking far too long. 107 108 TotalBuildTimes is the number of circuit build times that we 109 observed in order to build the above measurements fields. If it 110 reaches a cap, then older measurements get thrown away. 111 112 Guard [key=value] [key=value]... 113 114 Describes a single entry guard used by the client. Key=value 115 entries with unrecognized keys are persisted. Order is not 116 significant. For more information about terminology used here, 117 system, see guard-spec.txt in the tor specifications repository. 118 119 Recognized keys are: 120 121 in (string) 122 123 The name of a guard selection that this guard is in. 124 125 rsa_id (string) 126 127 RSA fingerprint of this guard, without spaces. 128 129 nickname (string) 130 131 Declared nickname of this guard. 132 133 sampled_on (Time in ISO YYYY-MM-DDTHH:MM:SS format) 134 135 When was this guard added to the Guard sample? 136 137 sampled_by (tor version) 138 139 Which version of Tor added this Guard to the sample? 140 (Used to help with debugging.) 141 142 sampled_idx (integer) 143 144 Index of this guard among sampled guards. 145 146 listed (boolean) 147 148 Did this guard appear in the most recent consensus? 149 150 unlisted_since (Time in ISO YYYY-MM-DDTHH:MM:SS format) 151 152 If this guard is not listed, when is the earliest 153 consensus in which we found it unlisted? 154 155 confirmed_on (Time in ISO YYYY-MM-DDTHH:MM:SS format) 156 157 When did this guard become confirmed? 158 159 confirmed_idx (integer) 160 161 Index of this guard among confirmed guards. 162 163 bridge_addr (address) 164 165 If this guard is a bridge, its current address. 166 167 pb_use_attempts 168 pb_use_successes 169 pb_circ_attempts 170 pb_successful_circuits_closed 171 pb_collapsed_circuits 172 pb_unusable_circuits 173 pb_timeouts 174 175 Used by the pathbias subsystem to keep a record of the 176 behavior of circuits built through this guard, in hopes of 177 detecting guards try to that interfere with traffic. 178 179 All of these fields are floating-point integers which 180 represent a count of circuits that have been trated in 181 various ways. These counts decay with time. 182 183 "use_attempts" is a count of the circuits that we've built 184 and tried to use for traffic. 185 186 "successful_circuits_closed" is a count of circuits that 187 have closed "naturally" without timeout or error. 188 189 "use_successes" is a count of circuits that we've sent 190 traffic on, and which closed "naturally" without timeout 191 or error. 192 193 "circ_attempts" is a count of circuits we've tried to 194 build through this guard. 195 196 "collapsed_circuits" is a count of circuits that failed 197 after having been built, but before sending traffic. 198 199 "unusable_circuits" is a count of circuits that we 200 built, but where streams or probes but which failed, 201 or which encountered questionable errors. 202 203 "timeouts" is a count of circuits that encountered a 204 timeout while we were building them. 205 206 Obsolete fields include: 207 208 EntryGuard 209 EntryGuardDownSince 210 EntryGuardUnlistedSince 211 EntryGuardAddedBy 212 213 These lines formed sections related to entry guards. Each section 214 starts with a single EntryGuard line, and is then followed by 215 information on the state of the Entry guard. 216 217 The EntryGuard line contains a nickname, then an identity digest, of 218 the guard. 219 220 The EntryGuardDownSince and EntryGuardUnlistedSince lines are present 221 if the entry guard is believed to be non-running or non-listed. If 222 present, they contain a line in ISO format (YYYY-MM-DD HH:MM:SS). 223 224 The EntryGuardAddedBy line is optional. It contains three 225 space-separated fields: the identity of the entry guard, the version of 226 Tor that added it, and the ISO time at which it was added. 227 228 EntryGuardPathBias and EntryGuardPathUseBias are superseded by 229 the `pb_...` elements in the Guard flag, and served a similar purpose. 230 231 These entries have all been superseded by the Guard line type, 232 since Tor 0.3.0.1-alpha. 233 234 HidServRevCounter 235 236 It was once used to ensure that v3 onion service directory revision 237 numbers were strictly increasing; we now use an order-preserving 238 encryption scheme for that purpose. 239 240 This option could appear multiple times; each time it does, it 241 applies to a different hidden service.