doc/state-contents.txt

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