Keep your home server reachable with Dynamic DNS

This post is about a new feature for people who host their domain’s DNS with Fastmail, and it’s a technical one. You don’t need to change anything about your account or your email software, so if running your own services at home isn’t your thing, feel free to skip it.

Today we’re announcing Dynamic DNS support in Fastmail. It speaks dyndns2 at https://api.fastmail.com/dynamicdns/update, and there’s a simpler one-line variant for a self-hoster’s crontab.

The problem with a home IP address

Some customers, myself included, self-host some services at their homes. Residential ISPs typically don’t provide a static IP address. It might change daily, monthly or just often enough to be a pain. The problem this creates is you set up home.various.domains pointing at your home IP address, but eventually your IP changes and the hostname doesn’t point to you. Your NAS is still running and your home automation is still ticking, but now you can’t reach them. dyndns2 is a protocol that has solved this problem for 25 years and is supported by many home routers and popular clients such as ddclient.

Getting started

To get started, create a new API token of the Dynamic DNS type in Settings → Privacy & Security → Manage API tokens. Copy the token somewhere safe before you navigate away as it’s only shown once. Then go to Settings → Domains, click Edit next to your domain, then Customise DNS, and add a record of type Dynamic DNS with the name you want to keep up to date. The record starts out empty and is set via the API.

The security of the Dynamic DNS type

We built this as a new pseudo record type (an internal, non-standard type that resolves to an A or AAAA record), in the same vein as an ANAME record. Its value can only be set through the API, never in the web interface, so creating one is an explicit opt-in. That is what limits a Dynamic DNS token: it can only write to the records you’ve opted in, and can’t touch an A or AAAA record, your MX records or your DKIM keys. Therefore a token sitting in plain text in your basement can’t break your mail.

The dyndns2 API

If you have a dynamic DNS client on your home server, or your router supports it, you’re ready to go. Point it at https://api.fastmail.com/dynamicdns/update. dyndns2 uses HTTP Basic auth, with your Fastmail login as the username and the API token as the password. For compatibility with some older clients we also alias /nic/update to /dynamicdns/update.

Here’s a working config for ddclient 3.10.

# /etc/ddclient.conf
ssl=yes

protocol=dyndns2
server=api.fastmail.com
login=nobody@fastmail.com
password=********

home.various.domains

Substitute your own username next to login and replace the ******** with your API token, not your account password. ssl=yes is required, as we don’t want anyone sending credentials over plain text. Keep it owned by root and mode 600, since the token sits in it in plaintext.

The simple API

We added a simpler API too, for the selfish reason that some of us (me) live and die by our crontab. It’s perfect for a one-line curl entry.

*/15 * * * * curl -fsS "https://api.fastmail.com/dynamicdns/simple/home.various.domains/********/"

There’s no username required; the API token tells us which user it belongs to. The -f makes curl fail on HTTP errors and -S lets that error through, so cron only mails you when an update breaks. For convenience, omitting an IP address will set it to the request IP. Or set it explicitly, with IPv4 /dynamicdns/simple/home.various.domains/********/192.0.2.1 or IPv6 /dynamicdns/simple/home.various.domains/********/2001:db8::1.

The response body is always empty and the result is carried in the status code.

204 means the record is set, whether or not it changed
400 means we couldn’t parse the hostname or the address
401 means the token is wrong
404 means that name has no Dynamic DNS record

Why this matters if you host your DNS with us

Dynamic DNS isn’t going to improve your email, so why did we add this feature? DNS is vital for email, and these days it isn’t only MX records. It’s making sure SPF and DKIM are set up correctly too, and that list is only going to get longer. For some customers, not having Dynamic DNS support was a blocker to hosting their DNS with us. Remove that blocker and we can take care of all that complexity for you.

Dynamic DNS is available now on any domain you host with us, and our help page covers the full API.

Not a Fastmail user yet? Discover all our powerful features to make you more productive, or start your 30-day free trial today.