1CSV2_TXT(5) MaraDNS reference CSV2_TXT(5)
2
6 csv2_txt - Description of txt and raw resource records in the csv2 zone
7 file
8
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 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 ASCII AND UTF-8 DATA
19 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 a.example.com. TXT 'This is some text' ~
24 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.
31 The printable ASCII characters not allowed in quotes are the '
33 character, the '|' character, the '~' (tilde) character, and the '#'
34 character. See BACKSLASH ESCAPE SEQUENCES below for information on
35 adding these characters to TXT or RAW fields.
36 UNQUOTED DATA
38 Note that the record does not have to be quoted. As long as the record
40 only contains ASCII alphanumeric data, and/or the characters '-', '_',
41 '+', '%', '!', '^', and '=', the data can be unquoted as follows:
42 c.example.com. TXT This_is_100%_unquoted_text_+symbols!
44 It is also possible to mix quoted and unquoted text, such as this:
46 d.example.com. TXT This' is a mix 'of_unquoted' and quoted 'text!
48 Which will have its data look like this:
50 This is a mix of_unquoted and quoted text!
52 When mixing quoted and unquoted data, it is important to have all
54 whitespace inside quotes.
55 BACKSLASH ESCAPE SEQUENCES
57 In order to accommodate storing non-UTF-8 high bit characters, the
59 single quote character, non-printable ASCII control codes, the '|',
60 '~', and '#' characters, and to permit multi-line TXT/RAW records (with
61 comments allowed mid-record), the TXT/RAW RR allows backslashes. These
62 backslashes only have significance outside of quoted text; if they are
63 placed inside single quotes, they are not interpreted and result in a
64 literal backslash being added to the resource record data.
65 The following characters can be backslashed:
67 ' When backslashed, the adds a literal quote to the resource record.
69 whitespace
71 When any whitespace is backslashed (space, newline, cr, and tab),
72 this indicates that the record has not ended, and that more data for
73 this recource will follow. This also allows comments to be placed in
74 TXT and RAW resource records. What happens is that the backslash
75 indicates that any whitespace characters (space, tab, carraige
76 return, and line feed) are to be ignored until the next non-
77 whitespace character that is not a # (hash). If a # is seen, this
78 indicates that we ignore any and all characters until the next
79 carriage return or line feed, and continue to ignore everything
80 until the next non-whitespace character. See the section on multi-
81 line and commented records for examples.
82 0123
84 When a number between 0 and 3 is backslashed, this indicates the
85 beginning of a three-digit octal number.
86 x When an x is backslashed, this indicates the beginning of a two-
88 digit hexadecimal number.
89 Note that, with the exception of the single quote, the backslash
91 character is not used to remove the meta-significance of a given
92 character. In particular, unlike other environments, it is not
93 possible to backslash spaces. Spaces can be represented either as ' '
94 in quotes, \x20, or as \040.
95 Here are some examples of backslashed data. In this example, we see
97 backslash sequences being used to store non-UTF-8 hi-bit data:
98 e.example.com. TXT \x80\x81\x82\x83 ~
100 This same data can also be created as follows:
102 f.example.com. TXT \200\201\202\203 ~
104 Octal and hex information can be mixed:
106 g.example.com. TXT \200\x81\202\x83 ~
108 Literal single quotes can be placed in resource records:
110 h.example.com. TXT 'perl -e '\''print "A Perl of a TXT record!\n"'\' ~
112 The above example produces this record:
114 perl -e 'print "A Perl of a TXT record!\n"' ~
116 To render the '~' character, use the escape sequence \x7e (outside of
118 quotes). For example:
119 h1.example.com. TXT 'http://ocf.berkeley.edu/'\x7e'set' ~
121 Produces this record:
123 http://ocf.berkeley.edu/~set
125 To render the '|' character, use the escape sequence \x7c:
127 h2.example.com. TXT 'ls '\x7c' more' ~
129 Produces this record:
131 ls | more
133 To render the '#' character, use the escape sequence \x23:
135 h3.example.com. TXT 'Press '\x23' for customer service' ~
137 Produces this record:
139 Press # for customer service
141 MULTI-LINE AND COMMENTED RECORDS
143 By utilizing backslashes followed by comments, it is possible to have
145 multi-line and commented TXT and RAW records. The following resource
146 record will span more than one line on an 80-column display:
147 i.example.com. TXT 'Not only did the quick brown fox jump over the lazy dog, but the lazy dog jumped over the cat.' ~
149 Without affecting this resource record, the same data can be split over
151 multiple lines:
152 j.example.com. TXT 'Not only did the quick brown fox jump '\
154 'over the lazy dog, but the lazy dog'\
155 ' jumped over the cat.' ~
156 Some points:
158 * The backslash must be outsize of the quotes (or a literal backslash
160 will be added to the record)
161 * The backslash must be present before any unquoted white space.
163 Usually, the backslash is placed immediately after the quote
164 character.
165 * Unlike other environments, it does not matter whether or not there is
167 invisible whitespace after the backslash.
168 It is also possible to add comments after such a backslash as follows:
170 k.example.com. TXT 'Not only did the quick brown fox jump '\ # The fox
172 'over the lazy dog, but the lazy dog'\ # The dog
173 ' jumped over the cat.' ~ # The cat
174 Note that, since the third comment is not preceeded by a backslash,
176 this indicates the end of the resource record.
177 There can also be multiple lines dedicated to comments (and,
179 optionally, even blank lines) in the middle of TXT and RAW record data:
180 k2.example.com. TXT 'This is some data '\
182 # Here we have some comments followed by a blank line
183 # Now we have some more comments,
185 # followed by the rest of the data
186 'and this is the rest of the data' ~
187 MULTIPLE TXT CHUNKS
189 TXT RRs may be divided up in to multiple "chunks" (RFC1035 calls these
191 "character-string"s). A single chunk can be anywhere from zero to 255
192 bytes long. The default is to have one chunk, as follows:
193 o.example.com. TXT 'TXT record with only one chunk' ~
195 It is also possible to have a record with multiple chunks. Chunks are
197 delimited by an unquoted ';' character:
198 p.example.com. TXT 'This is chunk one';'This is chunk two' ~
200 Or:
202 q.example.com. TXT 'This is chunk one';\ # Our first chunk
204 This_is_chunk_two;\ # Our second chunk
205 'This is chunk three' ~ # Our final chunk
206 Quoted ; characters simply add a ; to the record data.
208 If a single TXT chunk is longer than 255 bytes long, the csv2 parser
210 will report an error in the zone file: Single TXT chunk too long
211 In order to resolve this, place unquoted ; characters in the record
213 data so that each chunk is under 255 octets (bytes or characters) in
214 length.
215 It is possible to have zero length chunks:
217 r.example.com. TXT 'chunk one';;'chunk three' ~ # Chunk two zero-length
219 In particular, is is possible to have zero length chunks at the
221 beginning and end of a TXT record:
222 s.example.com. TXT ;'chunk two'; ~ # Chunks one and three zero-length
224 Do not place semicolons at the beginning nor end of TXT records unless
226 you wish to have these zero-length chunks.
227 Chunk support only exists for TXT records. An unquoted ; character will
229 cause a syntax error in a RAW record.
230 RAW RECORDS
232 With the exception of no support for chunk delimiters, and the addition
234 of a numeric record type before the record data, the format for RAW
235 records is identical to text records. For example, if we wish to have a
236 "Kitchen Sink" RR record, which has the 8-bit binary numbers "16", "1",
237 and "2", followed by the ASCII string "Kitchen sink+ data", we can
238 specify this in any of the following manners:
239 t1.example.com. RAW 40 \x10\x01\x02'Kitchen sink'\x2b' data' ~
241 t.example.com. RAW 40 \020\001\002Kitchen' sink+ data' ~
244 u.example.com. RAW 40 \x10\x01\x02Kitchen\x20sink+\x20data ~
247 v.example.com. RAW 40 \x10\001\x02\
250 'Kitchen sink+ data' ~
251 w.example.com. RAW 40 \x10\ # Meaning: 16
254 \x01\ # Coding: 1
255 \x02\ # Sub-coding: 2
256 'Kitchen sink+ data' ~ # Data: 'Kitchen sink+ data'
257
260 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS OR
261 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
262 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
263 DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
264 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
265 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
266 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
267 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
268 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
269 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
270 POSSIBILITY OF SUCH DAMAGE.
271
273 Sam Trenholme http://www.samiam.org/
274MARADNS January 2007 CSV2_TXT(5)