ezdyn

Gem library and command line tool for Dyn Managed DNS API access.

See https://help.dyn.com/dns-api-knowledge-base/

Installation

$ rake gem:install

Command Line Usage

Use the ezdyn tool installed with the gem to make one-off or batched DNS changes from the command line.

See ezdyn --help for all options. Use command line flags or environment variables (see below) for authentication.

Important options include:

  • --file <filename> provide a file of commands, one per line
  • --apply: apply changes when done (default is dry-run mode)
  • --check: check syntax only (does not connect to API or need credentials)

If --file is not specified, commands are read from the command line arguments. Each ezdyn command must be enclosed in quotes to distiguish it from other commands.

Command syntax

There are three possible commands:

  • create <type> <fqdn> <value> [<ttl>]
  • upsert <type> <fqdn> <value> [<ttl>]
  • delete <type> <fqdn>

The ttl field is always optional. You may use update as well as upsert, but both commands will create a record if it does not exist, and update an existing record if it does exist.

Examples

You can issue commands directly from the command line.

To perform a dry-run of creating a new A record:

$ ezdyn "create A test.example.com 192.168.0.1"

To check the syntax (requiring no API interaction) on creating two CNAME records:

$ ezdyn --check "create cname test1.example.com other1.example.com" \
                "create cname test2.example.com other2.example.com"

To actually update/upsert an A record:

$ ezdyn "update A test3.example.com 10.0.0.10" --apply

To process a list of commands from a file:

$ ezdyn --file dns-changes.txt

Where dns-changes.txt may look like:

create A web1.example.com 10.1.100.1 600
create A web2.example.com 10.1.200.1 1200
create A web3.example.com 192.168.0.2 30
delete ALL oldweb.example.com

Notes

  • Dry runs do interact with the Dyn API. This is useful to check for the validity of your changes before making them.
  • ezdyn does not yet deal correctly with multiple records on a single node. Delete operations will delete multiple records on a node, but create and update operations should bail and complain about multiple records.
  • Exception handling is poor at the moment, so when things go wrong it might look ugly, but most dangerous situations should be prevented.
  • Only A and CNAME records are supported at present.

Library Usage

require 'ezdyn'

# create new client object using explicit vars
dyn = EZDyn::Client.new(customer_name: customer_name,
                        username: username,
                        password: password)

# (or create one using environment variables (see below)
dyn2 = EZDyn::Client.new

# create a new A record
# (login step is implicit in first access)
dyn.create(type: "A",
           fqdn: "website.example.com",
           value: "10.0.0.1")

# no wait, take that back
dyn.rollback

# delete any CNAME records for alias.example.com
dyn.delete_all(type: "cname", fqdn: "alias.example.com")

# update the A record for mail.example.com, or, if it
# does not exist, create it with the given value and ttl
dyn.update(type: :a,
           fqdn: "mail.example.com",
           value: "10.0.0.2",
           ttl: 600)

# print all pending changes
puts "Pending changes:"
dyn.pending_changes.each do |pc|
  puts "  #{pc}"
end

# commit all changes (with optional zone update message)
dyn.commit(message: "Just an example")

# close session (it will time out after 60 minutes)
dyn.logout

Environment Variables

You may specify the customer_name, username, and password parameters via environment variables:

  • DYN_CUSTOMER_NAME
  • DYN_USERNAME
  • DYN_PASSWORD

You may also enable verbose debug logging by setting EZDYN_DEBUG to any value.

API Documentation

You can generate the YARD docs for the library by running rake docs. Then open doc/index.html in your web browser.

TODO

  • Implement actual Exception classes
  • Fewer exceptions should be raised overall
  • Support additional record types (esp MX, AAAA)
  • Mock API endpoint for testing, also actual tests