Control Spec Addition First Draft

[Damian Johnson]

Hi Roger. Here's the first draft of the proposed additions to address the
arm
wishlist. To start with:
- What more would be useful? I don't do core tor development nor analysis
like
 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
naively
 included included some things that might not be helpful (like the 'e/E'
flag
 to indicate if connections are encrypted), not to mention mistakes thanks
to
 a not-quite-so-perfect understanding of networking, tor, and writing specs.

- Anything dangerous? Doubt it, but the bandwidth measurements should
probably
 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
some
 '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
lsof
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
cached
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
corresponding
relay from raw connection data, it would be a lot nicer (and more accurate)
to
not need to guess. Providing additional information (like per-connection
bandwidth or buffer usage) might also be interesting, assuming we can do so
safely.

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:
       CONN_ID CIRC_ID OR_ID IP PORT TYPE_FLAGS READ WRITE UPTIME BUFF

     none of the parameters contain whitespace, and additional results must
be
     ignored to allow for future expansion. Parameters are defined as
follows:
       CONN_ID - Unique identifier associated with this connection.
       CIRC_ID - Unique identifier for the circuit this belongs to (0 if
this
         doesn't belong to any circuit). At most their may be two
connections
         (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
type
         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
connection.
       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,
in
     seconds).

   "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: <http://lists.torproject.org/pipermail/tor-dev/attachments/20091216/3212c7eb/attachment.htm>