Proposal: GETINFO controller option for connection information

[Damian Johnson]

>
> Hm.  But we don't necessarily know this.  Our "are we client-facing"
> tests are approximate, not certain, and the only way to tell whether
> we're intermediate or exiting is to wait and see if we're told to
> exit.
>

Understood that client facing tests fail by design when dealing with
bridges. In the case of the outbound connection component it sounds like
we'll need to wait until we're either asked to extend the circuit or exit
before counting it as an 'established circuit' and reporting it.

In fact, the leaky-pipe topology means that we're potentially
> intermediate _and_ exiting on a single circuit.
>

(to save other readers the googling, this means that clients can exit the
circuit prematurely, such as at a middle node if the exit policy permits it)

You're right, that would mess with the classification. If/when this is
implemented I'd suggest adding anther classification for middle hops when
they're first used to exit traffic.

The goal of these type flags are to indicate to controllers which circuits
are sensitive and which are less so. In arm for instance most information
for client/exit connections are scrubbed. Indicating via a change of the
circuits status (an UPDATE event) when this begins exiting traffic seems
good enough to me.

Also, it's still a tiny bit ambiguous: some people consider a circuit
> used for a rendezvous point as an exit, and some don't.
>

Not following what you mean here... do you mean a hidden service rendezvous?
If so then I don't see how this is exiting. Maybe the previous type
classifications that simply said whether or not the inbound/outbound
connection lies inside the tor network was clearer...

The only other change I'd suggest to xxx-circ-getinfo-option.txt is to
> consider using named parameters (like "WRITE=9090") rather than
> positional parameters
>

Good idea, done (though I didn't find a good example of the preferred syntax
for this).

Also, maybe rename the "circ" GETINFO to "rcirc" for consistency?
>

Done (pity the CIRC event had already been used...).

There totally is a way to tell how old a descriptor is: you just look
> at the "published" field on the descriptor, and that tells you when it
> was first uploaded to the authorities.
>

Sweet! Didn't realise this was available. Dropped from proposal.

It sounds like it should be a torrc option saying "Don't stop
> refetching descriptors when there's no network activity."  Actually,
> do we have one of those already?
>

Yup, we have FetchUselessDescriptors. However, setting this causes an extra
load on the directory authorities, hence the desire to be able to do this a
bit more selectively (for instance just fetching our own descriptor every
hour but letting the rest go stale).

Cheers! -Damian

On Mon, Jun 28, 2010 at 2:59 PM, Nick Mathewson <nickm at freehaven.net> wrote:

> On Thu, Jun 24, 2010 at 1:34 AM, Damian Johnson <atagar1 at gmail.com> wrote:
> > Hi Nick. Thanks for the comments!
> >
> >> * IN_TYPE/OUT_TYPE talk about the type of an inbound/outbound
> >> "connection."  Do you mean circuits, or connections on the circuits?
> >> Either way I'm confused.  For example, a control connection is never
> >> attached to a circuit at all.
> >
> > Yea, that isn't really appropriate and was making the spec messier than
> it
> > needed to be. Replaced with a single TYPE parameter to indicate the
> > placement in the circuit (guard/bridge, relay, exit, or one-hop in case
> > they're allowing them).
>
> Hm.  But we don't necessarily know this.  Our "are we client-facing"
> tests are approximate, not certain, and the only way to tell whether
> we're intermediate or exiting is to wait and see if we're told to
> exit.  In fact, the leaky-pipe topology means that we're potentially
> intermediate _and_ exiting on a single circuit.
>
> Also, it's still a tiny bit ambiguous: some people consider a circuit
> used for a rendezvous point as an exit, and some don't.
>
> The only other change I'd suggest to xxx-circ-getinfo-option.txt is to
> consider using named parameters (like "WRITE=9090") rather than
> positional parameters ('The third value is the write one').  This has
> turned out to make it way easier to expand events in the future.
> (Consider what would happen if we wanted to add another field to
> RCIRC.)
>
> Also, maybe rename the "circ" GETINFO to "rcirc" for consistency?
>
> On xxx-getinfo-option-expansion.txt :
>
> >> * On "desc/time", why is it important to know the latest time we
> >> fetched a server descriptor?
> >
> > There's some interesting information here such as your relay's observed
> > bandwidth. However, there's no way of telling how stale information
> provided
> > by the "desc/id/*" is, and since most relays stop fetching descriptors
> after
> > a time it's often hideously ancient.
>
> There totally is a way to tell how old a descriptor is: you just look
> at the "published" field on the descriptor, and that tells you when it
> was first uploaded to the authorities.
>
> If it's important to tell when you _fetched_ the descriptor (as
> opposed to when it was first published), we do store that information,
> but it should be made available on a per-descriptor basis, right?
> That would be more useful.
>
> > What I'd really like an option to manually refresh descriptors (both
> > individually and as a batch call), however since I was aiming to keep
> this
> > proposal limited to GETINFO options it seemed inappropriate. Do you have
> any
> > thoughts on this sort of functionality? What section of the control-spec
> > would it go under?
>
> It sounds like it should be a torrc option saying "Don't stop
> refetching descriptors when there's no network activity."  Actually,
> do we have one of those already?
>
> >> * Also on process/user: If you meant "username", then there  should
> >> indeed be an option to get all the *id stuff discussed upthread.
> >
> > I'm sure this is a dumb question but... why? I've never had use for the
> > numeric uid, let alone the three other varieties Jake mentioned
> (actually,
> > never heard of them before...). If you can think of use cases in which
> > they're useful then by all means include them. However, I don't
> particularly
> > care about that information.
>
> For unixy programs, it's way easier to work with uids than with
> usernames.  The other varieties are useful for telling you about Tor's
> setuid/setgid state.
>
> Other than that, looks good.
> --
> Nick
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.torproject.org/pipermail/tor-dev/attachments/20100629/7e73505f/attachment.htm>
-------------- next part --------------
Filename: xxx-circ-getinfo-option.txt
Title: GETINFO controller option for circuit information
Author: Damian Johnson
Created: 03-June-2010
Status: Draft

Overview:

    This details an additional GETINFO option that would provide information
    concerning a relay's current circuits.

Motivation:

    The original proposal was for connection related information, but Jake make
    the excellent point that any information retrieved from the control port
    is...
    
      1. completely ineffectual for auditing purposes since either (a) these
      results can be fetched from netstat already or (b) the information would
      only be provided via tor and can't be validated.
      
      2. The more useful uses for connection information can be achieved with
      much less (and safer) information.
    
    Hence the proposal is now for circuit based rather than connection based
    information. This would strip the most controversial and sensitive data
    entirely (ip addresses, ports, and connection based bandwidth breakdowns)
    while still being useful for the following purposes:

    - Basic Relay Usage Questions
    How is the bandwidth I'm contributing broken down? Is it being evenly
    distributed or is someone hogging most of it? Do these circuits belong to
    the hidden service I'm running or something else? Now that I'm using exit
    policy X am I desirable as an exit, or are most people just using me as a
    relay?

    - Debugging
    Say a relay has a restrictive firewall policy for outbound connections,
    with the ORPort whitelisted but doesn't realize that tor needs random high
    ports. Tor would report success ("your orport is reachable - excellent")
    yet the relay would be nonfunctional. This proposed information would
    reveal numerous RELAY -> YOU -> UNESTABLISHED circuits, giving a good
    indicator of what's wrong.

    - Visualization
    A nice benefit of visualizing tor's behavior is that it becomes a helpful
    tool in puzzling out how tor works. For instance, tor spawns numerous
    client connections at startup (even if unused as a client). As a newcomer
    to tor these asymmetric (outbound only) connections mystified me for quite
    a while until until Roger explained their use to me. The proposed
    TYPE_FLAGS would let controllers clearly label them as being client
    related, making their purpose a bit clearer.

    At the moment connection data can only be retrieved via commands like
    netstat, ss, and lsof. However, providing an alternative via the control
    port provides several advantages:

      - scrubbing for private data
          Raw connection data has no notion of what's sensitive and what is
          not. The relay's flags and cached consensus can be used to take
          educated guesses concerning which connections could possibly belong
          to client or exit traffic, but this is both difficult and inaccurate.
          Anything provided via the control port can scrubbed to make sure we
          aren't providing anything we think relay operators should not see.
     
      - additional information
          All connection querying commands strictly provide the ip address and
          port of connections, and nothing else. However, for the uses listed
          above the far more interesting attributes are the circuit's type,
          bandwidth usage and uptime.
     
      - improved performance
          Querying connection data is an expensive activity, especially for
          busy relays or low end processors (such as mobile devices). Tor
          already internally knows its circuits, allowing for vastly quicker
          lookups.
     
      - cross platform capability
          The connection querying utilities mentioned above not only aren't
          available under Windows, but differ widely among different *nix
          platforms. FreeBSD in particular takes a very unique approach,
          dropping important options from netstat and assigning ss to a
          spreadsheet application instead. A controller interface, however,
          would provide a uniform means of retrieving this information.

Security Implications:

    This is an open question. This proposal lacks the most controversial pieces
    of information (ip addresses and ports) and insight into potential threats
    this would pose would be very welcomed!

Specification:

   The following addition would be made to the control-spec's GETINFO section:

  "rcirc/id/<Circuit identity>" -- Provides entry for the associated relay
    circuit, formatted as:
      CIRC_ID=<circuit ID> CREATED=<timestamp> UPDATED=<timestamp> TYPE=<flag>
        READ=<bytes> WRITE=<bytes>

    none of the parameters contain whitespace, and additional results must be
    ignored to allow for future expansion. Parameters are defined as follows:
      CIRC_ID - Unique numeric identifier for the circuit this belongs to.
      CREATED - Unix timestamp (as seconds since the Epoch) for when the
          circuit was created.
      UPDATED - Unix timestamp for when this information was last updated.
      TYPE - Single character flag indicating the positioning in the circuit:
          C: client facing (first hop / bridge)
          M: intermediate
          E: exiting
          B: both client facing and exiting
      READ - Total bytes transmitted toward the exit over the circuit.
      WRITE - Total bytes transmitted toward the client over the circuit.

  "rcirc/all" -- The 'rcirc/id/*' output for all current circuits, joined by
    newlines.

   The following would be included for circ info update events.

4.1.X. Relay circuit status changed

  The syntax is:
     "650" SP "RCIRC" SP CircID SP Notice [SP Created SP Updated SP Type SP
          Read SP Write] CRLF
     
     Notice =
            "NEW"    / ; first information being provided for this circuit
            "UPDATE" / ; update for a previously reported circuit
            "CLOSED"   ; notice that the circuit no longer exists
    
  Notice indicating that queryable information on a relay related circuit has
  changed. If the Notice parameter is either "NEW" or "UPDATE" then this
  provides the same fields that would be given by calling "GETINFO rcirc/id/"
  with the CircID.
-------------- next part --------------
Filename: xxx-getinfo-option-expansion.txt
Title: GETINFO Option Expansion
Author: Damian Johnson
Created: 02-June-2010
Status: Draft

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.