• Stars
    star
    560
  • Rank 79,541 (Top 2 %)
  • Language
    Go
  • Created over 10 years ago
  • Updated over 8 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

DNS server that lets you look up ec2 instances by instance name

A DNS server that serves up your ec2 instances by name.

Usage

aws-name-server --domain aws.bugsnag.com \
                --aws-region us-east-1 \
                --aws-access-key-id <access_key> \
                --aws-secret-access-key <secret_key>

This will serve up DNS records for the following:

  • <name>.aws.bugsnag.com all your EC2 instances tagged with Name=<name>
  • <n>.<name>.aws.bugsnag.com the nth instances tagged with Name=<name>
  • <role>.role.aws.bugsnag.com all your EC2 instances tagged with Role=<role>
  • <n>.<role>.role.aws.bugsnag.com the nth instances tagged with Role=<role>
  • <instance-id>.aws.bugsnag.com all your EC2 instances by instance id.
  • <n>.<instance-id>.aws.bugsnag.com all your EC2 instances by instance id.

It uses CNAMEs so that instances will resolve to internal IP addresses if you query from inside AWS, and external IP addresses if you query from the outside.

Quick start

There's a long-winded Setup guide, but if you already know your way around EC2, you'll need to:

  1. Open up port 53 (UDP and TCP) on your security group.
  2. Boot an instance with an IAM Role with ec2:DescribeInstances permission. (or use an IAM user and configure aws-name-server manually).
  3. Install aws-name-server.
  4. Setup your NS records correctly.

Parameters

--domain

This is the domain you wish to serve. i.e. aws.example.com. It is the only required parameter.

--hostname

The publically resolvable hostname of the current machine. This defaults sensibly, so you only need to set this if you see a warning in the logs.

--aws-access-key-id and --aws-secret-access-key

An Amazon key pair with permission to run ec2:DescribeInstances. This defaults to the IAM role of the machine running aws-name-server or to the values of the environment variables $AWS_ACCESS_KEY_ID and $AWS_SECRET_ACCESS_KEY (or $AWS_ACCESS_KEY and $AWS_SECRET_KEY).

--aws-region

This defaults to the region in which aws-name-server is running, or us-east-1.

Setup

These instructions assume you're going to launch a new EC2 instance to run aws-name-server. If you want to run it on an existing server, adapt the instructions to suit.

1. Create an IAM role

IAM Roles let you give EC2 instances permission to access the AWS API. We will need our dns machine to run ec2:DescribeInstances.

  1. Log into the AWS web console and navigate to IAM.

  2. Create a new role called iam-role-aws-name-server

  3. Select the Amazon EC2 role type.

  4. Create a Custom Policy called describe-instances-only with the content:

    {
      "Version": "2012-10-17",
      "Statement": [{
        "Action": ["ec2:DescribeInstances"],
        "Effect": "Allow",
        "Resource": "*"
      }]
    }
    

2. Create a security group

Security groups describe what traffic is allowed to get to your instance. DNS servers use UDP port 53 and TCP port 53.

  1. Log into the AWS web console and navigate to EC2.

  2. Create a new security group called aws-name-server

  3. Configure it to have:

    # Type   # Protocol  # Port  # Source
    SSH      TCP         22      My IP     x.x.x.x/32
    DNS      UDP         53      Anywhere  0.0.0.0/0
    Custom   TCP         53      Anywhere  0.0.0.0/0
    

This will let you ssh in to the DNS server, and let anyone run DNS queries.

3. Launch an instance

I recommend running 64bit HVM-based EBS-backed Ubuntu 14.04 on a t2.micro (ami-acff23c4). You can use whatever distro you like the most.

  1. Log into the AWS web console and navigate to EC2.
  2. Click "Launch Instance"
  3. Select your favourite AMI (e.g. ami-acff23c4).
  4. Select your favourite cheap instance type (e.g. t2.micro) (If you don't have VPCs yet, choose t1.micro instead)
  5. Set IAM role to iam-role-aws-name-server
  6. Skip through disks (the default is fine)
  7. Skip through tags (though if you set Name=dns1 and Role=dns you can test the server :)
  8. Select an existing security group sg-aws-name-server.
  9. Launch!

4. Install the binary

  1. Download the latest version.

    wget http://gobuild.io/github.com/ConradIrwin/aws-name-server/master/linux/amd64 -O aws-name-server.zip
    unzip aws-name-server.zip
    
  2. Move the binary into /usr/bin.

    sudo cp aws-name-server /usr/bin
    sudo chmod +x /usr/bin/aws-name-server
    
  3. (optional) Set the capabilities of aws-name-server so it doesn't need to run as root.

    # the cap_net_bind_service capability allows this program to bind to ports below 1024
    # when it us run as a non-root user.
    sudo setcap cap_net_bind_service=+ep /usr/bin/aws-name-server
    

5. Configure upstart.

If you use upstart (the default process manager under ubuntu) you can use the provided upstart script. You'll need to change the script to reflect your hostname:

  1. Open upstart/aws-name-server.conf and change --domain=internal to --domain <your-domain>
  2. sudo cp upstart/aws-name-server.conf /etc/init/
  3. sudo initctl start aws-name-server

6. Configure NS Records

To add your DNS server into the global DNS tree, you need to add an NS record from the parent domain to your new server.

Let's say you currently have DNS for example.com, and you're running aws-name-server on the machine ec2-12-34-56-78.compute-1.amazonaws.com. In the admin page for example.coms DNS add a new record of the form:

# name             # ttl            # value
aws.example.com    300    IN   NS   ec2-12-34-56-78.compute-1.amazonaws.com

The TTL can be whatever you want, I like 5 minutes because it's not too long to wait if I make a mistake.

The value should be a hostname for your server that is directly resolvable (i.e. not a CNAME). The public hostnames that Amazon gives instances are perfect for this.

Troubleshooting

There's a lot that can go wrong, so troubleshooting takes a while.

Did it start?

First try looking in the logs (/var/log/upstart/aws-name-server.log if you're using upstart). If there's nothing there, then try /var/log/syslog.

Is it running?

Try running dig dns1.aws.example.com @localhost while ssh'd into the machine. It should return a CNAME record. If not, look in the logs, the chances are the DNS server is not running. This happens if your EC2 credentials are wrong.

Is the security group configured correctly?

Assuming you can make DNS lookups to localhost, try running dig dns1.aws.example.com @ec2-12-34-56-78.compute-1.amazonaws.com from your laptop. If you don't get a reply, double check the security group config.

Are the NS records set up correctly?

Assuming you can make DNS lookups correctly when pointing dig at the DNS server, try running dig NS aws.example.com. If this doesn't return anything, you probably need to update your NS records. If you've already done this, you might need to wait a few minutes for caches to clear.

Are you getting a warning about NS records in the logs but everything seems fine?

This happens when the --hostname parameter has been set or auto-detected to something different from what you've configured the NS records to be. This may cause hard-to-debug issues, so you should set --hostname correctly.

More Repositories

1

pry-rescue

Start a pry session whenever something goes wrong.
Ruby
850
star
2

showterm

The rubygem to upload to http://showterm.io
Ruby
600
star
3

vim-bracketed-paste

Handles bracketed-paste-mode in vim (aka. automatic `:set paste`)
Vim Script
481
star
4

showterm.io

The website for showterm!
JavaScript
354
star
5

async-profile

Asynchronous CPU profiling for node
CoffeeScript
264
star
6

dotgpg

A secure and easy-to-use store for your production secrets
Ruby
162
star
7

jist

Jist just gists
Ruby
160
star
8

git-aliae

Random git stuff....
Shell
81
star
9

console.log

Log to the Javascript console from ruby.
Ruby
79
star
10

font

golang parser for OpenType files.
Go
70
star
11

em-imap

An event machine based IMAP client
Ruby
69
star
12

lspace

Safe operation-local global variables!
Ruby
62
star
13

pry-debundle

Allows you to use gems not in your Gemfile from Pry.
Ruby
50
star
14

gpg-decoder

A port of the awesome ASN.1 Javascript Decoder for GPG messages
JavaScript
44
star
15

ruby-source_map

A Ruby library for interacting with the awesome javascript SourceMaps.
Ruby
40
star
16

trie-ing

The fastest weighted auto-completion trie known to...
JavaScript
33
star
17

unicode-dragon

Eats invalid unicode for breakfast.
JavaScript
25
star
18

interception

Listen to raise in ruby
Ruby
24
star
19

twitter-followers

A tool to download all a user's twitter followers
Go
22
star
20

http_load

hard-core HTTP load tester from http://acme.com/software/http_load/
C
20
star
21

pry-syntax-hacks

Some syntactic "high fructose corn syrup"s for pry.
Ruby
16
star
22

zepto-ghostclick

A Zepto plugin to help avoid ghost clicks
JavaScript
14
star
23

rfc2047-ruby

An RFC 2047 compliant email header parser
Ruby
11
star
24

motion-rubygems

Very very broken support for rubygems in RubyMotion
Ruby
11
star
25

pry-highlight

Highlights strings in pry output
Ruby
9
star
26

cap-runit

Capistrano 3 runit support
Ruby
9
star
27

gotar

A replacement for `go build` that includes static assets
Go
9
star
28

cause

A backport of Exception#cause from Ruby-2.1.0
Ruby
9
star
29

golo

defer go compile errors to runtime
Go
8
star
30

pry-em

Playing with async stuff is as easy as pry!
Ruby
8
star
31

ruby18_source_location

Giving Ruby 1.8.7 a chance to join in the #source_location fun.
Ruby
8
star
32

conradirwin.github.com

My Blog.
HTML
6
star
33

mongoid-rails

Strong parameters integration with mongoid
Ruby
6
star
34

yada_yada

A reimplementation of perl's Yada Yada operator in ruby!
Ruby
6
star
35

pry-capture

The old version of pry-rescue!
Ruby
5
star
36

encoding-codepage

A rubygem that lets you look up encodings by Microsoft® Code Page Identifier
Ruby
5
star
37

thin-attach_socket

Adds Thin::Backend::AttachSocket for running thin behind einhorn
Ruby
4
star
38

vim-comment-object

Perform actions on an entire comment.
Vim Script
4
star
39

wiktionary

A python library for playing with Wiktionary
Python
4
star
40

go-dwarf

DWARF debugging data parser in go
Go
4
star
41

self

Provides debug-access to private methods and instance variables of ruby Objects
Ruby
4
star
42

optimistic_dev

An optimistic developer twitter persona!
Go
4
star
43

secure_equals

Constant time equality for ruby.
Ruby
4
star
44

canvas-animation-loader

GPU-accelerated canvas animations in webpack
JavaScript
3
star
45

rbenv-all

Provides "rbenv all" for running one command against all your rubies
Shell
3
star
46

p_enwikt

git fork of https://fisheye.toolserver.org/browse/enwikt/
Perl
3
star
47

git-fetch-series

A tool to let you download patches from the git mailing list.
Python
3
star
48

c_location

source_location for methods written in C (Method#c_location)
Ruby
3
star
49

autoconfig.mozillamessaging.com

Mirror of http://svn.mozilla.org/mozillamessaging.com/sites/autoconfig.mozillamessaging.com, Mozilla's ISPDB
DIGITAL Command Language
3
star
50

pry-lexer

A pygments lexer for pry sessions!
Python
3
star
51

proxies

Ruby
2
star
52

jslint-node

Run jslint with node
JavaScript
2
star
53

mruby-example

"Hello world!" executable with mruby
Ruby
2
star
54

bisect

Library for maintaining sorted Arrays borrowed from Python
Ruby
2
star
55

go-for-rubyists

Go for rubyists, a tech talk.
JavaScript
2
star
56

amfs

Go
2
star
57

fireplace

Go
2
star
58

howtobuilda.bike

A writeup of building a bike
CSS
2
star
59

Commune

Ruby
2
star
60

libxml2

My fork of git://git.gnome.org/libxml2
C
2
star
61

motion-rubygems-example

An example project that uses motion-rubygems
Ruby
2
star
62

better-gmail

clean up gmail interface
JavaScript
1
star
63

node-zset

Disk backed semi-sorted sets
CoffeeScript
1
star
64

test

1
star
65

bytes

A small utility for dealing with raw bytes
Go
1
star
66

cap3-elb

Capistrano commands for managing your ELB.
Ruby
1
star
67

qrcode-raplet

A raplet to make it easier to phone people
JavaScript
1
star
68

udt

Ideas for CRDTs
Go
1
star
69

mrsa

Mediated RSA in golang
Go
1
star
70

em-monitor

For monitoring the distribution of CPU-spans in your event machine reactor thread.
Ruby
1
star
71

parallel

Structured concurrency for go
Go
1
star
72

browser-action-open

JavaScript
1
star
73

plotocrat

Automatically plot probability distributions
JavaScript
1
star
74

code-point-mapping

Map between javascript string indices and unicode code point offsets effectively
TypeScript
1
star
75

ggg

An experimental self-hosted debugger for go
Go
1
star
76

music

LilyPond
1
star
77

source_map-jsmin

A Source Map enabled pure-ruby version of Doug Crockford's awesome jsmin
JavaScript
1
star
78

goer

Some people like to browse, other's prefer to go directly.
JavaScript
1
star
79

introducing-teacup

The really simple sample app created in http://cirw.in/blog/introducing-teacup
Ruby
1
star
80

beamer-bootstrap

A bootstrap for beamer presentations that include code and images.
C
1
star
81

airpad

An iPad client for the awesome http://airbrake.io/
Objective-C
1
star
82

tracing-bug

Rust
1
star
83

lxterminal-clicky

A terminal emulator you can click on
C
1
star