csv2_txt (5) - Linux Manuals

csv2_txt: Description of txt and raw resource records in the csv2 zone

NAME

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

DESCRIPTION

Due to the complexity of TXT and RAW records, this man page is dedicated to describing the csv2 format of this RR.

TXT and RAW rrs in MaraDNSaq csv2 zone files can store any arbitrary binary data. Additionally, it is possible to arbitrarily divide up TXT records in to chunks (chunks, which RFC1035 call "character-string"s, are described below).

ASCII AND UTF-8 DATA

If a given TXT field or RAW record contains only ASCII data, creating a record is easy: Place the full data between single quotes, like this:

a.example.com. TXT aqThis is some textaq ~

It is also possible, to place almost any printable ASCII characters between quotes. The aq~aq (tilde) character is not allowed unless csv2_tilde_handling has a value of 0; the aq|aq (pipe), aq#aq (hash) and non-printable ASCII control characters are not allowed in TXT data if the ~ is used to separate records. If there are any bytes with a value of 0x80 or more, the data must be UTF-8 encoded Unicode.

The printable ASCII characters not allowed in quotes are the aq character, the aq|aq character, the aq~aq (tilde) character, and the aq#aq character. See BACKSLASH ESCAPE SEQUENCES below for information on adding these characters to TXT or RAW fields.

UNQUOTED DATA

Note that the record does not have to be quoted. As long as the record only contains ASCII alphanumeric data, and/or the characters aq-aq, aq_aq, aq+aq, aq%aq, aq!aq, aq^aq, and aq=aq, the data can be unquoted as follows:

c.example.com. TXT This_is_100%_unquoted_text_+symbols!

It is also possible to mix quoted and unquoted text, such as this:

d.example.com. TXT Thisaq is a mix aqof_unquotedaq and quoted aqtext!

Which will have its data look like this:

This is a mix of_unquoted and quoted text!

When mixing quoted and unquoted data, it is important to have all whitespace inside quotes.

BACKSLASH ESCAPE SEQUENCES

In order to accommodate storing non-UTF-8 high bit characters, the single quote character, non-printable ASCII control codes, the aq|aq, aq~aq, and aq#aq characters, and to permit multi-line TXT/RAW records (with comments allowed mid-record), the TXT/RAW RR allows backslashes. These backslashes only have significance outside of quoted text; if they are placed inside single quotes, they are not interpreted and result in a literal backslash being added to the resource record data.

The following characters can be backslashed:

aq

When backslashed, the adds a literal quote to the resource record.

whitespace

When any whitespace is backslashed (space, newline, cr, and tab), this indicates that the record has not ended, and that more data for this recource will follow. This also allows comments to be placed in TXT and RAW resource records. What happens is that the backslash indicates that any whitespace characters (space, tab, carraige return, and line feed) are to be ignored until the next non-whitespace character that is not a # (hash). If a # is seen, this indicates that we ignore any and all characters until the next carriage return or line feed, and continue to ignore everything until the next non-whitespace character. See the section on multi-line and commented records for examples.

0123

When a number between 0 and 3 is backslashed, this indicates the beginning of a three-digit octal number.

x

When an x is backslashed, this indicates the beginning of a two-digit hexadecimal number.

Note that, with the exception of the single quote, the backslash character is not used to remove the meta-significance of a given character. In particular, unlike other environments, it is not possible to backslash spaces. Spaces can be represented either as aq aq in quotes, \x20, or as \040.

Here are some examples of backslashed data. In this example, we see backslash sequences being used to store non-UTF-8 hi-bit data:

e.example.com. TXT \x80\x81\x82\x83 ~

This same data can also be created as follows:

f.example.com. TXT \200\201\202\203 ~

Octal and hex information can be mixed:

g.example.com. TXT \200\x81\202\x83 ~

Literal single quotes can be placed in resource records:

h.example.com. TXT aqperl -e aq\aqaqprint "A Perl of a TXT record!\n"aq\aq ~

The above example produces this record:

perl -e aqprint "A Perl of a TXT record!\n"aq ~

To render the aq~aq character, use the escape sequence \x7e (outside of quotes). For example:

h1.example.com. TXT aqhttp://ocf.berkeley.edu/aq\x7eaqsetaq ~

Produces this record:

http://ocf.berkeley.edu/~set

To render the aq|aq character, use the escape sequence \x7c:

h2.example.com. TXT aqls aq\x7caq moreaq ~

Produces this record:

ls | more

To render the aq#aq character, use the escape sequence \x23:

h3.example.com. TXT aqPress aq\x23aq for customer serviceaq ~

Produces this record:

Press # for customer service

MULTI-LINE AND COMMENTED RECORDS

By utilizing backslashes followed by comments, it is possible to have multi-line and commented TXT and RAW records. The following resource record will span more than one line on an 80-column display:

i.example.com. TXT aqNot only did the quick brown fox jump over the lazy dog, but the lazy dog jumped over the cat.aq ~

Without affecting this resource record, the same data can be split over multiple lines:

j.example.com. TXT aqNot only did the quick brown fox jump aq\
                   aqover the lazy dog, but the lazy dogaq\
                   aq jumped over the cat.aq ~

Some points:

*

The backslash must be outsize of the quotes (or a literal backslash will be added to the record)

*

The backslash must be present before any unquoted white space. Usually, the backslash is placed immediately after the quote character.

*

Unlike other environments, it does not matter whether or not there is invisible whitespace after the backslash.

It is also possible to add comments after such a backslash as follows:

k.example.com. TXT aqNot only did the quick brown fox jump aq\ # The fox
                   aqover the lazy dog, but the lazy dogaq\    # The dog
                   aq jumped over the cat.aq ~                 # The cat

Note that, since the third comment is not preceeded by a backslash, this indicates the end of the resource record.

There can also be multiple lines dedicated to comments (and, optionally, even blank lines) in the middle of TXT and RAW record data:

k2.example.com. TXT aqThis is some data aq\
# Here we have some comments followed by a blank line

# Now we have some more comments, 
# followed by the rest of the data
    aqand this is the rest of the dataaq ~

MULTIPLE TXT CHUNKS

TXT RRs may be divided up in to multiple "chunks" (RFC1035 calls these "character-string"s). A single chunk can be anywhere from zero to 255 bytes long. The default is to have one chunk, as follows:

o.example.com. TXT aqTXT record with only one chunkaq ~

It is also possible to have a record with multiple chunks. Chunks are delimited by an unquoted aq;aq character:

p.example.com. TXT aqThis is chunk oneaq;aqThis is chunk twoaq ~

Or:

q.example.com. TXT aqThis is chunk oneaq;\   # Our first chunk
                    This_is_chunk_two;\    # Our second chunk
                   aqThis is chunk threeaq ~ # Our final chunk

Quoted ; characters simply add a ; to the record data.

If a single TXT chunk is longer than 255 bytes long, the csv2 parser will report an error in the zone file: Single TXT chunk too long

In order to resolve this, place unquoted ; characters in the record data so that each chunk is under 255 octets (bytes or characters) in length.

It is possible to have zero length chunks:

r.example.com. TXT aqchunk oneaq;;aqchunk threeaq ~ # Chunk two zero-length

In particular, is is possible to have zero length chunks at the beginning and end of a TXT record:

s.example.com. TXT ;aqchunk twoaq; ~ # Chunks one and three zero-length

Do not place semicolons at the beginning nor end of TXT records unless you wish to have these zero-length chunks.

Chunk support only exists for TXT records. An unquoted ; character will cause a syntax error in a RAW record.

RAW RECORDS

With the exception of no support for chunk delimiters, and the addition of a numeric record type before the record data, the format for RAW records is identical to text records. For example, if we wish to have a "Kitchen Sink" RR record, which has the 8-bit binary numbers "16", "1", and "2", followed by the ASCII string "Kitchen sink+ data", we can specify this in any of the following manners:

t1.example.com. RAW 40 \x10\x01\x02aqKitchen sinkaq\x2baq dataaq ~

t.example.com. RAW 40 \020\001\002Kitchenaq sink+ dataaq ~

u.example.com. RAW 40 \x10\x01\x02Kitchen\x20sink+\x20data ~

v.example.com. RAW 40 \x10\001\x02\
                      aqKitchen sink+ dataaq ~

w.example.com. RAW 40 \x10\ # Meaning: 16
                      \x01\ # Coding: 1
                      \x02\ # Sub-coding: 2
                      aqKitchen sink+ dataaq ~ # Data: aqKitchen sink+ dataaq

LEGAL DISCLAIMER

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

AUTHOR

Sam Trenholme http://www.samiam.org/