This is a tool that will read a local file in /etc/hosts format and
synchronize the contents of that file to a specific domain in AWS Route 53.
The contents of the /etc/hosts file can be filtered such that only records in
specific networks will be synchronized. By default the program will run
continuously, detecting changes in the hosts file automatically via inotify and
running periodic syncs to clean up any rogue Route 53 changes.
This was written to be used on Ubiquiti EdgeOS devices like the EdgeRouter Lite. This can be useful if you have public IP ranges hosted behind your router, or if you have a VPN connection into the a private network. This will allow you to use any DNS caching resolver, instead of forcing DNS resolution through a private DNSMasq instance.
There is nothing inherently specific to EdgeOS in this project, so if you need
something to sync an /etc/hosts file to Route53 once, or on a regular basis,
this might work well for you.
-
The local hosts file given is considered to be the source of truth for the networks you specify to be managed. Changes in Route 53 that don't match what is in the hosts file will be removed or overwritten.
-
Host aliases in the input file are ignored. Entries in
/etc/hostson EdgeOS devices that are added via DHCP never have alias entries. -
This app is written in Go, mostly because it generates binaries with no dependencies and it makes cross compiles for other architectures easy.
-
Binaries can be found on the GitHub releases page
-
MIPS64 binaries are built and available on the GitHub releases page, but aren't recommended. When tested on EdgeOS 1.9.1, inotify does not appear to work with the MIPS64 binary, but does work with the MIPS (32 bit) build. In addition, when testing this in QEMU w/MIPS64, the binary just crashes on startup in the Golang GC code.
This program uses the official AWS golang
libary. Because of this, any of the normal
methods of storing credentials for AWS that work with the CLI tools should work
for this program. For example, you can set and export the AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY environment variables. More information can be
found in the "SDK Configuration"
section of the library documentation.
It is recommended that you set up an AWS IAM user specifically to be used with this program. That IAM user should be limited to only be able to add and remove records in Route 53. If you have multiple domains, you may wish to limit that user to just the specific domain you wish to synchronize against.
Use sync-hosts-to-route53 --help for a complete list of available options.
The options available include:
This options must be either oneshot or daemon. The default is daemon.
When run with --mode daemon or no --mode argument, the program will
synchronize the host file with Route 53 once, then setup inotify watches for
the host file, and synchronize automatically by default every 15 minutes.
When run with --mode oneshot the program will synchronize the host file
given with Route 53 once, then exit.
This specifies the local hosts file to keep in sync with Route 53. This should
be in the format of UNIX style /etc/hosts file. This defaults to
/etc/hosts.
This option will direct the program to ignore all host entries in the local
file, or in the Route 53 domain that are not inside of the network blocks
given. This option is required and can be specified more than once. If you
wish to affect all entries in the domain, then you can specify 0.0.0.0/0
to match all IP addresses.
This specifies the Route 53 domain to synchronize with the local hosts file. This option is required and has no default.
How often to run the synchronization, even if no changes have been detected in the local hosts file. Local changes should be detected automatically, so this mostly serves to correct any changes made in Route 53 that don't match the local file. This defaults to 15 minutes. This is ignored in oneshot mode.
This is the DNS record TTL in seconds to set on new Route 53 records. This defaults to 3600 seconds, or one hour.
By default the Route53 domain will be appended to the end of any host file
entries that appear to be lacking it. To disable this behavior, specify
--no-qualifiy-hosts.
Exclude specific hosts from being synced to Route53. This can be used to prevent manually created items from being deleted during the sync process. This can be specified multiple times.
By default the program will wait for Route 53 updates to propagate after
submitting them. To disable this behavior, specify --no-wait.
Enable logging to syslog in addition to stdout.
Syslog facility to log to. Defaults to user. See syslog(3) for list of
options.
Log just to syslog, skipping stdout entirely. If this is specified then
--syslog is implied. Note a single message will be logged to stdout
indicating all further output will go to syslog.
Enable debug level logging.
Print version to stdout and exit.
Print summary of these options
Dependencies for this project are managed using go mod
To build binaries for all platforms (used for releases), run make build-all-arch.
Clayton O'Neill clayton@oneill.net