This is a simple controller, that discovers the public IP address of the node where it's running from (using the ipify API), and creates an A record pointing to that public IP address. It currently supports two DNS providers: Route 53 and Cloudflare.
The value of the controller is to create a consistent hostname that can be used in cases where acquiring a fixed IP address is not practical.
Although this can be run as a one-off Go script, the intended design is to run it as a Docker container (optimally, in Kubernetes or other container orchestration platform) and it will continuously keep a record updated with the value of the public IP address of your home router, which may change after a reboot.
Exposing your home network to the internet will always be a risk. Only use this if you're aware of what you're doing and you have taken the appropriate steps to mitigate the risk, like protecting your home network with a firewall, or routing the traffic through a CDN (Content delivery network).
| Command-line argument | Default | Description |
|---|---|---|
-provider |
DNS provider where the record will be created. Valid values are: route53 and cloudflare |
|
-route53-hosted-zone-id |
Route 53 hosted zone id | |
-cloudflare-zone-name |
Cloudflare zone name | |
-cloudflare-proxied |
false |
Set to true if Cloudflare requests to this hostname will be proxied through Cloudflare |
-record-name |
DNS record name | |
-ttl |
60 | DNS record TTL |
-sync-period-minutes |
15 | The amount of time, in minutes, to wait between syncs |
The controller will need AWS credentials and will discover them using the default credential provider chain, so they can either use static credentials provisioned manually, or another dynamic credential injection mechanism, such as Vault's AWS Secrets Engine, kube2iam, kiam, etc., depending on the runtime.
The only permission required is route53:ChangeResourceRecordSets.
The Cloudflare credentials are injected via environment variables. The controller only supports Cloudflare API tokens (as opposed to email/token combinations). The environment variable CLOUDFLARE_API_TOKEN should be set to the value of the token to be used.
It should have Edit - DNS Zone permissions.
The Notary project is a CNCF incubating project that aims to provide trust and security to software distribution. Docker Hub runs a Notary server at https://notary.docker.io for the repositories it hosts.
Docker Content Trust is the mechanism used to verify digital signatures and enforce security by adding a validating layer.
You can inspect the signed tags for this project by doing docker trust inspect --pretty docker.io/patoarvizu/residential-dns, or (if you already have notary installed) notary -d ~/.docker/trust/ -s https://notary.docker.io list docker.io/patoarvizu/residential-dns.
If you run docker pull with DOCKER_CONTENT_TRUST=1, the Docker client will only pull images that come from registries that have a Notary server attached (like Docker Hub).
In addition to the digital validation done by Docker on the image itself, you can do your own human validation by making sure the image's content matches the Git commit information (including tags if there are any) and that the GPG signature on the commit matches the key on the commit on github.com.
For example, if you run docker pull patoarvizu/residential-dns:379621f0660bf65242afb77b14198fabc32be0a9 to pull the image tagged with that commit id, then run docker inspect patoarvizu/residential-dns:379621f0660bf65242afb77b14198fabc32be0a9 | jq -r '.[0].Config.Labels' (assuming you have jq installed) you should see that the GIT_COMMIT label matches the tag on the image. Furthermore, if you go to https://github.com/patoarvizu/residential-dns/commit/379621f0660bf65242afb77b14198fabc32be0a9 (notice the matching commit id), and click on the Verified button, you should be able to confirm that the GPG key ID used to match this commit matches the value of the SIGNATURE_KEY label, and that the key belongs to the AUTHOR_EMAIL label. When an image belongs to a commit that was tagged, it'll also include a GIT_TAG label, to further validate that the image matches the content.
Keep in mind that this isn't tamper-proof. A malicious actor with access to publish images can create one with malicious content but with values for the labels matching those of a valid commit id. However, when combined with Docker Content Trust, the certainty of using a legitimate image is increased because the chances of a bad actor having both the credentials for publishing images, as well as Notary signing credentials are significantly lower and even in that scenario, compromised signing keys can be revoked or rotated.
Here's the list of included Docker labels:
AUTHOR_EMAILCOMMIT_TIMESTAMPGIT_COMMITGIT_TAGSIGNATURE_KEY
Manifests published with the semver tag (e.g. patoarvizu/residential-dns:v0.0.0), as well as latest are multi-architecture manifest lists. In addition to those, there are architecture-specific tags that correspond to an image manifest directly, tagged with the corresponding architecture as a suffix, e.g. v0.0.0-amd64. Both types (image manifests or manifest lists) are signed with Notary as described above.
Here's the list of architectures the images are being built for, and their corresponding suffixes for images:
linux/amd64,-amd64linux/arm64,-arm64linux/arm/v7,-arm7