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