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