mirror of
https://github.com/StackExchange/dnscontrol.git
synced 2024-05-11 05:55:12 +00:00
Fix TXT docs, remove AUTOSPLIT (#1083)
This commit is contained in:
@@ -10,11 +10,7 @@ TXT adds an TXT record To a domain. The name should be the relative
|
||||
label for the record. Use `@` for the domain apex.
|
||||
|
||||
The contents is either a single or multiple strings. To
|
||||
specify multiple strings, include them in an array.
|
||||
|
||||
TXT records with multiple strings are only supported by some
|
||||
providers. DNSControl will produce a validation error if the
|
||||
provider does not support multiple strings.
|
||||
specify multiple strings, specify them as an array.
|
||||
|
||||
Each string is a JavaScript string (quoted using single or double
|
||||
quotes). The (somewhat complex) quoting rules of the DNS protocol
|
||||
@@ -30,46 +26,82 @@ Modifiers can be any number of [record modifiers](#record-modifiers) or json obj
|
||||
TXT('multiple', ['one', 'two', 'three']), // Multiple strings
|
||||
TXT('quoted', 'any "quotes" and escapes? ugh; no worries!'),
|
||||
TXT('_domainkey', 't=y; o=-;'), // Escapes are done for you automatically.
|
||||
TXT('long', '#'.repeat(10), AUTOSPLIT) // Escapes are done for you automatically.
|
||||
TXT('long', 'X'.repeat(300)) // Long strings are split automatically.
|
||||
);
|
||||
{%endhighlight%}
|
||||
{% include endExample.html %}
|
||||
|
||||
NOTE: In the past, long strings had to be annotated with the keyword
|
||||
`AUTOSPLIT`. This is no longer required. The keyword is now a no-op.
|
||||
|
||||
# Long and multiple strings
|
||||
# Long strings
|
||||
|
||||
DNS RFCs limit TXT strings to 255 bytes, but you can have multiple
|
||||
such strings. Most applications blindly concatenate the strings but
|
||||
some services that use TXT records join them with a space between each
|
||||
substring (citation needed!).
|
||||
Strings that are longer than 255 octets (bytes) will be quietly
|
||||
split into 255-octets chunks or the provider may report an error
|
||||
if it does not handle multiple strings.
|
||||
|
||||
Not all providers support multiple strings and those that do often put
|
||||
limits on them.
|
||||
|
||||
Therefore, DNSControl requires you to explicitly mark TXT records that
|
||||
should be split.
|
||||
# TXT record edge cases.
|
||||
|
||||
Here are some examples:
|
||||
Most providers do not support the full possibilities of what a TXT
|
||||
record can store. DNSControl can not handle all the edge cases
|
||||
and incompatibles that providers have introduced. Instead, it
|
||||
stores the string(s) that you provide and passes them to the provider
|
||||
verbatim. The provider may opt to accept the data, fix it, or
|
||||
reject it. This happens early in the processing, long before
|
||||
the DNSControl talks to the provider's API.
|
||||
|
||||
VERY_LONG_STRING = 'Z'.repeat(300)
|
||||
The RFCs specify that a TXT record stores one or more strings,
|
||||
each is up to 255 octets (bytes) long. We call these individual
|
||||
strings *chunks*. Each chunk may be zero to 255 octets long.
|
||||
There is no limit to the number of chunks in a TXT record,
|
||||
other than IP packet length restrictions. The contents of each chunk
|
||||
may be octets of value from 0x00 to 0xff.
|
||||
|
||||
// This will produce a validation-time error:
|
||||
TXT('long1', VERY_LONG_STRING),
|
||||
In reality DNS Service Providers (DSPs) place many restrictions on TXT
|
||||
records.
|
||||
|
||||
// String will be split on 255-byte boundaries:
|
||||
TXT('long', VERY_LONG_STRING, AUTOSPLIT),
|
||||
Some DSPs only support a single string of 255 octets or fewer.
|
||||
Multiple strings, or any one string being longer than 255 octets will
|
||||
result in an error. One provider limits the string to 254 octets,
|
||||
which makes me think they're code has an off-by-one error.
|
||||
|
||||
// String split manually:
|
||||
TXT('long', ['part1', 'part2', 'part3']),
|
||||
Some DSPs only support one string, but it may be of any length.
|
||||
Behind the scenes the provider splits it into 255-octet chunks
|
||||
(except the last one, of course).
|
||||
|
||||
NOTE: Old releases of DNSControl blindly sent long strings to
|
||||
providers. Some gave an error at that time, others quietly truncated
|
||||
the strings, and some silently split them into multiple short
|
||||
strings. If you see an error that mentions
|
||||
`ERROR: txt target >255 bytes and AUTOSPLIT not set` this means you
|
||||
need to add AUTOSPLIT to explicitly split the string manually.
|
||||
Some DSPs support multiple strings, but API requests must be 512-bytes
|
||||
or fewer, and with quoting, escaping, and other encoding mishegoss
|
||||
you can't be sure what will be permitted until you actually try it.
|
||||
|
||||
An example error might look like this:
|
||||
Regardless of the quantity and length of strings, some providers ban
|
||||
double quotes, back-ticks, or other chars.
|
||||
|
||||
2020/11/21 00:03:21 printIR.go:94: ERROR: txt target >255 bytes and AUTOSPLIT not set: label="20201._domainkey" index=0 len=424 string[:50]="v=DKIM1; k=rsa; t=s; s=email; p=MIIBIjANBgkqhkiG9w..."
|
||||
# Testing the support of a provider
|
||||
|
||||
## How can you tell if a provider will support a particular `TXT()` record?
|
||||
|
||||
Include the `TXT()` record in a `D()` as usual, along
|
||||
with the `DnsProvider()` for that provider. Run `dnscontrol check` to
|
||||
see if any errors are produced. The check command does not talk to
|
||||
the provider's API, thus permitting you to do this without having an
|
||||
account at that provider.
|
||||
|
||||
## What if the provider rejects a string that is supported?
|
||||
|
||||
Suppose I can create the TXT record using the DSP's web portal but
|
||||
DNSControl rejects the string?
|
||||
|
||||
It is possible that the provider code in DNSControl rejects strings
|
||||
that the DSP accepts. This is because the test is done in code, not
|
||||
by querying the provider's API. It is possible that the code was
|
||||
written to work around a bug (such as rejecting a string with a
|
||||
back-tick) but now that bug has been fixed.
|
||||
|
||||
All such checks are in `providers/${providername}/auditrecords.go`.
|
||||
You can try removing the check that you feel is in error and see if
|
||||
the provider's API accepts the record. You can do this by running the
|
||||
integration tests, or by simply adding that record to an existing
|
||||
`dnsconfig.js` and seeing if `dnscontrol push` is able to push that
|
||||
record into production. (Be careful if you are testing this on a
|
||||
domain used in production.)
|
||||
|
Reference in New Issue
Block a user