github.com/teknogeek/dnscontrol@v0.2.8/docs/getting-started.md (about) 1 --- 2 layout: default 3 title: Getting Started 4 --- 5 # Getting Started 6 7 8 ## 1. Install the software 9 10 You can either download the latest 11 [github release](https://github.com/StackExchange/dnscontrol/releases), 12 or build from the go source: 13 14 go get github.com/StackExchange/dnscontrol 15 16 The `go get` command will will download the source, compile it, and 17 install `dnscontrol` in your `bin` directory. 18 19 20 ## 2. Create a place for the config files. 21 22 Create a directory where you'll be storing your configuration files. 23 We highly recommend storing these files in a Git repo, but for 24 simple tests anything will do. 25 26 Note: Do **not** store your creds.json file in Git unencrypted. 27 That is unsafe. In fact you should include `creds.json` in your 28 `.gitignore` file. We recommend you encrypt the file using something 29 like [git-crypt](https://www.agwa.name/projects/git-crypt) or 30 [Blackbox](https://github.com/StackExchange/blackbox). 31 32 Create a subdirectory called `zones` in the same directory as the 33 configuration files. (`mkdir zones`). `zones` is where the BIND 34 provider writes the zonefiles it creates. Even if you don't 35 use BIND, it is useful for testing. 36 37 38 ## 3. Create the initial `dnsconfig.js` 39 40 `dnsconfig.js` is the main configuration and defines providers, DNS 41 domains, and so on. 42 43 Start your `dnsconfig.js` file by downloading 44 [dnsconfig.js-example.txt]({{ site.github.url }}/assets/dnsconfig.js-example.txt)) 45 and renaming it. 46 47 The file looks like: 48 49 {% highlight js %} 50 51 // Providers: 52 53 var REG_NONE = NewRegistrar('none', 'NONE'); // No registrar. 54 var DNS_BIND = NewDnsProvider('bind', 'BIND'); // ISC BIND. 55 56 // Domains: 57 58 D('example.com', REG_NONE, DnsProvider(DNS_BIND), 59 A('@', '1.2.3.4') 60 ); 61 {%endhighlight%} 62 63 You may modify this file to match your particular providers and domains. See [the javascript docs]({{site.github.url}}/js) and [the provider docs]({{site.github.url}}/provider-list) for more details. 64 If you are using other providers, you will likely need to make a `creds.json` file with api tokens and other account information. For example, to use both name.com and Cloudflare, you would have: 65 66 {% highlight js %} 67 { 68 "cloudflare":{ // provider name to be used in dnsconfig.js 69 "apikey": "key", // API key 70 "apiuser": "username" // username for cloudflare 71 }, 72 "namecom":{ // provider name to be used in dnsconfig.js 73 "apikey": "key", // API Key 74 "apiuser": "username" // username for name.com 75 } 76 } 77 {%endhighlight%} 78 79 There are 2 types of providers: 80 81 A "Registrar" is who you register the domain with. Start with 82 `REG_NONE`, which is a provider that never talks to or updates the 83 registrar. You can define your registrar later when you want to 84 use advanced features. 85 86 The `DnsProvider` is the service that actually provides DNS service 87 (port 53) and may be the same or different company. Even if both 88 your Registrar and DnsProvider are the same company, two different 89 defintions must be included in `dnsconfig.js`. 90 91 92 ## 4. Create the initial `creds.json` 93 94 `creds.json` stores credentials and a few global settings. 95 It is only needed if any providers require credentials (API keys, 96 usernames, passwords, etc.). 97 98 Start your `creds.json` file by downloading 99 [creds.json-example.txt]({{ site.github.url }}/assets/creds.json-example.txt)) 100 and renaming it. 101 102 The file looks like: 103 104 {% highlight js %} 105 { 106 "bind": { 107 }, 108 "r53_ACCOUNTNAME": { 109 "KeyId": "change_to_your_keyid", 110 "SecretKey": "change_to_your_secretkey" 111 } 112 } 113 {%endhighlight%} 114 115 Ignore the `r53_ACCOUNTNAME` section. It is a placeholder and will be ignored. You 116 can use it later when you define your first set of API credentials. 117 118 Note that `creds.json` is a JSON file. JSON is very strict about commas 119 and other formatting. There are a few different ways to check for typos: 120 121 Python: 122 123 python -m json.tool creds.json 124 125 jq: 126 127 jq < creds.json 128 129 FYI: `creds.json` fields can be an environment variable. The field must begin with a `$` followed by the variable name. No other text. For example: 130 131 "apiuser": "$GANDI_APIUSER", 132 133 ## 5. Test the sample files. 134 135 Before you edit the sample files, verify that the system is working. 136 137 First run `dnscontrol preview` and make sure that it completes with 138 no errors. The preview command is the "dry run" mode that shows 139 what changes need to be made and never makes any actual changes. 140 It will use APIs if needed to find out what DNS entries currently 141 exist. 142 143 It should look something like this: 144 145 {% highlight js %} 146 147 $ dnscontrol preview 148 Initialized 1 registrars and 1 dns service providers. 149 ******************** Domain: example.com 150 ----- Getting nameservers from: bind 151 ----- DNS Provider: bind... 1 correction 152 #1: GENERATE_ZONEFILE: example.com 153 (2 records) 154 155 ----- Registrar: none 156 Done. 1 corrections. 157 {%endhighlight%} 158 159 Next run `dnscontrol push` to actually make the changes. In this 160 case, the change will be to create a zone file where one didn't 161 previously exist. 162 163 {% highlight js %} 164 $ dnscontrol push 165 Initialized 1 registrars and 1 dns service providers. 166 ******************** Domain: example.com 167 ----- Getting nameservers from: bind 168 ----- DNS Provider: bind... 1 correction 169 #1: GENERATE_ZONEFILE: example.com 170 (2 records) 171 172 CREATING ZONEFILE: zones/example.com.zone 173 SUCCESS! 174 ----- Registrar: none 175 Done. 1 corrections. 176 {%endhighlight%} 177 178 179 ## 6. Make a change. 180 181 Try making a change to `dnsconfig.js`. For example, change the IP 182 address of in `A('@', '1.2.3.4')` or add an additional A record. 183 184 In our case, we changed the IP address to 10.10.10.10. Previewing 185 our change looks like this: 186 187 {% highlight js %} 188 $ dnscontrol preview 189 Initialized 1 registrars and 1 dns service providers. 190 ******************** Domain: example.com 191 ----- Getting nameservers from: bind 192 ----- DNS Provider: bind... 1 correction 193 #1: GENERATE_ZONEFILE: example.com 194 MODIFY A example.com: (1.2.3.4 300) -> (10.10.10.10 300) 195 196 ----- Registrar: none 197 Done. 1 corrections. 198 {%endhighlight%} 199 200 Notice that it read the old zone file and was able to produce a 201 "diff" between the old `A` record and the new one. If the zonefile 202 didn't exist, the output would look different because the zone file 203 was being created from scratch. 204 205 Run `dnscontrol push` to see the system generate a new zone file. 206 207 Other providers use an API do do updates. In those cases the 208 individual changes will translate into API calls that update the 209 specific records. 210 211 Take a look at the `zones/example.com.zone` file. It should look 212 like: 213 214 {% highlight js %} 215 $TTL 300 216 @ IN SOA DEFAULT_NOT_SET. DEFAULT_NOT_SET. 1 3600 600 604800 1440 217 IN A 10.10.10.10 218 {%endhighlight%} 219 220 You can change the "DEFAULT_NOT_SET" text by following the documentation 221 for the [BIND provider]({{site.github.url}}/providers/bind) to set 222 the "master" and "mbox" settings. Try that now. 223 224 225 ## 7. Use your own domains 226 227 Now that we know the system is working for test data, try controlling 228 a real domain (or a test domain if you have one). 229 230 Set up the provider: Add the providers's definition to `dnsconfig.js` 231 and list any credentials in `creds.json`. Each provider is different. 232 See [the provider docs]({{site.github.url}}/provider-list) for 233 specifics. 234 235 Edit the domain: Add the `D()` entry for the domain, or repurpose 236 the `example.com` domain. Add individual `A()`, `MX()` and other 237 records as needed. Remember that the first parameter to `D()` is 238 always a Registrar. 239 240 Run `dnscontrol preview` to test your work. It may take a few tries 241 to list all the DNS records that make up the domain. When preview 242 shows no changes required, then you know you are at feature parity. 243 244 The [Migrating]({{site.github.url}}/migrating) doc has advice 245 about converting from other systems. 246 You can manually create the `D()` statements, or you can 247 generate them automatically using the 248 [convertzone](https://github.com/StackExchange/dnscontrol/blob/master/cmd/convertzone/README.md) 249 utility that is included in the DNSControl repo (it converts 250 BIND-style zone files and OctoDNS-style YAML files to DNSControl's language). 251 252 Now you can make change to the domain(s) and run `dnscontrol preview` 253 254 255 ## 8. Production Advice 256 257 If you are going to use this in production, we highly recommend the following: 258 259 * Store the configuration files in Git. 260 * Encrypt the `creds.json` file before storing it in Git. 261 * Use a CI/CD tool like Jenkins to automatically push DNS changes. 262 * Join the DNSControl community. File [issues and PRs](https://github.com/StackExchange/dnscontrol).