1 files changed, 101 insertions, 0 deletions
diff --git a/doc/spec/proposals/173-getinfo-option-expansion.txt b/doc/spec/proposals/173-getinfo-option-expansion.txt
new file mode 100644
index 0000000000..03e18ef8d4
--- /dev/null
+++ b/doc/spec/proposals/173-getinfo-option-expansion.txt
@@ -0,0 +1,101 @@
+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
+