Write initial documentation for the contents of the state file

Fixes bug 2987.  There is still some information to go, but now we
have a place to put it.
This commit is contained in:
Nick Mathewson 2012-03-28 04:08:07 -04:00
parent 8387d8571f
commit a9c0e9fec2
4 changed files with 112 additions and 1 deletions

3
changes/bug2987 Normal file
View File

@ -0,0 +1,3 @@
o Documentation
- Begin a state-contents.txt file in doc to explain the contents of the
Tor state file. Fixes bug 2987.

View File

@ -37,7 +37,8 @@ endif
EXTRA_DIST = HACKING asciidoc-helper.sh \ EXTRA_DIST = HACKING asciidoc-helper.sh \
$(html_in) $(man_in) $(txt_in) \ $(html_in) $(man_in) $(txt_in) \
tor-rpm-creation.txt \ tor-rpm-creation.txt \
tor-win32-mingw-creation.txt spec/README tor-win32-mingw-creation.txt spec/README \
state-contents.txt
docdir = @docdir@ docdir = @docdir@

105
doc/state-contents.txt Normal file
View File

@ -0,0 +1,105 @@
Contents of the Tor state file
==============================
The state file is structured with more or less the same rules as torrc.
Recognized fields are:
TorVersion
The version of Tor that wrote this file
LastWritten
Time when this state file was written.
Given in ISO format (YYYY-MM-DD HH:MM:SS)
AccountingBytesReadInInterval (memory unit)
AccountingBytesWrittenInInterval (memory unit)
AccountingExpectedUsage (memory unit)
AccountingIntervalStart (ISO time)
AccountingSecondsActive (time interval)
AccountingSecondsToReachSoftLimit (time interval)
AccountingSoftLimitHitAt (ISO time)
AccountingBytesAtSoftLimit (memory unit)
These fields describe the state of the accounting subsystem.
The IntervalStart is the time at which the current accounting
interval began. We were expecting to use ExpectedUsage over the
course of the interval. BytesRead/BytesWritten are the total
number of bytes transferred over the whole interval. If Tor has
been active during the interval, then AccountingSecondsActive is
the amount of time for which it has been active. We were expecting
to hit the bandwidth soft limit in SecondsToReachSoftLimit after we
became active. When we hit the soft limit, we record
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.
The format is "transportname addr:port", to remember the address at
which a pluggable transport was listening.
[XXXX why?]
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.
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.
LastRotatedOnionKey
The last time that we changed our onion key for a new one.
Given in ISO format (YYYY-MM-DD HH:MM:SS)
TotalBuildTimes
CircuitBuildAbandonedCount
CircuitBuildTimeBin
XXXX writeme.

View File

@ -484,6 +484,8 @@ static const config_var_t testing_tor_network_defaults[] = {
/** Array of "state" variables saved to the ~/.tor/state file. */ /** Array of "state" variables saved to the ~/.tor/state file. */
static config_var_t _state_vars[] = { static config_var_t _state_vars[] = {
/* Remember to document these in state-contents.txt ! */
V(AccountingBytesReadInInterval, MEMUNIT, NULL), V(AccountingBytesReadInInterval, MEMUNIT, NULL),
V(AccountingBytesWrittenInInterval, MEMUNIT, NULL), V(AccountingBytesWrittenInInterval, MEMUNIT, NULL),
V(AccountingExpectedUsage, MEMUNIT, NULL), V(AccountingExpectedUsage, MEMUNIT, NULL),