github.com/teknogeek/dnscontrol/v2@v2.10.1-0.20200227202244-ae299b55ba42/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 `dnscontrol get-zones` subcommand
    46  [documented here]({{site.github.url}}/get-zones)
    47  can automate 90% of the conversion for you. It
    48  reads BIND-style zonefiles, or will use a providers API to gather the DNS records.  It will then output the records in a variety of formats, including
    49  the as a `D()` statement
    50  that is usually fairly complete. You may need to touch it up a bit,
    51  especially if you use pseudo record types in one provider that are
    52  not supported by another.
    53  
    54  Example 1: Read a BIND zonefile
    55  
    56  Most DNS Service Providers have an 'export to zonefile' feature.
    57  
    58  ```
    59  dnscontrol get-zones -format=dsl bind BIND example.com
    60  dnscontrol get-zones -format=dsl -out=draft.js bind BIND example.com
    61  ```
    62  
    63  This will read the file `zones/example.com.zone`. The system is a bit
    64  inflexible and that must be the filename. You can copy the file to
    65  that name, or use a symlink.
    66  
    67  Add the contents of `draft.js` to `dnsconfig.js` and edit it as needed.
    68  
    69  Example 2: Read from a provider
    70  
    71  This requires creating a `creds.json` file as described in
    72  [Getting Started]({{site.github.url}}/getting-started).
    73  
    74  Suppose your `creds.json` file has the name `global_aws`
    75  for the provider `ROUTE53`.  Your command would look like this:
    76  
    77  ```
    78  dnscontrol get-zones -format=dsl global_aws ROUTE53 example.com
    79  dnscontrol get-zones -format=dsl -out=draft.js global_aws ROUTE53 example.com
    80  ```
    81  
    82  Add the contents of `draft.js` to `dnsconfig.js` and edit it as needed.
    83  
    84  Run `dnscontrol preview` and see if it finds any differences.
    85  Edit dnsconfig.js until `dnscontrol preview` shows no errors and
    86  no changes to be made. This means the conversion of your old DNS
    87  data is correct.
    88  
    89  `dnscontrol get-zones` makes a guess at what to do with NS records.
    90  An NS record at the apex is turned into a NAMESERVER() call, the
    91  rest are left as NS().  You probably want to check each of them for
    92  correctness.
    93  
    94  Resist the temptation to clean up and old, obsolete, records or to
    95  add anything new. Experience has shown that making changes at this
    96  time leads to unhappy surprises, and people will blame DNSControl.
    97  Of course, once `dnscontrol preview` runs cleanly, you can do any
    98  kind of cleanups you want.  In fact, they should be easier to do
    99  now that you are using DNSControl!
   100  
   101  If `dnscontrol get-zones` could have done a better job, please
   102  [let us know](https://github.com/StackExchange/dnscontrol/issues)!
   103  
   104  ## Example workflow
   105  
   106  Here is an example series of commands that would be used
   107  to convert a zone. Lines that start with `#` are comments.
   108  
   109      # Note this command uses ">>" to append to dnsconfig.js.  Do
   110      # not use ">" as that will erase the existing file.
   111      dnscontrol get-zones -format=dsl -out=draft.js bind BIND foo.com
   112      cat >>dnsconfig.js draft.js   # Append to dnsconfig.js
   113      #
   114      dnscontrol preview
   115      vim dnsconfig.js
   116      # (repeat these two commands until all warnings/errors are resolved)
   117      #
   118      # When everything is as you wish, push the changes live:
   119      dnscontrol push
   120      # (this should be a no-op)
   121      #
   122      # Make any changes you do desire:
   123      vim dnsconfig.js
   124      dnscontrol preview
   125      # (repeat until all warnings/errors are resolved)
   126      dnscontrol push