update logwatch readme

update readme files
refactor(SAMPLE): remove un-needed email address
2021-05-09 23:43:41 -06:00 · 2021-05-09 14:39:28 -06:00 · 2021-05-09 10:44:21 -06:00 · 2021-05-09 10:43:05 -06:00 · 2021-05-09 10:28:17 -06:00 · 2021-05-09 10:24:15 -06:00
16 changed files with 1349 additions and 452 deletions
@@ -0,0 +1,81 @@
+# Common settings that generally should always be used with your language specific settings
+
+# Auto detect text files and perform LF normalization
+# https://www.davidlaing.com/2012/09/19/customise-your-gitattributes-to-become-a-git-ninja/
+*          text=auto
+
+#
+# The above will handle all files NOT found below
+#
+
+# Documents
+*.bibtex   text diff=bibtex
+*.doc      diff=astextplain
+*.DOC      diff=astextplain
+*.docx     diff=astextplain
+*.DOCX     diff=astextplain
+*.dot      diff=astextplain
+*.DOT      diff=astextplain
+*.pdf      diff=astextplain
+*.PDF      diff=astextplain
+*.rtf      diff=astextplain
+*.RTF      diff=astextplain
+*.md       text diff=markdown
+*.tex      text diff=tex
+*.adoc     text
+*.textile  text
+*.mustache text
+*.csv      text
+*.tab      text
+*.tsv      text
+*.txt      text
+*.sql      text
+*.ps1      text eol=crlf
+
+# Graphics
+*.png      binary
+*.jpg      binary
+*.jpeg     binary
+*.gif      binary
+*.tif      binary
+*.tiff     binary
+*.ico      binary
+# SVG treated as an asset (binary) by default.
+*.svg      text
+# If you want to treat it as binary,
+# use the following line instead.
+# *.svg    binary
+*.eps      binary
+
+# Scripts
+*.bash     text eol=lf
+*.fish     text eol=lf
+*.sh       text eol=lf
+# These are explicitly windows files and should use crlf
+*.bat      text eol=crlf
+*.cmd      text eol=crlf
+
+# Serialisation
+*.json     text
+*.toml     text
+*.xml      text
+*.yaml     text
+*.yml      text
+
+# Archives
+*.7z       binary
+*.gz       binary
+*.tar      binary
+*.tgz      binary
+*.zip      binary
+
+# Text files where line endings should be preserved
+*.patch    -text
+
+#
+# Exclude files from exporting
+#
+
+.gitattributes export-ignore
+.gitignore     export-ignore
+.gitkeep       export-ignore
@@ -0,0 +1,13 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Rider ignored files
+/contentModel.xml
+/modules.xml
+/projectSettingsUpdater.xml
+/.idea.CloudflareDDNS.iml
+# Datasource local storage ignored files
+/../../../../../../../../../:\Redirected\Asif\Documents\RiderProjects\CloudflareDDNS\.idea\.idea.CloudflareDDNS.dir\.idea/dataSources/
+/dataSources.local.xml
+# Editor-based HTTP Client requests
+/httpRequests/
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ContentModelUserStore">
+    <attachedFolders />
+    <explicitIncludes />
+    <explicitExcludes />
+  </component>
+</project>
@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="possibleLocalVar" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+  </profile>
+</component>
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RIDER_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$/../.." />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="CommitMessageInspectionProfile">
+    <profile version="1.0">
+      <inspection_tool class="BodyLimit" enabled="true" level="ERROR" enabled_by_default="true" />
+      <inspection_tool class="SubjectBodySeparation" enabled="true" level="ERROR" enabled_by_default="true" />
+      <inspection_tool class="SubjectLimit" enabled="true" level="ERROR" enabled_by_default="true" />
+    </profile>
+  </component>
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>
@@ -1,154 +1,262 @@
-# CloudflareDDNS
+# CloudflareDDNS <!-- omit in toc -->

-Update your CloudFlare DNS records with your current (dynamic) IP address via
-systemd timers and a bash script.
+Update your *existing* Cloudflare DNS records with your current (dynamic) IP address via systemd timers and a (POSIX) shell script.

-**NOTE: You can rename *cfddns.sh* anything you want, the script will
-auto-update itself.  However, you MUST update the systemd service file,
-*cfddns.service*, *ExecStart* line manually as explained below**
+## Contents <!-- omit in toc -->

-## cfddns.sh
-#### Installation:
-I recommend putting this in your */usr/local/bin* directory or somewhere else in
-your path so it's easy to run.
-1. Copy the script file to your desired path (/usr/local/bin recommended) and
-   rename as desired.
-   ```Bash
-   sudo cp cfddns.sh /usr/local/bin/
+<!-- toc -->
+
+- [Prerequisites](#prerequisites)
+- [cfddns&#46;sh](#cfddns%2346sh)
+  * [Installation](#installation)
+  * [Usage](#usage)
+    + [Parameters](#parameters)
+- [Cloudflare credentials file](#cloudflare-credentials-file)
+  * [File structure](#file-structure)
+  * [Bearer token](#bearer-token)
+  * [Zone ID](#zone-id)
+- [cfddns.service](#cfddnsservice)
+  * [IP4 and/or IP6](#ip4-andor-ip6)
+    + [Examples](#examples)
+- [cfddns.timer](#cfddnstimer)
+  * [Activation](#activation)
+- [Logging](#logging)
+  * [Using Logwatch to monitor this script](#using-logwatch-to-monitor-this-script)
+  * [Using Logrotate to control log file size](#using-logrotate-to-control-log-file-size)
+- [Final thoughts](#final-thoughts)
+
+<!-- tocstop -->
+
+## Prerequisites
+
+This script requires that `curl` and `jq` are installed. `curl` is used to interact with the Cloudflare API and `jq` is used to efficiently and reliably construct/deconstruct the JSON strings and arrays which is how the Cloudflare API communicates. In most cases you can install these programs using your package manager running as root or via sudo. On Debian/Ubuntu, for example, you would run:
+
+```bash
+apt install -y curl jq
 ```
+
+While the script does *not* require root privileges, you will need sudo/root access to install the *systemd* service and timer.
+
+## cfddns&#46;sh
+
+### Installation
+
+I recommend putting this script in your */usr/local/bin* directory or somewhere else in your path so it's easy to run.
+
+1. Copy the script file to your desired path and rename if you want.
+
+   ```Bash
+   sudo cp cfddns.sh /usr/local/bin/   # just copy it
+   sudo cp cfddns.sh /usr/local/bin/cloudflare-update.sh   # copy and rename (choose any name)
+   ```
+
 2. Make it executable:
+
   ```Bash
   sudo chmod +x /usr/local/bin/cfddns.sh
   ```
-#### Usage:
-If you run the script with no parameters, it will display the help screen.  The
-script accepts several parameters with 2 being required.  The parameters are
-summarized here (taken from the help screen).  You can access the help screen
-and example usage screens by running: *cfddns.sh -h* for help and *cfddns.sh -x*
-for examples.

-**-f: account details file with path**
-This parameter is *required*.  This is the full path to a plain-text file
-containing your CloudFlare account details.  This file must contain 3 lines in
-the following order:
-* authorized email address
-   This is an email address that is permitted to login to your CloudFlare account.
-* global api-key
-   You can get your Global API-key by going to your CloudFlare dashboard,
-   clicking on your profile picture in the upper-right and opening your profile.
-   Scroll to the very bottom to the API Keys section.  Click on the View button
-   next to Global API Key.
-* zone identifier
-   You should be able to find this on the Overview page of your CloudFlare dashboard.
+> Note: You can rename *cfddns.sh* to anything you want, the script will auto-update itself. However, you **must** manually update the systemd service file (*cfddns.service*) `ExecStart` line as [explained below](#cfddns.service).

-Your completed file should look like:
-> johndoe@example.com
-> e7882db52804aca6fab22780e055b97056466
-> 492af8aa69f8c44baf043342c74319fd
+### Usage
+
+If you run the script with no parameters, it will display the help screen.  The script accepts several parameters with only one (1) being required.  The parameters are summarized below.  You can access the help screen and example usage screens by running:

-You should secure this file by changing the owner of the file to root
 ```Bash
-chown root:root path/to/filename
+cfddns.sh --help   # display help screen
+cfddns.sh --examples   # show script usage examples
 ```
-and then restricting access to only the root user
-```Bash
-chmod 600 path/to/filename
+
+#### Parameters
+
+|Parameter|Description|Default|Required?|
+|---|---|---|:---:|
+|-r<br>--record<br>--records|The fully qualified hostname(s) that should be updated with new IP addresses. You can supply a comma-delimited list (no spaces) or just one. Note that the script can only update *either* A *or* AAAA records during a single run so you may need to batch your hostnames, depending on your set-up.<br>N.B. This script will only update *existing* host records, it will **not** create new ones!|none|YES|
+|-c<br>--cred<br>--creds<br>--credentials<br>-f|Full path to your CloudFlare credentials file. This file contains your access token and zone id. See the [relevant section](#cloudflare-credentials-file) of this readme for more information.|scriptPath/cloudflare.credentials|NO|
+|-i<br>--ip<br>--ip-address<br>-a<br>--address|The IP address that should be used to update Host A/AAAA records. If you omit this value, the script will attempt to auto-detect your public IP4/IP6 address and use that as appropriate. Use this option to manually force a specific IP to be used or when auto-detection fails. Note that the script does *not* check your IP addresses for correctness or proper form!|IP4 auto-detect|NO|
+|-4<br>--ip4<br>--ipv4|Update Host A records only (IP4). The script can only update *either* A *or* AAAA records in a single run. If you specify this and also use the IP6 mode switch, the most recent one will take effect.|Enabled, update A records|NO|
+|-6<br>--ip6<br>--ipv6|Update Host AAAA records only (IP6). The script can only update *either* A *or* AAAA records in a single run. If you specify this and also use the IP4 mode switch, the most recent one will take effect.|Disabled, update A records|NO|
+|||||
+|-l<br>--log|Full path where the script should save its log. Recommend */var/log/scriptName.log*|scriptPath/scriptName.log|NO|
+|--nc<br>--no-color<br>--no-colour|Do not use ANSI colour-coding when writing to the log. This is useful if you review the logs using a reader that does not support ANSI colour-coding and instead displays control symbols which makes your log difficult to read.|Disabled, do colourful logs|NO|
+|--log-console|Output the log to the console instead of a log file. You may use `--nc` with this option also.|Disabled, write to log file|NO|
+|--no-log|Do not write a log file or output to the console. You will not have **any** feedback from the script if you run in this mode so you will not know if updates were successful or not. I’m not really sure why you’d want this option, but it’s available.|Disabled, write to log file|NO|
+|-h<br>--help<br>-?|Display built-in help screen explaining these same parameters.|||
+|--examples|Display some usage examples. Sometimes it's just easier to understand by seeing rather than reading.|||
+
+## Cloudflare credentials file
+
+This repo includes a sample credentials file (*cloudflare.credentials* at the root of the repo) with pretty self-explanatory variable names. The script reads this file to get the credentials it needs to connect to your Cloudflare account and update DNS entries. It should be noted that the script is designed to use a *bearer token* and **not** your username/password or your Global API token! Let’s break this down in case things are a little fuzzy still...
+
+### File structure
+
+The file is a basic shell script variables file. Make sure you **do not** put spaces between the variable name, equal sign and the value. Also, **do not** add any executable code since it will be run! The file should contain values for the following two variables:
+
+| Variable | Value                                                        |
+| -------- | ------------------------------------------------------------ |
+| cfKey    | The bearer token granting access to *edit* the DNS records of the zone (domain) in question. |
+| cfZoneId | The Cloudflare Zone ID of the zone (domain) you wish to update. |
+
+You can add comments if you’d like since the script will ignore them. In the end, your file should look something like this, but obviously with your data instead of this nonsense sample information:
+
+```ini
+#
+# Cloudflare token for my.domain.tld
+#
+
+cfKey=_dLuyyRNaKN8SLG4-csmNYYfC39nnCmPVA7aYUJj
+cfZoneId=83d564234134513245311b23412331dd
+
 ```
-**-r: target DNS entry to update**
-At least one entry here is *required*  This is the A or AAAA record you want to
-update the IP address for in your DNS zone file.  If you have multiple A or AAAA
-records you want to update, simply specifiy multiple -r parameters.
-*Note: You can only specify *either* A records *or* AAAA records.  You have to
-update IP4 and IP6 records by running this script multiple times (once for A
-records, once for AAAA records even if the hostname is the same).*

-**-4 or -6: type of record to update**
-The default option is -4 and it does not need to be specified.  This will update
-*A records* specified by the -r parameter(s).  If you specify -6, then *AAAA
-records* will updated as specified by the -r parameter(s).
+You can save the file as anything you like and anywhere you’d like as long as you inform the script of its location using the `--credentials` parameter. By default, the script will look for a file named *cloudflare.credentials* in the same path as the script.

-**-i: use the specified IP address**
-The script will auto-detect the IP address of the machine it's being run on by
-accessing an external service and asking for that service to echo the machine's
-IP address.  If running with -4, then the IP4 will be requested for echo.  If
-running with -6, then the IP6 addresses will be requested for echo.
-This parameter let's you bypass auto-detection and specify a particular address
-to be used instead.
-*NOTE: The address you supply is NOT checked for correctness.  So ensure you're
-supplying a valid address of the correct type based on your choice of -4 or -6
-parameter!*
+### Bearer token

-**-l (lower-case L): specify where the log file should be written**
-The script will default to writing it's log file in the same directory as the
-script is located.  It will use it's own name and append a *.log* extension.
-So, the default name for the log file is *cfddns.log*.  If you rename the script
-*something.sh* then the generated log file name will be *something.log*.
-This can be messy if you store the script in /usr/bin/local/ as recommended.
-Therefore, it's recommended you choose a different location for
-the logfile (*/var/log/cfddns.log* is recommended).
+I chose to use an API bearer token instead of a username/password or Global API token for security reasons. Your username/password and Global API token provide unfettered access to your account so if anyone gets hold of them, they can do anything to your account. An API bearer token, by contrast, can only do what you authorize it to do and you can revoke it at any time. Therefore, I suggest making a bearer token that is based on the “Edit zone DNS” template and restricted to the specific domain/zone you wish to update. Cloudflare provides an [excellent article](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys) on how to generate this token.

-**-h: display help**
-Displays the help screen, which is an abbreviated version of this section you
-are currently reading.
+> N.B. This is a breaking change from previous versions of this script!
+
+### Zone ID
+
+This is required by the Cloudflare API so it knows which zone you are editing and can check the permissions of the bearer token. This script only caters to one zone so likely only one domain per configuration file. If you need to update multiple zones, you can have multiple configuration files and call them as required on separate invocations of the script.
+
+To get your Zone ID, log into your Cloudflare account and open the domain in question. On the overview page, scroll down a bit and look to the right. You will see your Zone ID listed there. Copy that string into your configuration file.

-**-x: display examples**
-This is the best way to learn how this script works.  Several examples are
-provided

 ## cfddns.service
-This is the systemd file that **must** be copied to your */etc/systemd/system*
-directory.  If you change the name of the cfddns.sh file, you must update the
-filename in the *ExecStart* line as shown below:
+
+This file **must** be copied to your */etc/systemd/system* directory (or equivalent directory if you're not running Debian/Ubuntu). If you change the name of the cfddns&#46;sh file, you must update the filename in the `ExecStart` line as shown below:
+
 ````Ini
 ...
 [Service]
 Type=oneshot
-ExecStart=/full/path/to/your/renamed.file
+ExecStart=/full/path/to/your/renamed.file -parameter1 -parameter2 -parameter...
 ...
 ````

+Don’t forget to reload systemd after copying this file so it is recognized by the system! On most systems you can do this by running the following as root or via sudo:
+
+```bash
+systemctl daemon-reload
+```
+
+### IP4 and/or IP6
+
+The cfddns.service file includes two *ExecStart* lines, one without a specified IP-protocol parameter (default IP4) and the other with the -6 (IP6) parameter. The service will run the cfddns&#46;sh script in default (IP4) mode with specified parameters first and then will run the script again in IP6 mode with specified parameters.
+
+*Note: The parameters *can be different* in each case.*
+
+#### Examples
+
+1. **Only update A records**
+    Update *mail<span>.example.com* A record with the current auto-detected public IP4 address of this machine and log results to */var/log/cfddns.log*.
+  
+    ```Ini
+   [Service]
+   Type=oneshot
+   ExecStart=/usr/local/bin/cfddns.sh -c /root/cloudflare.credentials -r mail.example.com -l /var/log/cfddns.log
+   ...
+   ```
+
+2. **Only update AAAA records**
+    Update *git<span>.example.com* and *mail<span>.example.com* AAAA records with the current auto-detected public IP6 address of this machine. Log will be stored in the same directory as the script file (/usr/local/bin).
+
+    ```Ini
+    [Service]
+    Type=oneshot
+    ExecStart=/usr/local/bin/cfddns.sh -6 -c /home/johndoe/cloudflare.credentials -r git.example.com,mail.example.com
+    ...
+    ```
+
+3. **Update A records then AAAA records**
+   Update *mail<span>.example.com* A record with auto-detected public IP4 address of this machine and write to log file stored at */var/log/DDNS_IP4.log*.  Then, update both *mail<span>.example.com* and *git<span>.example.com* AAAA records with the specified IP6 address and write to log file at */var/log/DDNS_IP6.log*.
+   
+   ```Ini
+   [Service]
+   Type=oneshot
+   # update IP4 addresses
+   ExecStart=/usr/local/bin/cfddns.sh -c /dir1/account.cf -r mail.example.com -l /var/log/DDNS_IP4.log
+   # update IP6 addresses
+   ExecStart=/usr/local/bin/cfddns.sh -6 -c /dir2/cloudflare.details -r mail.example.com,git.example.com --ip fd3f:e6db:9817:df84::a001 -l /var/log/DDNS_IP6.log
+   ...
+   ```
+
 ## cfddns.timer
-This is the timer file that tells your system how often to call the
-cfddns.service file which runs the cfddns.sh script.  By default, the timer is
-set for 5 minutes after the system boots up (to allow for other processes to
-initialize even on slower systems like a RasPi) and then run every 15 minutes
-thereafter as long as the system is powered on.  Remember when settings your
-timer that CloudFlare limits API calls to 1200 every 5 minutes
-You can change the timer by modifying the relevant section of the cfddns.timer
-file:
-````Ini
+
+This is the timer file that tells your system how often to call the *cfddns.service* file which runs the *cfddns&#46;sh* script.  By default, the timer is set for 5 minutes after the system boots up (to allow for other processes to initialize even on slower systems like a RasPi) and is then run every 15 minutes thereafter.  Remember when setting your timer that Cloudflare limits API calls to 1200 every 5 minutes.
+
+You can change the timer by modifying the relevant section of the *cfddns.timer* file:
+
+```Ini
 [Timer]
 OnBootSec=5min
 OnUnitActiveSec=15min
-````
-OnBootSec is how long to wait after the system boots up before executing calling
-thd cfddns.service.  OnUnitActiveSec will then wait the specified time from that
-first (after boot) call before calling cfddns.service again.  Therefore,
-eveything is relative to your system boot up.  I recommend setting
-OnUnitActiveSec to a low value (like 2 minutes) for testing then setting it to a
-more reasonable time (like 15 minutes) after everything is working.
+```

-## The log file
-The script logs every major action it takes and provides details on any errors
-it encounters in the log file (see the above section for details on log file
-location and name).  If errors are encountered, they are colour coded red and
-an explanation of the error code is provided.
-While the log file is as terse as I felt reasonable, you may still want to
-configure any logwatch programs to further filter things for you so you don't
-have to review this log as part of your daily routine.  To make that easier, the
-following conventions are observed in the log file:
-* Errors always appear as "-- [ERROR] text and error code here --"
-* Errors are followed by an explanation of the specific error code on a new line
-* A clean exit appears as "-- [SUCCESS] some text here --"
-* The script always starts a new set of log entries with "-- Start CloudFlare
-  DDNS script execution --
-* All log file entries start with a time-stamp in [square brackets]
+*OnBootSec* is how long to wait after the system boots up before executing the *cfddns.service*.  *OnUnitActiveSec* will then wait the specified time from that first (after boot) call or after the timer is explicitly started before calling *cfddns.service* again.  I recommend setting OnUnitActiveSec to a low value (like 2 minutes) for testing then setting it to a more reasonable time (like 15
+minutes) after everything is working.
+
+### Activation
+
+You can start the timer system immediately via *systemctl*
+
+```Bash
+systemctl start cfddns.timer
+```
+
+and can enable it to start automatically on boot by typing
+
+```Bash
+systemctl enable cfddns.timer
+```
+
+You can check the status of the timer via systemctl also
+
+```Bash
+systemctl status cfddns.timer
+```
+
+It is NOT necessary to enable/start the *cfddns.service*, only the timer needs to be active.
+
+## Logging
+
+The script logs every major action it takes and provides details on any errors it encounters in the log file (see the [parameters section](#parameters) for details about setting log location and name).  If errors are encountered, they are colour coded red and an explanation of the error code is provided.
+
+While the log file is as terse as I felt reasonable, you may still want to configure any log-watch programs to further filter things for you so you don't have to review this log as part of your daily routine.  To make that easier, the following conventions are observed in the log file and can be used to program your log-watch system:
+
+- Specific update process errors: **[TIMESTAMP] ERR: message**
+  - These can be counted/filtered separately if you only care about update errors and not any other errors.
+- Error messages: **[TIMESTAMP] ERROR: message (code: number)**
+  - Only one summary error message will be displayed for any/all update errors. This message contains a tally of failed updates. If you want to count individual update errors, filter for the above process error message format.
+  - While process error messages only relate to updates, these general error messages are logged for a variety of error conditions so it’s a good idea to include them in any filters.
+- Cloudflare API error messages:  **[TIMESTAMP] CF-ERR: message (code: cf-error-code)**
+  - These are only logged when update process errors occur so that you can see exactly what the Cloudflare API is complaining about.
+- Specific update process warnings: **[TIMESTAMP] WARN: message**
+  - These can be counted/filtered separately from general warning messages. Presently, there are *no* general warning messages.
+- Warning messages: **[TIMESTAMP] WARNING: message**
+  - Summary of each type of warning. Contains a tally of the specific warning.
+  - Currently, warnings are only issued for hostnames that are not found (i.e. update process warnings).
+- Success messages: **[TIMESTAMP] SUCCESS: message**
+  - Each successful update generates a success message. There is no process or tally message.
+- Already up-to-date: **[TIMESTAMP] IP address for {fqdn} is already up-to-date**
+  - Already up-to-date host entries generate a success message but you may still want to filter for them separately using this criteria.
+- A session log always starts with **[TIMESTAMP] -- Cloudflare DDNS update-script: starting --**
+- A successful session log always ends with **[TIMESTAMP] -- Cloudflare DDNS update-script: completed successfully --**
+- A session ending with errors always ends with **[TIMESTAMP] -- Cloudflare DDNS update-script: completed with error(s) --**
+
+### Using Logwatch to monitor this script
+
+If you are using the Logwatch package to monitor your system, see the README in the */etc/logwatch* folder for details about the pre-configured service files already done for you :-)
+
+### Using Logrotate to control log file size
+
+Logrotate is pre-installed on standard Debian/Ubuntu distributions and is a great way to automatically rotate your log files and control how many old logs you keep on your system so they don't accumulate and eat up your disk space. I've included a sample configuration file you can copy to your */etc/logrotate.d/* folder.  This file is set up to rotate your logs once a week, keep 3 weeks worth of history (compressed) and delete all logs older than that.  The configuration file is located in this git archive at
+*/etc/logrotate.d/cfddns* and is fully commented to help you customize it to suit your needs.

 ## Final thoughts
-I'm by no means an expert in BASH scripting and I only program/script as a hobby
-when I find stuff that irritates me and no other good solutions seem easily 
-available.  So, by all means, please comment, provide feedback and suggestions
-to make this script better!  Thanks, I hope this helps someone else out!

-Please check out my blog at [https://mytechiethoughts.com](https://mytechiethoughts.com) where I tackle
-problems like this all the time and find free/cheap solutions to tech problems.
+Hopefully this helps you with an easy and reliable way to  update your Cloudflare DNS entries with a dynamic IP address. Please feel free to comment and provide feedback and suggestions to make this script better!
+
+Please check out my blog at [https://mytechiethoughts.com](https://mytechiethoughts.com) where I tackle problems like this all the time and find free/cheap solutions to tech problems.
@@ -4,7 +4,8 @@ After=network.target

 [Service]
 Type=oneshot
-ExecStart=/usr/local/bin/cfddns.sh
+ExecStart=/usr/local/bin/cfddns.sh -c /path/to/account.details -r server.domain.tld -l /var/log/cfddns.log
+ExecStart=/usr/local/bin/cfddns.sh -6 -c /path/to/account.details -r server.domain.tld -l /var/log/cfddns.log

 [Install]
 WantedBy=multi-user.target
@@ -1,352 +1,550 @@
-#!/bin/bash
+#!/bin/sh

+#
+# update Cloudflare DNS records with current (dynamic) IP address
+#    Script by Asif Bacchus <asif@bacchus.cloud>
+#    Last modified: May 7, 2021
+#

-### Define functions
-
-function scriptHelp {
-echo -e "\e[1;39mUsage:"
-echo -e "\e[1;36m$(basename ${0})" \
-    "\e[1;35m-f /path/to/account/details.file"
-echo -e "\t\e[1;33m-r record.to.update [-r another.record.to.update -r ...]"
-echo -e "\t\e[0;92m[optional parameters]\e[0m\n"
-echo -e "\e[1;39mNotes:\e[0m"
-echo -e "-f and -r parameters are REQUIRED."
-echo -e "Multiple A/AAAA records to update can be specified by supplying"
-echo -e "\tmultiple -r parameters (see examples below)."
-echo "This script can operate only in either IP4 OR IP6 mode. See below."
-echo "This script will NOT verify the format or validity of supplied IP"
-echo -e "\taddresses."
-echo -e "\n\e[1;39mOptional parameters\e[0m"
-echo -e "-i\tUse this IP address when updating DNS records"
-echo -e "\tIf NOT supplied, the script will attempt to auto-detect this"
-echo -e "\tmachine's IP address (depending on -4 or -6 parameters) and"
-echo -e "\tuse that address for DNS updates.  The script does NOT check"
-echo -e "\tthe validity of an address supplied using this parameter nor"
-echo -e "\tthe protocol type (IP4 vs IP6)."
-echo -e "-4\tOperate in IP4 mode and update A records (default)"
-echo -e "\tThis is the default operating mode and does not need to be"
-echo -e "\texplicitly specified.  Ensure you have supplied a valid IP4"
-echo -e "\taddress using the -i parameter or that your machine's IP4"
-echo -e "\taddress can be correctly detected externally."
-echo -e "-6\tOperate in IP6 mode and update AAAA records"
-echo -e "\tONLY AAAA records will be updated.  Ensure you have supplied"
-echo -e "\ta valid IP6 address using the -i parameter or that your"
-echo -e "\tmachine's IP6 address can be correctly detected externally."
-echo -e "-h\tDisplay this help page"
-echo -e "-x\tDisplay script examples"
-echo -e "-l\tLocation for log file output"
-echo -e "\tDefault: scriptname.ext.log in same directory as this script"
-echo -e "\n\e[1;39mExamples:"
-echo -e "\e[0;39mRun \e[1;36m$(basename ${0}) \e[1;92m-x\e[0m\n"
-echo -e "\n"
-
-# exit with any error code used to call this help screen
-quit none $1
-}
-
-
-function scriptExamples {
-echo -e "\n\e[1;39m$(basename ${0}) Examples:\e[0m"
-echo -e "\n\e[1;39mExample: \e[0mUse details from myCloudFlareDetails.info"
-echo -e "file in /home/janedoe directory. Update server.mydomain.com A record"
-echo -e "with this machine's auto-detected IP4 address."
-echo -e "\t\e[1;36m$(basename ${0})" \
-    "\e[1;35m-f /home/janedoe/myCloudFlareDetails.info"
-echo -e "\t\e[1;33m-r server.mydomain.com\e[0m"
-echo -e "\n\e[1;39mExample: \e[0mUse details from myCloudFlareDetails.info"
-echo -e "file in /home/janedoe directory. Update server.mydomain.com AND"
-echo -e "server2.mydomain.com A records with this machine's auto-detected IP6"
-echo -e "address."
-echo -e "\t\e[1;36m$(basename ${0})" \
-    "\e[1;35m-f /home/janedoe/myCloudFlareDetails.info"
-echo -e "\t\e[1;33m-r server.mydomain.com" \
-    "-r server2.mydomain.com \e[1;92m-6\e[0m"
-echo -e "\n\e[1;39mExample: \e[0mUse details from myCloudFlareDetails.info"
-echo -e "file in /home/janedoe directory. Update server.mydomain.com A record"
-echo -e "using IP4 address 1.2.3.4."
-echo -e "\t\e[1;36m$(basename ${0})" \
-    "\e[1;35m-f /home/janedoe/myCloudFlareDetails.info"
-echo -e "\t\e[1;33m-r server.mydomain.com \e[1;92m-i 1.2.3.4\e[0m"
-echo -e "\n\e[1;39mExample: \e[0mUse details from myCloudFlareDetails.info"
-echo -e "file in /home/janedoe directory. Update server3.mydomain.com AND"
-echo -e "server7.mydomain.com AAAA records using IP6 address FE80::286A:FF91."
-echo -e "\t\e[1;36m$(basename ${0})" \
-    "\e[1;35m-f /home/janedoe/myCloudFlareDetails.info"
-echo -e "\t\e[1;33m-r server.mydomain.com" \
-    "\e[1;33m-r server2.mydomain.com \e[1;92m-i FE80::286A:FF91\e[0m"
-
-quit none
-}
-
-
-function quit {
-    if [ -z "$1" ]; then
-        # exit cleanly
-        echo -e "\e[1;32m[`date +%Y-%m-%d` `date +%H:%M:%S`]" \
-        "--[SUCCESS] Script completed --\e[0m" >> $logFile
-        exit 0
-    elif [ "$1" = "none" ]; then
-        if [ -z "$2" ]; then
-            # exit cleanly
-            exit 0
+### text formatting presets using tput
+if command -v tput >/dev/null; then
+    bold=$(tput bold)
+    cyan=$(tput setaf 6)
+    err=$(tput bold)$(tput setaf 1)
+    magenta=$(tput setaf 5)
+    norm=$(tput sgr0)
+    ok=$(tput setaf 2)
+    warn=$(tput bold)$(tput setaf 3)
+    yellow=$(tput setaf 3)
+    width=$(tput cols)
 else
-            # exit with error code but don't log/display it
-            exit "$2"
+    bold=""
+    cyan=""
+    err=""
+    magenta=""
+    norm=""
+    ok=""
+    warn=""
+    yellow=""
+    width=80
 fi
-    elif [ "$1" = "199" ]; then
-        # list DNS entries that were not updated
-        for failedName in "${failedDNS[@]}"; do
-            echo -e "\e[1;31m[`date +%Y-%m-%d` `date +%H:%M:%S`]" \
-            "-- [ERROR] $failedName was NOT updated --\e[0m" >> $logFile
-        done
-        exit "$1"
-    else
-        # notify use that error has occurred and provide exit code
-        echo -e "\e[1;31m[`date +%Y-%m-%d` `date +%H:%M:%S`]" \
-        "-- [ERROR] Script exited with code $1 --" >> $logFile
-        echo -e "\e[0;31m${errorExplain[$1]}\e[0m" >> $logFile
-        exit "$1"
+
+### functions
+badParam() {
+    if [ "$1" = "null" ]; then
+        printf "\n%sERROR: '%s' cannot have a NULL (empty) value.\n" "$err" "$2"
+        printf "%sPlease use '--help' for assistance.%s\n\n" "$cyan" "$norm"
+        exit 1
+    elif [ "$1" = "dne" ]; then
+        printf "\n%sERROR: '%s %s'\n" "$err" "$2" "$3"
+        printf "file or directory does not exist or is empty.%s\n\n" "$norm"
+        exit 1
+    elif [ "$1" = "errMsg" ]; then
+        printf "\n%sERROR: %s%s\n\n" "$err" "$2" "$norm"
+        exit 1
    fi
 }

-### end of functions
-
-
-### unset environment variables used in this script and initialize arrays
-unset PARAMS
-unset accountFile
-unset ipAddress
-errorExplain=()
-dnsRecords=()
-cfDetails=()
-cfRecords=()
-currentIP=()
-recordID=()
-failedDNS=()
-ip4=1
-ip6=0
-
-
-## define error code explainations
-errorExplain[1]="Missing or invalid parameters on script invocation."
-errorExplain[2]="curl is required to access CloudFlare API.  Please install curl. (apt-get install curl on debian/ubuntu)."
-errorExplain[101]="Location of file with CloudFlare account details was NOT provided (-f parameter missing)."
-errorExplain[102]="CloudFlare account details file is empty or does not exist"
-errorExplain[103]="No DNS records to update were specified (-r parameter(s) missing)."
-errorExplain[104]="There are no DNS records specified that match those found in your CloudFlare account to update."
-errorExplain[201]="Could not detect this machine's IP address. Please re-run this script with the -i option."
-errorExplain[254]="Could not connect with CloudFlare API. Please re-run this script later."
-
-
-## Logging parameters -- default set to scriptname.ext.log in same 
-## directory as this script
-scriptPath="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-scriptName="$(basename ${0})"
-logFile="$scriptPath/${scriptName%.*}.log"
-
-
-### Process script parameters
-if [ -z $1 ]; then
-    scriptHelp 1
-fi
-
-while getopts ':f:r:i:46hxl:' PARAMS; do
-    case "$PARAMS" in
-        f)
-            # path to file with CloudFlare account details
-            accountFile="${OPTARG}"
+exitError() {
+    case "$1" in
+    3)
+        errMsg="Unable to connect to Cloudflare servers. This is probably a temporary networking issue. Please try again later."
        ;;
-        r)
-            # DNS records to update
-            dnsRecords+=($OPTARG)
+    10)
+        errMsg="Unable to auto-detect IP address. Try again later or supply the IP address to be used."
        ;;
-        i)
-            # IP address to use -- NOT parsed for correctness
-            ipAddress="$OPTARG"
+    20)
+        errMsg="Cloudflare authorized email address (cfEmail) is either null or undefined. Please check your Cloudflare credentials file."
        ;;
-        4)
-            # Put script in IP4 mode (default)
-            ip4=1
-            ip6=0
+    21)
+        errMsg="Cloudflare authorized API key (cfKey) is either null or undefined. Please check your Cloudflare credentials file."
        ;;
-        6)
-            # Put script in IP6 mode
-            ip4=0
-            ip6=1
+    22)
+        errMsg="Cloudflare zone id (cfZoneId) is either null or undefined. Please check your Cloudflare credentials file."
        ;;
-        h)
-            # Display info on script usage
-            scriptHelp
+    25)
+        errMsg="Cloudflare API error. Please review any 'CF-ERR:' lines in this log for details."
        ;;
-        x)
-            # Show examples of script usage
-            scriptExamples
+    26)
+        errMsg="${failedHostCount} host update(s) failed. Any 'CF-ERR:' lines noted in this log may help determine what went wrong."
        ;;
-        l)
-            # Path to write log file
-            logFile="${OPTARG}"
-            ;;
-        ?)
-            scriptHelp 1
+    *)
+        writeLog error "An unspecified error occurred. (code: 99)"
+        printf "%s[%s] -- Cloudflare DDNS update-script: completed with error(s) --%s\n" "$err" "$(stamp)" "$norm" >>"$logFile"
+        exit 99
        ;;
    esac
+    writeLog error "$errMsg" "$1"
+    printf "%s[%s] -- Cloudflare DDNS update-script: completed with error(s) --%s\n" "$err" "$(stamp)" "$norm" >>"$logFile"
+    exit "$1"
+}
+
+exitOK() {
+    printf "%s[%s] -- Cloudflare DDNS update-script: completed successfully --%s\n" "$ok" "$(stamp)" "$norm" >>"$logFile"
+    exit 0
+}
+
+listCFErrors() {
+    # extract error codes and messages in separate variables, replace newlines with underscores
+    codes="$(printf "%s" "$1" | jq -r '.errors | .[] | .code' | tr '\n' '_')"
+    messages="$(printf "%s" "$1" | jq -r '.errors | .[] | .message' | tr '\n' '_')"
+
+    # iterate codes and messages and assemble into coherent messages in log
+    while [ -n "$codes" ] && [ -n "$messages" ]; do
+        # get first code and message in respective sets
+        code="${codes%%_*}"
+        message="${messages%%_*}"
+
+        # update codes and messages sets by removing first item in each set
+        codes="${codes#*_}"
+        messages="${messages#*_}"
+
+        # output to log
+        writeLog cf "$message" "$code"
+    done
+}
+
+scriptExamples() {
+    newline
+    printf "Update Cloudflare DNS host A/AAAA records with current IP address.\n"
+    printf "%sUsage: %s --records host.domain.tld[,host2.domain.tld,...] [parameters]%s\n\n" "$bold" "$scriptName" "$norm"
+    textBlock "${magenta}--- usage examples ---${norm}"
+    newline
+    textBlockSwitches "${scriptName} -r myserver.mydomain.net"
+    textBlock "Update Cloudflare DNS records for myserver.mydomain.net with the auto-detected public IP4 address. Credentials will be expected in the default location and the log will be written in the default location also."
+    newline
+    textBlockSwitches "${scriptName} -r myserver.mydomain.net -6"
+    textBlock "Same as above, but update AAAA host records with the auto-detected public IP6 address."
+    newline
+    textBlockSwitches "${scriptName} -r myserver.mydomain.net,myserver2.mydomain.net -l /var/log/cfddns.log --nc"
+    textBlock "Update DNS entries for both listed hosts using auto-detected IP4 address. Write a non-coloured log to '/var/log/cfddns.log'."
+    newline
+    textBlockSwitches "${scriptName} -r myserver.mydomain.net,myserver2.mydomain.net -l /var/log/cfddns.log --ip6 --ip fd21:7a62:2737:9c3a::a151"
+    textBlock "Update DNS AAAA entries for listed hosts using the *specified* IP address. Write a colourful log to the location specified."
+    newline
+    textBlockSwitches "${scriptName} -r myserver.mydomain.net -c /root/cloudflare.creds -l /var/log/cfddns.log --ip 1.2.3.4"
+    textBlock "Update DNS A entry for listed hostname with the provided IP address. Read cloudflare credentials file from specified location, save log in specified location."
+    newline
+    textBlockSwitches "${scriptName} -r myserver.mydomain.net -c /root/cloudflare.creds -l /var/log/cfddns.log -6 -i fd21:7a62:2737:9c3a::a151"
+    textBlock "Exact same as above, but change the AAAA record. This is how you run the script once for IP4 and again for IP6."
+    exit 0
+}
+
+scriptHelp() {
+    newline
+    printf "Update Cloudflare DNS host A/AAAA records with current IP address.\n"
+    printf "%sUsage: %s --records host.domain.tld[,host2.domain.tld,...] [parameters]%s\n\n" "$bold" "$scriptName" "$norm"
+    textBlock "The only required parameter is '--records' which is a comma-delimited list of hostnames to update. However, there are several other options which may be useful to implement."
+    textBlock "Parameters are listed below and followed by a description of their effect. If a default value exists, it will be listed on the following line in (parentheses)."
+    newline
+    textBlock "${magenta}--- script related parameters ---${norm}"
+    newline
+    textBlockSwitches "-c | --cred | --creds | --credentials | -f (deprecated, backward-compatibility)"
+    textBlock "Path to file containing your Cloudflare *token* credentials. Please refer to the repo README for more information on format, etc."
+    textBlockDefaults "(${accountFile})"
+    newline
+    textBlockSwitches "-l | --log"
+    textBlock "Path where the log file should be written."
+    textBlockDefaults "(${logFile})"
+    newline
+    textBlockSwitches "--nc | --no-color | --no-colour"
+    textBlock "Switch value. Disables ANSI colours in the log. Useful if you review the logs using a reader that does not parse ANSI colour codes."
+    textBlockDefaults "(disabled: print logs in colour)"
+    newline
+    textBlockSwitches "--log-console"
+    textBlock "Switch value. Output log to console (stdout) instead of a log file. Can be combined with --nc if desired."
+    textBlockDefaults "(disabled: output to log file)"
+    newline
+    textBlockSwitches "--no-log"
+    textBlock "Switch value. Do not create a log (i.e. no console, no file). You will not have *any* output from the script if you choose this option, so you will not know if updates succeeded or failed."
+    textBlockDefaults "(disabled: output to log file)"
+    newline
+    textBlockSwitches "-h | --help | -?"
+    textBlock "Display this help screen."
+    newline
+    textBlockSwitches "--examples"
+    textBlock "Show some usage examples."
+    newline
+    textBlock "${magenta}--- DNS related parameters ---${norm}"
+    newline
+    textBlockSwitches "-r | --record | --records"
+    textBlock "Comma-delimited list of hostnames for which IP addresses should be updated in Cloudflare DNS. This parameter is REQUIRED. Note that this script will only *update* records, it will not create new ones. If you supply hostnames that are not already defined in DNS, the script will log a warning and will skip those hostnames."
+    newline
+    textBlockSwitches "-i | --ip | --ip-address | -a | --address"
+    textBlock "New IP address for DNS host records. If you omit this, the script will attempt to auto-detect your public IP address and use that."
+    newline
+    textBlockSwitches "-4 | --ip4 | --ipv4"
+    textBlock "Switch value. Update Host 'A' records (IP4) only. Note that this script can only update either A *or* AAAA records. If you need to update both, you'll have to run the script once in IP4 mode and again in IP6 mode. If you specify both this switch and the IP6 switch, the last one specified will take effect."
+    textBlockDefaults "(enabled: update A records)"
+    newline
+    textBlockSwitches "-6 | --ip6 | --ipv6"
+    textBlock "Switch value. Update Host 'AAAA' records (IP6) only. Note that this script can only update either A *or* AAAA records. If you need to update both, you'll have to run the script once in IP4 mode and again in IP6 mode. If you specify both this switch and the IP4 switch, the last one specified will take effect."
+    textBlockDefaults "(disabled: update A records)"
+    newline
+    textBlock "Please refer to the repo README for more detailed information regarding this script and how to automate and monitor it."
+    newline
+    exit 0
+}
+
+stamp() {
+    (date +%F" "%T)
+}
+
+newline() {
+    printf "\n"
+}
+
+textBlock() {
+    printf "%s\n" "$1" | fold -w "$width" -s
+}
+
+textBlockDefaults() {
+    printf "%s%s%s\n" "$yellow" "$1" "$norm"
+}
+
+textBlockSwitches() {
+    printf "%s%s%s\n" "$cyan" "$1" "$norm"
+}
+
+writeLog() {
+    case "$1" in
+    cf)
+        printf "[%s] CF-ERR: %s (code: %s)\n" "$(stamp)" "$2" "$3" >>"$logFile"
+        ;;
+    err)
+        printf "%s[%s] ERR: %s%s\n" "$err" "$(stamp)" "$2" "$norm" >>"$logFile"
+        ;;
+    error)
+        printf "%s[%s] ERROR: %s (code: %s)%s\n" "$err" "$(stamp)" "$2" "$3" "$norm" >>"$logFile"
+        ;;
+    process)
+        printf "%s[%s] %s... %s" "$cyan" "$(stamp)" "$2" "$norm" >>"$logFile"
+        ;;
+    process-done)
+        printf "%s%s%s\n" "$cyan" "$2" "$norm" >>"$logFile"
+        ;;
+    process-error)
+        printf "%sERROR%s\n" "$err" "$norm" >>"$logFile"
+        ;;
+    process-warning)
+        printf "%s%s%s\n" "$warn" "$2" "$norm" >>"$logFile"
+        ;;
+    stamped)
+        printf "[%s] %s\n" "$(stamp)" "$2" >>"$logFile"
+        ;;
+    success)
+        printf "%s[%s] SUCCESS: %s%s\n" "$ok" "$(stamp)" "$2" "$norm" >>"$logFile"
+        ;;
+    warn)
+        printf "%s[%s] WARN: %s%s\n" "$warn" "$(stamp)" "$2" "$norm" >>"$logFile"
+        ;;
+    warning)
+        printf "%s[%s] WARNING: %s%s\n" "$warn" "$(stamp)" "$2" "$norm" >>"$logFile"
+        ;;
+    *)
+        printf "%s\n" "$2" >>"$logFile"
+        ;;
+    esac
+}
+
+### default variable values
+scriptPath="$(CDPATH='' \cd -- "$(dirname -- "$0")" && pwd -P)"
+scriptName="$(basename "$0")"
+logFile="$scriptPath/${scriptName%.*}.log"
+accountFile="$scriptPath/cloudflare.credentials"
+colourizeLogFile=1
+dnsRecords=""
+dnsSeparator=","
+ipAddress=""
+ip4=1
+ip6=0
+ip4DetectionSvc="http://ipv4.icanhazip.com"
+ip6DetectionSvc="http://ipv6.icanhazip.com"
+invalidDomainCount=0
+failedHostCount=0
+
+### process startup parameters
+if [ -z "$1" ]; then
+    scriptHelp
+fi
+while [ $# -gt 0 ]; do
+    case "$1" in
+    -h | -\? | --help)
+        # display help
+        scriptHelp
+        ;;
+    --examples)
+        # display sample commands
+        scriptExamples
+        ;;
+    -l | --log)
+        # set log file location
+        if [ -n "$2" ]; then
+            logFile="${2%/}"
+            shift
+        else
+            badParam null "$@"
+        fi
+        ;;
+    --log-console)
+        # log to the console instead of a file
+        logFile="/dev/stdout"
+        ;;
+    --no-log)
+        # do not log anything
+        logFile="/dev/null"
+        ;;
+    --nc | --no-color | --no-colour)
+        # do not colourize log file
+        colourizeLogFile=0
+        ;;
+    -c | --cred* | -f)
+        # path to Cloudflare credentials file
+        if [ -n "$2" ]; then
+            if [ -f "$2" ] && [ -s "$2" ]; then
+                accountFile="${2%/}"
+                shift
+            else
+                badParam dne "$@"
+            fi
+        else
+            badParam null "$@"
+        fi
+        ;;
+    -r | --record | --records)
+        # DNS records to update
+        if [ -n "$2" ]; then
+            dnsRecords=$(printf "%s" "$2" | sed -e 's/ //g')
+            shift
+        else
+            badParam null "$@"
+        fi
+        ;;
+    -i | --ip | --ip-address | -a | --address)
+        # IP address to use (not parsed for correctness)
+        if [ -n "$2" ]; then
+            ipAddress="$2"
+            shift
+        else
+            badParam null "$@"
+        fi
+        ;;
+    -4 | --ip4 | --ipv4)
+        # operate in IP4 mode (default)
+        ip4=1
+        ip6=0
+        ;;
+    -6 | --ip6 | --ipv6)
+        # operate in IP6 mode
+        ip6=1
+        ip4=0
+        ;;
+    *)
+        printf "\n%sUnknown option: %s\n" "$err" "$1"
+        printf "%sUse '--help' for valid options.%s\n\n" "$cyan" "$norm"
+        exit 1
+        ;;
+    esac
+    shift
 done

-# Log beginning of script
-echo -e "\e[1;32m[`date +%Y-%m-%d` `date +%H:%M:%S`] -- Start CloudFlare" \
-    "DDNS script execution --\e[0m" >> $logFile
-
-# Check validity of parameters
-if [ -z "$accountFile" ] || [[ $accountFile == -* ]]; then
-    quit 101
-elif [ ! -s "$accountFile" ]; then
-    quit 102
-elif [ -z ${dnsRecords} ]; then
-    quit 103
+### pre-flight checks
+if ! command -v curl >/dev/null; then
+    printf "\n%sThis script requires 'curl' be installed and accessible. Exiting.%s\n\n" "$err" "$norm"
+    exit 2
+fi
+if ! command -v jq >/dev/null; then
+    printf "\n%sThis script requires 'jq' be installed and accessible. Exiting.%s\n\n" "$err" "$norm"
+    exit 2
+fi
+[ -z "$dnsRecords" ] && badParam errMsg "You must specify at least one DNS record to update. Exiting."
+# verify credentials file exists and is not empty (default check)
+if [ ! -f "$accountFile" ] || [ ! -s "$accountFile" ]; then
+    badParam errMsg "Cannot find Cloudflare credentials file (${accountFile}). Exiting."
+fi
+# turn off log file colourization if parameter is set
+if [ "$colourizeLogFile" -eq 0 ]; then
+    bold=""
+    cyan=""
+    err=""
+    magenta=""
+    norm=""
+    ok=""
+    warn=""
+    yellow=""
 fi

-# Check if curl is installed
-command -v curl >> /dev/null
-curlResult=$(echo "$?")
-if [ $curlResult -ne 0 ]; then
-    quit 2
+### initial log entries
+{
+    printf "%s[%s] -- Cloudflare DDNS update-script: starting --%s\n" "$ok" "$(stamp)" "$norm"
+    printf "Parameters:\n"
+    printf "script path: %s\n" "$scriptPath/$scriptName"
+    printf "credentials file: %s\n" "$accountFile"
+
+    if [ "$ip4" -eq 1 ]; then
+        printf "mode: IP4\n"
+    elif [ "$ip6" -eq 1 ]; then
+        printf "mode: IP6\n"
    fi

-# Log operating mode
-if [ $ip4 -eq 1 ]; then
-    echo -e "\e[1;36m[`date +%Y-%m-%d` `date +%H:%M:%S`] Script running in" \
-        "IP4 mode\e[0m" >> $logFile
-elif [ $ip6 -eq 1 ]; then
-    echo -e "\e[1;36m [`date +%Y-%m-%d` `date +%H:%M:%S`] Script running in" \
-        "IP6 mode\e[0m" >> $logFile
-fi
-
-
-## Extract needed information from accountDetails file
-mapfile -t cfDetails < "$accountFile"
-
-## Get current IP address, if not provided in parameters
+    # detect and report IP address
    if [ -z "$ipAddress" ]; then
-    echo -e "\e[1;36m[`date +%Y-%m-%d` `date +%H:%M:%S`] No IP address for" \
-        "update provided.  Detecting this machine's IP address..." \
-        >> $logFile
-    if [ $ip4 -eq 1 ]; then
-        ipAddress=$(curl -s http://ipv4.icanhazip.com)
-    elif [ $ip6 -eq 1 ]; then
-        ipAddress=$(curl -s http://ipv6.icanhazip.com)
-    fi
-    # check if curl reported any errors
-    ipLookupResult=$(echo "$?")
-    if [ "$ipLookupResult" -ne 0 ]; then
-        quit 201
+        # detect public ip address
+        if [ "$ip4" -eq 1 ]; then
+            if ! ipAddress="$(curl -s $ip4DetectionSvc)"; then
+                printf "ddns ip address:%s ERROR%s\n" "$err" "$norm"
+                exitError 10
            fi
        fi
-echo -e "\e[1;36m[`date +%Y-%m-%d` `date +%H:%M:%S`] Using IP address:" \
-    "$ipAddress" >> $logFile
-
-
-## Check if desired record(s) exist at CloudFlare
-echo -e "\e[0m[`date +%Y-%m-%d` `date +%H:%M:%S`] Performing CloudFlare" \
-    "lookup on specified DNS records...\e[0m" >> $logFile
-# perform checks on A or AAAA records based on invocation options
-if [ $ip4 -eq 1 ]; then
-    echo -e "[`date +%Y-%m-%d` `date +%H:%M:%S`] (IP4: ${dnsRecords[*]})" \
-        >> $logFile
-    for cfLookup in "${dnsRecords[@]}"; do
-    cfRecords+=("$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones/${cfDetails[2]}/dns_records?name=$cfLookup&type=A" -H "X-Auth-Email: ${cfDetails[0]}" -H "X-Auth-Key: ${cfDetails[1]}" -H "Content-Type: application/json")")
-    done
-elif [ $ip6 -eq 1 ]; then
-    echo -e "[`date +%Y-%m-%d` `date +%H:%M:%S`] (IP6: ${dnsRecords[*]})" \
-        >> $logFile
-    for cfLookup in "${dnsRecords[@]}"; do
-    cfRecords+=("$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones/${cfDetails[2]}/dns_records?name=$cfLookup&type=AAAA" -H "X-Auth-Email: ${cfDetails[0]}" -H "X-Auth-Key: ${cfDetails[1]}" -H "Content-Type: application/json")")
-    done
+        if [ "$ip6" -eq 1 ]; then
+            if ! ipAddress="$(curl -s $ip6DetectionSvc)"; then
+                printf "ddns ip address:%s ERROR%s\n" "$err" "$norm"
+                exitError 10
            fi
-# check for curl errors
-cfLookupResult=$(echo "$?")
-if [ "$cfLookupResult" -ne 0 ]; then
-    quit 254
        fi
-# check for any non-existant domain names and remove from array
-for recordIdx in "${!cfRecords[@]}"; do
-    if [[ ${cfRecords[recordIdx]} == *"\"count\":0"* ]]; then
-        # inform user that domain not found in CloudFlare DNS records
-        echo -e "\e[0;31m[`date +%Y-%m-%d` `date +%H:%M:%S`] ***" \
-            "${dnsRecords[recordIdx]} not found in your" \
-            "CloudFlare DNS records***\e[0m" >> $logFile
-        # remove the entry from the dnsRecords array
-        unset dnsRecords[$recordIdx]
-        # remove the entry from the records array
-        unset cfRecords[$recordIdx]
-    fi
-done
-# contract the dnsRecords and cfRecords arrays to re-order them after any
-# deleted records
-dnsRecords=("${dnsRecords[@]}")
-cfRecords=("${cfRecords[@]}")
-
-# after trimming errant records, it's possible dnsRecords array is empty
-# check for this condition and exit (nothing to do), otherwise list arrays
-if [ -z ${dnsRecords} ]; then
-    quit 104
+        printf "ddns ip address (detected): %s\n" "$ipAddress"
    else
-    for recordIdx in "${!cfRecords[@]}"; do
-        echo -e "\e[1;39m[`date +%Y-%m-%d` `date +%H:%M:%S`] Found" \
-            "${dnsRecords[recordIdx]} (Index: $recordIdx):\e[0m" \
-            >> $logFile
-    done
+        printf "ddns ip address (supplied): %s\n" "$ipAddress"
    fi

+    # iterate DNS records to update
+    dnsRecordsToUpdate="$(printf '%s' "${dnsRecords}" | sed "s/${dnsSeparator}*$//")$dnsSeparator"
+    while [ -n "$dnsRecordsToUpdate" ] && [ "$dnsRecordsToUpdate" != "$dnsSeparator" ]; do
+        record="${dnsRecordsToUpdate%%${dnsSeparator}*}"
+        dnsRecordsToUpdate="${dnsRecordsToUpdate#*${dnsSeparator}}"

-## Get existing IP address and identifier in CloudFlare's DNS records
-for recordIdx in "${!cfRecords[@]}"; do
-    currentIP+=($(echo "${cfRecords[recordIdx]}" | \
-        grep -Po '(?<="content":")[^"]*'))
-    recordID+=($(echo "${cfRecords[recordIdx]}" | \
-        grep -Po '(?<="id":")[^"]*'))
-    echo -e "\e[0m[`date +%Y-%m-%d` `date +%H:%M:%S`] Index $recordIdx:" \
-        "For record ${dnsRecords[recordIdx]}" \
-        "with ID: ${recordID[recordIdx]}" \
-        "the current IP is \e[1;35m ${currentIP[recordIdx]}" \
-        "\e[0m" >> $logFile
+        if [ -z "$record" ]; then continue; fi
+        printf "updating record: %s\n" "$record"
    done

-## Check whether new IP matches old IP and update if they do not match
-for recordIdx in "${!currentIP[@]}"; do
-    if [ ${currentIP[recordIdx]} = $ipAddress ]; then
-        echo -e "\e[1;32m[`date +%Y-%m-%d` `date +%H:%M:%S`]" \
-        "${dnsRecords[recordIdx]} is up-to-date.\e[0m" \
-            >> $logFile
-    else
-        echo -e "\e[0;31m[`date +%Y-%m-%d` `date +%H:%M:%S`]" \
-        "${dnsRecords[recordIdx]} needs updating...\e[0m" \
-            >> $logFile
-        if [ $ip4 -eq 1 ]; then
-            # update record at CloudFlare with new IP
-            update=$(curl -s -X PUT "https://api.cloudflare.com/client/v4/zones/${cfDetails[2]}/dns_records/${recordID[recordIdx]}" -H "X-Auth-Email: ${cfDetails[0]}" -H "X-Auth-Key: ${cfDetails[1]}" -H "Content-Type: application/json" --data "{\"id\":\"${cfDetails[2]}\",\"type\":\"A\",\"proxied\":false,\"name\":\"${dnsRecords[recordIdx]}\",\"content\":\"$ipAddress\"}")
-        elif [ $ip6 -eq 1 ]; then
-            # update record at CloudFlare with new IP
-            update=$(curl -s -X PUT "https://api.cloudflare.com/client/v4/zones/${cfDetails[2]}/dns_records/${recordID[recordIdx]}" -H "X-Auth-Email: ${cfDetails[0]}" -H "X-Auth-Key: ${cfDetails[1]}" -H "Content-Type: application/json" --data "{\"id\":\"${cfDetails[2]}\",\"type\":\"AAAA\",\"proxied\":false,\"name\":\"${dnsRecords[recordIdx]}\",\"content\":\"$ipAddress\"}")
+    printf "(end of parameter list)\n"
+} >>"$logFile"
+
+### read Cloudflare credentials
+writeLog process "Reading Cloudflare credentials"
+case "$accountFile" in
+/*)
+    # absolute path, use as-is
+    # shellcheck source=./cloudflare.credentials
+    . "$accountFile"
+    ;;
+*)
+    # relative path, rewrite
+    # shellcheck source=./cloudflare.credentials
+    . "./$accountFile"
+    ;;
+esac
+if [ -z "$cfKey" ]; then
+    writeLog process-error
+    exitError 21
 fi
-        # check for success code from CloudFlare
-        if [[ $update == *"\"success\":true"* ]]; then
-            echo -e "\e[1;32m[`date +%Y-%m-%d` `date +%H:%M:%S`]" \
-                "${dnsRecords[recordIdx]} updated.\e[0m" >> $logFile
-        else
-            echo -e "\e[1;31m[`date +%Y-%m-%d` `date +%H:%M:%S`]" \
-                "${dnsRecords[recordIdx]} update failed\e[0m" >> $logFile
-                echo -e "\e[0;39m$update\e[0m" >> $logFile
-            failedDNS+=("${dnsRecords[recordIdx]}")
+if [ -z "$cfZoneId" ]; then
+    writeLog process-error
+    exitError 22
 fi
+writeLog process-done "DONE"
+
+### connect to Cloudflare and do what needs to be done!
+dnsRecordsToUpdate="$dnsRecords$dnsSeparator"
+if [ "$ip4" -eq 1 ]; then
+    recordType="A"
+elif [ "$ip6" -eq 1 ]; then
+    recordType="AAAA"
+fi
+
+# iterate hosts to update
+while [ -n "$dnsRecordsToUpdate" ] && [ "$dnsRecordsToUpdate" != "$dnsSeparator" ]; do
+    record="${dnsRecordsToUpdate%%${dnsSeparator}*}"
+    dnsRecordsToUpdate="${dnsRecordsToUpdate#*${dnsSeparator}}"
+
+    if [ -z "$record" ]; then continue; fi
+    writeLog process "Processing ${record}"
+
+    # exit if curl/network error
+    if ! cfLookup="$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones/${cfZoneId}/dns_records?name=${record}&type=${recordType}" \
+        -H "Authorization: Bearer ${cfKey}" \
+        -H "Content-Type: application/json")"; then
+        writeLog process-error
+        exitError 3
+    fi
+
+    # exit if API error
+    # exit here since API errors on GET request probably indicates authentication error which would affect all remaining operations
+    # no reason to continue processing other hosts and pile-up errors which might look like a DoS attempt
+    cfSuccess="$(printf "%s" "$cfLookup" | jq -r '.success')"
+    if [ "$cfSuccess" = "false" ]; then
+        writeLog process-error
+        listCFErrors "$cfLookup"
+        exitError 25
+    fi
+
+    resultCount="$(printf "%s" "$cfLookup" | jq '.result_info.count')"
+
+    # skip to next host if cannot find existing host record (this script *updates* only, does not create!)
+    if [ "$resultCount" = "0" ]; then
+        # warn if record of host not found
+        writeLog process-warning "NOT FOUND"
+        writeLog warn "Cannot find existing record to update for DNS entry: ${record}"
+        invalidDomainCount=$((invalidDomainCount + 1))
+        continue
+    fi
+
+    objectId=$(printf "%s" "$cfLookup" | jq -r '.result | .[] | .id')
+    currentIpAddr=$(printf "%s" "$cfLookup" | jq -r '.result | .[] | .content')
+    writeLog process-done "FOUND: IP = ${currentIpAddr}"
+
+    # skip to next hostname if record already up-to-date
+    if [ "$currentIpAddr" = "$ipAddress" ]; then
+        writeLog stamped "IP address for ${record} is already up-to-date"
+        continue
+    fi
+
+    # update record
+    writeLog process "Updating IP address for ${record}"
+    updateJSON="$(jq -n --arg key0 content --arg value0 "${ipAddress}" '{($key0):$value0}')"
+
+    # exit if curl/network error
+    if ! cfResult="$(curl -s -X PATCH "https://api.cloudflare.com/client/v4/zones/${cfZoneId}/dns_records/${objectId}" \
+        -H "Authorization: Bearer ${cfKey}" \
+        -H "Content-Type: application/json" \
+        --data "${updateJSON}")"; then
+        writeLog process-error
+        exitError 3
+    fi
+
+    # note update success or failure
+    cfSuccess="$(printf "%s" "$cfResult" | jq '.success')"
+    if [ "$cfSuccess" = "true" ]; then
+        writeLog process-done "DONE"
+        writeLog success "IP address for ${record} updated."
+    else
+        writeLog process-error
+        listCFErrors "$cfResult"
+        writeLog err "Unable to update IP address for ${record}"
+        # do not exit with error, API error here is probably an update issue specific to this host
+        # increment counter and note it after all processing finished
+        failedHostCount=$((failedHostCount + 1))
    fi
 done

-# Check if failedDNS array contains entries and exit with error, else exit 0
-if [ -z "${failedDNS}" ]; then
-    quit
+# exit
+if [ "$invalidDomainCount" -ne 0 ]; then
+    writeLog warning "${invalidDomainCount} invalid host(s) supplied for updating."
+fi
+if [ "$failedHostCount" -ne 0 ]; then
+    exitError 26
 else
-    quit 199
+    exitOK
 fi

-# this code should never be executed
-exit 99
+### exit return codes
+# 0:    normal exit, no errors
+# 1:    invalid or unknown parameter
+# 2:    cannot find or access required external program(s)
+# 3:    curl error (probably connection)
+# 10:   cannot auto-detect IP address
+# 21:   accountFile has a null or missing cfKey variable
+# 22:   accountFile has a null or missing cfZoneId variable
+# 25:   Cloudflare API error
+# 26:   one or more updates failed
+# 99:   unspecified error occurred
@@ -0,0 +1,6 @@
+#
+# CloudFlare token for my.domain.tld
+#
+
+cfKey=_dLuyyRNaKN8SLG4-csmNYYfC39nnCmPVA7aYUJj
+cfZoneId=83d564234134513245311b23412331dd
@@ -0,0 +1,15 @@
+### Rotate cfddns log file
+
+# location of log file (-l parameter of script file)
+/path/to/cfddns.log {
+    
+    # rotate log file weekly -- you could also use 'daily', 'monthly' or
+    # specify a size using 'size 100k', for example
+    weekly
+    
+    # keep 3 weeks of old logs (3 files) and delete older ones
+    rotate 3
+    
+    # compress old log files using gzip (default)
+    compress
+}
@@ -0,0 +1,238 @@
+# Using Logwatch to monitor Cloudflare DDNS updater script <!-- omit in toc -->
+
+The Cloudflare DDNS update script's log file has been set up so that utilities like Logwatch can easily parse it.  In order to make that happen, a LogFile Group file, Service and Script have to be created for Logwatch to generate reports.  The correct (general) directory structure has been created in this git archive already.  Below are the details of each file.
+
+You can implement this setup easily by copying it into your */etc/logwatch* directory and then modifying the files as necessary:
+
+```bash
+cd /etc/logwatch
+cp -R /path/to/CloudflareDDNS_repo/etc/logwatch/* ./
+```
+
+If you need help getting logwatch installed and set-up, please [check out my blog post](#https://mytechiethoughts.com/linux/easily-monitor-your-logs-using-logwatch/).
+
+## Contents <!-- omit in toc -->
+
+<!-- toc -->
+
+- [LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)](#logfile-group-file-etclogwatchconflogfilescfddnsconf)
+  * [Log file location](#log-file-location)
+  * [Archive location and name format](#archive-location-and-name-format)
+  * [External script for timestamp processing](#external-script-for-timestamp-processing)
+- [Service definition file (/etc/logwatch/conf/services/cfddns.conf)](#service-definition-file-etclogwatchconfservicescfddnsconf)
+  * [LogFile Group file definition](#logfile-group-file-definition)
+  * [Report title](#report-title)
+  * [Detail level](#detail-level)
+- [Service script (/etc/logwatch/scripts/services/cfddns)](#service-script-etclogwatchscriptsservicescfddns)
+  * [Detail levels](#detail-levels)
+- [Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere)](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere)
+  * [The time format specification](#the-time-format-specification)
+  * [The search REGEX](#the-search-regex)
+- [Testing](#testing)
+- [Final thoughts](#final-thoughts)
+
+<!-- tocstop -->
+
+## LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)
+
+### Log file location
+
+Update this as needed to point to the location and name of the log file generated by the updater script.  Remember, by default, the log file is created in the same directory as the script itself.
+
+```Ini
+LogFile = /path/to/your/cfddns.log
+...
+```
+
+Best practices suggest you use the `--log` flag to change this location to something like */var/log/cfddns.log*, for example.  In that case, the entry would look like:
+
+```Ini
+LogFile = /var/log/cfddns.log
+...
+```
+
+### Archive location and name format
+
+If you want Logwatch to process old (archived) log files generated by something like *Logrotate*, then you have to specify the location and file name format of those files.  I've included the generalized compressed format of such rotated files as the default in the script.  Suppose you store your log files in the recommended location (*/var/log/*) and are using *Logrotate* with compression enabled, the archive line would look like:
+
+```Ini
+...
+Archive = /var/log/cfddns.log.?.gz
+...
+```
+
+This would tell Logwatch, when the archive option is set to true, that your *cfddns.log* files are archived as: *cfddns.log.1.gz*, *cfddns.log.2.gz*, etc. and are all located in */var/log/*.
+
+> Note: This line is totally optional and only used if you set the archive option in Logwatch to true.  You can comment/delete this line if you wish.
+
+### External script for timestamp processing
+
+Since the log file uses a non-standard (according to Logwatch) method of date-stamping, a custom filter had to be created.  See the [relevant](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere) section of this document for more information.
+
+The script file is called with an asterisk (*\**) before the filename.
+
+```Ini
+...
+*sqFullStampAnywhere
+...
+```
+
+If you change the name of this file, you will have to change this line. Remember that whatever you type here as a name is converted to all-lowercase so your filename should be all lowercase also.
+
+## Service definition file (/etc/logwatch/conf/services/cfddns.conf)
+
+### LogFile Group file definition
+
+The service file needs to know what group of log files it is responsible for processing.  This MUST match the name of your *LogFile Group file*:
+
+```Ini
+LogFile = cfddns
+...
+```
+
+If you change your LogFile Group filename, then update it here also without the *.conf* extension.
+
+### Report title
+
+The Logwatch output file (html or text) is divided into sections.  You can define the title to be anything that has meaning for you.  I have arbitrarily chosen *"CloudFlare DDNS update"* but you can change it to anything you want by modifying the line:
+
+```Ini
+...
+Title = "CloudFlare DDNS update"
+```
+### Detail level
+
+If you want to set the *detail* level of this service differently from your other services (which will use the *--detail* switch value or the value in your *logwatch.conf*), then you can define that level here.  By default, it appears like this in the service configuration file:
+
+```Ini
+...
+# Override the detail level for this service
+# Remember the levels are: 0, 1-4, 5, 6+
+# Detail = 0
+```
+
+Simply change it to the value you want enforced.  For example, here I'm setting it to output level 5 regardless of whatever settings everything else is using.
+
+```Ini
+# Override the detail level for this service
+# Remember the levels are: 0, 1-4, 5, 6+
+Detail = 5
+```
+
+## Service script (/etc/logwatch/scripts/services/cfddns)
+
+Logwatch calls any script with a name that **matches the service name**.  You'll notice that I just named everything *cfddns* to keep things simple.  You can change this to whatever you want.  If you changed the service name to *"cloudflare*.conf", for example, you would have to rename this script file to "*cloudflare*" with no extension.  Note: The script is a PERL file (note the
+shebang) but it can be written in any language.
+
+In essence, Logwatch just spits out the log file(s) defined in the LogFile Group file as standard input (STDIN) for the script and then takes whatever is output (STDOUT) from the script to assemble into its report.
+
+### Detail levels
+
+The script supports four (4) detail levels as follows:
+
+- **Level 0: Summary output only**
+  - This will display a simple aggregate of status message categories over the reporting period:
+    - Entries successfully updated
+    - Entries already up-to-date
+    - Hosts failed to update
+    - Undefined hosts (i.e. requested to update but record doesn’t exist)
+    - Total warning messages
+    - Total errors
+    
+  - **This is the recommended reporting level.**  It does not take up much space and is quick to read.  If you see successful updates and/or up-to-date numbers match what you expect and no errors logged, then you can assume things are working properly. If the numbers aren’t right or you see errors/warnings, then you can investigate the situation by consulting the actual logs or increasing the detail level in logwatch.
+  
+  - For example: Let’s suppose you are running an update every 15 minutes. Doing the math...
+    $$
+    (update_{success}) + (update_{up-to-date}) = (24h \times 60min)/15min = 96
+    $$
+    Therefore, you expect to see ‘Entries successfully updated’ and ‘Entries already up-to-date’ total *96*. If that’s the case and no errors or warnings are logged, things are ok. Pretty easy, right? That’s why this is the recommended filter setting.
+- **Levels 1-4: Critical messages**
+  
+  - This uses the data which is summarized by Level 0 but outputs the *actual messages* in the log file.  For example, you will see the actual text of the errors logged instead of just a total number of errors.  This level of reporting is useful when *initially* monitoring the script's operation since you can see the text of any generated errors.
+  - Levels 1, 2, 3 & 4 are identical so pick your favourite number.
+- **Level 5: Verbose output**
+  - Like the previous level, this outputs the actual messages found in the log file.  However, it also includes *CF-ERR* tags and tally count messages. This can help you pinpoint why the Cloudflare API is rejecting your requests by letting you see things like authentication errors or malformed addresses, etc.
+  - Honestly, this is not much more information than L1-L4 and is often a better choice while debugging any issues since you get the Cloudflare API messages.
+  - This level of output is much more verbose than the summary report. It also takes *much* more time and patience to review so it is only recommended when you’re dealing with issues.
+  - This is *not* recommended for day-to-day or routine reports.
+- **Levels 6+: Complete log file dump**
+  - Any number greater than 5 passed as a detail level will trigger the script to dump the entire log file out to Logwatch line-by-line.  This is really only useful during debugging or dealing with serious issues where you do not have access to the actual log file. While this is an exact ‘echo’ of the log file, it likely will not be colour-coded which makes it harder to review.
+  - **Use this detail level only when you need to see the entire log file and cannot otherwise access the log file.**
+  - Depending on how your logwatch treats this log dump, you may see gibberish control codes like *\e[0m;]*. If this is the case, run the script with the `--no-colour` or `--nc` option to remove ANSI colour formatting.
+
+## Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere)
+
+This is basically a modified version of the '*applyeurodate*' script that comes with Logwatch.  It had to be modified to search within [square brackets] and to accept characters coming before the stamp (i.e. ANSI colour codes).  If you change the '**stamp**' variable in the updater script to update the timestamp to your liking (which to totally fine!) then you'll probably have to update this file.  There are two lines you need to modify to suit your new '**stamp**' variable.
+
+> This entire section is only applicable if you are a very curious person or if you change the hard-coded ‘stamp’ function in the script. If you did not make any changes and you like a little mystery in your life, you can safely skip this entire section.
+
+### The time format specification
+
+'*$SearchDate*' is the variable used in the PERL script to do exactly what it says, search for the date stamp.  I have it set up to look for the format '*year-month-date hour:minute:second*'.  Note, we don't care about brackets or anything here, we're just defining the format of the date/time stamp.
+
+```Perl
+...
+$SearchDate = TimeFilter('%Y-%m-%d %H:%M:%S');
+...
+```
+
+If you changed the '**stamp**' variable so it was formatted as '*month/day/year hour:minute*' (ex: '*[09/27/2018 18:38]*') then you'd update the **$SearchDate** variable as follows (note: no mention of the square brackets!):
+
+```Perl
+...
+$SearchDate = TimeFilter('%m/%d/%Y %H:%M');
+...
+```
+
+### The search REGEX
+
+The PERL script uses a '*regular expression*' (REGEX) to search within the log file for '*$SearchDate*'.  For the default date stamp, this specification looks like:
+
+```Perl
+...
+if ($ThisLine =~ m/\[$SearchDate\] /o) {
+...
+```
+
+The REGEX appears between '*m/*' and '*/o*'.  In this case, it searches for '*$SearchDate*' inside [square brackets] appearing anywhere on the line.  This is because ANSI colour-codes often appear before the date stamp in the default log file.  If you have modified this so that your date stamp appears at the beginning of the line and in the example format in the section above (using slashes instead of dashes) then you'd rewrite this REGEX as follows:
+
+```Perl
+...
+if ($ThisLine =~ m/^\[$SearchDate\] /o) {
+...
+```
+
+or using regular brackets anywhere on the line:
+
+```Perl
+...
+if ($ThisLine =~ m/\($SearchDate\) /o) {
+...
+```
+
+or without any brackets but appearing at the beginning of the line:
+
+```Perl
+...
+if ($ThisLine =~ m/^$SearchDate /o) {
+...
+```
+
+## Testing
+
+Run *logwatch --help* and note the options.  You can test just this service locally on your screen with the following command (assuming you kept default names for everything):
+
+```Bash
+# Summary output, entire duration of log file
+logwatch --service cfddns --output stdout --format text --range all --detail 0
+
+# Minimal detail, yesterday only
+logwatch --service cfddns --output stdout --format text --range yesterday --detail 1
+
+# Verbose output, today only
+logwatch --service cfddns --output stdout --format text --range today --detail 5
+```
+
+## Final thoughts
+
+That's it!  I'm a horrible PERL programmer so if anyone can optimize/improve the script file used for Logwatch then please do it!  Otherwise, I hope this made sense and helped you integrate the updater script with Logwatch for easy monitoring :-)
@@ -0,0 +1,13 @@
+# Location of your script's log file, -l parameter
+LogFile = /path/to/your/cfddns.log
+
+# Format of logrotate archives for your script. Example assumes compression and
+# extension preservation
+Archive = /path/to/your/logfile.ext.?.gz
+
+# Apply the correct date/time filtering to match the format of the script's log
+# We are using a custom pl script in /etc/logwatch/scripts/shared/
+# You don't need to change this unless you have altered the 'stamp' variable in
+# the script in which case you will want to update the regex in the custom pl
+# script below
+*sqFullStampAnywhere
@@ -0,0 +1,9 @@
+# Name of the logfile group without any extension
+LogFile = cfddns
+
+# Heading displayed on Logwatch's report for this service
+Title = "CloudFlare DDNS update"
+
+# Override the detail level for this service
+# Remember the levels are: 0, 1-4, 5, 6+
+# Detail = 0
@@ -0,0 +1,144 @@
+#!/usr/bin/perl
+
+#############################################################################
+# $Id$
+#############################################################################
+# Log: CloudFlare updater script (cfddns)
+# Revision 2.1  2021/05/08
+# Written by Asif Bacchus
+#############################################################################
+
+
+use strict;
+
+### Get Logwatch detail level
+my $detailLevel = $ENV{'LOGWATCH_DETAIL_LEVEL'} || 0;
+
+
+### Declare variables
+my $summaryErr;
+my $summaryFailedUpdate;
+my $summaryInvalidHost;
+my $summaryUpdated;
+my $summaryUpToDate;
+my $summaryWarning;
+
+my %reportHash = ();
+my $key;
+
+
+### Minimal detail level: provide summary data only
+if ($detailLevel == 0) {
+    ### process logfile and summarize message types
+    while (defined(my $ThisLine = <STDIN>)) {
+        if ($ThisLine =~ /ERR: Unable to update IP address/) {
+            $summaryFailedUpdate++;
+        }
+        elsif ($ThisLine =~ /ERROR: /) {
+            $summaryErr++;
+        }
+        elsif ($ThisLine =~ /WARN: Cannot find existing record/) {
+            $summaryInvalidHost++;
+        }
+        elsif ($ThisLine =~ /WARNING: /){
+            $summaryWarning++;
+        }
+        elsif ($ThisLine =~ /SUCCESS: /) {
+            $summaryUpdated++;
+        }
+        elsif ($ThisLine =~ /already up-to-date/) {
+            $summaryUpToDate++;
+        }
+    }
+
+    ### fill hash table with headings and summary counts
+    if ($summaryUpdated > 0) {
+        $reportHash{"Entries successfully updated"} = $summaryUpdated;
+    }
+    if ($summaryUpToDate > 0) {
+        $reportHash{"Entries already up-to-date"} = $summaryUpToDate;
+    }
+    if ($summaryFailedUpdate > 0) {
+        $reportHash{"Hosts failed to update"} = $summaryFailedUpdate;
+    }
+    if ($summaryInvalidHost > 0) {
+        $reportHash{"Undefined hosts"} = $summaryInvalidHost;
+    }
+    if ($summaryWarning > 0) {
+        $reportHash{"Total warnings"} = $summaryWarning;
+    }
+    if ($summaryErr > 0) {
+        $reportHash{"Total errors"} = $summaryErr;
+    }
+
+    ### print hash table
+    foreach $key (sort keys %reportHash) {
+        print "$key: $reportHash{$key}\n";
+    }
+}
+### Levels 1-4 provide the actual error, status and success messages instead of
+### a summary count
+elsif ($detailLevel >= 1 && $detailLevel <= 4) {
+    while (defined(my $ThisLine = <STDIN>)) {
+        if ($ThisLine =~ /ERR: /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /WARN: /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /SUCCESS: /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /already up-to-date/) {
+            print $ThisLine;
+        }
+    }
+}
+### Level 5 includes warning and error tally count messages and Cloudflare
+### debugging messages
+elsif ($detailLevel == 5) {
+    while (defined(my $ThisLine = <STDIN>)) {
+        if ($ThisLine =~ /ERR: /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /ERROR: /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /CF-ERR: /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /WARN: /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /WARNING: /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /SUCCESS: /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /already up-to-date/) {
+            print $ThisLine;
+        }
+    }
+}
+### Any level 6 or above will echo the entire log. The log itself is purposefully terse
+### so while this level of detail is likely rarely needed, it is still not an overwhelming
+### level of detail.
+### Generally, however, using this level of detail should only be done if you cannot view
+### the actual log file directly for whatever reason. The actual log file is colour-coded
+### for easier debugging.
+elsif ($detailLevel > 5) {
+    while (defined(my $ThisLine = <STDIN>)) {
+        print $ThisLine;
+    }
+}
+
+### Exit gracefully
+exit (0);
+
+# vi: shiftwidth=3 tabstop=3 et
+# Local Variables:
+# mode: perl
+# perl-indent-level: 3
+# indent-tabs-mode: nil
+# End:
@@ -0,0 +1,37 @@
+#!/usr/bin/perl
+
+##########################################################################
+# $Id$
+##########################################################################
+
+###############################################################################
+## Filter dates in full-date-time international format, surrounded by square
+## brackets located anywhere on a given line
+## Format: '[%Y-%m-%d %H:%M:%S]'
+###############################################################################
+
+use Logwatch ':dates';
+
+my $Debug = $ENV{'LOGWATCH_DEBUG'} || 0;
+
+### Specify the format of the date/time stamp itself
+$SearchDate = TimeFilter('%Y-%m-%d %H:%M:%S');
+
+if ( $Debug > 5 ) {
+   print STDERR "DEBUG: Inside FullDateTime...\n";
+   print STDERR "DEBUG: Looking For: " . $SearchDate . "\n";
+}
+
+while (defined($ThisLine = <STDIN>)) {
+   ### specify the regex that defines how to find 'SearchDate'
+   if ($ThisLine =~ m/\[$SearchDate\] /o) {
+      print $ThisLine;
+   }
+}
+
+# vi: shiftwidth=3 syntax=perl tabstop=3 et
+# Local Variables:
+# mode: perl
+# perl-indent-level: 3
+# indent-tabs-mode: nil
+# End:
Author	SHA1	Message	Date
Asif Bacchus	0cd84a3711	update logwatch readme	2021-05-09 23:43:41 -06:00
Asif Bacchus	d8fe395a19	update readme files	2021-05-09 14:39:28 -06:00
Asif Bacchus	ac4cf940ff	refactor(SAMPLE): remove un-needed email address	2021-05-09 10:44:21 -06:00
Asif Bacchus	dc13e1d412	refactor(LOGWATCH): use new log tags - update to reference new log tags - adjust count to separate tally messages - add CF-ERR tag reports - re-add level 5 reporting detail	2021-05-09 10:43:05 -06:00
Asif Bacchus	e344b027f9	refactor: remove err label on code 99	2021-05-09 10:28:17 -06:00
Asif Bacchus	8801e55e30	style: fix typo, invalid hosts warning summary	2021-05-09 10:24:15 -06:00
Asif Bacchus	b05192a613	fix: wrong pipeline variable ref in writelog	2021-05-09 09:49:47 -06:00
Asif Bacchus	d796bf6f63	fix: wrong variable referenced for list to update	2021-05-09 09:47:41 -06:00
Asif Bacchus	db8a615d36	refactor: use function to write to log - much more consistent - one place to change all entries	2021-05-09 09:46:15 -06:00
Asif Bacchus	31eb503245	style: change 'domain' to 'host' terminology is more correct and less potentially confusing	2021-05-09 08:48:56 -06:00
Asif Bacchus	3f9d164285	style: rename functions to clear spellcheck	2021-05-09 08:45:24 -06:00
Asif Bacchus	39f5445c28	perf: simpler iteration condition checking - less complex conditions - easier code to understand - cleans up extraneous delimiters - skips null entries immediately	2021-05-09 08:44:47 -06:00
Asif Bacchus	220263c1f9	refactor: change log tags - separate tags for summary vs individual messages for accurate logwatch counting - update code 99 exit to match other errors - change CF error tags to match new format	2021-05-09 07:08:44 -06:00
Asif Bacchus	fe0f9caef1	feature: process multiple CF API errors - handle multiple CF API errors properly by grouping and reporting - update error messages - unify CF error tags in log to CF-ERROR	2021-05-09 06:49:49 -06:00
Asif Bacchus	d9600c822f	style: alphabetize functions	2021-05-09 06:39:55 -06:00
Asif Bacchus	5569bbc535	refactor: remove cfEmail - authorized email not required by CF when using bearer token	2021-05-09 04:35:46 -06:00
Asif Bacchus	f4f3c89e5e	refactor: reduce nesting, update err codes - detect curl vs CF API errors separately - error 25 changed to error 3 (curl/network) - error 25 reservedfor CF API errors - add CF error messages to all err 25s - change error 98 (updates) to error 26 - remove error code for exit with warning - add CF error messages on update failures - drastically reduce if/else nesting	2021-05-09 04:33:41 -06:00
Asif Bacchus	a7064805c3	style: log params in default colour vs magenta	2021-05-09 03:58:35 -06:00
Asif Bacchus	c1c7fd5149	style: correct spelling of Cloudflare	2021-05-09 00:42:53 -06:00
Asif Bacchus	d9224b5791	refactor(LOGWATCH): match new script structure - update keyword filters - update reporting detail levels - better targeting of useful information at summary detail level	2021-05-08 04:40:31 -06:00
Asif Bacchus	2805f560d7	docs: fix typos in comments, help, etc	2021-05-08 04:24:26 -06:00
Asif Bacchus	e7935dbd99	refactor(SYSTEMD): update service file switches	2021-05-08 04:06:04 -06:00
Asif Bacchus	029cef1d7f	chore(GIT): add gitattributes file	2021-05-08 04:03:18 -06:00
Asif Bacchus	52f5ef96e8	refactor: replace BASH script with new POSIX one	2021-05-08 04:00:15 -06:00
Asif Bacchus	124644e38e	feature: add console and no-logging features	2021-05-08 03:58:30 -06:00
Asif Bacchus	a060e72ea0	fix: confirm creds exist if using default location	2021-05-08 03:50:58 -06:00
Asif Bacchus	7bc5f73e27	docs: add in-script example commands	2021-05-08 03:43:47 -06:00
Asif Bacchus	94e1208af2	docs: add in-script help	2021-05-08 03:29:37 -06:00
Asif Bacchus	d7be713574	refactor: use patch to only change IP - remove proxy option, not needed - doesn't touch any other configured properties	2021-05-08 02:37:28 -06:00
Asif Bacchus	cc3f52b849	struct: finish operational rewrite - add requirement and check for jq for JSON processing - run all checks, confirmations and actions via JSON - check existing records - update records as needed - update error codes and reporting - less colourful logs by default	2021-05-08 02:05:32 -06:00
Asif Bacchus	36ececcb5d	struct(templates): add sample credentials file	2021-05-08 02:04:03 -06:00
Asif Bacchus	53f7245001	feature: auto-detect ip, update exit func - auto-detect IP address if not supplied - rework exit functions: one for error, one for success	2021-05-07 15:32:46 -06:00
Asif Bacchus	cf820d777d	refactor: ip4 and ip6 mutual override - use the most recently specified option	2021-05-07 14:03:52 -06:00
Asif Bacchus	1ede37961f	fix: turn off ip4 when ip6 selected	2021-05-07 14:00:32 -06:00
Asif Bacchus	5a477d6c86	feature: initial logging, add curl check	2021-05-07 13:59:07 -06:00
Asif Bacchus	911526dd08	struct: skeleton of POSIX script version	2021-05-07 13:30:51 -06:00
Asif Bacchus	2e978050b6	Added spacing for readability	2018-10-01 22:25:54 -06:00
Asif Bacchus	ba2b728e88	Added section about detail level in service config file	2018-10-01 22:25:18 -06:00
Asif Bacchus	7470b2c1fa	Added commented out Detail setting in the service defintion file	2018-10-01 22:20:17 -06:00
Asif Bacchus	a43a0bf80e	Updated to include logrotate instructions and new TOC	2018-09-28 00:07:41 -06:00
Asif Bacchus	2db482e800	Created sample logrotate config file	2018-09-27 23:52:03 -06:00
Asif Bacchus	7f90f496a9	Cleaned up TOC	2018-09-27 19:31:09 -06:00
Asif Bacchus	fe9b7fc578	Cleaned up markdown code	2018-09-27 19:30:14 -06:00
Asif Bacchus	a901fc7ea2	Proofreading	2018-09-27 19:25:23 -06:00
Asif Bacchus	689f11beba	Updated TOC to remove improper headings	2018-09-27 19:01:38 -06:00
Asif Bacchus	0b2668f150	Added auto-generated TOC	2018-09-27 18:55:20 -06:00
Asif Bacchus	35cdd91089	Initial Logwatch integration readme	2018-09-27 18:54:08 -06:00
Asif Bacchus	d9d9e58764	Cleaned up markdown coding	2018-09-27 17:42:43 -06:00
Asif Bacchus	74fab6429a	Updated readme to mention separate logwatch readme file.	2018-09-27 17:36:52 -06:00
Asif Bacchus	97c7105cb9	Corrected [INFO] tagging to have '--' prepended for consistency	2018-09-27 17:02:49 -06:00
Asif Bacchus	7f4de4f0f3	Changed REGEXs to look for updated tags in log file	2018-09-27 17:00:48 -06:00
Asif Bacchus	f0bc037416	Updated comments	2018-09-27 16:57:41 -06:00
Asif Bacchus	3b92b2c509	Added all other detail levels	2018-09-27 16:53:23 -06:00
Asif Bacchus	462d081b14	Rewrite logwatch script: changed to PERL instead of BASH. Initial code, summary only.	2018-09-27 16:40:53 -06:00
Asif Bacchus	47acc2684c	Updated Logwatch 'SearchDate' custom script. Renamed it. Updated notes in LogFile config.	2018-09-26 22:54:14 -06:00
Asif Bacchus	9ba6b40904	Corrected path sample in Logfile group configuration.	2018-09-26 02:05:25 -06:00
Asif Bacchus	9aafb7b023	Updated Logfile group configuration. Include archive and time-format.	2018-09-26 02:04:00 -06:00
Asif Bacchus	657bc1e3ee	Created date filter for parsing timestamps in logs	2018-09-26 01:53:16 -06:00
Asif Bacchus	2b9580382f	Cleaned up spacing in comments in cfddns Logwatch script	2018-09-26 01:16:20 -06:00
Asif Bacchus	87d3215c70	Initial: Script file Logwatch executes to parse cfddns.log	2018-09-26 01:11:29 -06:00
Asif Bacchus	662879e8a0	Created Logwatch service and logfile location config files	2018-09-26 00:40:25 -06:00
Asif Bacchus	3fd8a66257	Cleaned up code to remove unused variables and quote where needed	2018-09-26 00:35:33 -06:00
Asif Bacchus	07820587d8	Changed colour used for STATUS update. Fixed typo in "Script Completed" notation.	2018-09-25 18:43:35 -06:00
Asif Bacchus	b49be41577	Fixed spacing typo	2018-09-25 18:41:40 -06:00
Asif Bacchus	c7618c7a4b	Changed logfile notation for IP4 vs IP6 hostname list	2018-09-25 18:39:23 -06:00
Asif Bacchus	f8a23992ea	Fixed timestamp variable	2018-09-25 18:38:48 -06:00
Asif Bacchus	523c9984a6	Added INFO log tags to hostname lookup list	2018-09-25 18:36:40 -06:00
Asif Bacchus	a09dac147a	Updated help text	2018-09-25 18:24:06 -06:00
Asif Bacchus	8a0362a6e1	Updated logging with colour variables and logging tags	2018-09-25 18:17:30 -06:00
Asif Bacchus	92519055fc	Reformatted quit function log output	2018-09-25 18:01:29 -06:00
Asif Bacchus	3585490f80	Added formatting variables	2018-09-25 17:55:58 -06:00
Asif Bacchus	356dfc7f21	Removed [SUCCESS] tag from scipt completion notation	2018-09-25 17:49:12 -06:00
Asif Bacchus	1e8ff53075	Replaced repeated timestamp with single variable	2018-09-25 17:47:30 -06:00
Asif Bacchus	12c0cdde93	quoted logFile variable to prevent globbing	2018-09-25 17:24:14 -06:00
Asif Bacchus	8c24c6e625	Updated readme to remove auto-generated links in text	2018-09-16 22:03:30 -06:00
Asif Bacchus	e3c0de600c	Added auto-generated TOC	2018-09-16 07:41:04 -06:00
Asif Bacchus	551bd8a041	Fixed line-wrapping error	2018-09-16 07:29:24 -06:00
Asif Bacchus	f41d16646e	Updated readme to conform with markdown standards and fixed typos.	2018-09-16 07:27:32 -06:00
Asif Bacchus	0ef29d2ba6	Updated cfddns.service to include a separate command for IP6 updates.	2018-09-16 06:00:54 -06:00