forked from torproject/torspec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
control-spec.txt
4413 lines (3341 loc) · 178 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)
Table of Contents
0. Scope
1. Protocol outline
1.1. Forward-compatibility
2. Message format
2.1. Description format
2.1.1. Notes on an escaping bug
2.2. Commands from controller to Tor
2.3. Replies from Tor to the controller
2.4. General-use tokens
3. Commands
3.1. SETCONF
3.2. RESETCONF
3.3. GETCONF
3.4. SETEVENTS
3.5. AUTHENTICATE
3.6. SAVECONF
3.7. SIGNAL
3.8. MAPADDRESS
3.9. GETINFO
3.10. EXTENDCIRCUIT
3.11. SETCIRCUITPURPOSE
3.12. SETROUTERPURPOSE
3.13. ATTACHSTREAM
3.14. POSTDESCRIPTOR
3.15. REDIRECTSTREAM
3.16. CLOSESTREAM
3.17. CLOSECIRCUIT
3.18. QUIT
3.19. USEFEATURE
3.20. RESOLVE
3.21. PROTOCOLINFO
3.22. LOADCONF
3.23. TAKEOWNERSHIP
3.24. AUTHCHALLENGE
3.25. DROPGUARDS
3.26. HSFETCH
3.27. ADD_ONION
3.28. DEL_ONION
3.29. HSPOST
3.30. ONION_CLIENT_AUTH_ADD
3.31. ONION_CLIENT_AUTH_REMOVE
3.32. ONION_CLIENT_AUTH_VIEW
3.33. DROPOWNERSHIP
3.34. DROPTIMEOUTS
4. Replies
4.1. Asynchronous events
4.1.1. Circuit status changed
4.1.2. Stream status changed
4.1.3. OR Connection status changed
4.1.4. Bandwidth used in the last second
4.1.5. Log messages
4.1.6. New descriptors available
4.1.7. New Address mapping
4.1.8. Descriptors uploaded to us in our role as authoritative dirserver
4.1.9. Our descriptor changed
4.1.10. Status events
4.1.11. Our set of guard nodes has changed
4.1.12. Network status has changed
4.1.13. Bandwidth used on an application stream
4.1.14. Per-country client stats
4.1.15. New consensus networkstatus has arrived
4.1.16. New circuit buildtime has been set
4.1.17. Signal received
4.1.18. Configuration changed
4.1.19. Circuit status changed slightly
4.1.20. Pluggable transport launched
4.1.21. Bandwidth used on an OR or DIR or EXIT connection
4.1.22. Bandwidth used by all streams attached to a circuit
4.1.23. Per-circuit cell stats
4.1.24. Token buckets refilled
4.1.25. HiddenService descriptors
4.1.26. HiddenService descriptors content
4.1.27. Network liveness has changed
4.1.28. Pluggable Transport Logs
4.1.29. Pluggable Transport Status
5. Implementation notes
5.1. Authentication
5.2. Don't let the buffer get too big
5.3. Backward compatibility with v0 control protocol
5.4. Tor config options for use by controllers
5.5. Phases from the Bootstrap status event
5.5.1. Overview of Bootstrap reporting.
5.5.2. Phases in Bootstrap Stage 1
5.5.3. Phases in Bootstrap Stage 2
5.5.4. Phases in Bootstrap Stage 3
5.6 Bootstrap phases reported by older versions of Tor
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 behavior
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 version 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 messages when there are unexpected values, and
that it 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.
(If some list of alternatives is given, and there isn't an explicit
statement that clients must tolerate unexpected values, clients still
must tolerate unexpected values. The only exception would be if there
were an explicit statement that no future values will ever be added.)
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:
QuotedString = DQUOTE *qcontent DQUOTE
There are explicitly no limits on line length. All 8-bit characters
are permitted unless explicitly disallowed. In QuotedStrings,
backslashes and quotes must be escaped; other characters need not be
escaped.
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.1.1. Notes on an escaping bug
CString = DQUOTE *qcontent DQUOTE
Note that although these nonterminals have the same grammar, they
are interpreted differently. In a QuotedString, a backslash
followed by any character represents that character. But
in a CString, the escapes "\n", "\t", "\r", and the octal escapes
"\0" ... "\377" represent newline, tab, carriage return, and the
256 possible octet values respectively.
The use of CString in this document reflects a bug in Tor;
they should have been QuotedString instead. In the future, they
may migrate to use QuotedString instead. If they do, the
QuotedString implementation will never place a backslash before a
"n", "t", "r", or digit, to ensure that old controllers don't get
confused.
For future-proofing, controller implementors MAY use the following
rules to be compatible with buggy Tor implementations and with
future ones that implement the spec as intended:
Read \n \t \r and \0 ... \377 as C escapes.
Treat a backslash followed by any other character as that character.
Currently, many of the QuotedString instances below that Tor
outputs are in fact CStrings. We intend to fix this in future
versions of Tor, and document which ones were broken. (See
bugtracker ticket #14555 for a bit more information.)
Note that this bug exists only in strings generated by Tor for the
Tor controller; Tor should parse input QuotedStrings from the
controller correctly.
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 CmdData
EndReplyLine = StatusCode SP ReplyLine
ReplyLine = [ReplyText] CRLF
ReplyText = XXXX
StatusCode = 3DIGIT
Unless specified otherwise, multiple lines in a single reply from
Tor to the controller are guaranteed to share the same status
code. 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 ]
; For tors older than 0.3.1.3-alpha, LongName may have included an equal
; sign ("=") in lieu of a tilde ("~"). The presence of an equal sign
; denoted that the OR possessed the "Named" flag:
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
ConnID = 1*16 IDChar
QueueID = 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
; ISOTime, ISOTime2, and ISOTime2Frac are time formats as specified in
; ISO8601.
; example ISOTime: "2012-01-11 12:15:33"
; example ISOTime2: "2012-01-11T12:15:33"
; example ISOTime2Frac: "2012-01-11T12:15:33.51"
IsoDatePart = 4*DIGIT "-" 2*DIGIT "-" 2*DIGIT
IsoTimePart = 2*DIGIT ":" 2*DIGIT ":" 2*DIGIT
ISOTime = IsoDatePart " " IsoTimePart
ISOTime2 = IsoDatePart "T" IsoTimePart
ISOTime2Frac = IsoTime2 [ "." 1*DIGIT ]
; Numbers
LeadingDigit = "1" - "9"
UInt = LeadingDigit *Digit
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 OK" 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.
Some configuration options (e.g. "Bridge") take multiple values. Also,
some configuration keys (e.g. for hidden services and for entry
guard lists) form a context-sensitive group where order matters (see
GETCONF below). In these cases, setting _any_ of the options in a
SETCONF command is taken to reset all of the others. For example,
if two ORListenAddress values are configured, and a SETCONF command
arrives containing a single ORListenAddress 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 zero or more configuration variable(s).
The syntax is:
"GETCONF" *(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. (Right now, Tor supports no such misinterpretable values for
configuration options.)
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.
If no keywords were provided, Tor responds with "250 OK" message.
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 = 1*(ALPHA / "_") (see section 4.1.x for event types)
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
This command is used to authenticate to the server. The provided string is
one of the following:
* (For the HASHEDPASSWORD authentication method; see 3.21)
The original password represented as a QuotedString.
* (For the COOKIE is authentication method; see 3.21)
The contents of the cookie file, formatted in hexadecimal
* (For the SAFECOOKIE authentication method; see 3.21)
The HMAC based on the AUTHCHALLENGE message, in hexadecimal.
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, AUTHCHALLENGE, 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 or
AUTHCHALLENGE 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" [SP "FORCE"] 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.
If the %include option is used on torrc, SAVECONF will not write the
configuration to disk. If the flag string "FORCE" is provided, the
configuration will be overwritten even if %include is used. Using %include
on defaults-torrc does not affect SAVECONF. (Introduced in 0.3.1.1-alpha.)
See also the "getinfo config-text" command, if the controller wants
to write the torrc file itself.
See also the "getinfo config-can-saveconf" command, to tell if the FORCE
flag will be required. (Also introduced in 0.3.1.1-alpha.)
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" / "HEARTBEAT" / "ACTIVE" / "DORMANT"
The meaning of the signals are:
RELOAD -- Reload: reload config items.
SHUTDOWN -- Controlled shutdown: if server is an OP, exit immediately.
If it's an OR, close listeners and exit after
ShutdownWaitLength seconds.
DUMP -- Dump stats: log information about open connections and
circuits.
DEBUG -- Debug: switch all open logs to loglevel debug.
HALT -- Immediate shutdown: clean up and exit now.
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.)
HEARTBEAT -- Make Tor dump an unscheduled Heartbeat message to log.
DORMANT -- Tell Tor to become "dormant". A dormant Tor will
try to avoid CPU and network usage until it receives
user-initiated network request. (Don't use this
on relays or hidden services yet!)
ACTIVE -- Tell Tor to stop being "dormant", as if it had received
a user-initiated network request.
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.
Note that not all of these signals have POSIX signal equivalents. The
ones that do are as below. You may also use these POSIX names for the
signal that have them.
RELOAD: HUP
SHUTDOWN: INT
HALT: TERM
DUMP: USR1
DEBUG: USR2
[SIGNAL DORMANT and SIGNAL ACTIVE were added in 0.4.0.1-alpha.]
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 1.2.3.4=torproject.org
S: 250 1.2.3.4=torproject.org
C: GETINFO address-mappings/control
S: 250-address-mappings/control=1.2.3.4 torproject.org NEVER
S: 250 OK
C: MAPADDRESS 1.2.3.4=1.2.3.4
S: 250 1.2.3.4=1.2.3.4
C: GETINFO address-mappings/control
S: 250-address-mappings/control=
S: 250 OK
{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.
MapAddress replies MAY contain mixed status codes.
Example:
C: MAPADDRESS xxx=@@@ 0.0.0.0=bogus1.google.com
S: 512-syntax error: invalid address '@@@'
S: 250 127.199.80.246=bogus1.google.com
3.9. GETINFO
Sent from the client to the server. The syntax is as for GETCONF:
"GETINFO" 1*(SP keyword) CRLF
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
.
The server sends a 551 or 552 error on failure.
Recognized keys and their values include:
"version" -- The version of the server's software, which MAY include the
name of the software, such as "Tor 0.0.9.4". The name of the software,
if absent, is assumed to be "Tor".
"config-file" -- The location of Tor's configuration file ("torrc").
"config-defaults-file" -- The location of Tor's configuration
defaults file ("torrc.defaults"). This file gets parsed before
torrc, and is typically used to replace Tor's default
configuration values. [First implemented in 0.2.3.9-alpha.]
"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/default" -- The default exit policy lines that Tor will
*append* to the ExitPolicy config option.
"exit-policy/reject-private/default" -- The default exit policy lines
that Tor will *prepend* to the ExitPolicy config option when
ExitPolicyRejectPrivate is 1.
"exit-policy/reject-private/relay" -- The relay-specific exit policy
lines that Tor will *prepend* to the ExitPolicy config option based
on the current values of ExitPolicyRejectPrivate and
ExitPolicyRejectLocalInterfaces. These lines are based on the public
addresses configured in the torrc and present on the relay's
interfaces. Will send 552 error if the server is not running as
onion router. Will send 551 on internal error which may be transient.
"exit-policy/ipv4"
"exit-policy/ipv6"
"exit-policy/full" -- This OR's exit policy, in IPv4-only, IPv6-only, or
all-entries flavors. Handles errors in the same way as "exit-policy/
reject-private/relay" does.
"desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest
server descriptor for a given OR. (Note that modern Tor clients
do not download server descriptors by default, but download
microdescriptors instead. If microdescriptors are enabled, you'll
need to use "md" instead.)
"md/all" -- all known microdescriptors for the entire Tor network.
Each microdescriptor is terminated by a newline.
[First implemented in 0.3.5.1-alpha]
"md/id/<OR identity>" or "md/name/<OR nickname>" -- the latest
microdescriptor for a given OR. Empty if we have no microdescriptor for
that OR (because we haven't downloaded one, or it isn't in the
consensus). [First implemented in 0.2.3.8-alpha.]
"desc/download-enabled" -- "1" if we try to download router descriptors;
"0" otherwise. [First implemented in 0.3.2.1-alpha]
"md/download-enabled" -- "1" if we try to download microdescriptors;
"0" otherwise. [First implemented in 0.3.2.1-alpha]
"dormant" -- A nonnegative integer: zero if Tor is currently active and
building circuits, and nonzero if Tor has gone idle due to lack of use
or some similar reason. [First implemented in 0.2.3.16-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 (v3 directory style) for a given OR. Router status
info is as given in dir-spec.txt, and reflects the latest
consensus opinion 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.]
[In 0.2.0.9-alpha this switched from v2 directory style to v3]
"ns/all" -- Router status info (v3 directory style) for all ORs we
that the consensus has an opinion about, joined by newlines.
[First implemented in 0.1.2.3-alpha.]
[In 0.2.0.9-alpha this switched from v2 directory style to v3]
"ns/purpose/<purpose>" -- Router status info (v3 directory style)
for all ORs of this purpose. Mostly designed for /ns/purpose/bridge
queries.
[First implemented in 0.2.0.13-alpha.]
[In 0.2.0.9-alpha this switched from v2 directory style to v3]
[In versions before 0.4.1.1-alpha we set the Running flag on
bridges when /ns/purpose/bridge is accessed]
[In 0.4.1.1-alpha we set the Running flag on bridges when the
bridge networkstatus file is written to disk]
"desc/all-recent" -- the latest server descriptor for every router that
Tor knows about. (See md note about "desc/id" and "desc/name" above.)
"network-status" -- [Deprecated in 0.3.1.1-alpha, removed
in 0.4.5.1-alpha.]
"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 UTC 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)
"address/v4"
"address/v6"
the best guess at our respective external IPv4 or IPv6 address.
If we have no guess, return a 551 error. (Added in 0.4.5.1-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 CircuitID 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. Between 0.1.2.x-final and 0.2.6.3-alpha,
'down' was never generated.]
[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).
"uptime" -- Uptime of the Tor daemon (in seconds). Added in
0.3.5.1-alpha.
"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 UTC.
"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" /
"Dependent" / "Virtual" / "String" / "LineList"
Documentation = Text
Note: The incorrect spelling "Dependant" was used from the time this key
was introduced in Tor 0.1.1.4-alpha until it was corrected in Tor
0.3.0.2-alpha. It is recommended that clients accept both spellings.
"config/defaults"
A series of lines listing default values for each configuration
option. Options which don't have a valid default don't show up
in the list. Introduced in Tor 0.2.4.1-alpha.
OptionName SP OptionValue CRLF
OptionName = Keyword
OptionValue = 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 "/*"
The OptionPrefix form indicates a number of options beginning with the
prefix. So if "config/*" is listed, other options beginning with
"config/" will work, but "config/*" itself is not an option.
"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 features supported by this version
of Tor's USEFEATURE.
"signal/names"
A space-separated list of all the values supported by the SIGNAL
command.
"ip-to-country/ipv4-available"
"ip-to-country/ipv6-available"
"1" if the relevant geoip or geoip6 database is present; "0" otherwise.
This field was added in Tor 0.3.2.1-alpha.
"ip-to-country/*"
Maps IP addresses to 2-letter country codes. For example,
"GETINFO ip-to-country/18.0.0.1" should give "US".
"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-vote/current/consensus-microdesc" [added in Tor 0.4.3.1-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.
Note that, as of Tor 0.2.3.3-alpha, Tor clients don't download server
descriptors anymore, but microdescriptors. So, a "551 Servers
unavailable" reply to all "GETINFO dir/server/*" requests is actually
correct. If you have an old program which absolutely requires server
descriptors to work, try setting UseMicrodescriptors 0 or
FetchUselessDescriptors 1 in your client's torrc.
"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.
1 if there is no DirPort, and therefore no need for a reachability
check.
"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.
"status/fresh-relay-descs"
Provides fresh server and extra-info descriptors for our relay. Note
this is *not* the latest descriptors we've published, but rather what we
would generate if we needed to make a new descriptor right now.