migrating.md: NEW

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 <old/zone.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 <old/zone.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