Filename: 173-getinfo-option-expansion.txt Title: GETINFO Option Expansion Author: Damian Johnson Created: 02-June-2010 Status: Accepted Overview: Over the course of developing arm there's been numerous hacks and workarounds to gleam 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 of this 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 repored by the currently cached consensus. "process/user" -- Username under which the tor process is running, providing an empty string if none exists. "process/pid" -- Process id belonging to the main tor process, -1 if none exists for the platform. "process/uptime" -- Total uptime of the tor process (in seconds). "process/uptime-reset" -- Time since last reset (startup, sighup, or RELOAD signal, in seconds). "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/" -- 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