diff --git a/build/generate/featureMatrix.go b/build/generate/featureMatrix.go index c61e8a908..1eae083bf 100644 --- a/build/generate/featureMatrix.go +++ b/build/generate/featureMatrix.go @@ -56,12 +56,16 @@ func generateFeatureMatrix() error { } fm.SetSimple(name, true, func() bool { return providers.ProviderHasCabability(p, cap) }) } - setDoc := func(name string, cap providers.Capability) { + setDoc := func(name string, cap providers.Capability, defaultNo bool) { if notes[cap] != nil { fm[name] = notes[cap] + } else if defaultNo { + fm[name] = &providers.DocumentationNote{ + HasFeature: false, + } } } - setDoc("Official Support", providers.DocOfficiallySupported) + setDoc("Official Support", providers.DocOfficiallySupported, true) fm.SetSimple("Registrar", false, func() bool { return providers.RegistrarTypes[p] != nil }) fm.SetSimple("DNS Provider", false, func() bool { return providers.DNSProviderTypes[p] != nil }) setCap("ALIAS", providers.CanUseAlias) @@ -69,8 +73,8 @@ func generateFeatureMatrix() error { setCap("PTR", providers.CanUsePTR) setCap("CAA", providers.CanUseCAA) setCap("TLSA", providers.CanUseTLSA) - setDoc("dual host", providers.DocDualHost) - setDoc("create-domains", providers.DocCreateDomains) + setDoc("dual host", providers.DocDualHost, false) + setDoc("create-domains", providers.DocCreateDomains, true) // no purge is a freaky double negative cap := providers.CantUseNOPURGE diff --git a/docs/_includes/matrix.html b/docs/_includes/matrix.html index 8b67d93a1..bc1bf51ee 100644 --- a/docs/_includes/matrix.html +++ b/docs/_includes/matrix.html @@ -56,7 +56,9 @@ - + + + Registrar @@ -327,7 +329,9 @@ - + + + no_purge diff --git a/docs/index.md b/docs/index.md index bd7c3f921..26ef61ab6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -37,3 +37,5 @@ Dnscontrol is a platform for seamlessly managing your dns configuration across a ### [Adding new DNS record types]({{site.github.url}}/adding-new-rtypes) + +(Preview the new [frontpage]({{site.github.url}}/new-index.md) diff --git a/docs/migrating.md b/docs/migrating.md index 1232af6a3..9ff1156cc 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -1,3 +1,7 @@ +--- +layout: default +--- + # Migrating zones to DNSControl This document explains how to migrate (convert) DNS zones from diff --git a/docs/new-index.md b/docs/new-index.md new file mode 100644 index 000000000..1e4e9f242 --- /dev/null +++ b/docs/new-index.md @@ -0,0 +1,159 @@ +--- +layout: default +--- + +
+
+
+

DnsControl

+

DnsControl is a platform for seamlessly managing your DNS configuration across any number of DNS hosts, both in the cloud or in your own infrastructure. It manages all of the domains for the Stack Overflow network, and can do the same for you!

+
+
+
+ +
+
+

Try It

+

Want to jump right in? Follow our + quick start tutorial + on a new domain or + migrate + an existing one. Read the + language spec + for more info. +

+
+ +
+

Use It

+

Take advantage of the + advanced features. + Use macros and variables for easier updates. + + Upload your zones to + multiple DNS providers. +

+
+ +
+

Get Involved

+

Join our + mailing list. + We make it easy to contribute by using + GitHub, + you can make code changes with confidence thanks to extensive integration tests. + The project is + newbie-friendly + so jump right in! +

+
+
+ +

Features

+
+ +
+
+
+ +
+
+

Maintain your DNS data as a high-level DS, with macros, and variables for easier updates.

+
+
+
+
+
+

Super extensible! Plug-in architecture makes adding new DNS providers and Registrars easy!

+
+
+
+ +
+
+
+ +
+
+

Eliminate vendor lock-in. Switch between DNS providers easily.

+
+
+
+
+
+

Reduce points of failure: Easily maintain dual DNS providers.

+
+
+
+ +
+
+
+ +
+
+

Supports 10+ DNS Providers including BIND, AWS Route 53, Google DNS, and name.com

+
+
+
+
+
+

Apply CI/CD principles to DNS: Unit-tests, system-tests, automated deployment.

+
+
+
+ +
+
+
+ +
+
+

All the benefits of Git (or any VCS) for your DNS zone data.

+
+
+
+
+
+

Optimize DNS with SPF optimizer (coming soon!)

+
+
+
+ +
+
+
+ +
+
+

Runs on Linux, Windows, Mac, or any operating system supported by Go.

+
+
+
+
+
+

Enable/disable Cloudflare proxying (the "orange cloud" button) directly from your DNSControl files.

+
+
+
+ +
+
+
+ +
+
+

Assign an IP address to a constant and use the variable name throughout the configuration. Need to change the IP address globally? Just change the variable and "recompile."

+
+
+
+
+
+

Keep similar domains in sync with transforms, macros, and variables.

+
+
+
+ + +

Read More

+
diff --git a/docs/provider-list.md b/docs/provider-list.md index 2557d8dcd..ffd484141 100644 --- a/docs/provider-list.md +++ b/docs/provider-list.md @@ -6,7 +6,7 @@ layout: default - + {% for p in site.providers %} @@ -80,4 +80,4 @@ code to support this provider, please re-open the issue. We'd be glad to help in
  • Hurricane Electric (dns.he.net) (#118)
  • Linode (#121)
  • OVH (#143)
    • - \ No newline at end of file + diff --git a/docs/public/app-store.svg b/docs/public/app-store.svg new file mode 100644 index 000000000..f45ec5e20 --- /dev/null +++ b/docs/public/app-store.svg @@ -0,0 +1,15 @@ + + + + + + diff --git a/docs/public/cog.svg b/docs/public/cog.svg new file mode 100644 index 000000000..bc6fcfa1e --- /dev/null +++ b/docs/public/cog.svg @@ -0,0 +1,16 @@ + + + + + + diff --git a/docs/public/createToken.jpg b/docs/public/createToken.jpg new file mode 100644 index 000000000..cb959ebd2 Binary files /dev/null and b/docs/public/createToken.jpg differ diff --git a/docs/public/database.svg b/docs/public/database.svg new file mode 100644 index 000000000..9e0b4b1d1 --- /dev/null +++ b/docs/public/database.svg @@ -0,0 +1,11 @@ + + + + + + diff --git a/docs/public/grid.svg b/docs/public/grid.svg new file mode 100644 index 000000000..30673b68b --- /dev/null +++ b/docs/public/grid.svg @@ -0,0 +1,10 @@ + + + + + + diff --git a/docs/public/hour-glass.svg b/docs/public/hour-glass.svg new file mode 100644 index 000000000..fe457b115 --- /dev/null +++ b/docs/public/hour-glass.svg @@ -0,0 +1,16 @@ + + + + + + diff --git a/docs/public/inbox.svg b/docs/public/inbox.svg new file mode 100644 index 000000000..3aaadd9a9 --- /dev/null +++ b/docs/public/inbox.svg @@ -0,0 +1,11 @@ + + + + + + diff --git a/docs/public/sound-mute.svg b/docs/public/sound-mute.svg new file mode 100644 index 000000000..d24d150d1 --- /dev/null +++ b/docs/public/sound-mute.svg @@ -0,0 +1,11 @@ + + + + + + diff --git a/docs/public/timeline.jpg b/docs/public/timeline.jpg new file mode 100644 index 000000000..b681788e0 Binary files /dev/null and b/docs/public/timeline.jpg differ diff --git a/docs/public/windows-store.svg b/docs/public/windows-store.svg new file mode 100644 index 000000000..808b85879 --- /dev/null +++ b/docs/public/windows-store.svg @@ -0,0 +1,8 @@ + + + + + + diff --git a/docs/spf.md b/docs/spf.md new file mode 100644 index 000000000..a0916b7cf --- /dev/null +++ b/docs/spf.md @@ -0,0 +1,152 @@ +--- +layout: default +--- + +# The DNS Control SPF Optimizer + +SPF records are hints to email systems that help them determine if +an incoming email message might be spam. The SPF records are placed +in DNS TXT records like so: + + $ dig +short google.com txt + "v=spf1 include:_spf.google.com ~all" + +SPF records are intentionally limited to 10 verbs that would cause +DNS lookups. In the above example the `include:_spf.google.com` +would cause a DNS lookup. The reason for the "10 lookup limit" is +to make it difficult to leverage the SPF system to create a DDOS +attack on a DNS server. + +At StackOverflow, we use many SaaS services and we reached the "10 +lookup limit" years ago. We would like to unroll or "inline" the +includes but it would become a maintenance nightmare. What if we +unrolled the SPF include required for Google GSuite and then Google +changed the contents of the SPF records? + +We figured that DNSControl could do a better job. + +## Better comments + +Here's how we define our SPF record: + + var SPF_SO_LIST = [ + 'v=spf1', + 'ip4:198.252.206.0/24', // ny-mail* + 'ip4:192.111.0.0/24', // co-mail* + 'include:_spf.google.com', // GSuite + 'include:mailgun.org', // Greenhouse.io + 'include:spf-basic.fogcreek.com', // Fogbugz + 'include:mail.zendesk.com', // Zenddesk + 'include:servers.mcsv.net', // MailChimp (Ticket#12345) + 'include:sendgrid.net', // SendGrid + 'include:spf.mtasv.net', // Desk.com + '~all' + ].join(" "); + + D('example.com', ... + TXT("@", SPF_SO_LIST), + ... + ) + +The first thing you'll notice is that by defining it this way each +component can include a comment explaining what it is for. This +is important because, and we're not kidding here, for a long time +we didn't know what `include:spf.mtasv.net` was for and we were +afraid to remove it. Finally someone remembered that it was for +Desk.com and we breathed a sigh of relief. You'll also notice that +the Mailchimp entry includes the ticket number of the request to +add it. Now we can refer to that ticket to better understand the +history. + +In summary, listing your SPF record like this makes it easier to +maintain a complex SPF record. Certainly you agree that this is +better than `var SPF_SO_LIST = 'v=spf1 'ip4:198.252.206.0/24 'ip4:192.111.0.0/24 'include:_spf.google.com 'include:mailgun.org 'include:spf-basic.fogcreek.com 'include:mail.zendesk.com 'include:servers.mcsv.net 'include:sendgrid.net include:spf.mtasv.net ~all'` + +However, we can do better. + +# Better macros + +Because we don't want to have to remember the "@", and because we +use the same SPF record for multiple domains (any domain that is +attached to our GSuite account), we define a macro called SPF for +use with many domains: + + var SPF = [ TXT("@", SPF_SO_LIST) ] + D('example.com', ... + SPF, + ... + ) + D('otherexample.com', ... + SPF, + ... + ) + +This is a lot less typing. It is also less error-prone: you don't have to remember the `'@'`. + +However, we can do better. + +# SPF optimizer + +As mentioned before, SPF records are intentionally limited to 10 +verbs that would cause DNS lookups. This count includes recursive +includes. For example, if you use an `include:` that includes 5 +other domains, that's 6 lookups. That leaves you to only 4 more +lookups. + +We figured that DNSControl could do better. It could analyze an SPF +record and flatten it to reduce the number of lookups. + +However, we're very paranoid. If we break email, a lot of people +notice. Therefore our "flattening" system has some safety rules: + +* The system is "opt in". You must specify exactly which includes will be flattened. We recommend you only flatten the minimum needed. +* The flattening works off a cached copy of the DNS lookups. We are concerned +that if someone else's DNS server is down, the optimizer will break and you +won't be able to `dnscontrol push`, which would be very bad especially in +an emergency. Therefore. the process runs off a file called FILLIN but will +warn you if the file needs updating. The updates are easy to do (DNSControl generates +the new file for you to use). + +So what does it look like? + +Add metadata to the TXT records: + +* `flatten: "foo,bar"` (flatten include:foo and include:bar) +* `split: "_spf%d"` (if additional DNS records must be generated, make the labels `_spf1`, `_spf2`, `_spf3`, and so on.) + +Here's an example: + + var SPF = [ + TXT("@", SPF_SO_LIST, {flatten: "spf-basic.fogcreek.com,spf.mtasv.net", split: "_spf%d"}), + TXT("_rawspf", SPF_SO_LIST) // keep unmodified availible for other tools + ] + D('example.com', ... + SPF, + ... + ) + +As a result: + +* TXT record on `example.com` will be optimized. +* TXT record on `_rawspf.example.com` is the unoptimized version, used purely for demonstration purposes. + +You'll notice that we only flatten 2 of all the includes. These are sufficient to get +us to only 10 lookups. They're also the 2 domains that SPF records are the least important. +Thus, if their SPF records change and we don't notice, we won't be too greatly affected. + +# Operational Guide + + +FILL IN THE SEQUENCE OF COMMANDS TO MAINTAIN THE CACHE. + + +# Interactive mode + +FILL IN INFO ABOUT THE INTERACTIVE MDOE. + +# Future + +We'd like to add other optimizations such as: + +* De-dup +* Remove overlapping CIDR blocks \ No newline at end of file diff --git a/docs/toc.md b/docs/toc.md new file mode 100644 index 000000000..075034883 --- /dev/null +++ b/docs/toc.md @@ -0,0 +1,38 @@ +--- +layout: default +--- + +## Getting Started + +### [Getting Started]({{site.github.url}}/getting-started): A walk-through of the basics. + +### [Providers]({{site.github.url}}/provider-list): Which DNS providers are supported. + +### [Examples]({{site.github.url}}/examples): The DNSControl language by example. + +### [Migrating]({{site.github.url}}/migrating): Migrating zones to DNSControl. + + +## Reference + +### [Language Reference]({{site.github.url}}/js): Description of the DNSControl language (DSL). + +### [ALIAS / ANAME records in dnscontrol]({{site.github.url}}/alias) + +### [Why CNAME/MX/NS targets require a trailing "dot"]({{site.github.url}}/why-the-dot) + + +## Advanced Topics + +### [Testing]({{site.github.url}}/unittests): Unit Testing for you DNS Data. + +### [SPF Optimizer]({{site.github.url}}/spf): Optimize your SPF records. + +## Developer info + +### [github](https://github.com/StackExchange/dnscontrol): Get the source! + +### [Writing Providers]({{site.github.url}}/writing-providers) + +### [Adding new DNS record types]({{site.github.url}}/adding-new-rtypes) + diff --git a/docs/unittests.md b/docs/unittests.md index 5023aeeb8..bbe952eb3 100644 --- a/docs/unittests.md +++ b/docs/unittests.md @@ -1,6 +1,10 @@ +--- +layout: default +--- + # Unit Testing DNS Data -## Testing +## Built-in Tests DNSControl performs a number of tests during the validation stage. You can find them in `pkg/normalize/validate.go`.
    NameJavascript IdentifierIdentifier