123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138 |
- Filename: 172-circ-getinfo-option.txt
- Title: GETINFO controller option for circuit information
- Author: Damian Johnson
- Created: 03-June-2010
- Status: Accepted
- 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 flags indicating attributes in the circuit:
- (E)ntry : has a connection that doesn't belong to a known Tor server,
- indicating that this is either the first hop or bridged
- E(X)it : has been used for at least one exit stream
- (R)elay : has been extended
- Rende(Z)vous : is being used for a rendezvous point
- (I)ntroduction : is being used for a hidden service introduction
- (N)one of the above: none of the above have happened yet.
- 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.
|