1CSV2_TXT(5)                    MaraDNS reference                   CSV2_TXT(5)
2
3
4

NAME

6       csv2_txt - Description of txt and raw resource records in the csv2 zone
7       file
8

DESCRIPTION

10       Due to the complexity of TXT and RAW records, this man page is
11       dedicated to describing the csv2 format of this RR.
12
13       TXT and RAW rrs in MaraDNS' csv2 zone files can store any arbitrary
14       binary data. Additionally, it is possible to arbitrarily divide up TXT
15       records in to chunks (chunks, which RFC1035 call "character-string"s,
16       are described below).
17
18    ASCII AND UTF-8 DATA
19
20       If a given TXT field or RAW record contains only ASCII data, creating a
21       record is easy: Place the full data between single quotes, like this:
22
23       a.example.com. TXT 'This is some text' ~
24
25       It is also possible, to place almost any printable ASCII characters
26       between quotes. The '~' (tilde) character is not allowed unless
27       csv2_tilde_handling has a value of 0; the '|' (pipe), '#' (hash) and
28       non-printable ASCII control characters are not allowed in TXT data if
29       the ~ is used to separate records. If there are any bytes with a value
30       of 0x80 or more, the data must be UTF-8 encoded Unicode.  For example:
31
32       b.example.com. TXT 'This is an example UTF-8 character: I ♥ MaraDNS'
33
34       (If your font does not have this Unicode symbol, it is a heart)
35
36       The printable ASCII characters not allowed in quotes are the '
37       character, the '|' character, the '~' (tilde) character, and the '#'
38       character. See BACKSLASH ESCAPE SEQUENCES below for information on
39       adding these characters to TXT or RAW fields.
40
41    UNQUOTED DATA
42
43       Note that the record does not have to be quoted. As long as the record
44       only contains ASCII alphanumeric data, and/or the characters '-', '_',
45       '+', '%', '!', '^', and '=', the data can be unquoted as follows:
46
47       c.example.com. TXT This_is_100%_unquoted_text_+symbols!
48
49       It is also possible to mix quoted and unquoted text, such as this:
50
51       d.example.com. TXT This' is a mix 'of_unquoted' and quoted 'text!
52
53       Which will have its data look like this:
54
55       This is a mix of_unquoted and quoted text!
56
57       When mixing quoted and unquoted data, it is important to have all
58       whitespace inside quotes.
59
60    BACKSLASH ESCAPE SEQUENCES
61
62       In order to accommodate storing non-UTF-8 high bit characters, the
63       single quote character, non-printable ASCII control codes, the '|',
64       '~', and '#' characters, and to permit multi-line TXT/RAW records (with
65       comments allowed mid-record), the TXT/RAW RR allows backslashes. These
66       backslashes only have significance outside of quoted text; if they are
67       placed inside single quotes, they are not interpreted and result in a
68       literal backslash being added to the resource record data.
69
70       The following characters can be backslashed:
71
72       '  When backslashed, the adds a literal quote to the resource record.
73
74       whitespace
75          When any whitespace is backslashed (space, newline, cr, and tab),
76          this indicates that the record has not ended, and that more data for
77          this resource will follow. This also allows comments to be placed in
78          TXT and RAW resource records. What happens is that the backslash
79          indicates that any whitespace characters (space, tab, carriage
80          return, and line feed) are to be ignored until the next non-
81          whitespace character that is not a # (hash). If a # is seen, this
82          indicates that we ignore any and all characters until the next
83          carriage return or line feed, and continue to ignore everything
84          until the next non-whitespace character. See the section on multi-
85          line and commented records for examples.
86
87       0123
88          When a number between 0 and 3 is backslashed, this indicates the
89          beginning of a three-digit octal number.
90
91       x  When an x is backslashed, this indicates the beginning of a two-
92          digit hexadecimal number.
93
94       Note that, with the exception of the single quote, the backslash
95       character is not used to remove the meta-significance of a given
96       character. In particular, unlike other environments, it is not possible
97       to backslash spaces. Spaces can be represented either as ' ' in quotes,
98       \x20, or as \040.
99
100       Here are some examples of backslashed data. In this example, we see
101       backslash sequences being used to store non-UTF-8 hi-bit data:
102
103       e.example.com. TXT \x80\x81\x82\x83 ~
104
105       This same data can also be created as follows:
106
107       f.example.com. TXT \200\201\202\203 ~
108
109       Octal and hex information can be mixed:
110
111       g.example.com. TXT \200\x81\202\x83 ~
112
113       Literal single quotes can be placed in resource records:
114
115       h.example.com. TXT 'perl -e '\''print "A Perl of a TXT record!\n"'\' ~
116
117       The above example produces this record:
118
119       perl -e 'print "A Perl of a TXT record!\n"' ~
120
121       To render the '~' character, use the escape sequence \x7e (outside of
122       quotes). For example:
123
124       h1.example.com. TXT 'http://ocf.berkeley.edu/'\x7e'set' ~
125
126       Produces this record:
127
128       http://ocf.berkeley.edu/~set
129
130       To render the '|' character, use the escape sequence \x7c:
131
132       h2.example.com. TXT 'ls '\x7c' more' ~
133
134       Produces this record:
135
136       ls | more
137
138       To render the '#' character, use the escape sequence \x23:
139
140       h3.example.com. TXT 'Press '\x23' for customer service' ~
141
142       Produces this record:
143
144       Press # for customer service
145
146    MULTI-LINE AND COMMENTED RECORDS
147
148       By utilizing backslashes followed by comments, it is possible to have
149       multi-line and commented TXT and RAW records. The following resource
150       record will span more than one line on an 80-column display:
151
152       i.example.com. TXT 'Not only did the quick brown fox jump over the lazy dog, but the lazy dog jumped over the cat.' ~
153
154       Without affecting this resource record, the same data can be split over
155       multiple lines:
156
157       j.example.com. TXT 'Not only did the quick brown fox jump '\
158                          'over the lazy dog, but the lazy dog'\
159                          ' jumped over the cat.' ~
160
161       Some points:
162
163       * The backslash must be outsize of the quotes (or a literal backslash
164         will be added to the record)
165
166       * The backslash must be present before any unquoted white space.
167         Usually, the backslash is placed immediately after the quote
168         character.
169
170       * Unlike other environments, it does not matter whether or not there is
171         invisible whitespace after the backslash.
172
173       It is also possible to add comments after such a backslash as follows:
174
175       k.example.com. TXT 'Not only did the quick brown fox jump '\ # The fox
176                          'over the lazy dog, but the lazy dog'\    # The dog
177                          ' jumped over the cat.' ~                 # The cat
178
179       Note that, since the third comment is not preceded by a backslash, this
180       indicates the end of the resource record.
181
182       There can also be multiple lines dedicated to comments (and,
183       optionally, even blank lines) in the middle of TXT and RAW record data:
184
185       k2.example.com. TXT 'This is some data '\
186       # Here we have some comments followed by a blank line
187
188       # Now we have some more comments,
189       # followed by the rest of the data
190           'and this is the rest of the data' ~
191
192    MULTIPLE TXT CHUNKS
193
194       TXT RRs may be divided up in to multiple "chunks" (RFC1035 calls these
195       "character-string"s). A single chunk can be anywhere from zero to 255
196       bytes long. The default is to have one chunk, as follows:
197
198       o.example.com. TXT 'TXT record with only one chunk' ~
199
200       It is also possible to have a record with multiple chunks. Chunks are
201       delimited by an unquoted ';' character:
202
203       p.example.com. TXT 'This is chunk one';'This is chunk two' ~
204
205       Or:
206
207       q.example.com. TXT 'This is chunk one';\   # Our first chunk
208                           This_is_chunk_two;\    # Our second chunk
209                          'This is chunk three' ~ # Our final chunk
210
211       Quoted ; characters simply add a ; to the record data.
212
213       If a single TXT chunk is longer than 255 bytes long, the csv2 parser
214       will report an error in the zone file: Single TXT chunk too long
215
216       In order to resolve this, place unquoted ; characters in the record
217       data so that each chunk is under 255 octets (bytes or characters) in
218       length.
219
220       It is possible to have zero length chunks:
221
222       r.example.com. TXT 'chunk one';;'chunk three' ~ # Chunk two zero-length
223
224       In particular, is is possible to have zero length chunks at the
225       beginning and end of a TXT record:
226
227       s.example.com. TXT ;'chunk two'; ~ # Chunks one and three zero-length
228
229       Do not place semicolons at the beginning nor end of TXT records unless
230       you wish to have these zero-length chunks.
231
232       Chunk support only exists for TXT records. An unquoted ; character will
233       cause a syntax error in a RAW record.
234
235    RAW RECORDS
236
237       With the exception of no support for chunk delimiters, and the addition
238       of a numeric record type before the record data, the format for RAW
239       records is identical to text records. For example, if we wish to have a
240       "Kitchen Sink" RR record, which has the 8-bit binary numbers "16", "1",
241       and "2", followed by the ASCII string "Kitchen sink+ data", we can
242       specify this in any of the following manners:
243
244       t1.example.com. RAW 40 \x10\x01\x02'Kitchen sink'\x2b' data' ~
245       t.example.com. RAW 40 \020\001\002Kitchen' sink+ data' ~
246       u.example.com. RAW 40 \x10\x01\x02Kitchen\x20sink+\x20data ~
247       v.example.com. RAW 40 \x10\001\x02\
248                             'Kitchen sink+ data' ~
249       w.example.com. RAW 40 \x10\ # Meaning: 16
250                             \x01\ # Coding: 1
251                             \x02\ # Sub-coding: 2
252                             'Kitchen sink+ data' ~ # Data: 'Kitchen sink+ data'
253
254    DKIM RECORDS
255
256       DKIM is a format used to store e-mail authentication data via DNS.
257
258       MaraDNS can store a 2048-bit RSA DKIM key. Longer keys are not
259       supported because of the 512-byte limit for traditional DNS packets.
260
261       A DKIM record is a long “multi chunk” TXT record; DKIM records are
262       stored in a special _domainkey.example.com record. As per RFC6376
263       section 3.6.2.2, “Strings in a TXT RR MUST be concatenated together
264       before use with no intervening whitespace”; a single TXT “chunk” can
265       only be up to 255 bytes in length, but we need more than 255 bytes to
266       store a 2048 bit RSA key (6 bits per character, so we need 342
267       characters to store just the key) and a little more overhead to store
268       the other bits in our DKIM record. But, it doesn’t matter where we
269       split the chunks as long as each individual chunk is under 256 bytes in
270       size.
271
272       Here is a real-world DKIM key stored in a MaraDNS zone file:
273
274       x._domainkey.% +600 TXT 'v=DKIM1; k=rsa; '\
275       'p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCg'\
276       'KCAQEAuhKjx2Aepa3rllxUEZLgF3x'\
277       '68SWvZ8pEgnjZvxtqp94Vkra3AUC4C8dRLKf5SvT'\
278       'xFtIl6pF27jn+M/w2MzYwPFjBgqVf'\
279       'p2lf7xuKsrus63m0T9Sq958nIt1yuUlLDr71bFs7'\
280       'ZuZyQid0ciCc2JF5lwHno10cAvuNJ';'y1Q'\
281       'tFJa+lRJI6/kzY20Hi/ZTzFzctqgqaRZnSoJlTZHf'\
282       'Oy0uwfmF5ejkJ8xvHbEJp6TEc'\
283       '30DwsqrjVWSFLnUWYBv7lrAPB9sAHN7fCayhEuORn'\
284       'Ap+YUhjjMPWyPla1pvTS9h/LTE7g'\
285       '2d+jR/zOkRpV2Ak/4KpeP9dpsRJEOsPEaWGG1pQXgPw'\
286       'IDAQAB'
287

289       THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
290       IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
291       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
292       DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
293       ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
294       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
295       OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
296       HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
297       STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
298       IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
299       POSSIBILITY OF SUCH DAMAGE.
300

AUTHOR

302       Sam Trenholme http://www.samiam.org/
303
304
305
306
307MARADNS                          January 2007                      CSV2_TXT(5)
Impressum