github.com/teknogeek/dnscontrol@v0.2.8/docs/why-the-dot.md (about) 1 --- 2 layout: default 3 title: Why CNAME/MX/NS targets require a "dot" 4 --- 5 6 # Short version 7 8 You received this error message: 9 10 ``` 11 1: ERROR: target (ghs.googlehosted.com) includes a (.), must end with a (.) 12 ``` 13 14 This means you should add a "." to the end of the target. 15 16 ``` 17 OLD CNAME("foo", "ghs.googlehosted.com"), 18 NEW CNAME("foo", "ghs.googlehosted.com."), 19 ^ 20 ^ 21 ^ 22 ^Add this dot. 23 ``` 24 25 26 # Why CNAME/MX/NS targets require a "dot" 27 28 People are often confused about this error message: 29 30 ``` 31 1: ERROR: target (ghs.googlehosted.com) includes a (.), must end with a (.) 32 ``` 33 34 What this means is that CNAME/MX/NS records (anything where 35 the "target" is a hostname) must end with a "." to indicate 36 that it is a FQDN. The exception to this is that if it is 37 simply a "short name" (i.e. no dots) then DNSControl will 38 add the domain to it. 39 40 Here are four examples: 41 42 ``` 43 CNAME("foo", "bar) // Permitted. (expands to bar.$DOMAIN) 44 CNAME("foo", "bar.com.") // Permitted. (we are certain what the user wants) 45 CNAME("foo", "bar.com") // ERROR (amgiuous) 46 CNAME("foo", "meta.xyz") // ERROR (amgiuous) 47 48 ``` 49 50 The first 2 examples are permitted. The last 2 examples are 51 ambiguous and are therefore are considered errors. 52 53 How are they ambiguous? 54 55 * Should $DOMAIN be added to "bar.com"? Well, obviously not, because it already ends with ".com" and we all know that "bar.com.bar.com" is probably not what they want. No, it isn't that obvious! Why? (see the next bullet point) 56 * Should $DOMAIN be added to "meta.xyz"? Everyone knows that ".xyz" isn't a TLD. Obviously, yes, $DOMAIN should be appended. However, wait... ".xyz" became a TLD in June 2014. We don't want to be surprised by changes like that. Also, users should not be required to memorize all the TLDs. (In the old days it was reasonable to expect people to memorize the 7 TLDS (gov/edu/com/mil/org/net) but since 2000 that's all changed. By the way, we forgot to include "int" in the original and you didn't notice.) 57 * What is the CNAME target is "www.bar.com" and the domain is "bar.com". Then It is reasonable to infer the user's intent, right? "www.bar.com.bar.com." would be silly, right? Maybe. What if we are copying 100 lines of dnsconfig.js from one `D()` to another. Buried in the middle is this one CNAME that means something entirely different when in a new $DOMAIN. That would be bad. We've seen this in production and want to prevent this kind of error. 58 59 Yes, we could layer rule upon rule upon rule. Eventually we'd get 60 all the rules right. However, now a user would have to know all the 61 rules to be able to use Dnscontrol. The point of the Dnscontrol DSL 62 is to enable the casual user to be able to make DNS updates. By 63 "casual user" we do not mean someone someone that lives and breathes DNS 64 like you and I do. In fact, we mean someone that hasn't memorized 65 the list of rules. 66 67 We know of no time where a human intentionally wanted 68 "foo.example.com.domain.com" as the target of an MX record. 69 In fact, the opposite is true. StackExchange.com had 70 a big email outage in 2013 because MX records were updated and the 71 "trailing dot" was forgotten. Our MX records became 72 "aspmx.l.google.com.stackexchange.com" and due to a high TTL we 73 lost email for a few hours. Recently (2017) we had a similar problem 74 and it delayed a new service from working. Luckily this was a new 75 service and didn't have existing users so the problem was unnoticed 76 except for the fact that a project schedule slipped by 3 days. 77 78 Therefore, we prefer the rule to be "when in doubt, error out". It 79 is less to remember and catches errors. It also doesn't remove 80 the expressiveness of the language. One dot is better than 100 rules. 81 82 83 ## Simple mental models are better 84 85 SRE ... the R stands for reliability. 86 87 A big source of human error is mental-model mismatch. That is, when 88 operating a complex system, the user has a mental model of 89 what is going on in the system. They are, essentially, emulating 90 the software in their head to predict that the change they are 91 making will have the result they seek. The more complex the 92 system the less likely the mental model will match reality. 93 94 A mental model mismatch leads to confusion, frustration, and 95 more importantly it increases the risk of operating error the creates 96 production problems. 97 98 If the rules are simple, the mental model will be more accurate 99 than if it is complex. "If something is ambiguous, we give an error 100 and tell you to add a dot to the end" is *simple.* "If something 101 is ambiguous, we follow this list of 100 rules that decide what 102 the user had intended" is *complex.* 103 104 One could argue that your users are very smart and can memorize 105 all the rules. Why should they have to? It's just a single keystroke! 106 107 108 ## Future 109 110 We welcome proposals for how to resolve this ambiguity. 111 112 ["Future proofing is not adding stuff. Future proofing is making sure you can easily add code/features without breaking existing functionality."](http://softwareengineering.stackexchange.com/a/79591/116123) 113 By not solving the problem now, we open the door to upwards compatible 114 solutions. If we created a partial solution now, we might prevent 115 future solutions from being upward compatible. By simply giving an 116 error we open the door to new solutions. 117 118 We should warn you, however, that any new proposals should be 119 simpler than "add a dot".