doc/torrc_format.txt

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