Painless Dynamic DNS with AWS
Nimi - Painless Dynamic DNS with AWS
Nimi is yet another self-hosted dynamic DNS solution, built using Python, AWS Route53, Lambda and API Gateway.
While there are numerous implementations of similar systems available, this project was motivated by some of the shortcomings of projects I reviewed:
- The setup process is often manual, which is tedious and error prone.
- The clients interact directly with the cloud providers API, requiring appropriate credentials to be configured on each host.
Nimi aims to be easy to setup, manage and destroy - the tool provisions and tears down all the required AWS infrastructure. The dynamic DNS client does not interact with any AWS API's directly and can be deployed on any host with a bit more peace of mind.
pip install nimi
The package will install the
nimi command line tool, which is used to setup the AWS infrastructure
with CloudFront, add and remove domains from Route53 and configure dynamic DNS hostnames. This
requires valid AWS credentials to be configured.
nimi client is for use on the hosts added to the system and don't require any AWS
credentials. Instead, it's configured with values generated during the setup.
nimi tool does not accept credentials explicitly and expects them to be configured either in
the environment or configuration file as described in the
AWS CLI documentation.
In order to use Nimi, corresponding AWS infrastructure must be provisioned first. This is done automatically using CloudFormation by invoking the following command.
Add a domain
If your domain is already configured in Route53, skip this step. Otherwise run the following command to create a new hosted zone. Once complete, the output will include a list of name servers, which you will have to configure with your domain registrar.
nimi import <domain>
Add a host
nimi client, the desired hostname has to be configured. Invoking the following
command will add the hostname to the configuration and generate a shared secret, that the client
application will use to sign requests sent to the system. The hostname can either be the root domain
or a subdomain of any domain configured in Route53.
nimi add <hostname>
nimi client subcommands do not need or use any AWS credentials. Instead, the
deployments API URL, desired hostname and shared secret have to be passed as options to the command
or set as environment variables. Each configured hostname must be paired with a unique shared
secret, while the API URL is common between them all. Invoke the following command to view said
Make note of the configured values for the hostname you added. The mapping of values to environment variables and command line options are marked below.
Set the required environment variables and run the following command on the host you want to enable dynamic DNS for.
nimi client ping
Alternatively pass the values as command line options.
nimi client ping URL HOSTNAME SECRET
ping command sends a single request to the provisioned backend. The payload includes the
desired hostname and its HMAC-SHA256 hash created using the shared secret. The backend will validate
the request by comparing the hash and update the corresponding DNS
A record if the source IP
address has changed.
Running client periodically
ping command should be run periodically on the host to ensure the DNS records stay up to date.
The client currently has no means to setup periodic execution automatically.
Users should schedule the command to be executed at a desired interval using tools available on
the hosts platform, i.e. Cron on Linux or
launchd on Mac OS.
If you wish to stop using the system, the
nimi command line tool includes commands to delete
anything you configured with it.
Remove a configured hostname, any subsequent pings will have no effect.
nimi remove <hostname>
Remove a domain from Route53 and all associated hostnames.
nimi eject <domain>
Completely remove provisioned AWS infrastructure. Does not remove any domains from Route53.
For personal use, the cost of running the system should be neglieble, but not completely free. AWS Lambda includes a geneours free tier with up to a million requests per month for free and your usage should stay well within those limits.
API Gateways free tier is only valid for the first 12 months of the account, but for a small deployment the pricing is reasonable and usually comes to about $0.02 per month for a deployment with a couple of hosts pinging every 5 to 10 minutes.
The most costly part of the deployment is Route53, which charges $0.50 per hosted zone (domain), as well as for DNS queries served, though for a personal deployment the latter should be small enough to not be reflected in the bill.
There is no reason the system couldn't support other DNS providers that are cheaper or free, if you'd like to extend support feel free to contribute.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.