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