-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcontrol-spec.txt
2158 lines (1654 loc) · 88.6 KB
/
control-spec.txt
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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
TC: A Tor control protocol (Version 1)
0. Scope
This document describes an implementation-specific protocol that is used
for other programs (such as frontend user-interfaces) to communicate with a
locally running Tor process. It is not part of the Tor onion routing
protocol.
This protocol replaces version 0 of TC, which is now deprecated. For
reference, TC is described in "control-spec-v0.txt". Implementors are
recommended to avoid using TC directly, but instead to use a library that
can easily be updated to use the newer protocol. (Version 0 is used by Tor
versions 0.1.0.x; the protocol in this document only works with Tor
versions in the 0.1.1.x series and later.)
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
1. Protocol outline
TC is a bidirectional message-based protocol. It assumes an underlying
stream for communication between a controlling process (the "client"
or "controller") and a Tor process (or "server"). The stream may be
implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on,
but it must provide reliable in-order delivery. For security, the
stream should not be accessible by untrusted parties.
In TC, the client and server send typed messages to each other over the
underlying stream. The client sends "commands" and the server sends
"replies".
By default, all messages from the server are in response to messages from
the client. Some client requests, however, will cause the server to send
messages to the client indefinitely far into the future. Such
"asynchronous" replies are marked as such.
Servers respond to messages in the order messages are received.
1.1. Forward-compatibility
This is an evolving protocol; new client and server behavior will be
allowed in future versions. To allow new backward-compatible client
on behalf of the client, we may add new commands and allow existing
commands to take new arguments in future versions. To allow new
backward-compatible server behavior, we note various places below
where servers speaking a future versions of this protocol may insert
new data, and note that clients should/must "tolerate" unexpected
elements in these places. There are two ways that we do this:
* Adding a new field to a message:
For example, we might say "This message has three space-separated
fields; clients MUST tolerate more fields." This means that a
client MUST NOT crash or otherwise fail to parse the message or
other subsequent messages when there are more than three fields, and
that it SHOULD function at least as well when more fields are
provided as it does when it only gets the fields it accepts. The
most obvious way to do this is by ignoring additional fields; the
next-most-obvious way is to report additional fields verbatim to the
user, perhaps as part of an expert UI.
* Adding a new possible value to a list of alternatives:
For example, we might say "This field will be OPEN, CLOSED, or
CONNECTED. Clients MUST tolerate unexpected values." This means
that a client MUST NOT crash or otherwise fail to parse the message
or other subsequent when there are unexpected values, and that the
client SHOULD try to handle the rest of the message as well as it
can. The most obvious way to do this is by pretending that each
list of alternatives has an additional "unrecognized value" element,
and mapping any unrecognized values to that element; the
next-most-obvious way is to create a separate "unrecognized value"
element for each unrecognized value.
Clients SHOULD NOT "tolerate" unrecognized alternatives by
pretending that the message containing them is absent. For example,
a stream closed for an unrecognized reason is nevertheless closed,
and should be reported as such.
2. Message format
2.1. Description format
The message formats listed below use ABNF as described in RFC 2234.
The protocol itself is loosely based on SMTP (see RFC 2821).
We use the following nonterminals from RFC 2822: atom, qcontent
We define the following general-use nonterminals:
String = DQUOTE *qcontent DQUOTE
There are explicitly no limits on line length. All 8-bit characters are
permitted unless explicitly disallowed.
Wherever CRLF is specified to be accepted from the controller, Tor MAY also
accept LF. Tor, however, MUST NOT generate LF instead of CRLF.
Controllers SHOULD always send CRLF.
2.2. Commands from controller to Tor
Command = Keyword OptArguments CRLF / "+" Keyword OptArguments CRLF CmdData
Keyword = 1*ALPHA
OptArguments = [ SP *(SP / VCHAR) ]
A command is either a single line containing a Keyword and arguments, or a
multiline command whose initial keyword begins with +, and whose data
section ends with a single "." on a line of its own. (We use a special
character to distinguish multiline commands so that Tor can correctly parse
multi-line commands that it does not recognize.) Specific commands and
their arguments are described below in section 3.
2.3. Replies from Tor to the controller
Reply = SyncReply / AsyncReply
SyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
AsyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
MidReplyLine = StatusCode "-" ReplyLine
DataReplyLine = StatusCode "+" ReplyLine Data
EndReplyLine = StatusCode SP ReplyLine
ReplyLine = [ReplyText] CRLF
ReplyText = XXXX
StatusCode = 3DIGIT
Specific replies are mentioned below in section 3, and described more fully
in section 4.
[Compatibility note: versions of Tor before 0.2.0.3-alpha sometimes
generate AsyncReplies of the form "*(MidReplyLine / DataReplyLine)".
This is incorrect, but controllers that need to work with these
versions of Tor should be prepared to get multi-line AsyncReplies with
the final line (usually "650 OK") omitted.]
2.4. General-use tokens
; CRLF means, "the ASCII Carriage Return character (decimal value 13)
; followed by the ASCII Linefeed character (decimal value 10)."
CRLF = CR LF
; How a controller tells Tor about a particular OR. There are four
; possible formats:
; $Fingerprint -- The router whose identity key hashes to the fingerprint.
; This is the preferred way to refer to an OR.
; $Fingerprint~Nickname -- The router whose identity key hashes to the
; given fingerprint, but only if the router has the given nickname.
; $Fingerprint=Nickname -- The router whose identity key hashes to the
; given fingerprint, but only if the router is Named and has the given
; nickname.
; Nickname -- The Named router with the given nickname, or, if no such
; router exists, any router whose nickname matches the one given.
; This is not a safe way to refer to routers, since Named status
; could under some circumstances change over time.
;
; The tokens that implement the above follow:
ServerSpec = LongName / Nickname
LongName = Fingerprint [ ( "=" / "~" ) Nickname ]
Fingerprint = "$" 40*HEXDIG
NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
Nickname = 1*19 NicknameChar
; What follows is an outdated way to refer to ORs.
; Feature VERBOSE_NAMES replaces ServerID with LongName in events and
; GETINFO results. VERBOSE_NAMES can be enabled starting in Tor version
; 0.1.2.2-alpha and it is always-on in 0.2.2.1-alpha and later.
ServerID = Nickname / Fingerprint
; Unique identifiers for streams or circuits. Currently, Tor only
; uses digits, but this may change
StreamID = 1*16 IDChar
CircuitID = 1*16 IDChar
IDChar = ALPHA / DIGIT
Address = ip4-address / ip6-address / hostname (XXXX Define these)
; A "CmdData" section is a sequence of octets concluded by the terminating
; sequence CRLF "." CRLF. The terminating sequence may not appear in the
; body of the data. Leading periods on lines in the data are escaped with
; an additional leading period as in RFC 2821 section 4.5.2.
CmdData = *DataLine "." CRLF
DataLine = CRLF / "." 1*LineItem CRLF / NonDotItem *LineItem CRLF
LineItem = NonCR / 1*CR NonCRLF
NonDotItem = NonDotCR / 1*CR NonCRLF
3. Commands
All commands are case-insensitive, but most keywords are case-sensitive.
3.1. SETCONF
Change the value of one or more configuration variables. The syntax is:
"SETCONF" 1*(SP keyword ["=" value]) CRLF
value = String / QuotedString
Tor behaves as though it had just read each of the key-value pairs
from its configuration file. Keywords with no corresponding values have
their configuration values reset to 0 or NULL (use RESETCONF if you want
to set it back to its default). SETCONF is all-or-nothing: if there
is an error in any of the configuration settings, Tor sets none of them.
Tor responds with a "250 configuration values set" reply on success.
If some of the listed keywords can't be found, Tor replies with a
"552 Unrecognized option" message. Otherwise, Tor responds with a
"513 syntax error in configuration values" reply on syntax error, or a
"553 impossible configuration setting" reply on a semantic error.
When a configuration option takes multiple values, or when multiple
configuration keys form a context-sensitive group (see GETCONF below), then
setting _any_ of the options in a SETCONF command is taken to reset all of
the others. For example, if two ORBindAddress values are configured, and a
SETCONF command arrives containing a single ORBindAddress value, the new
command's value replaces the two old values.
Sometimes it is not possible to change configuration options solely by
issuing a series of SETCONF commands, because the value of one of the
configuration options depends on the value of another which has not yet
been set. Such situations can be overcome by setting multiple configuration
options with a single SETCONF command (e.g. SETCONF ORPort=443
ORListenAddress=9001).
3.2. RESETCONF
Remove all settings for a given configuration option entirely, assign
its default value (if any), and then assign the String provided.
Typically the String is left empty, to simply set an option back to
its default. The syntax is:
"RESETCONF" 1*(SP keyword ["=" String]) CRLF
Otherwise it behaves like SETCONF above.
3.3. GETCONF
Request the value of a configuration variable. The syntax is:
"GETCONF" 1*(SP keyword) CRLF
If all of the listed keywords exist in the Tor configuration, Tor replies
with a series of reply lines of the form:
250 keyword=value
If any option is set to a 'default' value semantically different from an
empty string, Tor may reply with a reply line of the form:
250 keyword
Value may be a raw value or a quoted string. Tor will try to use
unquoted values except when the value could be misinterpreted through
not being quoted.
If some of the listed keywords can't be found, Tor replies with a
"552 unknown configuration keyword" message.
If an option appears multiple times in the configuration, all of its
key-value pairs are returned in order.
Some options are context-sensitive, and depend on other options with
different keywords. These cannot be fetched directly. Currently there
is only one such option: clients should use the "HiddenServiceOptions"
virtual keyword to get all HiddenServiceDir, HiddenServicePort,
HiddenServiceVersion, and HiddenserviceAuthorizeClient option settings.
3.4. SETEVENTS
Request the server to inform the client about interesting events. The
syntax is:
"SETEVENTS" [SP "EXTENDED"] *(SP EventCode) CRLF
EventCode = "CIRC" / "STREAM" / "ORCONN" / "BW" / "DEBUG" /
"INFO" / "NOTICE" / "WARN" / "ERR" / "NEWDESC" / "ADDRMAP" /
"AUTHDIR_NEWDESCS" / "DESCCHANGED" / "STATUS_GENERAL" /
"STATUS_CLIENT" / "STATUS_SERVER" / "GUARD" / "NS" / "STREAM_BW" /
"CLIENTS_SEEN" / "NEWCONSENSUS" / "BUILDTIMEOUT_SET" / "SIGNAL"
Any events *not* listed in the SETEVENTS line are turned off; thus, sending
SETEVENTS with an empty body turns off all event reporting.
The server responds with a "250 OK" reply on success, and a "552
Unrecognized event" reply if one of the event codes isn't recognized. (On
error, the list of active event codes isn't changed.)
If the flag string "EXTENDED" is provided, Tor may provide extra
information with events for this connection; see 4.1 for more information.
NOTE: All events on a given connection will be provided in extended format,
or none.
NOTE: "EXTENDED" was first supported in Tor 0.1.1.9-alpha; it is
always-on in Tor 0.2.2.1-alpha and later.
Each event is described in more detail in Section 4.1.
3.5. AUTHENTICATE
Sent from the client to the server. The syntax is:
"AUTHENTICATE" [ SP 1*HEXDIG / QuotedString ] CRLF
The server responds with "250 OK" on success or "515 Bad authentication" if
the authentication cookie is incorrect. Tor closes the connection on an
authentication failure.
The authentication token can be specified as either a quoted ASCII string,
or as an unquoted hexadecimal encoding of that same string (to avoid escaping
issues).
For information on how the implementation securely stores authentication
information on disk, see section 5.1.
Before the client has authenticated, no command other than PROTOCOLINFO,
AUTHENTICATE, or QUIT is valid. If the controller sends any other command,
or sends a malformed command, or sends an unsuccessful AUTHENTICATE
command, or sends PROTOCOLINFO more than once, Tor sends an error reply and
closes the connection.
To prevent some cross-protocol attacks, the AUTHENTICATE command is still
required even if all authentication methods in Tor are disabled. In this
case, the controller should just send "AUTHENTICATE" CRLF.
(Versions of Tor before 0.1.2.16 and 0.2.0.4-alpha did not close the
connection after an authentication failure.)
3.6. SAVECONF
Sent from the client to the server. The syntax is:
"SAVECONF" CRLF
Instructs the server to write out its config options into its torrc. Server
returns "250 OK" if successful, or "551 Unable to write configuration
to disk" if it can't write the file or some other error occurs.
See also the "getinfo config-text" command, if the controller wants
to write the torrc file itself.
3.7. SIGNAL
Sent from the client to the server. The syntax is:
"SIGNAL" SP Signal CRLF
Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" /
"HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" /
"CLEARDNSCACHE"
The meaning of the signals are:
RELOAD -- Reload: reload config items. (like HUP)
SHUTDOWN -- Controlled shutdown: if server is an OP, exit immediately.
If it's an OR, close listeners and exit after
ShutdownWaitLength seconds. (like INT)
DUMP -- Dump stats: log information about open connections and
circuits. (like USR1)
DEBUG -- Debug: switch all open logs to loglevel debug. (like USR2)
HALT -- Immediate shutdown: clean up and exit now. (like TERM)
CLEARDNSCACHE -- Forget the client-side cached IPs for all hostnames.
NEWNYM -- Switch to clean circuits, so new application requests
don't share any circuits with old ones. Also clears
the client-side DNS cache. (Tor MAY rate-limit its
response to this signal.)
The server responds with "250 OK" if the signal is recognized (or simply
closes the socket if it was asked to close immediately), or "552
Unrecognized signal" if the signal is unrecognized.
3.8. MAPADDRESS
Sent from the client to the server. The syntax is:
"MAPADDRESS" 1*(Address "=" Address SP) CRLF
The first address in each pair is an "original" address; the second is a
"replacement" address. The client sends this message to the server in
order to tell it that future SOCKS requests for connections to the original
address should be replaced with connections to the specified replacement
address. If the addresses are well-formed, and the server is able to
fulfill the request, the server replies with a 250 message:
250-OldAddress1=NewAddress1
250 OldAddress2=NewAddress2
containing the source and destination addresses. If request is
malformed, the server replies with "512 syntax error in command
argument". If the server can't fulfill the request, it replies with
"451 resource exhausted".
The client may decline to provide a body for the original address, and
instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
"." for hostname), signifying that the server should choose the original
address itself, and return that address in the reply. The server
should ensure that it returns an element of address space that is unlikely
to be in actual use. If there is already an address mapped to the
destination address, the server may reuse that mapping.
If the original address is already mapped to a different address, the old
mapping is removed. If the original address and the destination address
are the same, the server removes any mapping in place for the original
address.
Example:
C: MAPADDRESS 0.0.0.0=torproject.org 1.2.3.4=tor.freehaven.net
S: 250-127.192.10.10=torproject.org
S: 250 1.2.3.4=tor.freehaven.net
{Note: This feature is designed to be used to help Tor-ify applications
that need to use SOCKS4 or hostname-less SOCKS5. There are three
approaches to doing this:
1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
feature) to resolve the hostname remotely. This doesn't work
with special addresses like x.onion or x.y.exit.
3. Use MAPADDRESS to map an IP address to the desired hostname, and then
arrange to fool the application into thinking that the hostname
has resolved to that IP.
This functionality is designed to help implement the 3rd approach.}
Mappings set by the controller last until the Tor process exits:
they never expire. If the controller wants the mapping to last only
a certain time, then it must explicitly un-map the address when that
time has elapsed.
3.9. GETINFO
Sent from the client to the server. The syntax is as for GETCONF:
"GETINFO" 1*(SP keyword) CRLF
one or more NL-terminated strings. The server replies with an INFOVALUE
message, or a 551 or 552 error.
Unlike GETCONF, this message is used for data that are not stored in the Tor
configuration file, and that may be longer than a single line. On success,
one ReplyLine is sent for each requested value, followed by a final 250 OK
ReplyLine. If a value fits on a single line, the format is:
250-keyword=value
If a value must be split over multiple lines, the format is:
250+keyword=
value
.
Recognized keys and their values include:
"version" -- The version of the server's software, including the name
of the software. (example: "Tor 0.0.9.4")
"config-file" -- The location of Tor's configuration file ("torrc").
"config-text" -- The contents that Tor would write if you send it
a SAVECONF command, so the controller can write the file to
disk itself. [First implemented in 0.2.2.7-alpha.]
["exit-policy/prepend" -- The default exit policy lines that Tor will
*prepend* to the ExitPolicy config option.
-- Never implemented. Useful?]
"exit-policy/default" -- The default exit policy lines that Tor will
*append* to the ExitPolicy config option.
"desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest
server descriptor for a given OR.
"md/id/<OR identity>" or "md/name/<OR nickname>" -- the latest
microdescriptor for a given OR. [First implemented in
0.2.3.8-alpha.]
"desc-annotations/id/<OR identity>" -- outputs the annotations string
(source, timestamp of arrival, purpose, etc) for the corresponding
descriptor. [First implemented in 0.2.0.13-alpha.]
"extra-info/digest/<digest>" -- the extrainfo document whose digest (in
hex) is <digest>. Only available if we're downloading extra-info
documents.
"ns/id/<OR identity>" or "ns/name/<OR nickname>" -- the latest router
status info (v2 directory style) for a given OR. Router status
info is as given in
dir-spec.txt, and reflects the current beliefs of this Tor about the
router in question. Like directory clients, controllers MUST
tolerate unrecognized flags and lines. The published date and
descriptor digest are those believed to be best by this Tor,
not necessarily those for a descriptor that Tor currently has.
[First implemented in 0.1.2.3-alpha.]
"ns/all" -- Router status info (v2 directory style) for all ORs we
have an opinion about, joined by newlines. [First implemented
in 0.1.2.3-alpha.]
"ns/purpose/<purpose>" -- Router status info (v2 directory style)
for all ORs of this purpose. Mostly designed for /ns/purpose/bridge
queries. [First implemented in 0.2.0.13-alpha.]
"desc/all-recent" -- the latest server descriptor for every router that
Tor knows about.
"network-status" -- a space-separated list (v1 directory style)
of all known OR identities. This is in the same format as the
router-status line in v1 directories; see dir-spec-v1.txt section
3 for details. (If VERBOSE_NAMES is enabled, the output will
not conform to dir-spec-v1.txt; instead, the result will be a
space-separated list of LongName, each preceded by a "!" if it is
believed to be not running.) This option is deprecated; use
"ns/all" instead.
"address-mappings/all"
"address-mappings/config"
"address-mappings/cache"
"address-mappings/control" -- a \r\n-separated list of address
mappings, each in the form of "from-address to-address expiry".
The 'config' key returns those address mappings set in the
configuration; the 'cache' key returns the mappings in the
client-side DNS cache; the 'control' key returns the mappings set
via the control interface; the 'all' target returns the mappings
set through any mechanism.
Expiry is formatted as with ADDRMAP events, except that "expiry" is
always a time in GMT or the string "NEVER"; see section 4.1.7.
First introduced in 0.2.0.3-alpha.
"addr-mappings/*" -- as for address-mappings/*, but without the
expiry portion of the value. Use of this value is deprecated
since 0.2.0.3-alpha; use address-mappings instead.
"address" -- the best guess at our external IP address. If we
have no guess, return a 551 error. (Added in 0.1.2.2-alpha)
"fingerprint" -- the contents of the fingerprint file that Tor
writes as a relay, or a 551 if we're not a relay currently.
(Added in 0.1.2.3-alpha)
"circuit-status"
A series of lines as for a circuit status event. Each line is of
the form described in section 4.1.1, omitting the initial
"650 CIRC ". Note that clients must be ready to accept additional
arguments as described in section 4.1.
"stream-status"
A series of lines as for a stream status event. Each is of the form:
StreamID SP StreamStatus SP CircID SP Target CRLF
"orconn-status"
A series of lines as for an OR connection status event. In Tor
0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
0.2.2.1-alpha and later by default, each line is of the form:
LongName SP ORStatus CRLF
In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line
is of the form:
ServerID SP ORStatus CRLF
"entry-guards"
A series of lines listing the currently chosen entry guards, if any.
In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
0.2.2.1-alpha and later by default, each line is of the form:
LongName SP Status [SP ISOTime] CRLF
In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line
is of the form:
ServerID2 SP Status [SP ISOTime] CRLF
ServerID2 = Nickname / 40*HEXDIG
The definition of Status is the same for both:
Status = "up" / "never-connected" / "down" /
"unusable" / "unlisted"
[From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called
"helper-nodes". Tor still supports calling "helper-nodes", but it
is deprecated and should not be used.]
[Older versions of Tor (before 0.1.2.x-final) generated 'down' instead
of unlisted/unusable. Current Tors never generate 'down'.]
[XXXX ServerID2 differs from ServerID in not prefixing fingerprints
with a $. This is an implementation error. It would be nice to add
the $ back in if we can do so without breaking compatibility.]
"traffic/read" -- Total bytes read (downloaded).
"traffic/written" -- Total bytes written (uploaded).
"accounting/enabled"
"accounting/hibernating"
"accounting/bytes"
"accounting/bytes-left"
"accounting/interval-start"
"accounting/interval-wake"
"accounting/interval-end"
Information about accounting status. If accounting is enabled,
"enabled" is 1; otherwise it is 0. The "hibernating" field is "hard"
if we are accepting no data; "soft" if we're accepting no new
connections, and "awake" if we're not hibernating at all. The "bytes"
and "bytes-left" fields contain (read-bytes SP write-bytes), for the
start and the rest of the interval respectively. The 'interval-start'
and 'interval-end' fields are the borders of the current interval; the
'interval-wake' field is the time within the current interval (if any)
where we plan[ned] to start being active. The times are GMT.
"config/names"
A series of lines listing the available configuration options. Each is
of the form:
OptionName SP OptionType [ SP Documentation ] CRLF
OptionName = Keyword
OptionType = "Integer" / "TimeInterval" / "TimeMsecInterval" /
"DataSize" / "Float" / "Boolean" / "Time" / "CommaList" /
"Dependant" / "Virtual" / "String" / "LineList"
Documentation = Text
"info/names"
A series of lines listing the available GETINFO options. Each is of
one of these forms:
OptionName SP Documentation CRLF
OptionPrefix SP Documentation CRLF
OptionPrefix = OptionName "/*"
"events/names"
A space-separated list of all the events supported by this version of
Tor's SETEVENTS.
"features/names"
A space-separated list of all the events supported by this version of
Tor's USEFEATURE.
"ip-to-country/*"
Maps IP addresses to 2-letter country codes. For example,
"GETINFO ip-to-country/18.0.0.1" should give "US".
"next-circuit/IP:port"
XXX todo.
"process/pid" -- Process id belonging to the main tor process.
"process/uid" -- User id running the tor process, -1 if unknown (this is
unimplemented on Windows, returning -1).
"process/user" -- Username under which the tor process is running,
providing an empty string if none exists (this is unimplemented on
Windows, returning an empty string).
"process/descriptor-limit" -- Upper bound on the file descriptor limit, -1
if unknown.
"dir/status-vote/current/consensus" [added in Tor 0.2.1.6-alpha]
"dir/status/authority"
"dir/status/fp/<F>"
"dir/status/fp/<F1>+<F2>+<F3>"
"dir/status/all"
"dir/server/fp/<F>"
"dir/server/fp/<F1>+<F2>+<F3>"
"dir/server/d/<D>"
"dir/server/d/<D1>+<D2>+<D3>"
"dir/server/authority"
"dir/server/all"
A series of lines listing directory contents, provided according to the
specification for the URLs listed in Section 4.4 of dir-spec.txt. Note
that Tor MUST NOT provide private information, such as descriptors for
routers not marked as general-purpose. When asked for 'authority'
information for which this Tor is not authoritative, Tor replies with
an empty string.
"status/circuit-established"
"status/enough-dir-info"
"status/good-server-descriptor"
"status/accepted-server-descriptor"
"status/..."
These provide the current internal Tor values for various Tor
states. See Section 4.1.10 for explanations. (Only a few of the
status events are available as getinfo's currently. Let us know if
you want more exposed.)
"status/reachability-succeeded/or"
0 or 1, depending on whether we've found our ORPort reachable.
"status/reachability-succeeded/dir"
0 or 1, depending on whether we've found our DirPort reachable.
"status/reachability-succeeded"
"OR=" ("0"/"1") SP "DIR=" ("0"/"1")
Combines status/reachability-succeeded/*; controllers MUST ignore
unrecognized elements in this entry.
"status/bootstrap-phase"
Returns the most recent bootstrap phase status event
sent. Specifically, it returns a string starting with either
"NOTICE BOOTSTRAP ..." or "WARN BOOTSTRAP ...". Controllers should
use this getinfo when they connect or attach to Tor to learn its
current bootstrap state.
"status/version/recommended"
List of currently recommended versions.
"status/version/current"
Status of the current version. One of: new, old, unrecommended,
recommended, new in series, obsolete, unknown.
"status/clients-seen"
A summary of which countries we've seen clients from recently,
formatted the same as the CLIENTS_SEEN status event described in
Section 4.1.14. This GETINFO option is currently available only
for bridge relays.
"net/listeners/or"
"net/listeners/dir"
"net/listeners/socks"
"net/listeners/trans"
"net/listeners/natd"
"net/listeners/dns"
"net/listeners/control"
A space-separated list of the addresses at which Tor is listening for
connections of each specified type. [New in Tor 0.2.2.26-beta.]
Examples:
C: GETINFO version desc/name/moria1
S: 250+desc/name/moria=
S: [Descriptor for moria]
S: .
S: 250-version=Tor 0.1.1.0-alpha-cvs
S: 250 OK
3.10. EXTENDCIRCUIT
Sent from the client to the server. The format is:
"EXTENDCIRCUIT" SP CircuitID
[SP ServerSpec *("," ServerSpec)
SP "purpose=" Purpose] CRLF
This request takes one of two forms: either the CircuitID is zero, in
which case it is a request for the server to build a new circuit,
or the CircuitID is nonzero, in which case it is a request for the
server to extend an existing circuit with that ID according to the
specified path.
If the CircuitID is 0, the controller has the option of providing
a path for Tor to use to build the circuit. If it does not provide
a path, Tor will select one automatically from high capacity nodes
according to path-spec.txt.
If CircuitID is 0 and "purpose=" is specified, then the circuit's
purpose is set. Two choices are recognized: "general" and
"controller". If not specified, circuits are created as "general".
If the request is successful, the server sends a reply containing a
message body consisting of the CircuitID of the (maybe newly created)
circuit. The syntax is "250" SP "EXTENDED" SP CircuitID CRLF.
3.11. SETCIRCUITPURPOSE
Sent from the client to the server. The format is:
"SETCIRCUITPURPOSE" SP CircuitID SP Purpose CRLF
This changes the circuit's purpose. See EXTENDCIRCUIT above for details.
3.12. SETROUTERPURPOSE
Sent from the client to the server. The format is:
"SETROUTERPURPOSE" SP NicknameOrKey SP Purpose CRLF
This changes the descriptor's purpose. See +POSTDESCRIPTOR below
for details.
NOTE: This command was disabled and made obsolete as of Tor
0.2.0.8-alpha. It doesn't exist anymore, and is listed here only for
historical interest.
3.13. ATTACHSTREAM
Sent from the client to the server. The syntax is:
"ATTACHSTREAM" SP StreamID SP CircuitID [SP "HOP=" HopNum] CRLF
This message informs the server that the specified stream should be
associated with the specified circuit. Each stream may be associated with
at most one circuit, and multiple streams may share the same circuit.
Streams can only be attached to completed circuits (that is, circuits that
have sent a circuit status 'BUILT' event or are listed as built in a
GETINFO circuit-status request).
If the circuit ID is 0, responsibility for attaching the given stream is
returned to Tor.
If HOP=HopNum is specified, Tor will choose the HopNumth hop in the
circuit as the exit node, rather than the last node in the circuit.
Hops are 1-indexed; generally, it is not permitted to attach to hop 1.
Tor responds with "250 OK" if it can attach the stream, 552 if the circuit
or stream didn't exist, or 551 if the stream couldn't be attached for
another reason.
{Implementation note: Tor will close unattached streams by itself,
roughly two minutes after they are born. Let the developers know if
that turns out to be a problem.}
{Implementation note: By default, Tor automatically attaches streams to
circuits itself, unless the configuration variable
"__LeaveStreamsUnattached" is set to "1". Attempting to attach streams
via TC when "__LeaveStreamsUnattached" is false may cause a race between
Tor and the controller, as both attempt to attach streams to circuits.}
{Implementation note: You can try to attachstream to a stream that
has already sent a connect or resolve request but hasn't succeeded
yet, in which case Tor will detach the stream from its current circuit
before proceeding with the new attach request.}
3.14. POSTDESCRIPTOR
Sent from the client to the server. The syntax is:
"+POSTDESCRIPTOR" [SP "purpose=" Purpose] [SP "cache=" Cache]
CRLF Descriptor CRLF "." CRLF
This message informs the server about a new descriptor. If Purpose is
specified, it must be either "general", "controller", or "bridge",
else we return a 552 error. The default is "general".
If Cache is specified, it must be either "no" or "yes", else we
return a 552 error. If Cache is not specified, Tor will decide for
itself whether it wants to cache the descriptor, and controllers
must not rely on its choice.
The descriptor, when parsed, must contain a number of well-specified
fields, including fields for its nickname and identity.
If there is an error in parsing the descriptor, the server must send a
"554 Invalid descriptor" reply. If the descriptor is well-formed but
the server chooses not to add it, it must reply with a 251 message
whose body explains why the server was not added. If the descriptor
is added, Tor replies with "250 OK".
3.15. REDIRECTSTREAM
Sent from the client to the server. The syntax is:
"REDIRECTSTREAM" SP StreamID SP Address [SP Port] CRLF
Tells the server to change the exit address on the specified stream. If
Port is specified, changes the destination port as well. No remapping
is performed on the new provided address.
To be sure that the modified address will be used, this event must be sent
after a new stream event is received, and before attaching this stream to
a circuit.
Tor replies with "250 OK" on success.
3.16. CLOSESTREAM
Sent from the client to the server. The syntax is:
"CLOSESTREAM" SP StreamID SP Reason *(SP Flag) CRLF
Tells the server to close the specified stream. The reason should be one
of the Tor RELAY_END reasons given in tor-spec.txt, as a decimal. Flags is
not used currently; Tor servers SHOULD ignore unrecognized flags. Tor may
hold the stream open for a while to flush any data that is pending.
Tor replies with "250 OK" on success, or a 512 if there aren't enough
arguments, or a 552 if it doesn't recognize the StreamID or reason.
3.17. CLOSECIRCUIT
The syntax is:
"CLOSECIRCUIT" SP CircuitID *(SP Flag) CRLF
Flag = "IfUnused"
Tells the server to close the specified circuit. If "IfUnused" is
provided, do not close the circuit unless it is unused.
Other flags may be defined in the future; Tor SHOULD ignore unrecognized
flags.
Tor replies with "250 OK" on success, or a 512 if there aren't enough
arguments, or a 552 if it doesn't recognize the CircuitID.
3.18. QUIT
Tells the server to hang up on this controller connection. This command
can be used before authenticating.
3.19. USEFEATURE
Adding additional features to the control protocol sometimes will break
backwards compatibility. Initially such features are added into Tor and
disabled by default. USEFEATURE can enable these additional features.
The syntax is:
"USEFEATURE" *(SP FeatureName) CRLF
FeatureName = 1*(ALPHA / DIGIT / "_" / "-")
Feature names are case-insensitive.
Once enabled, a feature stays enabled for the duration of the connection
to the controller. A new connection to the controller must be opened to
disable an enabled feature.
Features are a forward-compatibility mechanism; each feature will eventually
become a standard part of the control protocol. Once a feature becomes part
of the protocol, it is always-on. Each feature documents the version it was
introduced as a feature and the version in which it became part of the
protocol.
Tor will ignore a request to use any feature that is always-on. Tor will give
a 552 error in response to an unrecognized feature.
EXTENDED_EVENTS
Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to
request the extended event syntax.
This feature was first introduced in 0.1.2.3-alpha. It is always-on
and part of the protocol in Tor 0.2.2.1-alpha and later.
VERBOSE_NAMES
Replaces ServerID with LongName in events and GETINFO results. LongName
provides a Fingerprint for all routers, an indication of Named status,
and a Nickname if one is known. LongName is strictly more informative
than ServerID, which only provides either a Fingerprint or a Nickname.
This feature was first introduced in 0.1.2.2-alpha. It is always-on and
part of the protocol in Tor 0.2.2.1-alpha and later.
3.20. RESOLVE
The syntax is
"RESOLVE" *Option *Address CRLF
Option = "mode=reverse"
Address = a hostname or IPv4 address
This command launches a remote hostname lookup request for every specified
request (or reverse lookup if "mode=reverse" is specified). Note that the
request is done in the background: to see the answers, your controller will
need to listen for ADDRMAP events; see 4.1.7 below.
[Added in Tor 0.2.0.3-alpha]
3.21. PROTOCOLINFO
The syntax is:
"PROTOCOLINFO" *(SP PIVERSION) CRLF
The server reply format is:
"250-PROTOCOLINFO" SP PIVERSION CRLF *InfoLine "250 OK" CRLF
InfoLine = AuthLine / VersionLine / OtherLine
AuthLine = "250-AUTH" SP "METHODS=" AuthMethod *("," AuthMethod)
*(SP "COOKIEFILE=" AuthCookieFile) CRLF
VersionLine = "250-VERSION" SP "Tor=" TorVersion OptArguments CRLF
AuthMethod =
"NULL" / ; No authentication is required
"HASHEDPASSWORD" / ; A controller must supply the original password
"COOKIE" / ; A controller must supply the contents of a cookie
AuthCookieFile = QuotedString
TorVersion = QuotedString
OtherLine = "250-" Keyword OptArguments CRLF
PIVERSION: 1*DIGIT
Tor MAY give its InfoLines in any order; controllers MUST ignore InfoLines
with keywords they do not recognize. Controllers MUST ignore extraneous
data on any InfoLine.
PIVERSION is there in case we drastically change the syntax one day. For
now it should always be "1". Controllers MAY provide a list of the
protocolinfo versions they support; Tor MAY select a version that the
controller does not support.
AuthMethod is used to specify one or more control authentication
methods that Tor currently accepts.
AuthCookieFile specifies the absolute path and filename of the
authentication cookie that Tor is expecting and is provided iff
the METHODS field contains the method "COOKIE". Controllers MUST handle
escape sequences inside this string.
The VERSION line contains the Tor version.
[Unlike other commands besides AUTHENTICATE, PROTOCOLINFO may be used (but
only once!) before AUTHENTICATE.]
[PROTOCOLINFO was not supported before Tor 0.2.0.5-alpha.]
3.22. LOADCONF
The syntax is:
"+LOADCONF" CRLF ConfigText CRLF "." CRLF
This command allows a controller to upload the text of a config file
to Tor over the control port. This config file is then loaded as if
it had been read from disk.
[LOADCONF was added in Tor 0.2.1.1-alpha.]
3.23. TAKEOWNERSHIP
The syntax is:
"TAKEOWNERSHIP" CRLF
This command instructs Tor to shut down (as if it had received
SIGINT or a "SIGNAL INT" controller command) when this control
connection is closed. This command affects each control connection
that sends it independently; if multiple control connections send
the TAKEOWNERSHIP command to a Tor instance, Tor will shut down when
any of those connections closes.
This command is intended to be used with the
__OwningControllerProcess configuration option. A controller that
starts a Tor process which the user cannot easily control or stop
should 'own' that Tor process:
* When starting Tor, the controller should specify its PID in an