dyndns

README

dyndns

Automatically updates DNS records for hosts that don't have a static IP

Features

📣 Dynamically updates DNS records to match their public IP address
🏰 Built-in resiliency for different failure scenarios
🚢 Server component supports running on AWS Lambda
🚀 Dispatch update requests via AWS SQS, MQTT and/or HTTP API calls
🚏 Detect public IP address by network interface's status or by calling HTTP APIs
🎭 Runs in client / server mode to limit blast-radius of leaked credentials
🔧 Customizable list of HTTP APIs to detect IP updates
❤️ Specify HTTP APIs that detect IP updates which are preferred over other API endpoints
🔐 Messages are cryptographically signed, therefore public MQTT brokers can be used
🔑 Can use either dynamic credentials using Hashicorp Vault or static credentials
🔭 Observability through Prometheus metrics

Why would I need it?

📌 You don't have a static public IP address but want to connect to your home network
🤹 Ideally, you have multiple endpoints you want to assign DNS records to

Installation

AWS Lambda

Run the lambda-server Makefile target to build an archive for the provided.al2 Lambda runtime and the arm64 architecture. Either create a Lambda function using AWS cli / Console or run the Terraform code to create an API Gateway instance and Lambda function.

$ make lambda-server # build the server component
$ terraform -chdir=deployment/terraform/envs/dev apply # this command will deploy a dyndns-server as a Lambda function which is reachable via a new API Gateway instance
$ terraform -chdir=deployment/terraform/envs/dev output -raw gateway-url # display the url of the API endpoint

Docker / Podman

$ docker pull ghcr.io/soerenschneider/dyndns-server:main
$ docker pull ghcr.io/soerenschneider/dyndns-client:main

Binaries

Head over to the prebuilt binaries and download the correct binary for your system.

From Source

As a prerequesite, you need to have Golang SDK installed. After that, you can install dyndns from source by invoking:

$ go install github.com/soerenschneider/dyndns@latest

Configuration

Head over to the configuration section to see more details.

Getting Started

First, you need to build a keypair. This is easily done

$ docker run ghcr.io/soerenschneider/dyndns-client -gen-keypair
{"public_key":"IyXH8z/+vRsIUEAldlGgKKFcVHoll8w2tzC6o9717m8=","private_key":"h7jrhYupN0LVPnVWqFun6sN+bWNr0B0mh7/mgRaKnhsjJcfzP/69GwhQQCV2UaAooVxUeiWXzDa3MLqj3vXubw=="}

Architecture

Client Internals

Client states and client failure scenarios and their remediation is found here.

Message format

Data sent over the wire is expected to have the following format, encoded as a JSON message.

UpdateRecordRequest reference

Field Name	Description	JSON Key	Data Type	Optional
PublicIp	The resolved IP address.	"public_ip"	DnsRecord	No
Signature	The signature associated with the envelope.	"signature"	String	No

DnsRecord reference

Field Name	Description	JSON Key	Data Type	Optional
IpV4	The IPv4 address (optional).	"ipv4"	String	Yes
IpV6	The IPv6 address (optional).	"ipv6"	String	Yes
Host	The hostname associated with the resolved IP address.	"host"	String	No
Timestamp	The timestamp when the resolution occurred.	"timestamp"	Time	No

Observability

Head over to the metrics to see more details.

Changelog

The changelog can be found here