commit a9c0e9fec2ced629aefdc1436ec41467353cc9a0 Author: Nick Mathewson <nickm@torproject.org> Date: Wed Mar 28 04:08:07 2012 -0400 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. --- changes/bug2987 | 3 + doc/Makefile.am | 3 +- doc/state-contents.txt | 105 ++++++++++++++++++++++++++++++++++++++++++++++++ src/or/config.c | 2 + 4 files changed, 112 insertions(+), 1 deletions(-) diff --git a/changes/bug2987 b/changes/bug2987 new file mode 100644 index 0000000..727f376 --- /dev/null +++ b/changes/bug2987 @@ -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. diff --git a/doc/Makefile.am b/doc/Makefile.am index d8d9fbe..d26f830 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -37,7 +37,8 @@ endif EXTRA_DIST = HACKING asciidoc-helper.sh \ $(html_in) $(man_in) $(txt_in) \ tor-rpm-creation.txt \ - tor-win32-mingw-creation.txt spec/README + tor-win32-mingw-creation.txt spec/README \ + state-contents.txt docdir = @docdir@ diff --git a/doc/state-contents.txt b/doc/state-contents.txt new file mode 100644 index 0000000..730e2fb --- /dev/null +++ b/doc/state-contents.txt @@ -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. diff --git a/src/or/config.c b/src/or/config.c index 3de8426..05f53bd 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -484,6 +484,8 @@ static const config_var_t testing_tor_network_defaults[] = { /** Array of "state" variables saved to the ~/.tor/state file. */ static config_var_t _state_vars[] = { + /* Remember to document these in state-contents.txt ! */ + V(AccountingBytesReadInInterval, MEMUNIT, NULL), V(AccountingBytesWrittenInInterval, MEMUNIT, NULL), V(AccountingExpectedUsage, MEMUNIT, NULL),