1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
Filename: 218-usage-controller-events.txt
Title: Controller events to better understand connection/circuit usage
Author: Rob Jansen, Karsten Loesing
Created: 2013-02-06
Status: Open
Target: 0.2.5.x
1. Overview
This proposal defines three new controller events that shall help
understand connection and circuit usage. These events are designed
to be emitted in private Tor networks only. This proposal also
defines a tweak to an existing event for the same purpose.
2. Motivation
We need to better understand connection and circuit usage in order to
better simulate Tor networks. Existing controller events are a fine
start, but we need more detailed information about per-connection
bandwidth, processed cells by circuit, and token bucket refills. This
proposal defines controller events containing the desired information.
Most of these usage data are too sensitive to be captured in the
public network, unless aggregated sufficiently. That is why we're
focusing on private Tor networks first, that is, relays that have
TestingTorNetwork set. The new controller events described in this
proposal shall all be restricted to private Tor networks. In the next
step we might define aggregate statistics to be gathered by public
relays, but that will require a new proposal.
3. Design
The proposed new event types use Tor's asynchronous event mechanism
where a controller registers for events by type and processes events
received from the Tor process.
Tor controllers can register for any of the new event types, but
events will only be emitted if the Tor process is running in
TestingTorNetwork mode.
4. Security implications
There should be no security implications from the new event types,
because they are only emitted in private Tor networks.
5. Specification
5.1. ConnID Token
Addition for section 2.4 of the control-spec (General-use tokens).
; Connection ID which is locally unique among all connection types and which
; is only included in TestingTorNetwork mode.
ConnID = 1*16 IDChar
5.2. Adding an ID field to ORCONN events
The new syntax for ORCONN events is:
"650" SP "ORCONN" SP (LongName / Target) SP ORStatus
[ SP "ID=" ConnID ] [ SP "REASON=" Reason ]
[ SP "NCIRCS=" NumCircuits ] CRLF
The remaining specification of that event type stays unchanged.
5.3. Bandwidth used on an OR or DIR or EXIT connection
The syntax is:
"650" SP "CONN_BW" [ SP "ID=" ConnID ] [ SP "TYPE=" ConnType ]
[ SP "READ=" BytesRead ] [ SP "WRITTEN=" BytesWritten ]
CRLF
ConnType = "OR" / "DIR" / "EXIT"
BytesRead = 1*DIGIT
BytesWritten = 1*DIGIT
Controllers MUST tolerate unrecognized connection types.
BytesWritten and BytesRead are the number of bytes written and read
by Tor since the last CONN_BW event on this connection.
These events are generated about once per second per connection; no
events are generated for connections that have not read or written.
These events are only generated if TestingTorNetwork is set.
5.4. Per-circuit cell stats
The syntax is:
"650" SP "CELL_STATS"
[ SP "PCircID=" CircuitID ] [ SP "PConnID=" ConnID ]
[ SP "PAdded=" PAdded ] [ SP "PRemoved=" PRemoved ]
[ SP "PTime=" PTime ]
[ SP "NCircID=" CircuitID ] [ SP "NConnID=" ConnID ]
[ SP "NAdded=" NAdded ] [ SP "NRemoved=" NRemoved ]
[ SP "NTime=" NTime ] CRLF
PAdded, PRemoved, PTime, NAdded, NRemoved, NTime =
CellType ":" 1*DIGIT 0*( "," CellType ":" 1*DIGIT )
CellType = 1*( "a" - "z" / "0" - "9" / "_" )
PCircID and NCircID are the locally unique IDs of the app-ward
(PCircID) and exit-ward (NCircID) circuit.
PConnID and NConnID are the locally unique IDs of the app-ward
(PConnID) and exit-ward (NConnID) OR connection.
PAdded and NAdded are the total number of cells by cell type added to
the app-ward (PAdded) and exit-ward (NAdded) queues of this circuit.
PRemoved and NRemoved are the total number of cells by cell type
processed from the app-ward (PRemoved) and exit-ward (NRemoved)
queues of this circuit.
PTime and NTime are the total waiting times in milliseconds of all
processed cells by cell type in the app-ward (PTime) and exit-ward
(NTime) queues of this circuit.
These events are generated about once per second per circuit; no
events are generated for circuits that have not added or processed any
cell. These events are only generated if TestingTorNetwork is set.
5.5. Token buckets refilled
The syntax is:
"650" SP "TB_EMPTY" SP "BUCKET=" BucketName [ SP "ID=" ConnID ]
[ SP "READ=" ReadBucketEmpty ]
[ SP "WRITTEN=" WriteBucketEmpty ]
[ SP "LAST=" LastRefill ] CRLF
BucketName = "GLOBAL" / "RELAY" / "ORCONN"
ReadBucketEmpty = 1*DIGIT
WriteBucketEmpty = 1*DIGIT
LastRefill = 1*DIGIT
This event is generated when refilling a previously empty token
bucket. BucketNames "GLOBAL" and "RELAY" keywords are used for the
global or relay token buckets, BucketName "ORCONN" is used for the
token buckets of an OR connection. Controllers MUST tolerate unrecognized
bucket names.
ConnID is only included if the BucketName is "ORCONN".
If both global and relay buckets and/or the buckets of one or more OR
connections run out of tokens at the same time, multiple separate
events are generated.
ReadBucketEmpty (WriteBucketEmpty) is the time in millis that the read
(write) bucket was empty. LastRefill is the time in millis since the
last refill. ReadBucketEmpty or WriteBucketEmpty are capped at
LastRefill in order not to report empty times more than once.
These events are only generated if TestingTorNetwork is set.
6. Compatibility
There should not be any compatibility issues with other Tor versions.
7. Implementation
Most of the implementation should be straight-forward.
There's one exception: we pondered adding a unique circuit ID to
CELL_STATS events, but so far, only origin circuits have a unique ID.
We could move that field from origin_circuit_t to circuit_t and
update all references in the code. But this may have undesired side
effects which we're not yet aware of. We don't have a good answer
yet if we need this ID or not.
8. Performance and scalability notes
Most of the new code won't be executed in normal Tor mode. Wherever
we needed new fields in existing structs, we tried hard to keep them
as small as possible. Still, we should make sure that memory
requirements won't grow significantly on busy relays.
|
