torrc_format.txt 6.3 KB

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