dockerhub.txt

<h1>Amazon AWS Route53 Dynamic DNS Client</h1>
<h3><b>Key features:</b>
<ul>
  <li>Supports multiple domains simultaneously to the same entry point</li>
  <li>Supports specific URL's as well as wild cards. e.g. home.example1.com and *.example2.com </li>
  <li>Wild card domain mapping supports the use of reverse proxy servers to access internal services</li>
  <li>Multiple methods (4) are supported for specifying the AWS credentials for ease of use. See <i>Providing the AWS Credentials</i> below.</li>
  <li>Up to 10 web hooks to monitor correct function and errors. Ideal for use with monitors such as Uptime Kuma.</li>
</ul>
</h3>
Developed using Python and Amazon's BOTO3 library this container will update one or more A records in multiple hosted zones with the locally detected external IP address.

Please see:

> https://github.com/ArthurMitchell42/Amazon_AWS_DDNS_Client

> https://github.com/ArthurMitchell42/AWS_Route53_DDNS_Docker

<h2>Supported Architectures</h2>
<p>
Currently supports  AMD64 (developed on windows and the Synology DS918+ NAS),  ARM32 V7 (armhf) (suitable for running on docker under Raspberry PI 32-bit OS) & ARM64 (ARM64V8) (suitable for running on docker under Raspberry PI with a 64-bit OS such as Raspberry PI OS 64-bit and Ubuntu 64-bit)   
<br>

<table>
<thead>
<tr bgcolor="lightblue"><th align="center">Architecture</th>
<th>Tag</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center">AMD64</td>
<td>latest-amd64 For PC and Synology DSM</td>
</tr>
<tr>
<td align="center">ARM32V7 (armhf 32-bit)</td>
<td>latest-arm32v7 For Raspberry PI with a 32-bit OS</td>
</tr>
<tr>
<td align="center">ARM64V8 (ARM64)</td>
<td>arm64v8-latest. For Raspberry PI with a 64-bit OS (RaspberryPI OS 64-bit or Ubuntu 64-bit</td>
</tr>
</tbody></table>
Going forward I'll be focusing on 64-bit containers for security reasons.

<h2>History</h2>
See the app readme.md information at <a href="https://github.com/ArthurMitchell42/Amazon_AWS_DDNS_Client">GitHub</a><br>

<table>
<thead>
<tr bgcolor="lightblue"><th align="center">Date</th>
<th>Version</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td align="top">27/06/2023</td>
<td align="left">2.2.1.0</td>
<td align="left">
<ol>
    <li>Added support for 10 optional web hooks in the configuration file.</li>
    <li>Re-based image to the Python-Alpine image to halve the size of the image.</li>
    <li>Bug fixes including catching errors from AWS service outages.</li>
</ol>
<b><i>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.</b></i>
</td>
</tr>
<tr>
<td  align="top">15/10/2022</td>
<td align="left">2.1.0.0</td>
<td align="left">
<ol>
<li>Added support for multiple methods (four ways) of specifying the AWS credentials, either via environment variables, the configuration file, docker secrets or the AWS credentials file for convienience.</li>
</ol>
</td>
</tr>
<tr>
<td align="left">03/06/2022</td>
<td align="left">2.0.0.3</td>
<td align="left">
  <ol>
<li>Fixed potential crash on connectivity issue when obtailing the external IP address</li>
<li>Added try catch to reading the config file</li>
<li>Improved the docker health check to account for the update duration information</li>
<li>Added Webhooks for alerting on errors updating and for healthy update</li>
  </ol>
</tr>
<tr>
<td align="left">8/7/21</td>
<td align="left">2.0.0.2</td>
<td align="left">
  <ol>
  <li>Added support for docker health checking</li>
  <li><b>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.</b></li>
  <li>Added Config parameters Sleep_Time_Initial_Autherisation and Sleep_Time_Inter_Domain to control the hit rate on AWS</li>
  <li>Changes to support re-reading a config file if it's edited while the container is running. This removes the need to re-start the container if the configuration is changed. This is intended to harden the system and lower maintainance.</li>
  </ol>
</td>
</tr>
</tbody></table>

<h2>PLEASE NOTE</h2>
<b>The current Raspberry PI 32-bit OS based on Buster has a bug in the libseccomp library.</b>

Please see this note: https://docs.linuxserver.io/faq#libseccomp

If you wish to use the ARM32V7 image on a 32-bit Raspberry PI OS you have 2 options:

<ol>
  <li>Run the container as privelidged (Not generally recommended)</li>
  <li>Follow the link above to the Linuxserver team's documents and follow option 2 (My personal preference, although I haven't tested the other option.) to update your docker host Raspberry PI</li>
</ol>

This should instantly fix this, and any other "funnies" you are having with docker containers.

<h2>Preparation and Application Setup</h2>
<p>
The following steps should be taken when setting up this container:<br>
<h3>Prepair an AWS key</h3>
<ol>
  <li>Get an AWS IAM key pair</li>
  <li>Enable permissions to access Route53 (and only Route53) for the key</li>
</ol>

<h3>Setup the AWS Route53 Zones and Records</h3>
<ol start="3">
  <li>Have a functional hosted zone for your domain</li>
  <li>If you want one specific URL to point to your IP set up a single A-Record such as <b><i>home.yourdomain.com</b></i></li>
  <li>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.</li>
</ol>

<h3>Setup the container</h3>
<ol start="6">
  <li>Create the configuration directory on the mapped docker share directory.</li>
  <li>Create the .ini file with the nessesary information in the mapped docker share directory.</li>
  <li>Add the container to your system and start.</li>
</ol>
</p>

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

<h3>Example Configuration File</h3>
<tt><pre>[Domains]
yourdomain.com = home.yourdomain.com
yourdomain.eu = yourdomain.eu
yourdomain.click = yourdomain.click

[Credentials]
; See notes below on the four methods of providing credentials
;AWS_Access_Key_ID = AAAAAAAAAAAAAAAAAAAAAA
;AWS_Secret_Access_Key = BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB
;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 = 3211
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'</tt></pre>


> <b>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.</b>

<h2>The Configuration File Parameters</h2>
<p>
The parameters for the configuration file are as follows.
<br>
<table>
<thead>
<tr><th align="center">Parameter</th>
<th>Status</th>
<th>Default</th>
<th>Function</th>
</tr>
</thead>
<tbody><tr>
<tr>
<tr>
<td align="left"><b>[Domains] Section</b></td>
<td>Required</td>
<td></td>
<td>Any (resonable) number of lines can be included here.</td>
</tr>
<tr>
<td align="left">Hosted zone name</td>
<td></td>
<td></td>
<td>The text name of the hosted zone (also called the domain name) <b>without</b> the trailing dot '.' that is often used to demark them.</td>
</tr>
<tr>
<td align="left">Record name</td>
<td></td>
<td></td>
<td>This is the value for the corrosponding hosted zone (domain) name. See below for options on this.</td>
</tr>
<tr>
<td align="left"><b>[Defaults] Section</b></td>
<td>Optional</td>
<td></td>
<td></td>
</tr>
<tr>
<td align="left">Update_Interval</td>
<td>Optional</td>
<td>3600</td>
<td>The interval between checking the external IP to see if the address has changed.</td>
</tr>
<tr>
<td align="left">Exception_Interval</td>
<td>Optional</td>
<td>Update_Interval value</td>
<td>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.</td>
</tr>
<tr>
<td align="left">Log_Level_Logfile</td>
<td>Optional</td>
<td>Warning</td>
<td>Sets the detail and level for the file stored in the /config mapping</td>
</tr>
<tr>
<td align="left">Log_Level_Console</td>
<td>Optional</td>
<td>Error</td>
<td>Sets the detail and level for the console (docker log)</td>
</tr>
<tr>
<td align="left"></td>
<td></td>
<td></td>
<td>Logging levels options are :- Critical Error Warning Info Debug</td>
</tr>
<tr>
<td align="left">TTL</td>
<td>Optional</td>
<td>3600</td>
<td>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.</td>
</tr>
<tr>
<td align="left">Sleep_Time_Initial_Authorisation</td>
<td>Optional</td>
<td>1</td>
<td>The time to pause before first domain changes after start up. <i>Not normally required</i></td>
</tr>
<tr>
<td align="left">Sleep_Time_Inter_Domain </td>
<td>Optional</td>
<td>1</td>
<td>The time to pause between consecutive domain interrogations. <i>Not normally required</i></td>
</tr>
<tr>
<td align="left">WebHook_Alive<br>WebHook_Alive1<br>WebHook_Alive2<br>.<br>WebHook_Alive9</td>
<td>Optional</td>
<td>-</td>
<td>Each given entry is called when the update of all records was successful. There can be up to 10 entries, starting with WebHook_Alive, then WebHook_Alive1 and so on until WebHook_Alive9. Entries need not be contiguous and so can be commented out as required.</td>
</tr>
<tr>
<td align="left">WebHook_Alert<br>WebHook_Alert1<br>WebHook_Alert2<br>.<br>WebHook_Alert9</td>
<td>Optional</td>
<td>-</td>
<td>Each given entry is called when the update of any record was unsuccessful. There can be up to 10 entries, starting with WebHook_Alert, then WebHook_Alert1 and so on until WebHook_Alert9. Entries need not be contiguous and so can be commented out as required.</td>
</tr>

<tr>
<td align="left"><b>[Credentials]</b></td>
<td>Optional</td>
<td>-</td>
<td>Only required as below.</td>
</tr>

<tr>
<td align="left">AWS_Access_Key_ID<br>AWS_Secret_Access_Key</td>
<td>Optional</td>
<td>-</td>
<td>The second option for providing AWS credentials. (See below)</td>
</tr>

<tr>
<td align="left">AWS_Credential_Profile</td>
<td>Optional</td>
<td>-</td>
<td>Use only when using the AWS credentials file option for providing AWS credentials.</td>
</tr>

</tbody></table>
<br>
</p>
<p>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 <b><i>home.yourdomain.com</b></i> is given the external IP address. This is the most simple case and you must create an A-Record with the name <b><i>home.yourdomain.com</b></i> in AWS before it can be updated.</p>
<p>
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 <b><i>yourdomain.click</b></i> and then a second A-Record called <b><i>*.yourdomain.click</b></i> that has a value of <b><i>yourdomain.click</b></i>. This will cause any DNS request for sub-domains of this address such as <b><i>voip.yourdomain.click</b></i> or <b><i>sonarr.yourdomain.click</b></i> to be mapped through to the IP address set up in the <b><i>yourdomain.click</b></i> A-Record.
</p>

<h2>Providing the AWS Credentials</h2>
<p>The AWS authorisation credentials can be provided in one of 4 methods.</p>
<ol>
<li>Add them to the <b><i>AWS_Route53_DDNS.ini</b></i> file using the <b><i>AWS_Access_Key_ID</b></i> and <b><i>AWS_Secret_Access_Key</b></i> options</li>
<p style="margin-left:10%; margin-right:10%;">This method is the easiest to get started. It does mean the credentials could be exposed through backups or to users who have access to change the setup however.</p>
<li>Add them to the container when the container is created, usually through docker compose, using the <b><i>AWS_ACCESS_KEY_ID</b></i> and <b><i>AWS_SECRET_ACCESS_KEY</b></i> environment variables</li>
<p style="margin-left:10%; margin-right:10%;">This is also quick and easy but has the draw back that anyone with access to the docker system via a management tool such as Portainer can access the credentials.</p>
<li>Use docker secrets using the <b><i>AWS_ACCESS_KEY_ID_FILE</b></i> and <b><i>AWS_SECRET_ACCESS_KEY_FILE</b></i> environment variables</li>
<p style="margin-left:10%; margin-right:10%;">This is the most secure method of providing credentials.</p>
<li>Use a <b><i>credentials</b></i> file in the standard AWS format placed in the directory mapped to <b><i>/config</b></i></li>
<p style="margin-left:10%; margin-right:10%;">This method is ideal if you want to have a single file with multiple credentials that is shared between multiple applications such as S3 or SES services. Use the <b><i>AWS_Credential_Profile</b></i> to target the correct profile.</p>
</ol>

<p style="background-color:gold;padding:10px"> <b>Note</b> 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.  
</p>

<h2>Usage</h2>
<p>
Create you container locally by either:
<br>
<h3>Docker CLI</h3>
<tt><pre>
docker run -d \
        --name AWS_Route53_DDNS \
        -v /path/to/config:/config \
        -e AWS_ACCESS_KEY_ID=your-access-ID \
        -e AWS_SECRET_ACCESS_KEY=your-key-secret \
        -e TZ=Europe/London  \
        --restart unless-stopped 
        kronos443/aws-route53-ddns
</tt></pre>
<tt><pre>
docker run -d \
        --name AWS_Route53_DDNS \
        -v /path/to/config:/config \
        -e AWS_ACCESS_KEY_ID_FILE=/run/secrets/aws-access-key-id \
        -e AWS_SECRET_ACCESS_KEY_FILE=/run/secrets/aws-secret-access-key \
        -e TZ=Europe/London  \
        --restart unless-stopped 
        kronos443/aws-route53-ddns
</tt></pre>

<h3>Docker Compose</h3>
Options 1 & 4
<tt><pre>
---
version: "2.1"
services:
  aws-route53-ddns:
    image: kronos443/aws-route53-ddns:amd64-latest
    container_name: AWS_Route53_DDNS
    environment:
      - TZ=Europe/London
    volumes:
      - /path/to/config:/config
    restart: unless-stopped
</tt></pre>
Option 2
<tt><pre>
---
version: "2.1"
services:
  aws-route53-ddns:
    image: kronos443/aws-route53-ddns:amd64-latest
    container_name: AWS_Route53_DDNS
    environment:
      - TZ=Europe/London
      - AWS_ACCESS_KEY_ID=your-access-ID
      - AWS_SECRET_ACCESS_KEY=your-key-secret
    volumes:
      - /path/to/config:/config
    restart: unless-stopped
</tt></pre>
Option 3
<tt><pre>
---
version: "2.1"
services:
  aws-route53-ddns:
    image: kronos443/aws-route53-ddns:amd64-latest
    container_name: AWS_Route53_DDNS
    environment:
      - TZ=Europe/London
      - AWS_ACCESS_KEY_ID_FILE=/run/secrets/your-access-id-file
      - AWS_SECRET_ACCESS_KEY_FILE=/run/secrets/your-key-secret-file
    volumes:
      - /path/to/config:/config
    restart: unless-stopped
</tt></pre>

<h3>Synology NAS</h3>
<p>To run the container on a Synology NAS:</p>
<ol>
  <li>Open File Station and create a new directory to act as the /config volume. E.g. /docker/AWS_Route53_DDNS.</li>
  <li>Put your customised  <b><i>AWS_Route53_DDNS.ini</b></i>  file in this directory.</li>
  <li>Use the GUI on the desktop to search the registry for kronos443.</li>
  <li>Download the image from the registry by double clicking it.</li>
  <li>On the image tab, double click the newly downloaded image to start configuring it.</li>
  <li>On the Gerneral Settings window, name the image and if you want eneable resource limitation.</li>
  <li>Click advanced settings</li>
  <li>On the Advanced Settings window under the Advanced Settings tab enable auto-restart</li>
  <li>On the volume tab add folder and map your new docker/AWS_Route53_DDNS directory to /config</li>
  <li>On the netwrok tab select 'Use same network as Docker Host'</li>
  <li>On the Environment tab add the environment variables</li>
  <li>Click apply, then Next and on the Summary window Apply </li>
</ol>

<h2>Parameters</h2>
<p>
The parameters are described below.
<br>
<table>
<thead>
<tr><th align="center">Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">-v /path/to/config:/config</td>
<td>The directory on your host that is shared with the container. Place your  <b><i>AWS_Route53_DDNS.ini</b></i>  file here. Log files will also be written here.</td>
</tr>
<tr>
<td align="left">-e AWS_ACCESS_KEY_ID=your-access-ID</td>
<td>The access key string generated by you on AWS IAM</td>
</tr>
<td align="left">-e AWS_SECRET_ACCESS_KEY=your-key-secret</td>
<td>The secret code for the ID, generated by you on AWS IAM</td>
</tr>
<tr>
<td align="left">-e AWS_ACCESS_KEY_ID_FILE=/run/secrets/your-access-id-file</td>
<td>The docker secrets file containing access key string generated by you on AWS IAM</td>
</tr>
<td align="left">-e AWS_SECRET_ACCESS_KEY_FILE=/run/secrets/your-key-secret-file</td>
<td>The docker secrets file containing the secret code for the ID, generated by you on AWS IAM</td>
</tr>
<td align="left">TZ=Europe/London</td>
<td>Time zone, e.g. Europe/London optional but means the log times will be in the local timezone rather than UT</td>
</tr>
</tbody></table>
</p>


<p><b>If you find this container useful then please consider</b> <a href="https://www.paypal.com/donate?hosted_button_id=N6F4E9YCD5VC8">buying me a coffee by following this link or scanning the QR below.</a> :)</p>

<a href="https://www.paypal.com/donate?hosted_button_id=N6F4E9YCD5VC8"> <img src="http://www.ajwm.uk/dockerdonate.jpg" alt="Please consider donating" width="120" height="120"> </a>