github.com/philhug/dnscontrol@v0.2.4-0.20180625181521-921fa9849001/docs/migrating.md (about)

     1  ---
     2  layout: default
     3  title: Migrating zones to DNSControl
     4  ---
     5  
     6  # Migrating zones to DNSControl
     7  
     8  This document explains how to migrate (convert) DNS zones from
     9  other systems to DNSControl's `dnsconfig.js` file.
    10  
    11  This document assumes you have DNSControl set up and working on at
    12  least one zone.  You should have a working `dnsconfig.js` file and
    13  `creds.json` file as explained in the
    14  [Getting Started]({{site.github.url}}/getting-started) doc.
    15  
    16  ## General advice
    17  
    18  First, use the
    19  [Getting Started]({{site.github.url}}/getting-started) doc
    20  so that you have a working `dnsconfig.js` with at least one domain.
    21  
    22  We recommend migrating one zone at a time. Start with a small,
    23  non-critical, zone first to learn the process.  Convert larger,
    24  more important, zones as you gain confidence.
    25  
    26  Experience has taught us that the best way to migrate a zone is
    27  to create an exact duplicate first. That is, convert the old DNS records
    28  with no changes.  It is tempting to clean up the data as you do the migration...
    29  removing that old CNAME that nobody uses any more, or adding an
    30  A record you discovered was missing. Resist that temptation.  If you make any
    31  changes it will be difficult to tell which changes were intentional
    32  and which are mistakes. During the migration you will know you are done
    33  when `dnscontrol preview` says there are no changes needed. At that
    34  point it is safe to do any cleanups.
    35  
    36  ## Create the first draft
    37  
    38  Create the first draft of the `D()` statement either manually or
    39  automatically.
    40  
    41  For a small domain you can probably create the `D()` statements by
    42  hand, possibly with your text editor's search and replace functions.
    43  However, where's the fun in that?
    44  
    45  The `convertzone` tool can automate 90% of the conversion for you. It
    46  reads a BIND-style zone file or an OctoDNS-style YAML file and outputs a `D()` statement
    47  that is usually fairly complete. You may need to touch it up a bit.
    48  
    49  The convertzone command is in the `cmd/convertzone` subdirectory.
    50  Build instructions are
    51  [here](https://github.com/StackExchange/dnscontrol/blob/master/cmd/convertzone/README.md).
    52  
    53  If you do not use BIND already, most DNS providers will export your
    54  existing zone data to a file called the BIND zone file format.
    55  
    56  For example, suppose you owned the `foo.com` domain and the zone file
    57  was in a file called `old/zone.foo.com`. This command will convert the file:
    58  
    59      convertzone -out=dsl foo.com <old/zone.foo.com >first-draft.js
    60  
    61  If you are converting an OctoDNS file, add the flag `-in=octodns`:
    62  
    63      convertzone -in=octodns -out=dsl foo.com <config/foo.com.yaml >first-draft.js
    64  
    65  Add the contents of `first-draft.js` to `dnsconfig.js`
    66  
    67  Run `dnscontrol preview` and see if it finds any differences.
    68  Edit dnsconfig.js until `dnscontrol preview` shows no errors and
    69  no changes to be made. This means the conversion of your old DNS
    70  data is correct.
    71  
    72  convertzone makes a guess at what to do with NS records.
    73  An NS record at the apex is turned into a NAMESERVER() call, the
    74  rest are left as NS().  You probably want to check each of them for
    75  correctness.
    76  
    77  Resist the temptation to clean up and old, obsolete, records or to
    78  add anything new. Experience has shown that making changes at this
    79  time leads to unhappy surprises, and people will blame DNSControl.
    80  Of course, once `dnscontrol preview` runs cleanly, you can do any
    81  kind of cleanups you want.  In fact, they should be easier to do
    82  now that you are using DNSControl!
    83  
    84  If convertzone could have done a better job, please
    85  [let us know](https://github.com/StackExchange/dnscontrol/issues)!
    86  
    87  ## Example workflow
    88  
    89  Here is an example series of commands that would be used
    90  to convert a zone. Lines that start with `#` are comments.
    91  
    92      # Note this command uses ">>" to append to dnsconfig.js.  Do
    93      # not use ">" as that will erase the existing file.
    94      convertzone -out=dsl foo.com <old/zone.foo.com >>dnsconfig.js
    95      #
    96      dnscontrol preview
    97      vim dnsconfig.js
    98      # (repeat these two commands until all warnings/errors are resolved)
    99      #
   100      # When everything is as you wish, push the changes live:
   101      dnscontrol push
   102      # (this should be a no-op)
   103      #
   104      # Make any changes you do desire:
   105      vim dnsconfig.js
   106      dnscontrol preview
   107      # (repeat until all warnings/errors are resolved)
   108      dnscontrol push