Control Spec Addition First Draft

Damian Johnson atagar1 at
Thu Dec 17 02:24:30 UTC 2009

Hi Roger. Here's the first draft of the proposed additions to address the
wishlist. To start with:
- What more would be useful? I don't do core tor development nor analysis
 Karsten so I'm not sure what you'd like from a monitor for debugging or
 network examination. One thought might be a GETINFO option for getting log
 entries related to a given connection (would be especially interesting in
 case investigating circuit extension failures and such). Probably not
 possible since it would require tor to remember log data...

- Comments like "Wtf? That's utterly useless/wrong!" appreciated! I've
 included included some things that might not be helpful (like the 'e/E'
 to indicate if connections are encrypted), not to mention mistakes thanks
 a not-quite-so-perfect understanding of networking, tor, and writing specs.

- Anything dangerous? Doubt it, but the bandwidth measurements should
 either be rounded or provided occasionally (say, every second) to address
 correlation attacks. I'm sure Sebastian will enthusiastically sink some
 paranoia into this later. ;)

- Should we document how frequently the connection data is updated or have
 'last updated time' parameter?

- When hosting hidden services I'd imagine some connections are dedicated to
 them. If so, lets add a flag to indicate them.

Cheers! -Damian


The following is a proposal for additions to the control-spec's GETINFO
parameters to reveal additional information related to tor connections and
circuits. The intention is to provide a viable alternative to netstat and
for discovering these stats with the following benefits:

- Performance
Frequently querying this information via external tools has a significant
overhead (especially for busy relays). Tor already has this information
so being able to fetch it via the control port would introduce significant
performance benefits for monitoring tools like arm.

- Authoritative
How does tor view the world? An external perspective of how tor is utilizing
network resources is interesting, but from an auditing perspective it's even
more interesting if this can be used to validate tor's internal accounting.

- Additional Information
While we can infer some information like the connection type and
relay from raw connection data, it would be a lot nicer (and more accurate)
not need to guess. Providing additional information (like per-connection
bandwidth or buffer usage) might also be interesting, assuming we can do so

Most of this information is already available to relays (both benign and
malicious), but if you spot some troubling privacy implication then please
speak up! Nothing here should end the world, but we certainly don't want to
make things easier for not-so-well-meaning people.


   "conn/<Connection identity>" -- Provides entry for the associated
     connection, formatted as:

     none of the parameters contain whitespace, and additional results must
     ignored to allow for future expansion. Parameters are defined as
       CONN_ID - Unique identifier associated with this connection.
       CIRC_ID - Unique identifier for the circuit this belongs to (0 if
         doesn't belong to any circuit). At most their may be two
         (one inbound, one outbound) with any given CIRC_ID.
       OR_ID - Relay fingerprint, 0 if connection doesn't belong to a relay.
       IP/PORT - IP address and port used by the associated connection.
       TYPE_FLAGS - Single character flags indicating directionality and
         of the connection (consists of one from each category, may become
         longer for future expansion).
           I: inbound, i: listening (unestablished inbound),
             O: outbound, o: unestablished outbound
           C: client related, R: relay related, X: control, D: directory
           T: inter-tor connection, t: outside the tor network
           E: encrypted traffic, e: unencrypted traffic
         For instance, "IRtE" would indicate that this was an established
         1st-hop (or bridged) relay connection.
       READ/WRITE - Total bytes read/written over the life of this
       UPTIME - Time the connection's been established in seconds.
       BUFF - Bytes of data buffered for this relay connection.

   "conn/all" -- Newline separated listing of all current connections.

   "info/relay/bw-limit" -- Effective relayed bandwidth limit (currently
     RelayBandwidthRate if set, otherwise BandwidthRate).

   "info/relay/burst-limit" -- Effective relayed burst limit.

   "info/relay/read-total" -- Total bytes relayed (download).

   "info/relay/write-total" -- Total bytes relayed (upload).

   "info/relay/buffer-cap" -- Maximum buffer size for relay connections.

   "info/uptime-process" -- Total uptime of the tor process (in seconds).

   "info/uptime-reset" -- Time since last reset (startup or sighup signal,

   "info/descriptor-used" -- Count of file descriptors used.

   "info/descriptor-limit" -- File descriptor limit (getrlimit results).

   "ns/authority" -- Router status info (v2 directory style) for all
     recognized directory authorities, joined by newlines.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the tor-dev mailing list