Filename: 173-getinfo-option-expansion.txt
Title: GETINFO Option Expansion
Author: Damian Johnson
Created: 02-June-2010
Status: Obsolete
Overview:
Over the course of developing arm there's been numerous hacks and
workarounds to glean pieces of basic, desirable information about the tor
process. As per Roger's request I've compiled a list of these pain points
to try and improve the control protocol interface.
Motivation:
The purpose of this proposal is to expose additional process and relay
related information that is currently unavailable in a convenient,
dependable, and/or platform independent way. Examples are:
- The relay's total contributed bandwidth. This is a highly requested
piece of information and, based on the following patch from pipe, looks
trivial to include.
http://www.mail-archive.com/or-talk@freehaven.net/msg13085.html
- The process ID of the tor process. There is a high degree of guess work
in obtaining this. Arm for instance uses pidof, netstat, and ps yet
still fails on some platforms, and Orbot recently got a ticket about
its own attempt to fetch it with ps:
https://trac.torproject.org/projects/tor/ticket/1388
This just includes the pieces of missing information I've noticed
(suggestions or questions of their usefulness are welcome!).
Security Implications:
None that I'm aware of. From a security standpoint this seems decently
innocuous.
Specification:
The following addition would be made to the control-spec's GETINFO section:
"relay/bw-limit" -- Effective relayed bandwidth limit.
"relay/burst-limit" -- Effective relayed burst limit.
"relay/read-total" -- Total bytes relayed (download).
"relay/write-total" -- Total bytes relayed (upload).
"relay/flags" -- Space separated listing of flags currently held by the
relay as reported by the currently cached consensus.
"process/user" -- Username under which the tor process is running,
or an empty string if none exists.
[what do we mean 'if none exists'?]
[Implemented in 0.2.3.1-alpha.]
"process/pid" -- Process id belonging to the main tor process, -1 if none
exists for the platform.
[Implemented in 0.2.3.1-alpha.]
"process/uptime" -- Total uptime of the tor process (in seconds).
"process/uptime-reset" -- Time since last reset (startup, sighup, or RELOAD
signal, in seconds). [should clarify exactly which events cause an
uptime reset]
"process/descriptors-used" -- Count of file descriptors used.
"process/descriptor-limit" -- File descriptor limit (getrlimit results).
"ns/authority" -- Router status info (v2 directory style) for all
recognized directory authorities, joined by newlines.
"state/names" -- A space-separated list of all the keys supported by this
version of Tor's state.
"state/val/<key>" -- Provides the current state value belonging to the
given key. If undefined, this provides the key's default value.
"status/ports-seen" -- A summary of which ports we've seen connections'
circuits connect to recently, formatted the same as the EXITS_SEEN status
event described in Section 4.1.XX. This GETINFO option is currently
available only for exit relays.
4.1.XX. Per-port exit stats
The syntax is:
"650" SP "EXITS_SEEN" SP TimeStarted SP PortSummary CRLF
We just generated a new summary of which ports we've seen exiting circuits
connecting to recently. The controller could display this for the user, e.g.
in their "relay" configuration window, to give them a sense of how they're
being used (popularity of the various ports they exit to). Currently only
exit relays will receive this event.
TimeStarted is a quoted string indicating when the reported summary
counts from (in GMT).
The PortSummary keyword has as its argument a comma-separated, possibly
empty set of "port=count" pairs. For example (without linebreak),
650-EXITS_SEEN TimeStarted="2008-12-25 23:50:43"
PortSummary=80=16,443=8