1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036 |
- 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 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
- 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 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. (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.
- 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 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
- 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" -- 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 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)
- "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/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.
- "net/listeners/*"
- A quoted, space-separated list of the locations where Tor is listening
- for connections of the specified type. These can contain IPv4
- network address...
- "127.0.0.1:9050" "127.0.0.1:9051"
- ... or local unix sockets...
- "unix:/home/my_user/.tor/socket"
- ... or IPv6 network addresses:
- "[2001:0db8:7000:0000:0000:dead:beef:1234]:9050"
- [New in Tor 0.2.2.26-beta.]
- "net/listeners/or"
- Listeners for OR connections. Talks Tor protocol as described in
- tor-spec.txt.
- "net/listeners/dir"
- Listeners for Tor directory protocol, as decribed in dir-spec.txt.
- "net/listeners/socks"
- Listeners for onion proxy connections that talk SOCKS4/4a/5 protocol.
- "net/listeners/trans"
- Listeners for transparent connections redirected by firewall, such as
- pf or netfilter.
- "net/listeners/natd"
- Listeners for transparent connections redirected by natd.
- "net/listeners/dns"
- Listeners for a subset of DNS protocol that Tor network supports.
- "net/listeners/control"
- Listeners for Tor control protocol, described herein.
- "net/listeners/extor"
- Listeners corresponding to Extended ORPorts for integration with
- pluggable transports. See proposals 180 and 196.
- "net/listeners/httptunnel"
- Listeners for onion proxy connections that leverage HTTP CONNECT
- tunnelling.
- [The extor and httptunnel lists were added in 0.3.2.12, 0.3.3.10, and
- 0.3.4.6-rc.]
- "dir-usage"
- A newline-separated list of how many bytes we've served to answer
- each type of directory request. The format of each line is:
- Keyword 1*SP Integer 1*SP Integer
- where the first integer is the number of bytes written, and the second
- is the number of requests answered.
- [This feature was added in Tor 0.2.2.1-alpha, and removed in
- Tor 0.2.9.1-alpha. Even when it existed, it only provided
- useful output when the Tor client was built with either the
- INSTRUMENT_DOWNLOADS or RUNNING_DOXYGEN compile-time options.]
- "bw-event-cache"
- A space-separated summary of recent BW events in chronological order
- from oldest to newest. Each event is represented by a comma-separated
- tuple of "R,W", R is the number of bytes read, and W is the number of
- bytes written. These entries each represent about one second's worth
- of traffic.
- [New in Tor 0.2.6.3-alpha]
- "consensus/valid-after"
- "consensus/fresh-until"
- "consensus/valid-until"
- Each of these produces an ISOTime describing part of the lifetime of
- the current (valid, accepted) consensus that Tor has.
- [New in Tor 0.2.6.3-alpha]
- "hs/client/desc/id/<ADDR>"
- Prints the content of the hidden service descriptor corresponding to
- the given <ADDR> which is an onion address without the ".onion" part.
- The client's cache is queried to find the descriptor. The format of
- the descriptor is described in section 1.3 of the rend-spec.txt
- document.
- If <ADDR> is unrecognized or if not found in the cache, a 551 error is
- returned.
- [New in Tor 0.2.7.1-alpha]
- [HS v3 support added 0.3.3.1-alpha]
- "hs/service/desc/id/<ADDR>"
- Prints the content of the hidden service descriptor corresponding to
- the given <ADDR> which is an onion address without the ".onion" part.
- The service's local descriptor cache is queried to find the descriptor.
- The format of the descriptor is described in section 1.3 of the
- rend-spec.txt document.
- If <ADDR> is unrecognized or if not found in the cache, a 551 error is
- returned.
- [New in Tor 0.2.7.2-alpha]
- [HS v3 support added 0.3.3.1-alpha]
- "onions/current"
- "onions/detached"
- A newline-separated list of the Onion ("Hidden") Services created
- via the "ADD_ONION" command. The 'current' key returns Onion Services
- belonging to the current control connection. The 'detached' key
- returns Onion Services detached from the parent control connection
- (as in, belonging to no control connection).
- The format of each line is:
- HSAddress
- [New in Tor 0.2.7.1-alpha.]
- [HS v3 support added 0.3.3.1-alpha]
- "network-liveness"
- The string "up" or "down", indicating whether we currently believe the
- network is reachable.
- "downloads/"
- The keys under downloads/ are used to query download statuses; they all
- return either a sequence of newline-terminated hex encoded digests, or
- a "serialized download status" as follows:
- SerializedDownloadSatus =
- -- when do we plan to next attempt to download this object?
- "next-attempt-at" SP ISOTime CRLF
- -- how many times have we failed since the last success?
- "n-download-failures" SP UInt CRLF
- -- how many times have we tried to download this?
- "n-download-attempts" SP UInt CRLF
- -- according to which schedule rule will we download this?
- "schedule" SP DownloadSchedule CRLF
- -- do we want to fetch this from an authority, or will any cache do?
- "want-authority" SP DownloadWantAuthority CRLF
- -- do we increase our download delay whenever we fail to fetch this,
- -- or whenever we attempt fetching this?
- "increment-on" SP DownloadIncrementOn CRLF
- -- do we increase the download schedule deterministically, or at
- -- random?
- "backoff" SP DownloadBackoff CRLF
- [
- -- with an exponential backoff, where are we in the schedule?
- "last-backoff-position" Uint CRLF
- -- with an exponential backoff, what was our last delay?
- "last-delay-used UInt CRLF
- ]
- where
- DownloadSchedule =
- "DL_SCHED_GENERIC" / "DL_SCHED_CONSENSUS" / "DL_SCHED_BRIDGE"
- DownloadWantAuthority =
- "DL_WANT_ANY_DIRSERVER" / "DL_WANT_AUTHORITY"
- DownloadIncrementOn =
- "DL_SCHED_INCREMENT_FAILURE" / "DL_SCHED_INCREMENT_ATTEMPT"
- DownloadBackoff =
- "DL_SCHED_DETERMINISTIC" / "DL_SCHED_RANDOM_EXPONENTIAL"
- The optional last two lines must be present if DownloadBackoff is
- "DL_SCHED_RANDOM_EXPONENTIAL" and must be absent if DownloadBackoff
- is "DL_SCHED_DETERMINISTIC".
- In detail, the keys supported are:
- "downloads/networkstatus/ns"
- The SerializedDownloadStatus for the NS-flavored consensus for
- whichever bootstrap state Tor is currently in.
- "downloads/networkstatus/ns/bootstrap"
- The SerializedDownloadStatus for the NS-flavored consensus at
- bootstrap time, regardless of whether we are currently bootstrapping.
- "downloads/networkstatus/ns/running"
- The SerializedDownloadStatus for the NS-flavored consensus when
- running, regardless of whether we are currently bootstrapping.
- "downloads/networkstatus/microdesc"
- The SerializedDownloadStatus for the microdesc-flavored consensus for
- whichever bootstrap state Tor is currently in.
- "downloads/networkstatus/microdesc/bootstrap"
- The SerializedDownloadStatus for the microdesc-flavored consensus at
- bootstrap time, regardless of whether we are currently bootstrapping.
- "downloads/networkstatus/microdesc/running"
- The SerializedDownloadStatus for the microdesc-flavored consensus when
- running, regardless of whether we are currently bootstrapping.
- "downloads/cert/fps"
- A newline-separated list of hex-encoded digests for authority
- certificates for which we have download status available.
- "downloads/cert/fp/<Fingerprint>"
- A SerializedDownloadStatus for the default certificate for the
- identity digest <Fingerprint> returned by the downloads/cert/fps key.
- "downloads/cert/fp/<Fingerprint>/sks"
- A newline-separated list of hex-encoded signing key digests for the
- authority identity digest <Fingerprint> returned by the
- downloads/cert/fps key.
- "downloads/cert/fp/<Fingerprint>/<SKDigest>"
- A SerializedDownloadStatus for the certificate for the identity
- digest <Fingerprint> returned by the downloads/cert/fps key and signing
- key digest <SKDigest> returned by the downloads/cert/fp/<Fingerprint>/
- sks key.
- "downloads/desc/descs"
- A newline-separated list of hex-encoded router descriptor digests
- [note, not identity digests - the Tor process may not have seen them
- yet while downloading router descriptors]. If the Tor process is not
- using a NS-flavored consensus, a 551 error is returned.
- "downloads/desc/<Digest>"
- A SerializedDownloadStatus for the router descriptor with digest
- <Digest> as returned by the downloads/desc/descs key. If the Tor
- process is not using a NS-flavored consensus, a 551 error is returned.
- "downloads/bridge/bridges"
- A newline-separated list of hex-encoded bridge identity digests. If
- the Tor process is not using bridges, a 551 error is returned.
- "downloads/bridge/<Digest>"
- A SerializedDownloadStatus for the bridge descriptor with identity
- digest <Digest> as returned by the downloads/bridge/bridges key. If
- the Tor process is not using bridges, a 551 error is returned.
- "sr/current"
- "sr/previous"
- The current or previous shared random value, as received in the
- consensus, base-64 encoded. An empty value means that either
- the consensus has no shared random value, or Tor has no consensus.
- "current-time/local"
- "current-time/utc"
- The current system or UTC time, as returned by the system, in ISOTime2
- format. (Introduced in 0.3.4.1-alpha.)
- "config-can-saveconf"
- 0 or 1, depending on whether it is possible to use SAVECONF without the
- FORCE flag. (Introduced in 0.3.1.1-alpha.)
- "limits/max-mem-in-queues"
- The amount of memory that Tor's out-of-memory checker will allow
- Tor to allocate (in places it can see) before it starts freeing memory
- and killing circuits. See the MaxMemInQueues option for more
- details. Unlike the option, this value reflects Tor's actual limit, and
- may be adjusted depending on the available system memory rather than on
- the MaxMemInQueues option. (Introduced in 0.2.5.4-alpha)
- 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=" 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, 555 if the stream isn't in an
- appropriate state to be attached (e.g. it's already open), 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" / ; ... or supply the contents of a cookie file
- "SAFECOOKIE" ; ... or prove knowledge of a cookie file's contents
- AuthCookieFile = QuotedString
- TorVersion = QuotedString
- OtherLine = "250-" Keyword OptArguments CRLF
- PIVERSION: 1*DIGIT
- This command tells the controller what kinds of authentication are
- supported.
- 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" and/or "SAFECOOKIE".
- Controllers MUST handle escape sequences inside this string.
- All authentication cookies are 32 bytes long. Controllers MUST NOT
- use the contents of a non-32-byte-long file as an authentication
- cookie.
- If the METHODS field contains the method "SAFECOOKIE", every
- AuthCookieFile must contain the same authentication cookie.
- The COOKIE authentication method exposes the user running a
- controller to an unintended information disclosure attack whenever
- the controller has greater filesystem read access than the process
- that it has connected to. (Note that a controller may connect to a
- process other than Tor.) It is almost never safe to use, even if
- the controller's user has explicitly specified which filename to
- read an authentication cookie from. For this reason, the COOKIE
- authentication method has been deprecated and will be removed from
- a future version of Tor.
- 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 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.
- (As of Tor 0.2.5.2-alpha, Tor does not wait a while for circuits to
- close when shutting down because of an exiting controller. If you
- want to ensure a clean shutdown--and you should!--then send "SIGNAL
- SHUTDOWN" and wait for the Tor process to close.)
- 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
- __OwningControllerProcess on Tor's command line. This will
- cause Tor to poll for the existence of a process with that PID,
- and exit if it does not find such a process. (This is not a
- completely reliable way to detect whether the 'owning
- controller' is still running, but it should work well enough in
- most cases.)
- * Once the controller has connected to Tor's control port, it
- should send the TAKEOWNERSHIP command along its control
- connection. At this point, *both* the TAKEOWNERSHIP command and
- the __OwningControllerProcess option are in effect: Tor will
- exit when the control connection ends *and* Tor will exit if it
- detects that there is no process with the PID specified in the
- __OwningControllerProcess option.
- * After the controller has sent the TAKEOWNERSHIP command, it
- should send "RESETCONF __OwningControllerProcess" along its
- control connection. This will cause Tor to stop polling for the
- existence of a process with its owning controller's PID; Tor
- will still exit when the control connection ends.
- [TAKEOWNERSHIP was added in Tor 0.2.2.28-beta.]
- 3.24. AUTHCHALLENGE
- The syntax is:
- "AUTHCHALLENGE" SP "SAFECOOKIE"
- SP ClientNonce
- CRLF
- ClientNonce = 2*HEXDIG / QuotedString
- This command is used to begin the authentication routine for the
- SAFECOOKIE method of authentication.
- If the server accepts the command, the server reply format is:
- "250 AUTHCHALLENGE"
- SP "SERVERHASH=" ServerHash
- SP "SERVERNONCE=" ServerNonce
- CRLF
- ServerHash = 64*64HEXDIG
- ServerNonce = 64*64HEXDIG
- The ClientNonce, ServerHash, and ServerNonce values are
- encoded/decoded in the same way as the argument passed to the
- AUTHENTICATE command. ServerNonce MUST be 32 bytes long.
- ServerHash is computed as:
- HMAC-SHA256("Tor safe cookie authentication server-to-controller hash",
- CookieString | ClientNonce | ServerNonce)
- (with the HMAC key as its first argument)
- After a controller sends a successful AUTHCHALLENGE command, the
- next command sent on the connection must be an AUTHENTICATE command,
- and the only authentication string which that AUTHENTICATE command
- will accept is:
- HMAC-SHA256("Tor safe cookie authentication controller-to-server hash",
- CookieString | ClientNonce | ServerNonce)
- [Unlike other commands besides AUTHENTICATE, AUTHCHALLENGE may be
- used (but only once!) before AUTHENTICATE.]
- [AUTHCHALLENGE was added in Tor 0.2.3.13-alpha.]
- 3.25. DROPGUARDS
- The syntax is:
- "DROPGUARDS" CRLF
- Tells the server to drop all guard nodes. Do not invoke this command
- lightly; it can increase vulnerability to tracking attacks over time.
- Tor replies with "250 OK" on success.
- [DROPGUARDS was added in Tor 0.2.5.2-alpha.]
- 3.26. HSFETCH
- The syntax is:
- "HSFETCH" SP (HSAddress / "v" Version "-" DescId)
- *[SP "SERVER=" Server] CRLF
- HSAddress = 16*Base32Character / 56*Base32Character
- Version = "2" / "3"
- DescId = 32*Base32Character
- Server = LongName
- This command launches hidden service descriptor fetch(es) for the given
- HSAddress or DescId.
- HSAddress can be version 2 or version 3 addresses. DescIDs can only be
- version 2 IDs. Version 2 addresses consist of 16*Base32Character and
- version 3 addresses consist of 56*Base32Character.
- If a DescId is specified, at least one Server MUST also be provided,
- otherwise a 512 error is returned. If no DescId and Server(s) are specified,
- it behaves like a normal Tor client descriptor fetch. If one or more
- Server are given, they are used instead triggering a fetch on each of them
- in parallel.
- The caching behavior when fetching a descriptor using this command is
- identical to normal Tor client behavior.
- Details on how to compute a descriptor id (DescId) can be found in
- rend-spec.txt section 1.3.
- If any values are unrecognized, a 513 error is returned and the command is
- stopped. On success, Tor replies "250 OK" then Tor MUST eventually follow
- this with both a HS_DESC and HS_DESC_CONTENT events with the results. If
- SERVER is specified then events are emitted for each location.
- Examples are:
- C: HSFETCH v2-gezdgnbvgy3tqolbmjrwizlgm5ugs2tl
- SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31
- S: 250 OK
- C: HSFETCH ajkhdsfuygaesfaa
- S: 250 OK
- C: HSFETCH vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd
- S: 250 OK
- [HSFETCH was added in Tor 0.2.7.1-alpha]
- [HS v3 support added 0.4.1.1-alpha]
- 3.27. ADD_ONION
- The syntax is:
- "ADD_ONION" SP KeyType ":" KeyBlob
- [SP "Flags=" Flag *("," Flag)]
- [SP "MaxStreams=" NumStreams]
- 1*(SP "Port=" VirtPort ["," Target])
- *(SP "ClientAuth=" ClientName [":" ClientBlob]) CRLF
- KeyType =
- "NEW" / ; The server should generate a key of algorithm KeyBlob
- "RSA1024" / ; The server should use the 1024 bit RSA key provided
- in as KeyBlob
- "ED25519-V3"; The server should use the ed25519 v3 key provided in as
- KeyBlob
- KeyBlob =
- "BEST" / ; The server should generate a key using the "best"
- supported algorithm (KeyType == "NEW")
- "RSA1024" / ; The server should generate a 1024 bit RSA key
- (KeyType == "NEW")
- "ED25519-V3"; The server should generate an ed25519 private key
- (KeyType == "NEW")
- String ; A serialized private key (without whitespace)
- Flag =
- "DiscardPK" / ; The server should not include the newly generated
- private key as part of the response.
- "Detach" / ; Do not associate the newly created Onion Service
- to the current control connection.
- "BasicAuth" / ; Client authorization is required using the "basic"
- method.
- "NonAnonymous" /; Add a non-anonymous Single Onion Service. Tor
- checks this flag matches its configured hidden
- service anonymity mode.
- "MaxStreamsCloseCircuit"; Close the circuit is the maximum streams
- allowed is reached.
- NumStreams = A value between 0 and 65535 which is used as the maximum
- streams that can be attached on a rendezvous circuit. Setting
- it to 0 means unlimited which is also the default behavior.
- VirtPort = The virtual TCP Port for the Onion Service (As in the
- HiddenServicePort "VIRTPORT" argument).
- Target = The (optional) target for the given VirtPort (As in the
- optional HiddenServicePort "TARGET" argument).
- ClientName = An identifier 1 to 16 characters long, using only
- characters in A-Za-z0-9+-_ (no spaces).
- ClientBlob = Authorization data for the client, in an opaque format
- specific to the authorization method.
- The server reply format is:
- "250-ServiceID=" ServiceID CRLF
- ["250-PrivateKey=" KeyType ":" KeyBlob CRLF]
- *("250-ClientAuth=" ClientName ":" ClientBlob CRLF)
- "250 OK" CRLF
- ServiceID = The Onion Service address without the trailing ".onion"
- suffix
- Tells the server to create a new Onion ("Hidden") Service, with the
- specified private key and algorithm. If a KeyType of "NEW" is selected,
- the server will generate a new keypair using the selected algorithm.
- The "Port" argument's VirtPort and Target values have identical
- semantics to the corresponding HiddenServicePort configuration values.
- The server response will only include a private key if the server was
- requested to generate a new keypair, and also the "DiscardPK" flag was
- not specified. (Note that if "DiscardPK" flag is specified, there is no
- way to recreate the generated keypair and the corresponding Onion
- Service at a later date).
- If client authorization is enabled using the "BasicAuth" flag, the
- service will not be accessible to clients without valid authorization
- data (configured with the "HidServAuth" option). The list of authorized
- clients is specified with one or more "ClientAuth" parameters. If
- "ClientBlob" is not specified for a client, a new credential will be
- randomly generated and returned.
- Tor instances can either be in anonymous hidden service mode, or
- non-anonymous single onion service mode. All hidden services on the same
- tor instance have the same anonymity. To guard against unexpected loss
- of anonymity, Tor checks that the ADD_ONION "NonAnonymous" flag matches
- the current hidden service anonymity mode. The hidden service anonymity
- mode is configured using the Tor options HiddenServiceSingleHopMode and
- HiddenServiceNonAnonymousMode. If both these options are 1, the
- "NonAnonymous" flag must be provided to ADD_ONION. If both these options
- are 0 (the Tor default), the flag must NOT be provided.
- Once created the new Onion Service will remain active until either the
- Onion Service is removed via "DEL_ONION", the server terminates, or the
- control connection that originated the "ADD_ONION" command is closed.
- It is possible to override disabling the Onion Service on control
- connection close by specifying the "Detach" flag.
- It is the Onion Service server application's responsibility to close
- existing client connections if desired after the Onion Service is
- removed.
- (The KeyBlob format is left intentionally opaque, however for "RSA1024"
- keys it is currently the Base64 encoded DER representation of a PKCS#1
- RSAPrivateKey, with all newlines removed. For a "ED25519-V3" key is
- the Base64 encoding of the concatenation of the 32-byte ed25519 secret
- scalar in little-endian and the 32-byte ed25519 PRF secret.)
- [Note: The ED25519-V3 format is not the same as, e.g., SUPERCOP
- ed25519/ref, which stores the concatenation of the 32-byte ed25519
- hash seed concatenated with the 32-byte public key, and which derives
- the secret scalar and PRF secret by expanding the hash seed with
- SHA-512. Our key blinding scheme is incompatible with storing
- private keys as seeds, so we store the secret scalar alongside the
- PRF secret, and just pay the cost of recomputing the public key when
- importing an ED25519-V3 key.]
- (The "NEW:BEST" option obeys the HiddenServiceVersion torrc option default
- value. Since 0.3.5.1-alpha, it is 3. For Tor versions before 0.3.5.1-alpha,
- default HiddenServiceVersion is 2.)
- Examples:
- C: ADD_ONION NEW:BEST Flags=DiscardPK Port=80
- S: 250-ServiceID=exampleonion1234
- S: 250 OK
- C: ADD_ONION RSA1024:[Blob Redacted] Port=80,192.168.1.1:8080
- S: 250-ServiceID=sampleonion12456
- S: 250 OK
- C: ADD_ONION NEW:BEST Port=22 Port=80,8080
- S: 250-ServiceID=testonion1234567
- S: 250-PrivateKey=RSA1024:[Blob Redacted]
- S: 250 OK
- C: ADD_ONION NEW:BEST Flags=DiscardPK,BasicAuth Port=22
- ClientAuth=alice:[Blob Redacted] ClientAuth=bob
- S: 250-ServiceID=testonion1234567
- S: 250-ClientAuth=bob:[Blob Redacted]
- S: 250 OK
- Examples with Tor in anonymous onion service mode:
- C: ADD_ONION NEW:BEST Flags=DiscardPK Port=22
- S: 250-ServiceID=testonion1234567
- S: 250 OK
- C: ADD_ONION NEW:BEST Flags=DiscardPK,NonAnonymous Port=22
- S: 512 Tor is in anonymous hidden service mode
- Examples with Tor in non-anonymous onion service mode:
- C: ADD_ONION NEW:BEST Flags=DiscardPK Port=22
- S: 512 Tor is in non-anonymous hidden service mode
- C: ADD_ONION NEW:BEST Flags=DiscardPK,NonAnonymous Port=22
- S: 250-ServiceID=testonion1234567
- S: 250 OK
- [ADD_ONION was added in Tor 0.2.7.1-alpha.]
- [ClientAuth was added in Tor 0.2.9.1-alpha.]
- [NonAnonymous was added in Tor 0.2.9.3-alpha.]
- [MaxStreams and MaxStreamsCloseCircuit were added in Tor 0.2.7.2-alpha]
- [HS v3 support added 0.3.3.1-alpha]
- 3.28. DEL_ONION
- The syntax is:
- "DEL_ONION" SP ServiceID CRLF
- ServiceID = The Onion Service address without the trailing ".onion"
- suffix
- Tells the server to remove an Onion ("Hidden") Service, that was
- previously created via an "ADD_ONION" command. It is only possible to
- remove Onion Services that were created on the same control connection
- as the "DEL_ONION" command, and those that belong to no control
- connection in particular (The "Detach" flag was specified at creation).
- If the ServiceID is invalid, or is neither owned by the current control
- connection nor a detached Onion Service, the server will return a 552.
- It is the Onion Service server application's responsibility to close
- existing client connections if desired after the Onion Service has been
- removed via "DEL_ONION".
- Tor replies with "250 OK" on success, or a 512 if there are an invalid
- number of arguments, or a 552 if it doesn't recognize the ServiceID.
- [DEL_ONION was added in Tor 0.2.7.1-alpha.]
- [HS v3 support added 0.3.3.1-alpha]
- 3.29. HSPOST
- The syntax is:
- "+HSPOST" *[SP "SERVER=" Server] [SP "HSADDRESS=" HSAddress]
- CRLF Descriptor CRLF "." CRLF
- Server = LongName
- HSAddress = 56*Base32Character
- Descriptor = The text of the descriptor formatted as specified
- in rend-spec.txt section 1.3.
- The "HSAddress" key is optional and only applies for v3 descriptors. A 513
- error is returned if used with v2.
- This command launches a hidden service descriptor upload to the specified
- HSDirs. If one or more Server arguments are provided, an upload is triggered
- on each of them in parallel. If no Server options are provided, it behaves
- like a normal HS descriptor upload and will upload to the set of responsible
- HS directories.
- If any value is unrecognized, a 552 error is returned and the command is
- stopped. If there is an error in parsing the descriptor, the server
- must send a "554 Invalid descriptor" reply.
- On success, Tor replies "250 OK" then Tor MUST eventually follow
- this with a HS_DESC event with the result for each upload location.
- Examples are:
- C: +HSPOST SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31
- [DESCRIPTOR]
- .
- S: 250 OK
- [HSPOST was added in Tor 0.2.7.1-alpha]
- 3.23. DROPOWNERSHIP
- The syntax is:
- "DROPOWNERSHIP" CRLF
- This command instructs Tor to relinquish ownership of its control
- connection. As such tor will not shut down when this control
- connection is closed.
- This method is idempotent. If the control connection does not
- already have ownership this method returns successfully, and
- does nothing.
- The controller can call TAKEOWNERSHIP again to re-establish
- ownership.
- [DROPOWNERSHIP was added in Tor 0.4.0.0-alpha]
- 4. Replies
- Reply codes follow the same 3-character format as used by SMTP, with the
- first character defining a status, the second character defining a
- subsystem, and the third designating fine-grained information.
- The TC protocol currently uses the following first characters:
- 2yz Positive Completion Reply
- The command was successful; a new request can be started.
- 4yz Temporary Negative Completion reply
- The command was unsuccessful but might be reattempted later.
- 5yz Permanent Negative Completion Reply
- The command was unsuccessful; the client should not try exactly
- that sequence of commands again.
- 6yz Asynchronous Reply
- Sent out-of-order in response to an earlier SETEVENTS command.
- The following second characters are used:
- x0z Syntax
- Sent in response to ill-formed or nonsensical commands.
- x1z Protocol
- Refers to operations of the Tor Control protocol.
- x5z Tor
- Refers to actual operations of Tor system.
- The following codes are defined:
- 250 OK
- 251 Operation was unnecessary
- [Tor has declined to perform the operation, but no harm was done.]
- 451 Resource exhausted
- 500 Syntax error: protocol
- 510 Unrecognized command
- 511 Unimplemented command
- 512 Syntax error in command argument
- 513 Unrecognized command argument
- 514 Authentication required
- 515 Bad authentication
- 550 Unspecified Tor error
- 551 Internal error
- [Something went wrong inside Tor, so that the client's
- request couldn't be fulfilled.]
- 552 Unrecognized entity
- [A configuration key, a stream ID, circuit ID, event,
- mentioned in the command did not actually exist.]
- 553 Invalid configuration value
- [The client tried to set a configuration option to an
- incorrect, ill-formed, or impossible value.]
- 554 Invalid descriptor
- 555 Unmanaged entity
- 650 Asynchronous event notification
- Unless specified to have specific contents, the human-readable messages
- in error replies should not be relied upon to match those in this document.
- 4.1. Asynchronous events
- These replies can be sent after a corresponding SETEVENTS command has been
- received. They will not be interleaved with other Reply elements, but they
- can appear between a command and its corresponding reply. For example,
- this sequence is possible:
- C: SETEVENTS CIRC
- S: 250 OK
- C: GETCONF SOCKSPORT ORPORT
- S: 650 CIRC 1000 EXTENDED moria1,moria2
- S: 250-SOCKSPORT=9050
- S: 250 ORPORT=0
- But this sequence is disallowed:
- C: SETEVENTS CIRC
- S: 250 OK
- C: GETCONF SOCKSPORT ORPORT
- S: 250-SOCKSPORT=9050
- S: 650 CIRC 1000 EXTENDED moria1,moria2
- S: 250 ORPORT=0
- Clients MUST tolerate more arguments in an asynchronous reply than
- expected, and MUST tolerate more lines in an asynchronous reply than
- expected. For instance, a client that expects a CIRC message like:
- 650 CIRC 1000 EXTENDED moria1,moria2
- must tolerate:
- 650-CIRC 1000 EXTENDED moria1,moria2 0xBEEF
- 650-EXTRAMAGIC=99
- 650 ANONYMITY=high
- If clients receives extended events (selected by USEFEATUERE
- EXTENDED_EVENTS in Tor 0.1.2.2-alpha..Tor-0.2.1.x, and always-on in
- Tor 0.2.2.x and later), then each event line as specified below may be
- followed by additional arguments and additional lines. Additional
- lines will be of the form:
- "650" ("-"/" ") KEYWORD ["=" ARGUMENTS] CRLF
- Additional arguments will be of the form
- SP KEYWORD ["=" ( QuotedString / * NonSpDquote ) ]
- Clients MUST tolerate events with arguments and keywords they do not
- recognize, and SHOULD process those events as if any unrecognized
- arguments and keywords were not present.
- Clients SHOULD NOT depend on the order of keyword=value arguments,
- and SHOULD NOT depend on there being no new keyword=value arguments
- appearing between existing keyword=value arguments, though as of this
- writing (Jun 2011) some do. Thus, extensions to this protocol should
- add new keywords only after the existing keywords, until all
- controllers have been fixed. At some point this "SHOULD NOT" might
- become a "MUST NOT".
- 4.1.1. Circuit status changed
- The syntax is:
- "650" SP "CIRC" SP CircuitID SP CircStatus [SP Path]
- [SP "BUILD_FLAGS=" BuildFlags] [SP "PURPOSE=" Purpose]
- [SP "HS_STATE=" HSState] [SP "REND_QUERY=" HSAddress]
- [SP "TIME_CREATED=" TimeCreated]
- [SP "REASON=" Reason [SP "REMOTE_REASON=" Reason]]
- [SP "SOCKS_USERNAME=" EscapedUsername]
- [SP "SOCKS_PASSWORD=" EscapedPassword]
- CRLF
- CircStatus =
- "LAUNCHED" / ; circuit ID assigned to new circuit
- "BUILT" / ; all hops finished, can now accept streams
- "GUARD_WAIT" / ; all hops finished, waiting to see if a
- ; circuit with a better guard will be usable.
- "EXTENDED" / ; one more hop has been completed
- "FAILED" / ; circuit closed (was not built)
- "CLOSED" ; circuit closed (was built)
- Path = LongName *("," LongName)
- ; 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, Path
- ; is as follows:
- ; Path = ServerID *("," ServerID)
- BuildFlags = BuildFlag *("," BuildFlag)
- BuildFlag = "ONEHOP_TUNNEL" / "IS_INTERNAL" /
- "NEED_CAPACITY" / "NEED_UPTIME"
- Purpose = "GENERAL" / "HS_CLIENT_INTRO" / "HS_CLIENT_REND" /
- "HS_SERVICE_INTRO" / "HS_SERVICE_REND" / "TESTING" /
- "CONTROLLER" / "MEASURE_TIMEOUT"
- HSState = "HSCI_CONNECTING" / "HSCI_INTRO_SENT" / "HSCI_DONE" /
- "HSCR_CONNECTING" / "HSCR_ESTABLISHED_IDLE" /
- "HSCR_ESTABLISHED_WAITING" / "HSCR_JOINED" /
- "HSSI_CONNECTING" / "HSSI_ESTABLISHED" /
- "HSSR_CONNECTING" / "HSSR_JOINED"
- EscapedUsername = QuotedString
- EscapedPassword = QuotedString
- HSAddress = 16*Base32Character / 56*Base32Character
- Base32Character = ALPHA / "2" / "3" / "4" / "5" / "6" / "7"
- TimeCreated = ISOTime2Frac
- Seconds = 1*DIGIT
- Microseconds = 1*DIGIT
- Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" /
- "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" /
- "OR_IDENTITY" / "OR_CONN_CLOSED" / "TIMEOUT" /
- "FINISHED" / "DESTROYED" / "NOPATH" / "NOSUCHSERVICE" /
- "MEASUREMENT_EXPIRED"
- The path is provided only when the circuit has been extended at least one
- hop.
- The "BUILD_FLAGS" field is provided only in versions 0.2.3.11-alpha
- and later. Clients MUST accept build flags not listed above.
- Build flags are defined as follows:
- ONEHOP_TUNNEL (one-hop circuit, used for tunneled directory conns)
- IS_INTERNAL (internal circuit, not to be used for exiting streams)
- NEED_CAPACITY (this circuit must use only high-capacity nodes)
- NEED_UPTIME (this circuit must use only high-uptime nodes)
- The "PURPOSE" field is provided only in versions 0.2.1.6-alpha and
- later, and only if extended events are enabled (see 3.19). Clients
- MUST accept purposes not listed above. Purposes are defined as
- follows:
- GENERAL (circuit for AP and/or directory request streams)
- HS_CLIENT_INTRO (HS client-side introduction-point circuit)
- HS_CLIENT_REND (HS client-side rendezvous circuit; carries AP streams)
- HS_SERVICE_INTRO (HS service-side introduction-point circuit)
- HS_SERVICE_REND (HS service-side rendezvous circuit)
- TESTING (reachability-testing circuit; carries no traffic)
- CONTROLLER (circuit built by a controller)
- MEASURE_TIMEOUT (circuit being kept around to see how long it takes)
- The "HS_STATE" field is provided only for hidden-service circuits,
- and only in versions 0.2.3.11-alpha and later. Clients MUST accept
- hidden-service circuit states not listed above. Hidden-service
- circuit states are defined as follows:
- HSCI_* (client-side introduction-point circuit states)
- HSCI_CONNECTING (connecting to intro point)
- HSCI_INTRO_SENT (sent INTRODUCE1; waiting for reply from IP)
- HSCI_DONE (received reply from IP relay; closing)
- HSCR_* (client-side rendezvous-point circuit states)
- HSCR_CONNECTING (connecting to or waiting for reply from RP)
- HSCR_ESTABLISHED_IDLE (established RP; waiting for introduction)
- HSCR_ESTABLISHED_WAITING (introduction sent to HS; waiting for rend)
- HSCR_JOINED (connected to HS)
- HSSI_* (service-side introduction-point circuit states)
- HSSI_CONNECTING (connecting to intro point)
- HSSI_ESTABLISHED (established intro point)
- HSSR_* (service-side rendezvous-point circuit states)
- HSSR_CONNECTING (connecting to client's rend point)
- HSSR_JOINED (connected to client's RP circuit)
- The "SOCKS_USERNAME" and "SOCKS_PASSWORD" fields indicate the credentials
- that were used by a SOCKS client to connect to Tor's SOCKS port and
- initiate this circuit. (Streams for SOCKS clients connected with different
- usernames and/or passwords are isolated on separate circuits if the
- IsolateSOCKSAuth flag is active; see Proposal 171.)
- The "REND_QUERY" field is provided only for hidden-service-related
- circuits, and only in versions 0.2.3.11-alpha and later. Clients
- MUST accept hidden service addresses in formats other than that
- specified above.
- The "TIME_CREATED" field is provided only in versions 0.2.3.11-alpha and
- later. TIME_CREATED is the time at which the circuit was created or
- cannibalized.
- The "REASON" field is provided only for FAILED and CLOSED events, and only
- if extended events are enabled (see 3.19). Clients MUST accept reasons
- not listed above. Reasons are as given in tor-spec.txt, except for:
- NOPATH (Not enough nodes to make circuit)
- MEASUREMENT_EXPIRED (As "TIMEOUT", except that we had left the circuit
- open for measurement purposes to see how long it
- would take to finish.)
- The "REMOTE_REASON" field is provided only when we receive a DESTROY or
- TRUNCATE cell, and only if extended events are enabled. It contains the
- actual reason given by the remote OR for closing the circuit. Clients MUST
- accept reasons not listed above. Reasons are as listed in tor-spec.txt.
- 4.1.2. Stream status changed
- The syntax is:
- "650" SP "STREAM" SP StreamID SP StreamStatus SP CircuitID SP Target
- [SP "REASON=" Reason [ SP "REMOTE_REASON=" Reason ]]
- [SP "SOURCE=" Source] [ SP "SOURCE_ADDR=" Address ":" Port ]
- [SP "PURPOSE=" Purpose] [SP "SOCKS_USERNAME=" EscapedUsername]
- [SP "SOCKS_PASSWORD=" EscapedPassword]
- [SP "CLIENT_PROTOCOL=" ClientProtocol] [SP "NYM_EPOCH=" NymEpoch]
- [SP "SESSION_GROUP=" SessionGroup] [SP "ISO_FIELDS=" IsoFields]
- CRLF
- StreamStatus =
- "NEW" / ; New request to connect
- "NEWRESOLVE" / ; New request to resolve an address
- "REMAP" / ; Address re-mapped to another
- "SENTCONNECT" / ; Sent a connect cell along a circuit
- "SENTRESOLVE" / ; Sent a resolve cell along a circuit
- "SUCCEEDED" / ; Received a reply; stream established
- "FAILED" / ; Stream failed and not retriable
- "CLOSED" / ; Stream closed
- "DETACHED" ; Detached from circuit; still retriable
- Target = TargetAddress ":" Port
- Port = an integer from 0 to 65535 inclusive
- TargetAddress = Address / "(Tor_internal)"
- EscapedUsername = QuotedString
- EscapedPassword = QuotedString
- ClientProtocol =
- "SOCKS4" /
- "SOCKS5" /
- "TRANS" /
- "NATD" /
- "DNS" /
- "HTTPCONNECT" /
- "UNKNOWN"
- NymEpoch = a nonnegative integer
- SessionGroup = an integer
- IsoFields = a comma-separated list of IsoField values
- IsoField =
- "CLIENTADDR" /
- "CLIENTPORT" /
- "DESTADDR" /
- "DESTPORT" /
- the name of a field that is valid for STREAM events
- The circuit ID designates which circuit this stream is attached to. If
- the stream is unattached, the circuit ID "0" is given. The target
- indicates the address which the stream is meant to resolve or connect to;
- it can be "(Tor_internal)" for a virtual stream created by the Tor program
- to talk to itself.
- Reason = "MISC" / "RESOLVEFAILED" / "CONNECTREFUSED" /
- "EXITPOLICY" / "DESTROY" / "DONE" / "TIMEOUT" /
- "NOROUTE" / "HIBERNATING" / "INTERNAL"/ "RESOURCELIMIT" /
- "CONNRESET" / "TORPROTOCOL" / "NOTDIRECTORY" / "END" /
- "PRIVATE_ADDR"
- The "REASON" field is provided only for FAILED, CLOSED, and DETACHED
- events, and only if extended events are enabled (see 3.19). Clients MUST
- accept reasons not listed above. Reasons are as given in tor-spec.txt,
- except for:
- END (We received a RELAY_END cell from the other side of this
- stream.)
- PRIVATE_ADDR (The client tried to connect to a private address like
- 127.0.0.1 or 10.0.0.1 over Tor.)
- [XXXX document more. -NM]
- The "REMOTE_REASON" field is provided only when we receive a RELAY_END
- cell, and only if extended events are enabled. It contains the actual
- reason given by the remote OR for closing the stream. Clients MUST accept
- reasons not listed above. Reasons are as listed in tor-spec.txt.
- "REMAP" events include a Source if extended events are enabled:
- Source = "CACHE" / "EXIT"
- Clients MUST accept sources not listed above. "CACHE" is given if
- the Tor client decided to remap the address because of a cached
- answer, and "EXIT" is given if the remote node we queried gave us
- the new address as a response.
- The "SOURCE_ADDR" field is included with NEW and NEWRESOLVE events if
- extended events are enabled. It indicates the address and port
- that requested the connection, and can be (e.g.) used to look up the
- requesting program.
- Purpose = "DIR_FETCH" / "DIR_UPLOAD" / "DNS_REQUEST" /
- "USER" / "DIRPORT_TEST"
- The "PURPOSE" field is provided only for NEW and NEWRESOLVE events, and
- only if extended events are enabled (see 3.19). Clients MUST accept
- purposes not listed above. The purposes above are defined as:
- "DIR_FETCH" -- This stream is generated internally to Tor for
- fetching directory information.
- "DIR_UPLOAD" -- An internal stream for uploading information to
- a directory authority.
- "DIRPORT_TEST" -- A stream we're using to test our own directory
- port to make sure it's reachable.
- "DNS_REQUEST" -- A user-initiated DNS request.
- "USER" -- This stream is handling user traffic, OR it's internal
- to Tor, but it doesn't match one of the purposes above.
- The "SOCKS_USERNAME" and "SOCKS_PASSWORD" fields indicate the credentials
- that were used by a SOCKS client to connect to Tor's SOCKS port and
- initiate this stream. (Streams for SOCKS clients connected with different
- usernames and/or passwords are isolated on separate circuits if the
- IsolateSOCKSAuth flag is active; see Proposal 171.)
- The "CLIENT_PROTOCOL" field indicates the protocol that was used by a client
- to initiate this stream. (Streams for clients connected with different
- protocols are isolated on separate circuits if the IsolateClientProtocol
- flag is active.) Controllers MUST tolerate unrecognized client protocols.
- The "NYM_EPOCH" field indicates the nym epoch that was active when a client
- initiated this stream. The epoch increments when the NEWNYM signal is
- received. (Streams with different nym epochs are isolated on separate
- circuits.)
- The "SESSION_GROUP" field indicates the session group of the listener port
- that a client used to initiate this stream. By default, the session group is
- different for each listener port, but this can be overridden for a listener
- via the "SessionGroup" option in torrc. (Streams with different session
- groups are isolated on separate circuits.)
- The "ISO_FIELDS" field indicates the set of STREAM event fields for which
- stream isolation is enabled for the listener port that a client used to
- initiate this stream. The special values "CLIENTADDR", "CLIENTPORT",
- "DESTADDR", and "DESTPORT", if their correspondingly named fields are not
- present, refer to the Address and Port components of the "SOURCE_ADDR" and
- Target fields.
- 4.1.3. OR Connection status changed
- The syntax is:
- "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON="
- Reason ] [ SP "NCIRCS=" NumCircuits ] [ SP "ID=" ConnID ] CRLF
- ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"
- ; 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, OR
- ; Connection is as follows:
- "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON="
- Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
- NEW is for incoming connections, and LAUNCHED is for outgoing
- connections. CONNECTED means the TLS handshake has finished (in
- either direction). FAILED means a connection is being closed that
- hasn't finished its handshake, and CLOSED is for connections that
- have handshaked.
- A LongName or ServerID is specified unless it's a NEW connection, in
- which case we don't know what server it is yet, so we use Address:Port.
- If extended events are enabled (see 3.19), optional reason and
- circuit counting information is provided for CLOSED and FAILED
- events.
- Reason = "MISC" / "DONE" / "CONNECTREFUSED" /
- "IDENTITY" / "CONNECTRESET" / "TIMEOUT" / "NOROUTE" /
- "IOERROR" / "RESOURCELIMIT" / "PT_MISSING"
- NumCircuits counts both established and pending circuits.
- The ORStatus values are as follows:
- NEW -- We have received a new incoming OR connection, and are starting
- the server-side handshake.
- LAUNCHED -- We have launched a new outgoing OR connection, and are
- starting the client-side handshake.
- CONNECTED -- The OR connection has been connected and the handshake is
- done.
- FAILED -- Our attempt to open the OR connection failed.
- CLOSED -- The OR connection closed in an unremarkable way.
- The Reason values for closed/failed OR connections are:
- DONE -- The OR connection has shut down cleanly.
- CONNECTREFUSED -- We got an ECONNREFUSED while connecting to the target
- OR.
- IDENTITY -- We connected to the OR, but found that its identity was
- not what we expected.
- CONNECTRESET -- We got an ECONNRESET or similar IO error from the
- connection with the OR.
- TIMEOUT -- We got an ETIMEOUT or similar IO error from the connection
- with the OR, or we're closing the connection for being idle for too
- long.
- NOROUTE -- We got an ENOTCONN, ENETUNREACH, ENETDOWN, EHOSTUNREACH, or
- similar error while connecting to the OR.
- IOERROR -- We got some other IO error on our connection to the OR.
- RESOURCELIMIT -- We don't have enough operating system resources (file
- descriptors, buffers, etc) to connect to the OR.
- PT_MISSING -- No pluggable transport was available.
- MISC -- The OR connection closed for some other reason.
- [First added ID parameter in 0.2.5.2-alpha]
- 4.1.4. Bandwidth used in the last second
- The syntax is:
- "650" SP "BW" SP BytesRead SP BytesWritten *(SP Type "=" Num) CRLF
- BytesRead = 1*DIGIT
- BytesWritten = 1*DIGIT
- Type = "DIR" / "OR" / "EXIT" / "APP" / ...
- Num = 1*DIGIT
- BytesRead and BytesWritten are the totals. [In a future Tor version,
- we may also include a breakdown of the connection types that used
- bandwidth this second (not implemented yet).]
- 4.1.5. Log messages
- The syntax is:
- "650" SP Severity SP ReplyText CRLF
- or
- "650+" Severity CRLF Data 650 SP "OK" CRLF
- Severity = "DEBUG" / "INFO" / "NOTICE" / "WARN"/ "ERR"
- Some low-level logs may be sent from signal handlers, so their destination
- logs must be signal-safe. These low-level logs include backtraces,
- logging function errors, and errors in code called by logging functions.
- Signal-safe logs are never sent as control port log events.
- Control port message trace debug logs are never sent as control port log
- events, to avoid modifying control output when debugging.
- 4.1.6. New descriptors available
- This event is generated when new router descriptors (not microdescs or
- extrainfos or anything else) are received.
- Syntax:
- "650" SP "NEWDESC" 1*(SP LongName) 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, it
- ; is as follows:
- "650" SP "NEWDESC" 1*(SP ServerID) CRLF
- 4.1.7. New Address mapping
- These events are generated when a new address mapping is entered in
- Tor's address map cache, or when the answer for a RESOLVE command is
- found. Entries can be created by a successful or failed DNS lookup,
- a successful or failed connection attempt, a RESOLVE command,
- a MAPADDRESS command, the AutomapHostsOnResolve feature, or the
- TrackHostExits feature.
- Syntax:
- "650" SP "ADDRMAP" SP Address SP NewAddress SP Expiry
- [SP "error=" ErrorCode] [SP "EXPIRES=" UTCExpiry] [SP "CACHED=" Cached]
- CRLF
- NewAddress = Address / "<error>"
- Expiry = DQUOTE ISOTime DQUOTE / "NEVER"
- ErrorCode = "yes" / "internal" / "Unable to launch resolve request"
- UTCExpiry = DQUOTE IsoTime DQUOTE
- Cached = DQUOTE "YES" DQUOTE / DQUOTE "NO" DQUOTE
- Error and UTCExpiry are only provided if extended events are enabled.
- The values for Error are mostly useless. Future values will be
- chosen to match 1*(ALNUM / "_"); the "Unable to launch resolve request"
- value is a bug in Tor before 0.2.4.7-alpha.
- Expiry is expressed as the local time (rather than UTC). This is a bug,
- left in for backward compatibility; new code should look at UTCExpiry
- instead. (If Expiry is "NEVER", UTCExpiry is omitted.)
- Cached indicates whether the mapping will be stored until it expires, or if
- it is just a notification in response to a RESOLVE command.
- 4.1.8. Descriptors uploaded to us in our role as authoritative dirserver
- [NOTE: This feature was removed in Tor 0.3.2.1-alpha.]
- Tor generates this event when it's an directory authority, and
- somebody has just uploaded a server descriptor.
- Syntax:
- "650" "+" "AUTHDIR_NEWDESCS" CRLF Action CRLF Message CRLF
- Descriptor CRLF "." CRLF "650" SP "OK" CRLF
- Action = "ACCEPTED" / "DROPPED" / "REJECTED"
- Message = Text
- The Descriptor field is the text of the server descriptor; the Action
- field is "ACCEPTED" if we're accepting the descriptor as the new
- best valid descriptor for its router, "REJECTED" if we aren't taking
- the descriptor and we're complaining to the uploading relay about
- it, and "DROPPED" if we decide to drop the descriptor without
- complaining. The Message field is a human-readable string
- explaining why we chose the Action. (It doesn't contain newlines.)
- 4.1.9. Our descriptor changed
- Syntax:
- "650" SP "DESCCHANGED" CRLF
- [First added in 0.1.2.2-alpha.]
- 4.1.10. Status events
- Status events (STATUS_GENERAL, STATUS_CLIENT, and STATUS_SERVER) are sent
- based on occurrences in the Tor process pertaining to the general state of
- the program. Generally, they correspond to log messages of severity Notice
- or higher. They differ from log messages in that their format is a
- specified interface.
- Syntax:
- "650" SP StatusType SP StatusSeverity SP StatusAction
- [SP StatusArguments] CRLF
- StatusType = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"
- StatusSeverity = "NOTICE" / "WARN" / "ERR"
- StatusAction = 1*ALPHA
- StatusArguments = StatusArgument *(SP StatusArgument)
- StatusArgument = StatusKeyword '=' StatusValue
- StatusKeyword = 1*(ALNUM / "_")
- StatusValue = 1*(ALNUM / '_') / QuotedString
- StatusAction is a string, and StatusArguments is a series of
- keyword=value pairs on the same line. Values may be space-terminated
- strings, or quoted strings.
- These events are always produced with EXTENDED_EVENTS and
- VERBOSE_NAMES; see the explanations in the USEFEATURE section
- for details.
- Controllers MUST tolerate unrecognized actions, MUST tolerate
- unrecognized arguments, MUST tolerate missing arguments, and MUST
- tolerate arguments that arrive in any order.
- Each event description below is accompanied by a recommendation for
- controllers. These recommendations are suggestions only; no controller
- is required to implement them.
- Compatibility note: versions of Tor before 0.2.0.22-rc incorrectly
- generated "STATUS_SERVER" as "STATUS_SEVER". To be compatible with those
- versions, tools should accept both.
- Actions for STATUS_GENERAL events can be as follows:
- CLOCK_JUMPED
- "TIME=NUM"
- Tor spent enough time without CPU cycles that it has closed all
- its circuits and will establish them anew. This typically
- happens when a laptop goes to sleep and then wakes up again. It
- also happens when the system is swapping so heavily that Tor is
- starving. The "time" argument specifies the number of seconds Tor
- thinks it was unconscious for (or alternatively, the number of
- seconds it went back in time).
- This status event is sent as NOTICE severity normally, but WARN
- severity if Tor is acting as a server currently.
- {Recommendation for controller: ignore it, since we don't really
- know what the user should do anyway. Hm.}
- DANGEROUS_VERSION
- "CURRENT=version"
- "REASON=NEW/OBSOLETE/UNRECOMMENDED"
- "RECOMMENDED=\"version, version, ...\""
- Tor has found that directory servers don't recommend its version of
- the Tor software. RECOMMENDED is a comma-and-space-separated string
- of Tor versions that are recommended. REASON is NEW if this version
- of Tor is newer than any recommended version, OBSOLETE if
- this version of Tor is older than any recommended version, and
- UNRECOMMENDED if some recommended versions of Tor are newer and
- some are older than this version. (The "OBSOLETE" reason was called
- "OLD" from Tor 0.1.2.3-alpha up to and including 0.2.0.12-alpha.)
- {Controllers may want to suggest that the user upgrade OLD or
- UNRECOMMENDED versions. NEW versions may be known-insecure, or may
- simply be development versions.}
- TOO_MANY_CONNECTIONS
- "CURRENT=NUM"
- Tor has reached its ulimit -n or whatever the native limit is on file
- descriptors or sockets. CURRENT is the number of sockets Tor
- currently has open. The user should really do something about
- this. The "current" argument shows the number of connections currently
- open.
- {Controllers may recommend that the user increase the limit, or
- increase it for them. Recommendations should be phrased in an
- OS-appropriate way and automated when possible.}
- BUG
- "REASON=STRING"
- Tor has encountered a situation that its developers never expected,
- and the developers would like to learn that it happened. Perhaps
- the controller can explain this to the user and encourage her to
- file a bug report?
- {Controllers should log bugs, but shouldn't annoy the user in case a
- bug appears frequently.}
- CLOCK_SKEW
- SKEW="+" / "-" SECONDS
- MIN_SKEW="+" / "-" SECONDS.
- SOURCE="DIRSERV:" IP ":" Port /
- "NETWORKSTATUS:" IP ":" Port /
- "OR:" IP ":" Port /
- "CONSENSUS"
- If "SKEW" is present, it's an estimate of how far we are from the
- time declared in the source. (In other words, if we're an hour in
- the past, the value is -3600.) "MIN_SKEW" is present, it's a lower
- bound. If the source is a DIRSERV, we got the current time from a
- connection to a dirserver. If the source is a NETWORKSTATUS, we
- decided we're skewed because we got a v2 networkstatus from far in
- the future. If the source is OR, the skew comes from a NETINFO
- cell from a connection to another relay. If the source is
- CONSENSUS, we decided we're skewed because we got a networkstatus
- consensus from the future.
- {Tor should send this message to controllers when it thinks the
- skew is so high that it will interfere with proper Tor operation.
- Controllers shouldn't blindly adjust the clock, since the more
- accurate source of skew info (DIRSERV) is currently
- unauthenticated.}
- BAD_LIBEVENT
- "METHOD=" libevent method
- "VERSION=" libevent version
- "BADNESS=" "BROKEN" / "BUGGY" / "SLOW"
- "RECOVERED=" "NO" / "YES"
- Tor knows about bugs in using the configured event method in this
- version of libevent. "BROKEN" libevents won't work at all;
- "BUGGY" libevents might work okay; "SLOW" libevents will work
- fine, but not quickly. If "RECOVERED" is YES, Tor managed to
- switch to a more reliable (but probably slower!) libevent method.
- {Controllers may want to warn the user if this event occurs, though
- generally it's the fault of whoever built the Tor binary and there's
- not much the user can do besides upgrade libevent or upgrade the
- binary.}
- DIR_ALL_UNREACHABLE
- Tor believes that none of the known directory servers are
- reachable -- this is most likely because the local network is
- down or otherwise not working, and might help to explain for the
- user why Tor appears to be broken.
- {Controllers may want to warn the user if this event occurs; further
- action is generally not possible.}
- CONSENSUS_ARRIVED
- Tor has received and validated a new consensus networkstatus.
- (This event can be delayed a little while after the consensus
- is received, if Tor needs to fetch certificates.)
- Actions for STATUS_CLIENT events can be as follows:
- BOOTSTRAP
- "PROGRESS=" num
- "TAG=" Keyword
- "SUMMARY=" String
- ["WARNING=" String]
- ["REASON=" Keyword]
- ["COUNT=" num]
- ["RECOMMENDATION=" Keyword]
- ["HOST=" QuotedString]
- ["HOSTADDR=" QuotedString]
- Tor has made some progress at establishing a connection to the
- Tor network, fetching directory information, or making its first
- circuit; or it has encountered a problem while bootstrapping. This
- status event is especially useful for users with slow connections
- or with connectivity problems.
- "Progress" gives a number between 0 and 100 for how far through
- the bootstrapping process we are. "Summary" is a string that can
- be displayed to the user to describe the *next* task that Tor
- will tackle, i.e., the task it is working on after sending the
- status event. "Tag" is a string that controllers can use to
- recognize bootstrap phases, if they want to do something smarter
- than just blindly displaying the summary string; see Section 5
- for the current tags that Tor issues.
- The StatusSeverity describes whether this is a normal bootstrap
- phase (severity notice) or an indication of a bootstrapping
- problem (severity warn).
- For bootstrap problems, we include the same progress, tag, and
- summary values as we would for a normal bootstrap event, but we
- also include "warning", "reason", "count", and "recommendation"
- key/value combos. The "count" number tells how many bootstrap
- problems there have been so far at this phase. The "reason"
- string lists one of the reasons allowed in the ORCONN event. The
- "warning" argument string with any hints Tor has to offer about
- why it's having troubles bootstrapping.
- The "reason" values are long-term-stable controller-facing tags to
- identify particular issues in a bootstrapping step. The warning
- strings, on the other hand, are human-readable. Controllers
- SHOULD NOT rely on the format of any warning string. Currently
- the possible values for "recommendation" are either "ignore" or
- "warn" -- if ignore, the controller can accumulate the string in
- a pile of problems to show the user if the user asks; if warn,
- the controller should alert the user that Tor is pretty sure
- there's a bootstrapping problem.
- The "host" value is the identity digest (in hex) of the node we're
- trying to connect to; the "hostaddr" is an address:port combination,
- where 'address' is an ipv4 or ipv6 address.
- Currently Tor uses recommendation=ignore for the first
- nine bootstrap problem reports for a given phase, and then
- uses recommendation=warn for subsequent problems at that
- phase. Hopefully this is a good balance between tolerating
- occasional errors and reporting serious problems quickly.
- ENOUGH_DIR_INFO
- Tor now knows enough network-status documents and enough server
- descriptors that it's going to start trying to build circuits now.
- [Newer versions of Tor (0.2.6.2-alpha and later):
- If the consensus contains Exits (the typical case), Tor will build
- both exit and internal circuits. If not, Tor will only build internal
- circuits.]
- {Controllers may want to use this event to decide when to indicate
- progress to their users, but should not interrupt the user's browsing
- to tell them so.}
- NOT_ENOUGH_DIR_INFO
- We discarded expired statuses and server descriptors to fall
- below the desired threshold of directory information. We won't
- try to build any circuits until ENOUGH_DIR_INFO occurs again.
- {Controllers may want to use this event to decide when to indicate
- progress to their users, but should not interrupt the user's browsing
- to tell them so.}
- CIRCUIT_ESTABLISHED
- Tor is able to establish circuits for client use. This event will
- only be sent if we just built a circuit that changed our mind --
- that is, prior to this event we didn't know whether we could
- establish circuits.
- {Suggested use: controllers can notify their users that Tor is
- ready for use as a client once they see this status event. [Perhaps
- controllers should also have a timeout if too much time passes and
- this event hasn't arrived, to give tips on how to troubleshoot.
- On the other hand, hopefully Tor will send further status events
- if it can identify the problem.]}
- CIRCUIT_NOT_ESTABLISHED
- "REASON=" "EXTERNAL_ADDRESS" / "DIR_ALL_UNREACHABLE" / "CLOCK_JUMPED"
- We are no longer confident that we can build circuits. The "reason"
- keyword provides an explanation: which other status event type caused
- our lack of confidence.
- {Controllers may want to use this event to decide when to indicate
- progress to their users, but should not interrupt the user's browsing
- to do so.}
- [Note: only REASON=CLOCK_JUMPED is implemented currently.]
- DANGEROUS_PORT
- "PORT=" port
- "RESULT=" "REJECT" / "WARN"
- A stream was initiated to a port that's commonly used for
- vulnerable-plaintext protocols. If the Result is "reject", we
- refused the connection; whereas if it's "warn", we allowed it.
- {Controllers should warn their users when this occurs, unless they
- happen to know that the application using Tor is in fact doing so
- correctly (e.g., because it is part of a distributed bundle). They
- might also want some sort of interface to let the user configure
- their RejectPlaintextPorts and WarnPlaintextPorts config options.}
- DANGEROUS_SOCKS
- "PROTOCOL=" "SOCKS4" / "SOCKS5"
- "ADDRESS=" IP:port
- A connection was made to Tor's SOCKS port using one of the SOCKS
- approaches that doesn't support hostnames -- only raw IP addresses.
- If the client application got this address from gethostbyname(),
- it may be leaking target addresses via DNS.
- {Controllers should warn their users when this occurs, unless they
- happen to know that the application using Tor is in fact doing so
- correctly (e.g., because it is part of a distributed bundle).}
- SOCKS_UNKNOWN_PROTOCOL
- "DATA=string"
- A connection was made to Tor's SOCKS port that tried to use it
- for something other than the SOCKS protocol. Perhaps the user is
- using Tor as an HTTP proxy? The DATA is the first few characters
- sent to Tor on the SOCKS port.
- {Controllers may want to warn their users when this occurs: it
- indicates a misconfigured application.}
- SOCKS_BAD_HOSTNAME
- "HOSTNAME=QuotedString"
- Some application gave us a funny-looking hostname. Perhaps
- it is broken? In any case it won't work with Tor and the user
- should know.
- {Controllers may want to warn their users when this occurs: it
- usually indicates a misconfigured application.}
- Actions for STATUS_SERVER can be as follows:
- EXTERNAL_ADDRESS
- "ADDRESS=IP"
- "HOSTNAME=NAME"
- "METHOD=CONFIGURED/DIRSERV/RESOLVED/INTERFACE/GETHOSTNAME"
- Our best idea for our externally visible IP has changed to 'IP'.
- If 'HOSTNAME' is present, we got the new IP by resolving 'NAME'. If the
- method is 'CONFIGURED', the IP was given verbatim as a configuration
- option. If the method is 'RESOLVED', we resolved the Address
- configuration option to get the IP. If the method is 'GETHOSTNAME',
- we resolved our hostname to get the IP. If the method is 'INTERFACE',
- we got the address of one of our network interfaces to get the IP. If
- the method is 'DIRSERV', a directory server told us a guess for what
- our IP might be.
- {Controllers may want to record this info and display it to the user.}
- CHECKING_REACHABILITY
- "ORADDRESS=IP:port"
- "DIRADDRESS=IP:port"
- We're going to start testing the reachability of our external OR port
- or directory port.
- {This event could affect the controller's idea of server status, but
- the controller should not interrupt the user to tell them so.}
- REACHABILITY_SUCCEEDED
- "ORADDRESS=IP:port"
- "DIRADDRESS=IP:port"
- We successfully verified the reachability of our external OR port or
- directory port (depending on which of ORADDRESS or DIRADDRESS is
- given.)
- {This event could affect the controller's idea of server status, but
- the controller should not interrupt the user to tell them so.}
- GOOD_SERVER_DESCRIPTOR
- We successfully uploaded our server descriptor to at least one
- of the directory authorities, with no complaints.
- {Originally, the goal of this event was to declare "every authority
- has accepted the descriptor, so there will be no complaints
- about it." But since some authorities might be offline, it's
- harder to get certainty than we had thought. As such, this event
- is equivalent to ACCEPTED_SERVER_DESCRIPTOR below. Controllers
- should just look at ACCEPTED_SERVER_DESCRIPTOR and should ignore
- this event for now.}
- SERVER_DESCRIPTOR_STATUS
- "STATUS=" "LISTED" / "UNLISTED"
- We just got a new networkstatus consensus, and whether we're in
- it or not in it has changed. Specifically, status is "listed"
- if we're listed in it but previous to this point we didn't know
- we were listed in a consensus; and status is "unlisted" if we
- thought we should have been listed in it (e.g. we were listed in
- the last one), but we're not.
- {Moving from listed to unlisted is not necessarily cause for
- alarm. The relay might have failed a few reachability tests,
- or the Internet might have had some routing problems. So this
- feature is mainly to let relay operators know when their relay
- has successfully been listed in the consensus.}
- [Not implemented yet. We should do this in 0.2.2.x. -RD]
- NAMESERVER_STATUS
- "NS=addr"
- "STATUS=" "UP" / "DOWN"
- "ERR=" message
- One of our nameservers has changed status.
- {This event could affect the controller's idea of server status, but
- the controller should not interrupt the user to tell them so.}
- NAMESERVER_ALL_DOWN
- All of our nameservers have gone down.
- {This is a problem; if it happens often without the nameservers
- coming up again, the user needs to configure more or better
- nameservers.}
- DNS_HIJACKED
- Our DNS provider is providing an address when it should be saying
- "NOTFOUND"; Tor will treat the address as a synonym for "NOTFOUND".
- {This is an annoyance; controllers may want to tell admins that their
- DNS provider is not to be trusted.}
- DNS_USELESS
- Our DNS provider is giving a hijacked address instead of well-known
- websites; Tor will not try to be an exit node.
- {Controllers could warn the admin if the relay is running as an
- exit node: the admin needs to configure a good DNS server.
- Alternatively, this happens a lot in some restrictive environments
- (hotels, universities, coffeeshops) when the user hasn't registered.}
- BAD_SERVER_DESCRIPTOR
- "DIRAUTH=addr:port"
- "REASON=string"
- A directory authority rejected our descriptor. Possible reasons
- include malformed descriptors, incorrect keys, highly skewed clocks,
- and so on.
- {Controllers should warn the admin, and try to cope if they can.}
- ACCEPTED_SERVER_DESCRIPTOR
- "DIRAUTH=addr:port"
- A single directory authority accepted our descriptor.
- // actually notice
- {This event could affect the controller's idea of server status, but
- the controller should not interrupt the user to tell them so.}
- REACHABILITY_FAILED
- "ORADDRESS=IP:port"
- "DIRADDRESS=IP:port"
- We failed to connect to our external OR port or directory port
- successfully.
- {This event could affect the controller's idea of server status. The
- controller should warn the admin and suggest reasonable steps to take.}
- HIBERNATION_STATUS
- "STATUS=" "AWAKE" | "SOFT" | "HARD"
- Our bandwidth based accounting status has changed, and we are now
- relaying traffic/rejecting new connections/hibernating.
- {This event could affect the controller's idea of server status. The
- controller MAY inform the admin, though presumably the accounting was
- explicitly enabled for a reason.}
- [This event was added in tor 0.2.9.0-alpha.]
- 4.1.11. Our set of guard nodes has changed
- Syntax:
- "650" SP "GUARD" SP Type SP Name SP Status ... CRLF
- Type = "ENTRY"
- Name = ServerSpec
- (Identifies the guard affected)
- Status = "NEW" | "UP" | "DOWN" | "BAD" | "GOOD" | "DROPPED"
- The ENTRY type indicates a guard used for connections to the Tor
- network.
- The Status values are:
- "NEW" -- This node was not previously used as a guard; now we have
- picked it as one.
- "DROPPED" -- This node is one we previously picked as a guard; we
- no longer consider it to be a member of our guard list.
- "UP" -- The guard now seems to be reachable.
- "DOWN" -- The guard now seems to be unreachable.
- "BAD" -- Because of flags set in the consensus and/or values in the
- configuration, this node is now unusable as a guard.
- "GOOD" -- Because of flags set in the consensus and/or values in the
- configuration, this node is now usable as a guard.
- Controllers must accept unrecognized types and unrecognized statuses.
- 4.1.12. Network status has changed
- Syntax:
- "650" "+" "NS" CRLF 1*NetworkStatus "." CRLF "650" SP "OK" CRLF
- The event is used whenever our local view of a relay status changes.
- This happens when we get a new v3 consensus (in which case the entries
- we see are a duplicate of what we see in the NEWCONSENSUS event,
- below), but it also happens when we decide to mark a relay as up or
- down in our local status, for example based on connection attempts.
- [First added in 0.1.2.3-alpha]
- 4.1.13. Bandwidth used on an application stream
- The syntax is:
- "650" SP "STREAM_BW" SP StreamID SP BytesWritten SP BytesRead SP
- Time CRLF
- BytesWritten = 1*DIGIT
- BytesRead = 1*DIGIT
- Time = ISOTime2Frac
- BytesWritten and BytesRead are the number of bytes written and read
- by the application since the last STREAM_BW event on this stream.
- Note that from Tor's perspective, *reading* a byte on a stream means
- that the application *wrote* the byte. That's why the order of "written"
- vs "read" is opposite for stream_bw events compared to bw events.
- The Time field is provided only in versions 0.3.2.1-alpha and later. It
- records when Tor created the bandwidth event.
- These events are generated about once per second per stream; no events
- are generated for streams that have not written or read. These events
- apply only to streams entering Tor (such as on a SOCKSPort, TransPort,
- or so on). They are not generated for exiting streams.
- 4.1.14. Per-country client stats
- The syntax is:
- "650" SP "CLIENTS_SEEN" SP TimeStarted SP CountrySummary SP
- IPVersions CRLF
- We just generated a new summary of which countries we've seen clients
- from recently. The controller could display this for the user, e.g.
- in their "relay" configuration window, to give them a sense that they
- are actually being useful.
- Currently only bridge relays will receive this event, but once we figure
- out how to sufficiently aggregate and sanitize the client counts on
- main relays, we might start sending these events in other cases too.
- TimeStarted is a quoted string indicating when the reported summary
- counts from (in UTCS).
- The CountrySummary keyword has as its argument a comma-separated,
- possibly empty set of "countrycode=count" pairs. For example (without
- linebreak),
- 650-CLIENTS_SEEN TimeStarted="2008-12-25 23:50:43"
- CountrySummary=us=16,de=8,uk=8
- The IPVersions keyword has as its argument a comma-separated set of
- "protocol-family=count" pairs. For example,
- IPVersions=v4=16,v6=40
- Note that these values are rounded, not exact. The rounding
- algorithm is specified in the description of "geoip-client-origins"
- in dir-spec.txt.
- 4.1.15. New consensus networkstatus has arrived
- The syntax is:
- "650" "+" "NEWCONSENSUS" CRLF 1*NetworkStatus "." CRLF "650" SP
- "OK" CRLF
- A new consensus networkstatus has arrived. We include NS-style lines for
- every relay in the consensus. NEWCONSENSUS is a separate event from the
- NS event, because the list here represents every usable relay: so any
- relay *not* mentioned in this list is implicitly no longer recommended.
- [First added in 0.2.1.13-alpha]
- 4.1.16. New circuit buildtime has been set
- The syntax is:
- "650" SP "BUILDTIMEOUT_SET" SP Type SP "TOTAL_TIMES=" Total SP
- "TIMEOUT_MS=" Timeout SP "XM=" Xm SP "ALPHA=" Alpha SP
- "CUTOFF_QUANTILE=" Quantile SP "TIMEOUT_RATE=" TimeoutRate SP
- "CLOSE_MS=" CloseTimeout SP "CLOSE_RATE=" CloseRate
- CRLF
- Type = "COMPUTED" / "RESET" / "SUSPENDED" / "DISCARD" / "RESUME"
- Total = Integer count of timeouts stored
- Timeout = Integer timeout in milliseconds
- Xm = Estimated integer Pareto parameter Xm in milliseconds
- Alpha = Estimated floating point Paredo parameter alpha
- Quantile = Floating point CDF quantile cutoff point for this timeout
- TimeoutRate = Floating point ratio of circuits that timeout
- CloseTimeout = How long to keep measurement circs in milliseconds
- CloseRate = Floating point ratio of measurement circuits that are closed
- A new circuit build timeout time has been set. If Type is "COMPUTED",
- Tor has computed the value based on historical data. If Type is "RESET",
- initialization or drastic network changes have caused Tor to reset
- the timeout back to the default, to relearn again. If Type is
- "SUSPENDED", Tor has detected a loss of network connectivity and has
- temporarily changed the timeout value to the default until the network
- recovers. If type is "DISCARD", Tor has decided to discard timeout
- values that likely happened while the network was down. If type is
- "RESUME", Tor has decided to resume timeout calculation.
- The Total value is the count of circuit build times Tor used in
- computing this value. It is capped internally at the maximum number
- of build times Tor stores (NCIRCUITS_TO_OBSERVE).
- The Timeout itself is provided in milliseconds. Internally, Tor rounds
- this value to the nearest second before using it.
- [First added in 0.2.2.7-alpha]
- 4.1.17. Signal received
- The syntax is:
- "650" SP "SIGNAL" SP Signal CRLF
- Signal = "RELOAD" / "DUMP" / "DEBUG" / "NEWNYM" / "CLEARDNSCACHE"
- A signal has been received and actions taken by Tor. The meaning of each
- signal, and the mapping to Unix signals, is as defined in section 3.7.
- Future versions of Tor MAY generate signals other than those listed here;
- controllers MUST be able to accept them.
- If Tor chose to ignore a signal (such as NEWNYM), this event will not be
- sent. Note that some options (like ReloadTorrcOnSIGHUP) may affect the
- semantics of the signals here.
- Note that the HALT (SIGTERM) and SHUTDOWN (SIGINT) signals do not currently
- generate any event.
- [First added in 0.2.3.1-alpha]
- 4.1.18. Configuration changed
- The syntax is:
- StartReplyLine *(MidReplyLine) EndReplyLine
- StartReplyLine = "650-CONF_CHANGED" CRLF
- MidReplyLine = "650-" KEYWORD ["=" VALUE] CRLF
- EndReplyLine = "650 OK"
- Tor configuration options have changed (such as via a SETCONF or RELOAD
- signal). KEYWORD and VALUE specify the configuration option that was changed.
- Undefined configuration options contain only the KEYWORD.
- 4.1.19. Circuit status changed slightly
- The syntax is:
- "650" SP "CIRC_MINOR" SP CircuitID SP CircEvent [SP Path]
- [SP "BUILD_FLAGS=" BuildFlags] [SP "PURPOSE=" Purpose]
- [SP "HS_STATE=" HSState] [SP "REND_QUERY=" HSAddress]
- [SP "TIME_CREATED=" TimeCreated]
- [SP "OLD_PURPOSE=" Purpose [SP "OLD_HS_STATE=" HSState]] CRLF
- CircEvent =
- "PURPOSE_CHANGED" / ; circuit purpose or HS-related state changed
- "CANNIBALIZED" ; circuit cannibalized
- Clients MUST accept circuit events not listed above.
- The "OLD_PURPOSE" field is provided for both PURPOSE_CHANGED and
- CANNIBALIZED events. The "OLD_HS_STATE" field is provided whenever
- the "OLD_PURPOSE" field is provided and is a hidden-service-related
- purpose.
- Other fields are as specified in section 4.1.1 above.
- [First added in 0.2.3.11-alpha]
- 4.1.20. Pluggable transport launched
- The syntax is:
- "650" SP "TRANSPORT_LAUNCHED" SP Type SP Name SP TransportAddress SP Port
- Type = "server" | "client"
- Name = The name of the pluggable transport
- TransportAddress = An IPv4 or IPv6 address on which the pluggable
- transport is listening for connections
- Port = The TCP port on which it is listening for connections.
- A pluggable transport called 'Name' of type 'Type' was launched
- successfully and is now listening for connections on 'Address':'Port'.
- 4.1.21. 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" / ; Carrying traffic within the tor network. This can
- either be our own (client) traffic or traffic we're
- relaying within the network.
- "DIR" / ; Fetching tor descriptor data, or transmitting
- descriptors we're mirroring.
- "EXIT" ; Carrying traffic between the tor network and an
- external destination.
- 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.
- [First added in 0.2.5.2-alpha]
- 4.1.22. Bandwidth used by all streams attached to a circuit
- The syntax is:
- "650" SP "CIRC_BW" SP "ID=" CircuitID SP "READ=" BytesRead SP
- "WRITTEN=" BytesWritten SP "TIME=" Time SP
- "DELIVERED_READ=" DeliveredBytesRead SP
- "OVERHEAD_READ=" OverheadBytesRead SP
- "DELIVERED_WRITTEN=" DeliveredBytesWritten CRLF
- "OVERHEAD_WRITTEN=" OverheadBytesWritten SP
- BytesRead = 1*DIGIT
- BytesWritten = 1*DIGIT
- OverheadBytesRead = 1*DIGIT
- OverheadBytesWritten = 1*DIGIT
- DeliveredBytesRead = 1*DIGIT
- DeliveredBytesWritten = 1*DIGIT
- Time = ISOTime2Frac
- BytesRead and BytesWritten are the number of bytes read and written
- on this circuit since the last CIRC_BW event. These bytes have not
- necessarily been validated by Tor, and can include invalid cells,
- dropped cells, and ignored cells (such as padding cells). These
- values include the relay headers, but not circuit headers.
- Circuit data that has been validated and processed by Tor is further
- broken down into two categories: delivered payloads and overhead.
- DeliveredBytesRead and DeliveredBytesWritten are the total relay cell
- payloads transmitted since the last CIRC_BW event, not counting relay
- cell headers or circuit headers. OverheadBytesRead and
- OverheadBytesWritten are the extra unused bytes at the end of each
- cell in order for it to be the fixed CELL_LEN bytes long.
- The sum of DeliveredBytesRead and OverheadBytesRead MUST be less than
- BytesRead, and the same is true for their written counterparts. This
- sum represents the total relay cell bytes on the circuit that
- have been validated by Tor, not counting relay headers and cell headers.
- Subtracting this sum (plus relay cell headers) from the BytesRead
- (or BytesWritten) value gives the byte count that Tor has decided to
- reject due to protocol errors, or has otherwise decided to ignore.
- The Time field is provided only in versions 0.3.2.1-alpha and later. It
- records when Tor created the bandwidth event.
- These events are generated about once per second per circuit; no events
- are generated for circuits that had no attached stream writing or
- reading.
- [First added in 0.2.5.2-alpha]
- [DELIVERED_READ, OVERHEAD_READ, DELIVERED_WRITTEN, and OVERHEAD_WRITTEN
- were added in Tor 0.3.4.0-alpha]
- 4.1.23. Per-circuit cell stats
- The syntax is:
- "650" SP "CELL_STATS"
- [ SP "ID=" CircuitID ]
- [ SP "InboundQueue=" QueueID SP "InboundConn=" ConnID ]
- [ SP "InboundAdded=" CellsByType ]
- [ SP "InboundRemoved=" CellsByType SP
- "InboundTime=" MsecByType ]
- [ SP "OutboundQueue=" QueueID SP "OutboundConn=" ConnID ]
- [ SP "OutboundAdded=" CellsByType ]
- [ SP "OutboundRemoved=" CellsByType SP
- "OutboundTime=" MsecByType ] CRLF
- CellsByType, MsecByType = CellType ":" 1*DIGIT
- 0*( "," CellType ":" 1*DIGIT )
- CellType = 1*( "a" - "z" / "0" - "9" / "_" )
- Examples are:
- 650 CELL_STATS ID=14 OutboundQueue=19403 OutboundConn=15
- OutboundAdded=create_fast:1,relay_early:2
- OutboundRemoved=create_fast:1,relay_early:2
- OutboundTime=create_fast:0,relay_early:0
- 650 CELL_STATS InboundQueue=19403 InboundConn=32
- InboundAdded=relay:1,created_fast:1
- InboundRemoved=relay:1,created_fast:1
- InboundTime=relay:0,created_fast:0
- OutboundQueue=6710 OutboundConn=18
- OutboundAdded=create:1,relay_early:1
- OutboundRemoved=create:1,relay_early:1
- OutboundTime=create:0,relay_early:0
- ID is the locally unique circuit identifier that is only included if the
- circuit originates at this node.
- Inbound and outbound refer to the direction of cell flow through the
- circuit which is either to origin (inbound) or from origin (outbound).
- InboundQueue and OutboundQueue are identifiers of the inbound and
- outbound circuit queues of this circuit. These identifiers are only
- unique per OR connection. OutboundQueue is chosen by this node and
- matches InboundQueue of the next node in the circuit.
- InboundConn and OutboundConn are locally unique IDs of inbound and
- outbound OR connection. OutboundConn does not necessarily match
- InboundConn of the next node in the circuit.
- InboundQueue and InboundConn are not present if the circuit originates
- at this node. OutboundQueue and OutboundConn are not present if the
- circuit (currently) ends at this node.
- InboundAdded and OutboundAdded are total number of cells by cell type
- added to inbound and outbound queues. Only present if at least one cell
- was added to a queue.
- InboundRemoved and OutboundRemoved are total number of cells by
- cell type processed from inbound and outbound queues. InboundTime and
- OutboundTime are total waiting times in milliseconds of all processed
- cells by cell type. Only present if at least one cell was removed from
- a queue.
- 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.
- [First added in 0.2.5.2-alpha]
- 4.1.24. Token buckets refilled
- The syntax is:
- "650" SP "TB_EMPTY" SP 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
- Examples are:
- 650 TB_EMPTY ORCONN ID=16 READ=0 WRITTEN=0 LAST=100
- 650 TB_EMPTY GLOBAL READ=93 WRITTEN=93 LAST=100
- 650 TB_EMPTY RELAY READ=93 WRITTEN=93 LAST=100
- 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 since the last refill. LastRefill is the
- time in millis since the last refill.
- If a bucket went negative and if refilling tokens didn't make it go
- positive again, there will be multiple consecutive TB_EMPTY events for
- each refill interval during which the bucket contained zero tokens or
- less. In such a case, 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.
- [First added in 0.2.5.2-alpha]
- 4.1.25. HiddenService descriptors
- The syntax is:
- "650" SP "HS_DESC" SP Action SP HSAddress SP AuthType SP HsDir
- [SP DescriptorID] [SP "REASON=" Reason] [SP "REPLICA=" Replica]
- [SP "HSDIR_INDEX=" HSDirIndex]
- Action = "REQUESTED" / "UPLOAD" / "RECEIVED" / "UPLOADED" / "IGNORE" /
- "FAILED" / "CREATED"
- HSAddress = 16*Base32Character / 56*Base32Character / "UNKNOWN"
- AuthType = "NO_AUTH" / "BASIC_AUTH" / "STEALTH_AUTH" / "UNKNOWN"
- HsDir = LongName / Fingerprint / "UNKNOWN"
- DescriptorID = 32*Base32Character / 43*Base64Character
- Reason = "BAD_DESC" / "QUERY_REJECTED" / "UPLOAD_REJECTED" / "NOT_FOUND" /
- "UNEXPECTED" / "QUERY_NO_HSDIR" / "QUERY_RATE_LIMITED"
- Replica = 1*DIGIT
- HSDirIndex = 64*HEXDIG
- These events will be triggered when required HiddenService descriptor is
- not found in the cache and a fetch or upload with the network is performed.
- If the fetch was triggered with only a DescriptorID (using the HSFETCH
- command for instance), the HSAddress only appears in the Action=RECEIVED
- since there is no way to know the HSAddress from the DescriptorID thus
- the value will be "UNKNOWN".
- If we already had the v0 descriptor, the newly fetched v2 descriptor
- will be ignored and a "HS_DESC" event with "IGNORE" action will be
- generated.
- For HsDir, LongName is always preferred. If HsDir cannot be found in node
- list at the time event is sent, Fingerprint will be used instead.
- If Action is "FAILED", Tor SHOULD send Reason field as well. Possible
- values of Reason are:
- - "BAD_DESC" - descriptor was retrieved, but found to be unparsable.
- - "QUERY_REJECTED" - query was rejected by HS directory.
- - "UPLOAD_REJECTED" - descriptor was rejected by HS directory.
- - "NOT_FOUND" - HS descriptor with given identifier was not found.
- - "UNEXPECTED" - nature of failure is unknown.
- - "QUERY_NO_HSDIR" - No suitable HSDir were found for the query.
- - "QUERY_RATE_LIMITED" - query for this service is rate-limited
- For "QUERY_NO_HSDIR" or "QUERY_RATE_LIMITED", the HsDir will be set to
- "UNKNOWN" which was introduced in tor 0.3.1.0-alpha and 0.4.1.0-alpha
- respectively.
- If Action is "CREATED", Tor SHOULD send Replica field as well. The Replica
- field contains the replica number of the generated descriptor. The Replica
- number is specified in rend-spec.txt section 1.3 and determines the
- descriptor ID of the descriptor.
- For hidden service v3, the following applies:
- The "HSDIR_INDEX=" is an optional field that is only for version 3
- which contains the computed index of the HsDir the descriptor was
- uploaded to or fetched from.
- The "DescriptorID" key is the descriptor blinded key used for the index
- value at the "HsDir".
- The "REPLICA=" field is not used for the "CREATED" event because v3
- doesn't use the replica number in the descriptor ID computation.
- Because client authentication is not yet implemented, the "AuthType"
- field is always "NO_AUTH".
- [HS v3 support added 0.3.3.1-alpha]
- 4.1.26. HiddenService descriptors content
- The syntax is:
- "650" "+" "HS_DESC_CONTENT" SP HSAddress SP DescId SP HsDir CRLF
- Descriptor CRLF "." CRLF "650" SP "OK" CRLF
- HSAddress = 16*Base32Character / 56*Base32Character / "UNKNOWN"
- DescId = 32*Base32Character / 32*Base64Character
- HsDir = LongName / "UNKNOWN"
- Descriptor = The text of the descriptor formatted as specified in
- rend-spec.txt section 1.3 (v2) or rend-spec-v3.txt
- section 2.4 (v3) or empty string on failure.
- This event is triggered when a successfully fetched HS descriptor is
- received. The text of that descriptor is then replied. If the HS_DESC
- event is enabled, it is replied just after the RECEIVED action.
- If a fetch fails, the Descriptor is an empty string and HSAddress is set
- to "UNKNOWN". The HS_DESC event should be used to get more information on
- the failed request.
- If the fetch fails for the QUERY_NO_HSDIR or QUERY_RATE_LIMITED reason from
- the HS_DESC event, the HsDir is set to "UNKNOWN". This was introduced in
- 0.3.1.0-alpha and 0.4.1.0-alpha respectively.
- It's expected to receive a reply relatively fast as in it's the time it
- takes to fetch something over the Tor network. This can be between a
- couple of seconds up to 60 seconds (not a hard limit). But, in any cases,
- this event will reply either the descriptor's content or an empty one.
- [HS_DESC_CONTENT was added in Tor 0.2.7.1-alpha]
- [HS v3 support added 0.3.3.1-alpha]
- 4.1.27. Network liveness has changed
- Syntax:
- "650" SP "NETWORK_LIVENESS" SP Status CRLF
- Status = "UP" / ; The network now seems to be reachable.
- "DOWN" / ; The network now seems to be unreachable.
- Controllers MUST tolerate unrecognized status types.
- [NETWORK_LIVENESS was added in Tor 0.2.7.2-alpha]
- 4.1.28. Pluggable Transport Logs
- Syntax:
- "650" SP "PT_LOG" SP PT=Program SP Message
- Program = The program path as defined in the *TransportPlugin
- configuration option. Tor accepts relative and full path.
- Message = The log message that the PT sends back to the tor parent
- process minus the "LOG" string prefix. Formatted as
- specified in pt-spec.txt section 3.3.4.
- This event is triggered when tor receives a log message from the PT.
- Example:
- PT (obfs4): LOG SEVERITY=debug MESSAGE="Connected to bridge A"
- the resulting control port event would be:
- Tor: 650 PT_LOG PT=/usr/bin/obs4proxy SEVERITY=debug MESSAGE="Connected to bridge A"
- [PT_LOG was added in Tor 0.4.0.1-alpha]
- 4.1.29. Pluggable Transport Status
- Syntax:
- "650" SP "PT_STATUS" SP PT=Program SP TRANSPORT=Transport SP Message
- Program = The program path as defined in the *TransportPlugin
- configuration option. Tor accepts relative and full path.
- Transport = This value indicate a hint on what the PT is such has the
- name or the protocol used for instance.
- Message = The status message that the PT sends back to the tor parent
- process minus the "STATUS" string prefix. Formatted as
- specified in pt-spec.txt section 3.3.5.
- This event is triggered when tor receives a log message from the PT.
- Example:
- PT (obfs4): STATUS TRANSPORT=obfs4 CONNECT=Success
- the resulting control port event would be:
- Tor: 650 PT_STATUS PT=/usr/bin/obs4proxy TRANSPORT=obfs4 CONNECT=Success
- [PT_STATUS was added in Tor 0.4.0.1-alpha]
- 5. Implementation notes
- 5.1. Authentication
- If the control port is open and no authentication operation is enabled, Tor
- trusts any local user that connects to the control port. This is generally
- a poor idea.
- If the 'CookieAuthentication' option is true, Tor writes a "magic
- cookie" file named "control_auth_cookie" into its data directory (or
- to another file specified in the 'CookieAuthFile' option). To
- authenticate, the controller must demonstrate that it can read the
- contents of the cookie file:
- * Current versions of Tor support cookie authentication
- using the "COOKIE" authentication method: the controller sends the
- contents of the cookie file, encoded in hexadecimal. This
- authentication method exposes the user running a controller to an
- unintended information disclosure attack whenever the controller
- has greater filesystem read access than the process that it has
- connected to. (Note that a controller may connect to a process
- other than Tor.) It is almost never safe to use, even if the
- controller's user has explicitly specified which filename to read
- an authentication cookie from. For this reason, the COOKIE
- authentication method has been deprecated and will be removed from
- Tor before some future version of Tor.
- * 0.2.2.x versions of Tor starting with 0.2.2.36, and all versions of
- Tor after 0.2.3.12-alpha, support cookie authentication using the
- "SAFECOOKIE" authentication method, which discloses much less
- information about the contents of the cookie file.
- If the 'HashedControlPassword' option is set, it must contain the salted
- hash of a secret password. The salted hash is computed according to the
- S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier.
- This is then encoded in hexadecimal, prefixed by the indicator sequence
- "16:". Thus, for example, the password 'foo' could encode to:
- 16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2
- ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- salt hashed value
- indicator
- You can generate the salt of a password by calling
- 'tor --hash-password <password>'
- or by using the example code in the Python and Java controller libraries.
- To authenticate under this scheme, the controller sends Tor the original
- secret that was used to generate the password, either as a quoted string
- or encoded in hexadecimal.
- 5.2. Don't let the buffer get too big.
- With old versions of Tor (before 0.2.0.16-alpha), if you ask for
- lots of events, and 16MB of them queue up on the buffer, the Tor
- process will close the socket.
- Newer Tor versions do not have this 16 MB buffer limit. However,
- if you leave huge numbers of events unread, Tor may still run out
- of memory, so you should still be careful about buffer size.
- 5.3. Backward compatibility with v0 control protocol.
- The 'version 0' control protocol was replaced in Tor 0.1.1.x. Support
- was removed in Tor 0.2.0.x. Every non-obsolete version of Tor now
- supports the version 1 control protocol.
- For backward compatibility with the "version 0" control protocol,
- Tor used to check whether the third octet of the first command is zero.
- (If it was, Tor assumed that version 0 is in use.)
- This compatibility was removed in Tor 0.1.2.16 and 0.2.0.4-alpha.
- 5.4. Tor config options for use by controllers
- Tor provides a few special configuration options for use by controllers.
- These options are not saved to disk by SAVECONF. Most can be set and
- examined by the SETCONF and GETCONF commands, but some (noted below) can
- only be given in a torrc file or on the command line.
- Generally, these options make Tor unusable by disabling a portion of Tor's
- normal operations. Unless a controller provides replacement functionality
- to fill this gap, Tor will not correctly handle user requests.
- __AllDirActionsPrivate
- If true, Tor will try to launch all directory operations through
- anonymous connections. (Ordinarily, Tor only tries to anonymize
- requests related to hidden services.) This option will slow down
- directory access, and may stop Tor from working entirely if it does not
- yet have enough directory information to build circuits.
- (Boolean. Default: "0".)
- __DisablePredictedCircuits
- If true, Tor will not launch preemptive "general-purpose" circuits for
- streams to attach to. (It will still launch circuits for testing and
- for hidden services.)
- (Boolean. Default: "0".)
- __LeaveStreamsUnattached
- If true, Tor will not automatically attach new streams to circuits;
- instead, the controller must attach them with ATTACHSTREAM. If the
- controller does not attach the streams, their data will never be routed.
- (Boolean. Default: "0".)
- __HashedControlSessionPassword
- As HashedControlPassword, but is not saved to the torrc file by
- SAVECONF. Added in Tor 0.2.0.20-rc.
- __ReloadTorrcOnSIGHUP
- If this option is true (the default), we reload the torrc from disk
- every time we get a SIGHUP (from the controller or via a signal).
- Otherwise, we don't. This option exists so that controllers can keep
- their options from getting overwritten when a user sends Tor a HUP for
- some other reason (for example, to rotate the logs).
- (Boolean. Default: "1")
- __OwningControllerProcess
- If this option is set to a process ID, Tor will periodically check
- whether a process with the specified PID exists, and exit if one
- does not. Added in Tor 0.2.2.28-beta. This option's intended use
- is documented in section 3.23 with the related TAKEOWNERSHIP
- command.
- Note that this option can only specify a single process ID, unlike
- the TAKEOWNERSHIP command which can be sent along multiple control
- connections.
- (String. Default: unset.)
- __OwningControllerFD
- If this option is a valid socket, Tor will start with an open control
- connection on this socket. Added in Tor 0.3.3.1-alpha.
- This socket will be an owning controller, as if it had already called
- TAKEOWNERSHIP. It will be automatically authenticated. This option
- should only be used by other programs that are starting Tor.
- This option cannot be changed via SETCONF; it must be set in a torrc or
- via the command line.
- (Integer. Default: -1.)
- __DisableSignalHandlers
- If this option is set to true during startup, then Tor will not install
- any signal handlers to watch for POSIX signals. The SIGNAL controller
- command will still work.
- This option is meant for embedding Tor inside another process, when
- the controlling process would rather handle signals on its own.
- This option cannot be changed via SETCONF; it must be set in a torrc or
- via the command line.
- (Boolean. Default: 0.)
- 5.5. Phases from the Bootstrap status event.
- [For the bootstrap phases reported by Tor prior to 0.4.0.x, see
- Section 5.6.]
- This section describes the various bootstrap phases currently reported
- by Tor. Controllers should not assume that the percentages and tags
- listed here will continue to match up, or even that the tags will stay
- in the same order. Some phases might also be skipped (not reported)
- if the associated bootstrap step is already complete, or if the phase
- no longer is necessary. Only "starting" and "done" are guaranteed to
- exist in all future versions.
- Current Tor versions enter these phases in order, monotonically.
- Future Tors MAY revisit earlier phases, for example, if the network
- fails.
- 5.5.1. Overview of Bootstrap reporting.
- Bootstrap phases can be viewed as belonging to one of three stages:
- 1. Initial connection to a Tor relay or bridge
- 2. Obtaining directory information
- 3. Building an application circuit
- Tor doesn't specifically enter Stage 1; that is a side effect of
- other actions that Tor is taking. Tor could be making a connection
- to a fallback directory server, or it could be making a connection
- to a guard candidate. Either one counts as Stage 1 for the purposes
- of bootstrap reporting.
- Stage 2 might involve Tor contacting directory servers, or it might
- involve reading cached directory information from a previous
- session. Large parts of Stage 2 might be skipped if there is already
- enough cached directory information to build circuits. Tor will
- defer reporting progress in Stage 2 until Stage 1 is complete.
- Tor defers this reporting because Tor can already have enough
- directory information to build circuits, yet not be able to connect
- to a relay. Without that deferral, a user might misleadingly see Tor
- stuck at a large amount of progress when something as fundamental as
- making a TCP connection to any relay is failing.
- Tor also doesn't specifically enter Stage 3; that is a side effect
- of Tor building circuits for some purpose or other. In a typical
- client, Tor builds predicted circuits to provide lower latency for
- application connection requests. In Stage 3, Tor might make new
- connections to relays or bridges that it did not connect to in Stage
- 1.
- 5.5.2. Phases in Bootstrap Stage 1.
- Phase 0:
- tag=starting summary="Starting"
- Tor starts out in this phase.
- Phase 1:
- tag=conn_pt summary="Connecting to pluggable transport"
- [This phase is new in 0.4.0.x]
- Tor is making a TCP connection to the transport plugin for a
- pluggable transport. Tor will use this pluggable transport to make
- its first connection to a bridge.
- Phase 2:
- tag=conn_done_pt summary="Connected to pluggable transport"
- [New in 0.4.0.x]
- Tor has completed its TCP connection to the transport plugin for the
- pluggable transport.
- Phase 3:
- tag=conn_proxy summary="Connecting to proxy"
- [New in 0.4.0.x]
- Tor is making a TCP connection to a proxy to make its first
- connection to a relay or bridge.
- Phase 4:
- tag=conn_done_proxy summary="Connected to proxy"
- [New in 0.4.0.x]
- Tor has completed its TCP connection to a proxy to make its first
- connection to a relay or bridge.
- Phase 5:
- tag=conn summary="Connecting to a relay"
- [New in 0.4.0.x; prior versions of Tor had a "conn_dir" phase that
- sometimes but not always corresponded to connecting to a directory server]
- Tor is making its first connection to a relay. This might be through
- a pluggable transport or proxy connection that Tor has already
- established.
- Phase 10:
- tag=conn_done summary="Connected to a relay"
- [New in 0.4.0.x]
- Tor has completed its first connection to a relay.
- Phase 14:
- tag=handshake summary="Handshaking with a relay"
- [New in 0.4.0.x; prior versions of Tor had a "handshake_dir" phase]
- Tor is in the process of doing a TLS handshake with a relay.
- Phase 15:
- tag=handshake_done summary="Handshake with a relay done"
- [New in 0.4.0.x]
- Tor has completed its TLS handshake with a relay.
- 5.5.3. Phases in Bootstrap Stage 2.
- Phase 20:
- tag=onehop_create summary="Establishing an encrypted directory connection"
- [prior to 0.4.0.x, this was numbered 15]
- Once TLS is finished with a relay, Tor will send a CREATE_FAST cell
- to establish a one-hop circuit for retrieving directory information.
- It will remain in this phase until it receives the CREATED_FAST cell
- back, indicating that the circuit is ready.
- Phase 25:
- tag=requesting_status summary="Asking for networkstatus consensus"
- [prior to 0.4.0.x, this was numbered 20]
- Once we've finished our one-hop circuit, we will start a new stream
- for fetching the networkstatus consensus. We'll stay in this phase
- until we get the 'connected' relay cell back, indicating that we've
- established a directory connection.
- Phase 30:
- tag=loading_status summary="Loading networkstatus consensus"
- [prior to 0.4.0.x, this was numbered 25]
- Once we've established a directory connection, we will start fetching
- the networkstatus consensus document. This could take a while; this
- phase is a good opportunity for using the "progress" keyword to indicate
- partial progress.
- This phase could stall if the directory server we picked doesn't
- have a copy of the networkstatus consensus so we have to ask another,
- or it does give us a copy but we don't find it valid.
- Phase 40:
- tag=loading_keys summary="Loading authority key certs"
- Sometimes when we've finished loading the networkstatus consensus,
- we find that we don't have all the authority key certificates for the
- keys that signed the consensus. At that point we put the consensus we
- fetched on hold and fetch the keys so we can verify the signatures.
- Phase 45
- tag=requesting_descriptors summary="Asking for relay descriptors"
- Once we have a valid networkstatus consensus and we've checked all
- its signatures, we start asking for relay descriptors. We stay in this
- phase until we have received a 'connected' relay cell in response to
- a request for descriptors.
- [Some versions of Tor (starting with 0.2.6.2-alpha but before
- 0.4.0.x): Tor could report having internal paths only; see Section
- 5.6]
- Phase 50:
- tag=loading_descriptors summary="Loading relay descriptors"
- We will ask for relay descriptors from several different locations,
- so this step will probably make up the bulk of the bootstrapping,
- especially for users with slow connections. We stay in this phase until
- we have descriptors for a significant fraction of the usable relays
- listed in the networkstatus consensus (this can be between 25% and 95%
- depending on Tor's configuration and network consensus parameters).
- This phase is also a good opportunity to use the "progress" keyword to
- indicate partial steps.
- [Some versions of Tor (starting with 0.2.6.2-alpha but before
- 0.4.0.x): Tor could report having internal paths only; see Section
- 5.6]
- Phase 75:
- tag=enough_dirinfo summary="Loaded enough directory info to build
- circuits"
- [New in 0.4.0.x; previously, Tor would misleadingly report the
- "conn_or" tag once it had enough directory info.]
- 5.5.4. Phases in Bootstrap Stage 3.
- Phase 76:
- tag=ap_conn_pt summary="Connecting to pluggable transport to build
- circuits"
- [New in 0.4.0.x]
- This is similar to conn_pt, except for making connections to
- additional relays or bridges that Tor needs to use to build
- application circuits.
- Phase 77:
- tag=ap_conn_done_pt summary="Connected to pluggable transport to build circuits"
- [New in 0.4.0.x]
- This is similar to conn_done_pt, except for making connections to
- additional relays or bridges that Tor needs to use to build
- application circuits.
- Phase 78:
- tag=ap_conn_proxy summary="Connecting to proxy to build circuits"
- [New in 0.4.0.x]
- This is similar to conn_proxy, except for making connections to
- additional relays or bridges that Tor needs to use to build
- application circuits.
- Phase 79:
- tag=ap_conn_done_proxy summary="Connected to proxy to build circuits"
- [New in 0.4.0.x]
- This is similar to conn_done_proxy, except for making connections to
- additional relays or bridges that Tor needs to use to build
- application circuits.
- Phase 80:
- tag=ap_conn summary="Connecting to a relay to build circuits"
- [New in 0.4.0.x]
- This is similar to conn, except for making connections to additional
- relays or bridges that Tor needs to use to build application
- circuits.
- Phase 85:
- tag=ap_conn_done summary="Connected to a relay to build circuits"
- [New in 0.4.0.x]
- This is similar to conn_done, except for making connections to
- additional relays or bridges that Tor needs to use to build
- application circuits.
- Phase 89:
- tag=ap_handshake summary="Finishing handshake with a relay to build circuits"
- [New in 0.4.0.x]
- This is similar to handshake, except for making connections to
- additional relays or bridges that Tor needs to use to build
- application circuits.
- Phase 90:
- tag=ap_handshake_done summary="Handshake finished with a relay to build circuits"
- [New in 0.4.0.x]
- This is similar to handshake_done, except for making connections to
- additional relays or bridges that Tor needs to use to build
- application circuits.
- Phase 95:
- tag=circuit_create summary="Establishing a[n internal] Tor circuit"
- [prior to 0.4.0.x, this was numbered 90]
- Once we've finished our TLS handshake with the first hop of a circuit,
- we will set about trying to make some 3-hop circuits in case we need them
- soon.
- [Some versions of Tor (starting with 0.2.6.2-alpha but before
- 0.4.0.x): Tor could report having internal paths only; see Section
- 5.6]
- Phase 100:
- tag=done summary="Done"
- A full 3-hop circuit has been established. Tor is ready to handle
- application connections now.
- [Some versions of Tor (starting with 0.2.6.2-alpha but before
- 0.4.0.x): Tor could report having internal paths only; see Section
- 5.6]
- 5.6 Bootstrap phases reported by older versions of Tor
- These phases were reported by Tor older than 0.4.0.x. For newer
- versions of Tor, see Section 5.5.
- [Newer versions of Tor (0.2.6.2-alpha and later):
- If the consensus contains Exits (the typical case), Tor will build both
- exit and internal circuits. When bootstrap completes, Tor will be ready
- to handle an application requesting an exit circuit to services like the
- World Wide Web.
- If the consensus does not contain Exits, Tor will only build internal
- circuits. In this case, earlier statuses will have included "internal"
- as indicated above. When bootstrap completes, Tor will be ready to handle
- an application requesting an internal circuit to hidden services at
- ".onion" addresses.
- If a future consensus contains Exits, exit circuits may become available.]
- Phase 0:
- tag=starting summary="Starting"
- Tor starts out in this phase.
- Phase 5:
- tag=conn_dir summary="Connecting to directory server"
- Tor sends this event as soon as Tor has chosen a directory server --
- e.g. one of the authorities if bootstrapping for the first time or
- after a long downtime, or one of the relays listed in its cached
- directory information otherwise.
- Tor will stay at this phase until it has successfully established
- a TCP connection with some directory server. Problems in this phase
- generally happen because Tor doesn't have a network connection, or
- because the local firewall is dropping SYN packets.
- Phase 10:
- tag=handshake_dir summary="Finishing handshake with directory server"
- This event occurs when Tor establishes a TCP connection with a relay or
- authority used as a directory server (or its https proxy if it's using
- one). Tor remains in this phase until the TLS handshake with the relay
- or authority is finished.
- Problems in this phase generally happen because Tor's firewall is
- doing more sophisticated MITM attacks on it, or doing packet-level
- keyword recognition of Tor's handshake.
- Phase 15:
- tag=onehop_create summary="Establishing an encrypted directory connection"
- Once TLS is finished with a relay, Tor will send a CREATE_FAST cell
- to establish a one-hop circuit for retrieving directory information.
- It will remain in this phase until it receives the CREATED_FAST cell
- back, indicating that the circuit is ready.
- Phase 20:
- tag=requesting_status summary="Asking for networkstatus consensus"
- Once we've finished our one-hop circuit, we will start a new stream
- for fetching the networkstatus consensus. We'll stay in this phase
- until we get the 'connected' relay cell back, indicating that we've
- established a directory connection.
- Phase 25:
- tag=loading_status summary="Loading networkstatus consensus"
- Once we've established a directory connection, we will start fetching
- the networkstatus consensus document. This could take a while; this
- phase is a good opportunity for using the "progress" keyword to indicate
- partial progress.
- This phase could stall if the directory server we picked doesn't
- have a copy of the networkstatus consensus so we have to ask another,
- or it does give us a copy but we don't find it valid.
- Phase 40:
- tag=loading_keys summary="Loading authority key certs"
- Sometimes when we've finished loading the networkstatus consensus,
- we find that we don't have all the authority key certificates for the
- keys that signed the consensus. At that point we put the consensus we
- fetched on hold and fetch the keys so we can verify the signatures.
- Phase 45
- tag=requesting_descriptors summary="Asking for relay descriptors
- [ for internal paths]"
- Once we have a valid networkstatus consensus and we've checked all
- its signatures, we start asking for relay descriptors. We stay in this
- phase until we have received a 'connected' relay cell in response to
- a request for descriptors.
- [Newer versions of Tor (0.2.6.2-alpha and later):
- If the consensus contains Exits (the typical case), Tor will ask for
- descriptors for both exit and internal paths. If not, Tor will only ask
- for descriptors for internal paths. In this case, this status will
- include "internal" as indicated above.]
- Phase 50:
- tag=loading_descriptors summary="Loading relay descriptors[ for internal
- paths]"
- We will ask for relay descriptors from several different locations,
- so this step will probably make up the bulk of the bootstrapping,
- especially for users with slow connections. We stay in this phase until
- we have descriptors for a significant fraction of the usable relays
- listed in the networkstatus consensus (this can be between 25% and 95%
- depending on Tor's configuration and network consensus parameters).
- This phase is also a good opportunity to use the "progress" keyword to
- indicate partial steps.
- [Newer versions of Tor (0.2.6.2-alpha and later):
- If the consensus contains Exits (the typical case), Tor will download
- descriptors for both exit and internal paths. If not, Tor will only
- download descriptors for internal paths. In this case, this status will
- include "internal" as indicated above.]
- Phase 80:
- tag=conn_or summary="Connecting to the Tor network[ internally]"
- Once we have a valid consensus and enough relay descriptors, we choose
- entry guard(s) and start trying to build some circuits. This step
- is similar to the "conn_dir" phase above; the only difference is
- the context.
- If a Tor starts with enough recent cached directory information,
- its first bootstrap status event will be for the conn_or phase.
- [Newer versions of Tor (0.2.6.2-alpha and later):
- If the consensus contains Exits (the typical case), Tor will build both
- exit and internal circuits. If not, Tor will only build internal circuits.
- In this case, this status will include "internal(ly)" as indicated above.]
- Phase 85:
- tag=handshake_or summary="Finishing handshake with first hop[ of internal
- circuit]"
- This phase is similar to the "handshake_dir" phase, but it gets reached
- if we finish a TCP connection to a Tor relay and we have already reached
- the "conn_or" phase. We'll stay in this phase until we complete a TLS
- handshake with a Tor relay.
- [Newer versions of Tor (0.2.6.2-alpha and later):
- If the consensus contains Exits (the typical case), Tor may be finishing
- a handshake with the first hop if either an exit or internal circuit. In
- this case, it won't specify which type. If the consensus contains no Exits,
- Tor will only build internal circuits. In this case, this status will
- include "internal" as indicated above.]
- Phase 90:
- tag=circuit_create summary="Establishing a[n internal] Tor circuit"
- Once we've finished our TLS handshake with the first hop of a circuit,
- we will set about trying to make some 3-hop circuits in case we need them
- soon.
- [Newer versions of Tor (0.2.6.2-alpha and later):
- If the consensus contains Exits (the typical case), Tor will build both
- exit and internal circuits. If not, Tor will only build internal circuits.
- In this case, this status will include "internal" as indicated above.]
- Phase 100:
- tag=done summary="Done"
- A full 3-hop circuit has been established. Tor is ready to handle
- application connections now.
- [Newer versions of Tor (0.2.6.2-alpha and later):
- If the consensus contains Exits (the typical case), Tor will build both
- exit and internal circuits. At this stage, Tor will be ready to handle
- an application requesting an exit circuit to services like the World
- Wide Web.
- If the consensus does not contain Exits, Tor will only build internal
- circuits. In this case, earlier statuses will have included "internal"
- as indicated above. At this stage, Tor will be ready to handle an
- application requesting an internal circuit to hidden services at ".onion"
- addresses.
- If a future consensus contains Exits, exit circuits may become available.]
|