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
8 Yes, some of this is quite stupid. My goal here is to explain what it
9 does, not what it should do.
17 ; The syntax here is defined an Augmented Backus-Naur form, as
18 ; specified in RFC5234.
20 ; A file is interpreted as every Entry in the file, in order.
23 Line = BlankLine / Entry
25 BlankLine = *WSP OptComment LF
28 OptComment = [ Comment ]
32 ; Each Entry is interpreted as an optional "Magic" flag, a key, and a
34 Entry = *WSP [ Magic ] Key 1*(1*WSP / "\" NL *WSP) Val LF
35 Entry =/ *WSP [ Magic ] Key *( *WSP / "\" NL *WSP) LF
39 ; Keys are always specified verbatim. They are case insensitive. It
40 ; is an error to specify a key that Tor does not recognize.
43 ; Sadly, every kind of value is decoded differently...
44 Val = QuotedVal / ContinuedVal / PlainVal
46 ; The text of a PlainVal is the text of its PVBody portion,
47 ; plus the optional trailing backslash.
48 PlainVal = PVBody [ "\" ] *WSP OptComment
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 )
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
59 CVal2 = PVBody ( "\" LF / Comment LF )
62 ; The text of a QuotedVal is decoded as if it were a C string.
63 QuotedVal = DQ QVBody DQ *WSP Comment
66 QVBody =/ "\" ( "n" / "r" / "t" / "\" / "'" / DQUOTE )
67 QVBOdy =/ "\" ( "x" 2HEXDIG / 1*3OCTDIG )
69 ; Anything besides NUL and LF
70 NonLF = %x01-%x09 / %x0b - %xff
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
78 2. Mid-level Semantics
81 There are four configuration "domains", from lowest to highest priority:
84 * The "torrc_defaults" file, if any
85 * The "torrc" file, if any
86 * Arguments provided on the command line, if any.
88 Normally, values from high-priority domains override low-priority
89 domains, but see 'magic' below.
91 Configuration keys fall into three categories: singletons, lists, and
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.
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'
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
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.)
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.
123 3. High-level semantics
125 There are further constraints on the values that each entry can take.
126 These constraints are out-of-scope for this document.
130 (Indentation is removed in this section, to avoid confusion.)
134 # Here is a simple configuration entry. The key is "Foo"; the value is
139 # A configuration entry can have spaces in its value, as below. Here the
140 # key is "Foo" and the value is "Bar Baz"
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"
147 # There can be an escaped newline between the value and the key. This
148 # is another way to say key="Hello", value="World"
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"
159 # One way to encode a complex entry is as a C string. This is the same
160 # as key="Hello", value="World!"
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"
167 # And now we get to the more-or-less awful part.
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"
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)
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"
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