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/<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