github.com/StackExchange/DNSControl@v0.2.8/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