From 85d0944bee6ceb08437a14fe0b33a676b54f4827 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Thu, 13 Apr 2017 10:58:15 -0400 Subject: [PATCH 1/6] getting-started.md: Add advice about converting old zones. --- docs/getting-started.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index fa2b09a3b..70e7a12ee 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -34,3 +34,16 @@ This will print out a list of "corrections" that need to be performed. It will n ## 4. Run `dnscontrol push` This will actually generate `zones/example.com.zone` for you. The bind provider is more configurable, and you can read more information [here.]({{site.github.url}}/providers/bind) + +# Converting from other providers + +Once you have the system working for a test zone, try converting +other zones. Most providers have an option to export all DNS records +as a BIND-style zone file. The utility +[convertzone](https://github.com/StackExchange/dnscontrol/blob/master/misc/convertzone/README.md) +(in the `misc` subdirectory) can read a zonefile and output the +first draft of a `D()` statement for a zone. + +Add the output to the `dnsconfig.js` and clean it up until +`dnscontrol preview` lists no changes. At that point, +it matches the running zone precisely and the conversion is done. From bfc5a59521a61a188e41b241d3937aa3092c822a Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Thu, 13 Apr 2017 11:26:53 -0400 Subject: [PATCH 2/6] convertzone: Add build instructions. --- README.md | 9 ++++++++- misc/convertzone/README.md | 14 ++++++++++++-- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index cfc1dcd58..382f0cd38 100644 --- a/README.md +++ b/README.md @@ -86,8 +86,15 @@ Writing new plugins is very easy. # Installation +## From source + +This command will download the source code, compile it, and put the resulting +binary in `~/bin/` + ```cmd go get github.com/StackExchange/dnscontrol ``` -or get prebuilt binaries from [github releases](https://github.com/StackExchange/dnscontrol/releases/latest). +## Via packages + +Get prebuilt binaries from [github releases](https://github.com/StackExchange/dnscontrol/releases/latest) diff --git a/misc/convertzone/README.md b/misc/convertzone/README.md index 3a6161ae3..018c55c7d 100644 --- a/misc/convertzone/README.md +++ b/misc/convertzone/README.md @@ -60,7 +60,17 @@ create a dnsconfig.js file that exactly replicates your existing configuration. Only when that is complete should you make any changes to the DNS zone data. This is not required, but it is a lot safer. -### Phase 1: Convert exactly as-is. +### Step 0: Build the software. + +Build the software and install in your personal bin: + +```cmd +$ cd misc/convertzone/ +$ go build +$ cp convertzone ~/bin/. +``` + +### Step 1: Convert exactly as-is. In this phase the goal is to create a dnsconfig.js that exactly replicates the existing DNS data. @@ -75,7 +85,7 @@ time leads to difficult-to-find errors. If convertzone could have done a better job, please let us know! -### Phase 2: Make any changes you desire. +### Step 2: Make any changes you desire. Once `dnscontrol preview` lists no changes, do any cleanups you want. For example, remove obsolete records or add new ones. From 321e4dc26dfe1a8ae3d011dbfe41b49d736529e5 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Thu, 13 Apr 2017 11:29:51 -0400 Subject: [PATCH 3/6] fixup! --- docs/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 70e7a12ee..06d95e4f1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -41,7 +41,7 @@ Once you have the system working for a test zone, try converting other zones. Most providers have an option to export all DNS records as a BIND-style zone file. The utility [convertzone](https://github.com/StackExchange/dnscontrol/blob/master/misc/convertzone/README.md) -(in the `misc` subdirectory) can read a zonefile and output the +(in the `misc/convertzone` subdirectory) can read a zonefile and output the first draft of a `D()` statement for a zone. Add the output to the `dnsconfig.js` and clean it up until From 2ea04e990f5a4637388a24c50db80224c671d3ba Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Thu, 13 Apr 2017 12:39:52 -0400 Subject: [PATCH 4/6] More migration advice --- docs/getting-started.md | 19 ++++----- docs/index.md | 12 +++--- misc/convertzone/README.md | 84 ++++++++++---------------------------- 3 files changed, 37 insertions(+), 78 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 06d95e4f1..e8472e0ca 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -35,15 +35,14 @@ This will print out a list of "corrections" that need to be performed. It will n This will actually generate `zones/example.com.zone` for you. The bind provider is more configurable, and you can read more information [here.]({{site.github.url}}/providers/bind) -# Converting from other providers +# Migrate more zones -Once you have the system working for a test zone, try converting -other zones. Most providers have an option to export all DNS records -as a BIND-style zone file. The utility +Once you have the system working for a test zone, migrate other +zones. You can manually create the `D()` statements, or you can +generate them automatically using the [convertzone](https://github.com/StackExchange/dnscontrol/blob/master/misc/convertzone/README.md) -(in the `misc/convertzone` subdirectory) can read a zonefile and output the -first draft of a `D()` statement for a zone. - -Add the output to the `dnsconfig.js` and clean it up until -`dnscontrol preview` lists no changes. At that point, -it matches the running zone precisely and the conversion is done. +utility that is included in the DNSControl repo (it converts +BIND-style zone files to DNSControl's language). To make sure the +migration is correct, use `dnscontrol preview` and make sure it +sees no differences. +[Migration]({{site.github.url}}/migration) doc gives more detailed advice. diff --git a/docs/index.md b/docs/index.md index e7327b129..90e864020 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,15 +5,17 @@ layout: default 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 Exchange network. -## [Getting Started]({{site.github.url}}/getting-started) +## [Getting Started]({{site.github.url}}/getting-started): A walk-through of the basics. -## [Providers]({{site.github.url}}/provider-list) +## [Providers]({{site.github.url}}/provider-list): Which DNS providers are supported. -## [Language Reference]({{site.github.url}}/js) +## [Language Reference]({{site.github.url}}/js): Description of the DNSControl language (DSL). -## [Examples]({{site.github.url}}/examples) +## [Examples]({{site.github.url}}/examples): DSL examples. -## [github](https://github.com/StackExchange/dnscontrol) +## [Migrating]({{site.github.url}}/migrating): Migrating zones to DNSControl. + +## [github](https://github.com/StackExchange/dnscontrol): Get the source! diff --git a/misc/convertzone/README.md b/misc/convertzone/README.md index 018c55c7d..cd00ffda2 100644 --- a/misc/convertzone/README.md +++ b/misc/convertzone/README.md @@ -1,5 +1,18 @@ # convertzone -- Converts a standard DNS zonefile into tsv, pretty, or DSL +## Building the software + +Build the software and install in your personal bin: + +```cmd +$ cd misc/convertzone/ +$ go build +$ cp convertzone ~/bin/. +``` + + +## Usage Overview + convertzone converts an old-style DNS zone file into one of three formats: convertzone [-mode=MODE] zonename [filename] @@ -20,7 +33,7 @@ Example: convertzone stackoverflow.com zone.stackoverflow.com >new/stackoverflow.com -## -mode=tsv: +### -mode=tsv: This is useful for `awk` and other systems that expect a very uniform set of input. @@ -30,7 +43,7 @@ Example: Print all CNAMEs: convertzone -mode=tsv foo.com " $5 }' -## -mode=pretty: +### -mode=pretty: This is useful for cleaning up a zonefile. It sorts the records, moving SOA and NS records to the top of the zone; all other records @@ -44,70 +57,15 @@ Example: Clean up a zone file: convertzone -mode=pretty foo.com new/zone.foo.com -## -mode=dsl: +### -mode=dsl: This is useful for generating your draft `dnsconfig.js` configuration. The output can be appended to the `dnsconfig.js` file as a good first draft. -You'll probably need to clean it up -a bit: -* remove NS records. DnsProvider() inserts NS records for you. -* re-order the records to be more logical and readable. (remember that the last item in a list must not end with a comma) -* manually check over the results. +Example: Generate statements for a dnsconfig.js file: -When converting a zonefile to DSL, we recommend a 2-phase process. First -create a dnsconfig.js file that exactly replicates your existing configuration. -Only when that is complete should you make any changes to the DNS zone data. -This is not required, but it is a lot safer. + convertzone -mode=dsl foo.com first-draft.js -### Step 0: Build the software. - -Build the software and install in your personal bin: - -```cmd -$ cd misc/convertzone/ -$ go build -$ cp convertzone ~/bin/. -``` - -### Step 1: Convert exactly as-is. - -In this phase the goal is to create a dnsconfig.js that exactly -replicates the existing DNS data. - -Edit dnsconfig.js until `dnscontrol preview` shows no errors and -no changes to be made. This means the conversion of your old DNS -data is correct. - -Resist the temptation to clean up and old, obsolete, records or to -add anything new. Experience has shown that making changes at this -time leads to difficult-to-find errors. - -If convertzone could have done a better job, please let us know! - -### Step 2: Make any changes you desire. - -Once `dnscontrol preview` lists no changes, do any cleanups -you want. For example, remove obsolete records or add new ones. - -### Example workflow - -Example: Convert a zone file and add it to your configuration: - - # Note this command uses ">>" to append to dnsconfig.js. Do - # not use ">" as that will erase the existing file. - convertzone -mode=dsl foo.com >dnsconfig.js - # - dnscontrol preview - vim dnsconfig.js - # (repeat until all warnings/errors are resolved) - # - # When everything is as you wish, push the changes live: - dnscontrol push - # (this should be a no-op) - # - # Make any changes you do desire: - vim dnsconfig.js - dnscontrol preview - # (repeat until all warnings/errors are resolved) - dnscontrol push +Note: The conversion is not perfect. You'll need to manually clean +it up and insert it into `dnsconfig.js`. More instructions in the +DNSControl [migration doc]({site.github.url}}/migration). From e7ed9edfb1b685e05037d7c89708754db24edff3 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Thu, 13 Apr 2017 12:41:28 -0400 Subject: [PATCH 5/6] migrating.md: NEW --- docs/migrating.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/migrating.md diff --git a/docs/migrating.md b/docs/migrating.md new file mode 100644 index 000000000..e0537958e --- /dev/null +++ b/docs/migrating.md @@ -0,0 +1,91 @@ +# Migrating zones to DNSControl + +This document explains how to migrate (convert) DNS zones from +other systems to DNSControl's `dnsconfig.js` file. + +This document assumes you have DNSControl set up and working on at +least one zone. You should have a working `dnsconfig.js` file and +`creds.json` file as explained in the +[Getting Started]({{site.github.url}}/getting-started) doc. + +## General advice: + +First, use the +[Getting Started]({{site.github.url}}/getting-started) doc +so that you have a working `dnsconfig.js` with at least one domain. + +We recommend migrating one zone at a time. Start with a small, +non-critical, zone first to learn the process. Convert larger, +more important, zones as you gain confidence. + +Experience has taught us that the best way to migrate a zone is +to create an exact duplicate first. That is, convert the old DNS records +with no changes. It is tempting to clean up the data as you do the migration... +removing that old CNAME that nobody uses any more, or adding that missing +A record you noticed. Resist that temptation. If you make any +changes it will be difficult to tell which changes were intentional +and which are typos. During the migration you will know you are done +when `dnscontrol preview` says there are no changes needed. If there +are items that should be cleaned up, do those cleanups now. + +## Create the first draft + +Create the first draft of the `D()` statement either manually or +automatically. + +For a small domain you can probably create the `D()` statements by +hand, possibly with your text editor's search and replace functions. +However, where's the fun in that? + +The `convertzone` tool can automate 90% of the conversion for you. It +reads a BIND-style zone file and outputs a `D()` statement +that is usually fairly complete. You may need to touch it up a bit. + +The convertzone command is in the `misc/convertzone` subdirectory. +Build instructions are +[here](https://github.com/StackExchange/dnscontrol/blob/master/misc/convertzone/README.md). + +If you do not use BIND already, most DNS providers will export your +existing zone data to a file called the BIND zone file format. + +For example, suppose you owned the `foo.com` domain and the zone file +was in a file called `old/zone.foo.com`. This command will convert the file: + + convertzone -mode=dsl foo.com first-draft.js + +Add the contents of `first-draft.js` to `dnsconfig.js` + +Edit dnsconfig.js until `dnscontrol preview` shows no errors and +no changes to be made. This means the conversion of your old DNS +data is correct. + +Resist the temptation to clean up and old, obsolete, records or to +add anything new. Experience has shown that making changes at this +time leads to unhappy surprises. Of course, once `dnscontrol preview` +runs cleanly, you can do any kind of cleanups you want. In fact, +they should be easier to do now that you are using DNSControl! + +If convertzone could have done a better job, please let us know! + +## Example workflow + +Here is an example series of commands that would be used +to convert a zone. Lines that start with `#` are comments. + + # Note this command uses ">>" to append to dnsconfig.js. Do + # not use ">" as that will erase the existing file. + convertzone -mode=dsl foo.com >dnsconfig.js + # + dnscontrol preview + vim dnsconfig.js + # (repeat these two commands until all warnings/errors are resolved) + # + # When everything is as you wish, push the changes live: + dnscontrol push + # (this should be a no-op) + # + # Make any changes you do desire: + vim dnsconfig.js + dnscontrol preview + # (repeat until all warnings/errors are resolved) + dnscontrol push From a64f0dfc1a3c9d6620dfc5f0f224056b90728eda Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Thu, 13 Apr 2017 12:45:13 -0400 Subject: [PATCH 6/6] fixup! --- docs/migrating.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/migrating.md b/docs/migrating.md index e0537958e..38a6911a1 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -8,7 +8,7 @@ least one zone. You should have a working `dnsconfig.js` file and `creds.json` file as explained in the [Getting Started]({{site.github.url}}/getting-started) doc. -## General advice: +## General advice First, use the [Getting Started]({{site.github.url}}/getting-started) doc @@ -61,11 +61,13 @@ data is correct. Resist the temptation to clean up and old, obsolete, records or to add anything new. Experience has shown that making changes at this -time leads to unhappy surprises. Of course, once `dnscontrol preview` -runs cleanly, you can do any kind of cleanups you want. In fact, -they should be easier to do now that you are using DNSControl! +time leads to unhappy surprises, and people will blame DNSControl. +Of course, once `dnscontrol preview` runs cleanly, you can do any +kind of cleanups you want. In fact, they should be easier to do +now that you are using DNSControl! -If convertzone could have done a better job, please let us know! +If convertzone could have done a better job, please +[let us know](https://github.com/StackExchange/dnscontrol/issues)! ## Example workflow