mirror of
https://github.com/StackExchange/dnscontrol.git
synced 2024-05-11 05:55:12 +00:00
Add "get-zone" command (#613)
* Add GetZoneRecords to DNSProvider interface * dnscontrol now uses ufave/cli/v2 * NEW: get-zones.md * HasRecordTypeName should be a method on models.Records not models.DomainConfig * Implement BIND's GetZoneRecords * new WriteZoneFile implemented * go mod vendor * Update docs to use get-zone instead of convertzone * Add CanGetZone capability and update all providers. * Get all zones for a provider at once (#626) * implement GetZoneRecords for cloudflare * munge cloudflare ttls * Implement GetZoneRecords for cloudflare (#625) Co-authored-by: Craig Peterson <192540+captncraig@users.noreply.github.com>
This commit is contained in:
Tom Limoncelli
GitHub
@@ -902,5 +902,72 @@
|
||||
<i class="fa fa-check text-success" aria-hidden="true"></i>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th class="row-header" style="text-decoration: underline;" data-toggle="tooltip" data-container="body" data-placement="top" title="indicates the dnscontrol get-zones subcommand is implemented.">get-zones</th>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="success">
|
||||
<i class="fa fa-check text-success" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="success">
|
||||
<i class="fa fa-check text-success" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td><i class="fa fa-minus dim"></i></td>
|
||||
<td class="success">
|
||||
<i class="fa fa-check text-success" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td><i class="fa fa-minus dim"></i></td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td><i class="fa fa-minus dim"></i></td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td><i class="fa fa-minus dim"></i></td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="success">
|
||||
<i class="fa fa-check text-success" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
<td class="info">
|
||||
<i class="fa fa-circle-o text-info" aria-hidden="true"></i>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
@@ -53,7 +53,7 @@ a minimum.
|
||||
* Add the capability to the file `dnscontrol/providers/capabilities.go` (look for `CanUseAlias` and add
|
||||
it to the end of the list.)
|
||||
* Add this feature to the feature matrix in `dnscontrol/build/generate/featureMatrix.go` (Add it to the variable `matrix` then add it later in the file with a `setCap()` statement.
|
||||
* Mark the `bind` provider as supporting this record type by updating `dnscontrol/providers/bind/bindProvider.go` (look for `providers.CanUs` and you'll see what to do).
|
||||
* Mark the `bind` provider as supporting this record type by updating `dnscontrol/providers/bind/bindProvider.go` (look for `providers.CanUse` and you'll see what to do).
|
||||
|
||||
## Step 3: Add a helper function
|
||||
|
||||
|
||||
85
docs/get-zones.md
Normal file
85
docs/get-zones.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
layout: default
|
||||
title: Get-Zones subcommand
|
||||
---
|
||||
|
||||
# get-zones (was "convertzone")
|
||||
|
||||
DNSControl has a stand-alone utility that will contact a provider,
|
||||
download the records of one or more zones, and output them to a file
|
||||
in a variety of formats.
|
||||
|
||||
The original purpose of this command is to help convert legacy domains
|
||||
to DNScontrol (bootstrapping). Since bootstrapping can not depend on
|
||||
`dnsconfig.js`, `get-zones` relies on command line parameters and
|
||||
`creds.json` exclusively.
|
||||
|
||||
Syntax:
|
||||
|
||||
dnscontrol get-zones [command options] credkey provider zone [...]
|
||||
|
||||
--creds value Provider credentials JSON file (default: "creds.json")
|
||||
--format value Output format: dsl tsv pretty (default: "pretty")
|
||||
--out value Instead of stdout, write to this file
|
||||
|
||||
ARGUMENTS:
|
||||
credkey: The name used in creds.json (first parameter to NewDnsProvider() in dnsconfig.js)
|
||||
provider: The name of the provider (second parameter to NewDnsProvider() in dnsconfig.js)
|
||||
zone: One or more zones (domains) to download; or "all".
|
||||
|
||||
EXAMPLES:
|
||||
dnscontrol get-zones myr53 ROUTE53 example.com
|
||||
dnscontrol get-zones gmain GANDI_V5 example.comn other.com
|
||||
dnscontrol get-zones cfmain CLOUDFLAREAPI all
|
||||
dnscontrol get-zones -format=tsv bind BIND example.com
|
||||
dnscontrol get-zones -format=dsl -out=draft.js glcoud GCLOUD example.com`,
|
||||
|
||||
|
||||
# Example commands
|
||||
|
||||
dnscontrol get-zone
|
||||
|
||||
# Developer Note
|
||||
|
||||
This command is not implemented for all providers.
|
||||
|
||||
To add this to a provider:
|
||||
|
||||
1. Document the feature
|
||||
|
||||
In the `*Provider.go` file, change the setting to implemented.
|
||||
|
||||
* OLD: ` providers.CanGetZones: providers.Unimplemented(),`
|
||||
* NEW: ` providers.CanGetZones: providers.Can(),`
|
||||
|
||||
2. Update the docs
|
||||
|
||||
```
|
||||
go generate
|
||||
```
|
||||
|
||||
3. Implement the `GetZoneRecords` function
|
||||
|
||||
Find the `GetZoneRecords` function in the `*Provider.go` file.
|
||||
|
||||
If currently returns `fmt.Errorf("not implemented")`.
|
||||
|
||||
Instead, it should gather the records from the provider
|
||||
and return them as a list of RecordConfig structs.
|
||||
|
||||
The code to do that already exists in `GetDomainCorrections`.
|
||||
You should extract it into its own function (`GetZoneRecords`), rather
|
||||
than having it be burried in the middle of `GetDomainCorrections`.
|
||||
`GetDomainCorrections` should call `GetZoneRecords`.
|
||||
|
||||
Once that is done the `get-zone` subcommand should work.
|
||||
|
||||
4. Optionally implemement the `ListZones` function
|
||||
|
||||
If the `ListZones` function is implemented, the command will activate
|
||||
the ability to specify `all` as the zone, at which point all zones
|
||||
will be downloaded.
|
||||
|
||||
(Technically what is happening is by implementing the `ListZones`
|
||||
function, you are completing the `ZoneLister` interface for that
|
||||
provider.)
|
||||
@@ -244,9 +244,10 @@ The [Migrating]({{site.github.url}}/migrating) doc has advice
|
||||
about converting from other systems.
|
||||
You can manually create the `D()` statements, or you can
|
||||
generate them automatically using the
|
||||
[convertzone](https://github.com/StackExchange/dnscontrol/blob/master/cmd/convertzone/README.md)
|
||||
utility that is included in the DNSControl repo (it converts
|
||||
BIND-style zone files and OctoDNS-style YAML files to DNSControl's language).
|
||||
[dnscontrol get-zones]({{site.github.url}}/get-zones)
|
||||
command to import the zone from (most) providers and output it as code
|
||||
that can be added to `dnsconfig.js` and used with very little
|
||||
modification.
|
||||
|
||||
Now you can make change to the domain(s) and run `dnscontrol preview`
|
||||
|
||||
|
||||
@@ -42,34 +42,51 @@ 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 or an OctoDNS-style YAML file and outputs a `D()` statement
|
||||
that is usually fairly complete. You may need to touch it up a bit.
|
||||
The `dnscontrol get-zones` subcommand
|
||||
[documented here]({{site.github.url}}/get-zones)
|
||||
can automate 90% of the conversion for you. It
|
||||
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
|
||||
the as a `D()` statement
|
||||
that is usually fairly complete. You may need to touch it up a bit,
|
||||
especially if you use pseudo record types in one provider that are
|
||||
not supported by another.
|
||||
|
||||
The convertzone command is in the `cmd/convertzone` subdirectory.
|
||||
Build instructions are
|
||||
[here](https://github.com/StackExchange/dnscontrol/blob/master/cmd/convertzone/README.md).
|
||||
Example 1: Read a BIND zonefile
|
||||
|
||||
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.
|
||||
Most DNS Service Providers have an 'export to zonefile' feature.
|
||||
|
||||
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:
|
||||
```
|
||||
dnscontrol get-zones -format=dsl bind BIND example.com
|
||||
dnscontrol get-zones -format=dsl -out=draft.js bind BIND example.com
|
||||
```
|
||||
|
||||
convertzone -out=dsl foo.com <old/zone.foo.com >first-draft.js
|
||||
This will read the file `zones/example.com.zone`. The system is a bit
|
||||
inflexible and that must be the filename. You can copy the file to
|
||||
that name, or use a symlink.
|
||||
|
||||
If you are converting an OctoDNS file, add the flag `-in=octodns`:
|
||||
Add the contents of `draft.js` to `dnsconfig.js` and edit it as needed.
|
||||
|
||||
convertzone -in=octodns -out=dsl foo.com <config/foo.com.yaml >first-draft.js
|
||||
Example 2: Read from a provider
|
||||
|
||||
Add the contents of `first-draft.js` to `dnsconfig.js`
|
||||
This requires creating a `creds.json` file as described in
|
||||
[Getting Started]({{site.github.url}}/getting-started).
|
||||
|
||||
Suppose your `creds.json` file has the name `global_aws`
|
||||
for the provider `ROUTE53`. Your command would look like this:
|
||||
|
||||
```
|
||||
dnscontrol get-zones -format=dsl global_aws ROUTE53 example.com
|
||||
dnscontrol get-zones -format=dsl -out=draft.js global_aws ROUTE53 example.com
|
||||
```
|
||||
|
||||
Add the contents of `draft.js` to `dnsconfig.js` and edit it as needed.
|
||||
|
||||
Run `dnscontrol preview` and see if it finds any differences.
|
||||
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.
|
||||
|
||||
convertzone makes a guess at what to do with NS records.
|
||||
`dnscontrol get-zones` makes a guess at what to do with NS records.
|
||||
An NS record at the apex is turned into a NAMESERVER() call, the
|
||||
rest are left as NS(). You probably want to check each of them for
|
||||
correctness.
|
||||
@@ -81,7 +98,7 @@ 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
|
||||
If `dnscontrol get-zones` could have done a better job, please
|
||||
[let us know](https://github.com/StackExchange/dnscontrol/issues)!
|
||||
|
||||
## Example workflow
|
||||
@@ -91,7 +108,8 @@ 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 -out=dsl foo.com <old/zone.foo.com >>dnsconfig.js
|
||||
dnscontrol get-zones -format=dsl -out=draft.js bind BIND foo.com
|
||||
cat >>dnsconfig.js draft.js # Append to dnsconfig.js
|
||||
#
|
||||
dnscontrol preview
|
||||
vim dnsconfig.js
|
||||
@@ -105,4 +123,4 @@ to convert a zone. Lines that start with `#` are comments.
|
||||
vim dnsconfig.js
|
||||
dnscontrol preview
|
||||
# (repeat until all warnings/errors are resolved)
|
||||
dnscontrol push
|
||||
dnscontrol push
|
||||
|
||||
Reference in New Issue
Block a user