Amazon_AWS_DDNS_Client

The Amazon AWS Route53 DDNS Client

Key features:

• Supports multiple domains simultaneously to the same entry point
• Supports specific URL's as well as wild cards. e.g. home.example1.com and *.example2.com
• Wild card domain mapping supports the use of reverse proxy servers to access internal services
• Multiple methods (4) are supported for specifying the AWS credentials for ease of use. See Providing the AWS Credentials below.
• Supports web hooks to monitor correct function and errors. Ideal for use with monitors such as Uptime Kuma.

History

Date	Version	Notes
27/06/2023	2.2.1.0	Added support for multiple web hooks. Built and pushed to DockerHub as https://hub.docker.com/r/kronos443/aws-route53-ddns tag V2.2.0.0 Please note, a configuration issue resulting in any domain record having an issue updating will cause the docker container to be be marked as unhealthy. Be mindful of this if your system is set to restart a container that marks itself as unhealthy since the solution may be to check the log and find any logical issues in the AWS configuration which might have caused this state rather than just restarting the container.
26/06/2023	2.2.0.1	Corrected spelling of Authorisation parameter. Built and pushed to DockerHub as https://hub.docker.com/r/kronos443/aws-route53-ddns tag V2.2.0.0 Please note, a configuration issue resulting in any domain record having an issue updating will cause the docker container to be be marked as unhealthy. Be mindful of this if your system is set to restart a container that marks itself as unhealthy since the solution may be to check the log and find any logical issues in the AWS configuration which might have caused this state rather than just restarting the container.
25/06/2023	2.2.0.0	Bug fixes and code tidy. Added catches for several issues raised but AWS service outages. Code tidy and re-structure. Corrected spelling of Authorisation parameter. Built and pushed to DockerHub as https://hub.docker.com/r/kronos443/aws-route53-ddns tag V2.2.0.0 Please note, a configuration issue resulting in any domain record having an issue updating will cause the docker container to be be marked as unhealthy. Be mindful of this if your system is set to restart a container that marks itself as unhealthy since the solution may be to check the log and find any logical issues in the AWS configuration which might have caused this state rather than just restarting the container.
15/10/2022	2.1.0.0	Added four mechanisms to provide AWS credentials Added option to put them in the .ini control file Maintained the option to add them as environment variables Added the option to load both ID and secret key from files. This is compatible when used in a container with Docker secrets. Added the option to load credentials from the AWS credentials file. This is compatible with any standard AWS BOTO3 application and allows for shared credential files. Built and pushed to DockerHub as https://hub.docker.com/r/kronos443/aws-route53-ddns tag V2.1.0.0 Please note, a configuration issue resulting in any domain record having an issue updating will cause the docker container to be be marked as unhealthy. Be mindful of this if your system is set to restart a container that marks itself as unhealthy since the solution may be to check the log and find any logical issues in the AWS configuration which might have caused this state rather than just restarting the container.
03/06/2022	2.0.0.3	Fixed potential crash on connectivity issue when obtaining the external IP address Added try catch to reading the config file Improved the docker health check to account for the update duration information Added Webhooks for alerting on errors updating and for healthy update
08/07/2021	2.0.0.2	Added support for docker health checking, if needed, using a "touched" file Added support for an environment variable, HEALTHCHECK_HEARTBEAT_FILE, defining the file path and name. Note, a failure to go round the main program loop or a configuration issue resulting in an issue updating a domain record will prevent the health check file from being "touched". Be mindful of this if your system is set to restart a conatiner that marks itself as unhealthy as the solution may be to check the log to find a logical issue in the AWS configuration which caused the condition rather than just restarting it. Added Config parameters Sleep_Time_Initial_Authorisation and Sleep_Time_Inter_Domain to control the hit rate on AWS Changes to support re-reading a config file if it's edited while the app is running. This removes the need to re-start the app/container if the configuration is changed. This is intended to harden the system and lower maintainance.

Credentials file

The AWS credentials file needs to be present on your system if you are using the forth method. Defult locations where the file will be found are:

Default locations:
Linux:

~/.aws/credentials

Windows:

C:\Users\USERNAME\.aws\credentials

Using environment variables set as follows

AWS_ACCESS_KEY_ID = XXXXXXXXXXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY = YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

Using file environment variables set as follows (using any appropriate location)

AWS_ACCESS_KEY_ID_FILE = ~/access-key-id-file
AWS_SECRET_ACCESS_KEY_FILE = ~/secret-access-key-file

Note In line with the principles of docker secrets the contents of the files should be just the string that forms the key or secret. The app will perform minor cleaning of the contents to remove white space and superfluous returns/line feeds however.

Preparation and Application Setup

The following steps should be taken when setting up this container:
Install the BOTO3 package:
On Windows

pip install boto3

Prepair an AWS key

1. Get an AWS IAM key pair
2. Enable permissions to access Route53 (and only Route53) for the key

Setup the AWS Route53 Zones and records

3. Have a functional hosted zone for your domain
4. If you want one specific URL to point to your IP set up a single A-Record such as home.yourdomain.com
5. If you want to use reverse proxy to have a number of sub-domain URLs pointing to a number of resources on your IP set up address then set up your records as listed below.

Setup the app

6. Create the configuration directory or use the working directory of the app.
7. Create the .ini file with the nessesary information.
8. Add the credentials file to your system or set the environment variables and start.

The Configuration File

A text file named AWS_Route53_DDNS.ini should be created in the /config mapped directory. This sets all the options for the program.
The log file is created in the same directory with the name AWS_Route53_DDNS.log and this file will rotate when it reaches 100KB with up to 5 logs named AWS_Route53_DDNS.log.1, AWS_Route53_DDNS.log.2 etc.

Example Configuration File

[Domains]
yourdomain.com = home.yourdomain.com
yourdomain.eu = yourdomain.eu
yourdomain.click = yourdomain.click
;
[Credentials]
;AWS_Access_Key_ID = AAAAAAAAAAAAAAAAAAAA
;AWS_Secret_Access_Key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
;AWS_Credential_Profile = Route53_User
;
[Defaults]
Update_Interval = 3600
Exception_Interval = 300
; Log_Level options are: Debug Info Warning Error Critical
Log_Level_Logfile = Info 
Log_Level_Console = Warning 
TTL = 3600
Sleep_Time_Initial_Authorisation = 1
Sleep_Time_Inter_Domain = 1
WebHook_Alive = 'HTTP://x.x.x.x/aaaaaaaaa'
WebHook_Alive1 = 'HTTP://x.x.x.x/aaaaaaaaa'
WebHook_Alive2 = 'HTTP://x.x.x.x/aaaaaaaaa'
WebHook_Alert = 'HTTP://x.x.x.x/aaaaaaaaa'
WebHook_Alert1 = 'HTTP://x.x.x.x/aaaaaaaaa'
WebHook_Alert2 = 'HTTP://x.x.x.x/aaaaaaaaa'

The Configuration File Parameters

The parameters for the configuration file are as follows.

Parameter	Status	Default	Function
[Domains] Section	Required		Any (resonable) number of lines can be included here.
Hosted zone name			The text name of the hosted zone (also called the domain name) without the trailing dot '.' that is often used to demark them.
Record name			This is the value for the corrosponding hosted zone (domain) name. See below for options on this.
[Defaults] Section	Optional
Update_Interval	Optional	3600	The interval between checking the external IP to see if the address has changed.
Exception_Interval	Optional	Update_Interval value	The checking interval after an error in obtaining the external IP or in obtailing the AWS hosted domain connection. You may wish to set this value lower than the usual update interval to resume correct mapping after a disruption to the IP address.
Log_Level_Logfile	Optional	Warning	Sets the detail and level for the file stored in the /config mapping
Log_Level_Console	Optional	Error	Sets the detail and level for the console (docker log)
			Logging levels options are :- Critical Error Warning Info Debug
TTL	Optional	3600	The time-to-live value for your entries in seconds. 1-2 hours is usual, less than 5 minutes is not recomended. Values below 60 are ignored and set to 60 seconds.
Sleep_Time_Inter_Domain	Optional	1	The time to pause between consecutive domain interrogations. Not normally required
Sleep_Time_Initial_Authorisation	Optional	1	The time to pause between Authorisation and domain interrogations. Not normally required
WebHook_Alive WebHook_Alive1 WebHook_Alive2 . WebHook_Alive9	Optional	-	The given URL is called when the update of all records was successful. URL's may be quoted. Up to 10 web hooks are supported by adding options WebHook_Alive1, WebHook_Alive2, ... to WebHook_Alive9
WebHook_Alert WebHook_Alert1 WebHook_Alert2 . WebHook_Alert9	Optional	-	The given URL is called when the update of any record was unsuccessful. URL's may be quoted. Up to 10 web hooks are supported by adding options WebHook_Alert1, WebHook_Alert2, ... to WebHook_Alert9
[Credentials] Section	Optional
AWS_Access_Key_ID AWS_Secret_Access_Key	Optional	-	Used only if specifying credentials in the .ini file.
AWS_Credential_Profile	Optional	Route53_User	Used only if specifying credentials using the AWS credentials file. If the profile named is not found the app will fall back to trying to use the 'default' profile.

The example file above shows two main options for configuring an address. The first updates a specific A record in the hosted domain so that home.yourdomain.com is given the external IP address. This is the most simple case and you must create an A-Record with the name home.yourdomain.com in AWS before it can be updated.

The second and third lines show a more flexible option that would allow you to create multiple sub-domain mappings to resources within your network using reverse proxy. To make this work you must create an A-Record within you hosted zone (domain) called yourdomain.click and then a second A-Record called *.yourdomain.click that has a value of yourdomain.click. This will cause any DNS request for sub-domains of this address such as voip.yourdomain.click or sonarr.yourdomain.click to be mapped through to the IP address set up in the yourdomain.click A-Record.

If you find this container useful then please consider buying me a coffee by following this link or scanning the QR below. :)