search

cunnie / sslip.io

Golang-based DNS server which maps DNS records with embedded IP addresses to those addresses.
Apache License 2.0
646 stars 77 forks source link
dns-server

readme

sslip.io

Test Type Status
Production Nameservers ci.nono.io
DNS Server Unit Tests ci.nono.io

sslip.io is a DNS server that maps specially-crafted DNS A records to IP addresses (e.g. "127-0-0-1.sslip.io" maps to 127.0.0.1). It is similar to, and inspired by, xip.io.

If you'd like to use sslip.io as a service, refer to the website (sslip.io) for more information. This README targets developers; the website targets users.

Quick Start

git clone https://github.com/cunnie/sslip.io.git
cd sslip.io
go mod tidy
sudo go run main.go
 # sudo is required on Linux, but not on macOS, to bind to privileged port 53

In another window:

dig @localhost 192.168.0.1.sslip.io +short
 # should return "192.168.0.1"

Quick Start Tests

go mod tidy
go generate
ginkgo -r -p .

Running Your Own Nameservers

We can customize our nameserver and address records (NS, A, and AAAA), which can be particularly useful in an internetless (air-gapped) environment. This can be done with a combination of the -nameservers flag and the -addresses flag.

For example, let's say we're the DNS admin for pivotal.io, and we'd like to have a subdomain, "xip.pivotal.io", that does sslip.io-style lookups (e.g. "127.0.0.1.xip.pivotal.io" would resolve to "127.0.0.1"). Let's say we have two servers that we've set aside for this purpose:

First, we delegate the subdomain "xip.pivotal.io" to our two nameservers, and then we run the following command run on each of the two servers:

# after we've cloned our repo & cd'ed into it
go run main.go \
  -nameservers=ns-sslip-0.pivotal.io,ns-sslip-1.pivotal.io \
  -addresses ns-sslip-0.pivotal.io=10.8.8.8,ns-sslip-1.pivotal.io=fc88::

Note: These nameservers are not general-purpose nameservers; for example, they won't look up google.com. They are not recursive. Don't ever configure a machine to point to these nameservers.

Running with Docker

Probably the easiest way to run the nameserver is with the official Docker image, cunnie/sslip.io-dns-server:

docker run \
  -it \
  --rm \
  -p 53:53/udp \
  cunnie/sslip.io-dns-server

If we see the error, "Error starting userland proxy: listen udp4 0.0.0.0:53: bind: address already in use.", we turn off the systemd resolver: sudo systemctl stop systemd-resolved

Let's try a more complicated setup: we're on our workstation, jammy.nono.io, whose IP addresses are 10.9.9.114 and 2601:646:0100:69f0:0:ff:fe00:72. We'd like our workstation to be the DNS server:

docker run \
  -it \
  --rm \
  -p 53:53/udp \
  cunnie/sslip.io-dns-server \
    -nameservers jammy.nono.io \
    -addresses jammy.nono.io=10.9.9.114,jammy.nono.io=2601:646:100:69f0:0:ff:fe00:72

From another machine, we look up the DNS NS record for "127.0.0.1.com", and we see the expected reply:

dig ns 127.0.0.1.com @jammy.nono.io +short
...
  ;; ANSWER SECTION:
  127.0.0.1.com.        604800  IN  NS  jammy.nono.io.

  ;; ADDITIONAL SECTION:
  jammy.nono.io.        604800  IN  A   10.9.9.114
  jammy.nono.io.        604800  IN  AAAA    2601:646:100:69f0:0:ff:fe00:72

The Docker image is multi-platform, supporting both x86_64 architecture as well as ARM64 (AWS Graviton, Apple M1/M2).

Command-line Flags

DNS Server Miscellany

Directory Structure

Acknowledgements