torrc_format.txt 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213
  1. This document specifies the current format and semantics of the torrc
  2. file, as of July 2015. Note that we make no guarantee about the
  3. stability of this format. If you write something designed for strict
  4. compatibility with this document, please expect us to break it sooner or
  5. later.
  6. Yes, some of this is quite stupid. My goal here is to explain what it
  7. does, not what it should do.
  8. - Nick
  9. 1. File Syntax
  10. ; The syntax here is defined an Augmented Backus-Naur form, as
  11. ; specified in RFC5234.
  12. ; A file is interpreted as every Entry in the file, in order.
  13. TorrcFile = *Line [ UnterminatedLine ]
  14. Line = BlankLine LF / Entry LF
  15. UnterminatedLine = BlankLine / Entry
  16. BlankLine = *WSP OptComment LF
  17. BlankLine =/ *WSP LF
  18. OptComment = [ Comment ]
  19. Comment = "#" *NonLF
  20. ; Each Entry is interpreted as an optional "Magic" flag, a key, and a
  21. ; value.
  22. Entry = *WSP [ Magic ] Key 1*(1*WSP / "\" NL *WSP) Val LF
  23. Entry =/ *WSP [ Magic ] Key *( *WSP / "\" NL *WSP) LF
  24. Magic = "+" / "/"
  25. ; Keys are always specified verbatim. They are case insensitive. It
  26. ; is an error to specify a key that Tor does not recognize.
  27. Key = 1*KC
  28. ; Sadly, every kind of value is decoded differently...
  29. Val = QuotedVal / ContinuedVal / PlainVal
  30. ; The text of a PlainVal is the text of its PVBody portion,
  31. ; plus the optional trailing backslash.
  32. PlainVal = PVBody [ "\" ] *WSP OptComment
  33. ; Note that a PVBody is copied verbatim. Slashes are included
  34. ; verbatim. No changes are made. Note that a body may be empty.
  35. PVBody = * (VC / "\" NonLF )
  36. ; The text of a ContinuedVal is the text of each of its PVBody
  37. ; sub-elements, in order, concatenated.
  38. ContinuedVal = CVal1 *CVal2 CVal3
  39. CVal1 = PVBody "\" LF
  40. CVal2 = PVBody ( "\" LF / Comment LF )
  41. CVal3 = PVBody
  42. ; The text of a QuotedVal is decoded as if it were a C string.
  43. QuotedVal = DQ QVBody DQ *WSP Comment
  44. QVBody = QC
  45. QVBody =/ "\" ( "n" / "r" / "t" / "\" / "'" / DQUOTE )
  46. QVBOdy =/ "\" ( "x" 2HEXDIG / 1*3OCTDIG )
  47. ; Anything besides NUL and LF
  48. NonLF = %x01-%x09 / %x0b - %xff
  49. ; Note that on windows, we open our configuration files in "text" mode,
  50. ; which causes CRLF pairs to be interpreted as LF. So, on windows:
  51. ; LF = [ %x0d ] %x0a
  52. ; but everywhere else,
  53. LF = %0x0a
  54. OCTDIG = '0' - '7'
  55. KC = Any character except an isspace() character or '#' or NUL
  56. VC = Any character except '\\', '\n', '#', or NUL
  57. QC = Any character except '\n', '\\', '\"', or NUL
  58. 2. Mid-level Semantics
  59. There are four configuration "domains", from lowest to highest priority:
  60. * Built-in defaults
  61. * The "torrc_defaults" file, if any
  62. * The "torrc" file, if any
  63. * Arguments provided on the command line, if any.
  64. Normally, values from high-priority domains override low-priority
  65. domains, but see 'magic' below.
  66. Configuration keys fall into three categories: singletons, lists, and
  67. groups.
  68. A singleton key may appear at most once in any domain. Its
  69. corresponding value is equal to its value in the highest-priority
  70. domain in which it occurs.
  71. A list key may appear any number of times in a domain. By default,
  72. its corresponding value is equal to all of the values specified for
  73. it in the highest-priority domain in which it appears. (See 'magic'
  74. below).
  75. A group key may appear any number of times in a domain. It is
  76. associated with a number of other keys in the same group. The
  77. relative positions of entries with the keys in a single group
  78. matters, but entries with keys not in the group may be freely
  79. interspersed. By default, the group has a value equal to all keys
  80. and values it contains, from the highest-priority domain in which any
  81. of its keys occurs.
  82. Magic:
  83. If the '/' flag is specified for an entry, it sets the value for
  84. that entry to an empty list. (This will cause a higher-priority
  85. domain to clear a list from a lower-priority domain, without
  86. actually adding any entries.)
  87. If the '+' flag is specified for the first entry in a list or a
  88. group that appears in a given domain, that list or group is
  89. appended to the list or group from the next-lowest-priority
  90. domain, rather than replacing it.
  91. 3. High-level semantics
  92. There are further constraints on the values that each entry can take.
  93. These constraints are out-of-scope for this document.
  94. 4. Examples
  95. (Indentation is removed in this section, to avoid confusion.)
  96. 4.1. Syntax examples
  97. # Here is a simple configuration entry. The key is "Foo"; the value is
  98. # "Bar"
  99. Foo Bar
  100. # A configuration entry can have spaces in its value, as below. Here the
  101. # key is "Foo" and the value is "Bar Baz"
  102. Foo Bar Baz
  103. # This configuration entry has space at the end of the line, but those
  104. # spaces don't count, so the key and value are still "Foo" and "Bar Baz"
  105. Foo Bar Baz
  106. # There can be an escaped newline between the value and the key. This
  107. # is another way to say key="Hello", value="World"
  108. Hello\
  109. World
  110. # In regular entries of this kind, you can have a comment at the end of
  111. # the line, either with a space before it or not. Each of these is a
  112. # different spelling of key="Hello", value="World"
  113. Hello World #today
  114. Hello World#tomorrow
  115. # One way to encode a complex entry is as a C string. This is the same
  116. # as key="Hello", value="World!"
  117. Hello "World!"
  118. # The string can contain the usual set of C escapes. This entry has
  119. # key="Hello", and value="\"World\"\nand\nuniverse"
  120. Hello "\"World\"\nand\nuniverse"
  121. # And now we get to the more-or-less awful part.
  122. #
  123. # Multi-line entries ending with a backslash on each line aren't so
  124. # bad. The backslash is removed, and everything else is included
  125. # verbatim. So this entry has key="Hello" and value="Worldandfriends"
  126. Hello\
  127. World\
  128. and\
  129. friends
  130. # Backslashes in the middle of a line are included as-is. The key of
  131. # this one is "Too" and the value is "Many\\Backsl\ashes \here" (with
  132. # backslashes in that last string as-is)
  133. Too \
  134. Many\\\
  135. Backsl\ashes \\
  136. here
  137. # And here's the really yucky part. If a comment appears in a multi-line
  138. # entry, the entry is still able to continue on the next line, as in the
  139. # following, where the key is "This" and the value is
  140. # "entry and some are silly"
  141. This entry \
  142. # has comments \
  143. and some \
  144. are # generally \
  145. silly
  146. # But you can also write that without the backslashes at the end of the
  147. # comment lines. That is to say, this entry is exactly the same as the
  148. # one above!
  149. This entry \
  150. # has comments
  151. and some \
  152. are # generally
  153. silly