feat(systemd): Update systemd unit-file

Update systemd unit-file to support v3 parameters. Use journald logging as the template example.

.gitattributes

@@ -0,0 +1,100 @@
+# 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
+
+# web frontend stack -- force LF so SRI hashes are always correct
+*.html     text eol=lf
+*.htm      text eol=lf
+*.css      text eol=lf
+*.min.css  text eol=lf
+*.js       text eol=lf
+*.min.js   text eol=lf
+*.php      text eol=lf
+
+# Visual Studio projects (Rider also)
+*.cs     diff=csharp
+*.sln    merge=union
+*.csproj merge=union
+*.vbproj merge=union
+*.fsproj merge=union
+*.dbproj merge=union
+
+# 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
+.idea           export-ignore
+.vscode         export-ignore

.gitignore

@@ -1 +1,35 @@
+#
+# JetBrains exclusions
+#
+
+riderModule.iml
+/_ReSharper.Caches/
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# Generated files
+.idea/**/contentModel.xml
+.idea/**/GitCommitMessageStorage.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# modules
+.idea_modules/
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# project-specific exclusions
 *.log

.idea/.idea.CloudflareDDNS.dir/.idea/.gitignore

@@ -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/

.idea/.idea.CloudflareDDNS.dir/.idea/indexLayout.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ContentModelUserStore">
+    <attachedFolders />
+    <explicitIncludes />
+    <explicitExcludes />
+  </component>
+</project>

.idea/.idea.CloudflareDDNS.dir/.idea/inspectionProfiles/Project_Default.xml

@@ -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>

.idea/.idea.CloudflareDDNS.dir/.idea/riderModule.iml

@@ -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>

.idea/.idea.CloudflareDDNS.dir/.idea/vcs.xml

@@ -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>

.idea/developer-tools.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="DeveloperToolsToolWindowSettingsV1" lastSelectedContentNodeId="base64-encoder-decoder" pluginVersion="9.0.0">
+    <developerToolsConfigurations />
+  </component>
+</project>

.idea/git_toolbox_prj.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="GitToolBoxProjectSettings">
+    <option name="commitMessageIssueKeyValidationOverride">
+      <BoolValueOverride>
+        <option name="enabled" value="true" />
+      </BoolValueOverride>
+    </option>
+    <option name="commitMessageValidationEnabledOverride">
+      <BoolValueOverride>
+        <option name="enabled" value="true" />
+      </BoolValueOverride>
+    </option>
+  </component>
+</project>

.idea/indexLayout.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="UserContentModel">
+    <attachedFolders />
+    <explicitIncludes />
+    <explicitExcludes />
+  </component>
+</project>

.idea/projectSettingsUpdater.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="RiderProjectSettingsUpdater">
+    <option name="singleClickDiffPreview" value="1" />
+    <option name="unhandledExceptionsIgnoreList" value="1" />
+    <option name="vcsConfiguration" value="3" />
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

Folder.DotSettings

@@ -0,0 +1,6 @@
+<wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=cfddns/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=ddns/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=logwatch/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=mydomain/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=myserver/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>

README.md

@@ -1,39 +1,73 @@
-# CloudflareDDNS <!-- omit in toc -->
+# CloudflareDDNS
 
-Update your CloudFlare DNS records with your current (dynamic) IP address via
+Update your *existing* Cloudflare DNS records with your current (dynamic) IP address via systemd timers and a (POSIX)
-systemd timers and a bash script.
+shell script.
 
-**NOTE: You can rename *cfddns.sh* to anything you want, the script will
+## Contents
-auto-update itself.  However, you MUST update the systemd service file
-*(cfddns.service)* *ExecStart* line manually as explained below.**
 
-## Contents <!-- omit in toc -->
+<!-- TOC -->
 
-- [cfddns&#46;sh](#cfddns46sh)
+* [CloudflareDDNS](#cloudflareddns)
-        - [Installation:](#installation)
+    * [Contents](#contents)
-        - [Usage:](#usage)
+    * [Prerequisites](#prerequisites)
-- [cfddns.service](#cfddnsservice)
+    * [cfddns script](#cfddns-script)
-        - [IP4 and/or IP6](#ip4-andor-ip6)
+        * [Installation](#installation)
-                - [Examples](#examples)
+        * [Usage](#usage)
-- [cfddns.timer](#cfddnstimer)
+            * [Parameters](#parameters)
-        - [Activation](#activation)
+    * [Cloudflare credentials file](#cloudflare-credentials-file)
-- [The log file](#the-log-file)
+        * [File structure](#file-structure)
-        - [Using Logwatch to monitor this script](#using-logwatch-to-monitor-this-script)
+        * [Bearer token](#bearer-token)
-        - [Using Logrotate to control log file size](#using-logrotate-to-control-log-file-size)
+        * [Zone ID](#zone-id)
-- [Final thoughts](#final-thoughts)
+    * [cfddns systemd service unit](#cfddns-systemd-service-unit)
+        * [IP4 or IP6](#ip4-or-ip6)
+            * [Examples](#examples)
+    * [cfddns systemd timer unit](#cfddns-systemd-timer-unit)
+        * [Activation](#activation)
+    * [Logging](#logging)
+        * [JSON format](#json-format)
+        * [SYSLOG format](#syslog-format)
+        * [Systemd journal (journald)](#systemd-journal-journald)
+        * [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)
 
-## cfddns&#46;sh
+<!-- TOC -->
 
-### Installation:
+## Prerequisites
 
-I recommend putting this script in your */usr/local/bin* directory or somewhere
+This script requires that `curl` and `jq` are installed. `curl` is used to interact with the Cloudflare API and `jq` is
-else in your path so it's easy to run.
+used to efficiently and reliably construct/deconstruct the JSON strings and arrays returned by the Cloudflare API. If
+you want to log to the system journal (journald), then `logger` must also be installed. In most cases you can install
+these programs using your package manager running as root or via sudo:
 
-1. Copy the script file to your desired path and rename if you want.
+```sh
+# Debian/Ubuntu
+sudo apt update && sudo apt install -y curl jq bsdutils
+
+# Arch
+sudo pacman -Sy curl jq logger
+
+# Redhat/CentOS/Fedora
+sudo dnf install curl jq util-linux
+
+# Redhat/CentOS/Fedora (older versions)
+sudo yum install curl jq util-linux
+```
+
+> While the script does *not* require root privileges, you will need sudo/root access to install the *systemd* service
+> and timer.
+
+## cfddns script
+
+### 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 it if you want.
 
    ```Bash
    sudo cp cfddns.sh /usr/local/bin/   # just copy it
-   sudo cp cfddns.sh /usr/local/bin/myscript.sh   # copy and rename
+   sudo cp cfddns.sh /usr/local/bin/cloudflare-update.sh   # copy and rename (choose any name)
    ```
 
 2. Make it executable:
@@ -42,112 +76,112 @@ else in your path so it's easy to run.
    sudo chmod +x /usr/local/bin/cfddns.sh
    ```
 
-### Usage:
+> Note: You can rename *cfddns.sh* to anything you want, the script will automatically use its current name. However,
+> you **must** manually update the systemd service file (*cfddns.service*) `ExecStart` line
+> as [explained below](#cfddns-script).
 
-If you run the script with no parameters, it will display the help screen.  The
+### Usage
-script accepts several parameters with 2 being required.  The parameters are
+
-summarized here.  You can access the help screen and example usage screens by
+If you run the script with no parameters, it will display the help screen. The script accepts several parameters with
-running:
+only one (1) being required. The parameters are summarized below. You can access the help screen and example usage
+screens by running:
 
 ```Bash
-cfddns.sh -h   # display help screen
+cfddns.sh --help   # display help screen
-cfddns.sh -x   # show script usage examples
+cfddns.sh --examples   # show script usage examples
 ```
 
-**-f: full path and filename containing account details (REQUIRED)**
+#### Parameters
-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
+| Parameter                                      | Description                                                                                                                                                                                                                                                                                                                                                                                            | Default                           | Required? |
-   This is an email address that is permitted to login to your CloudFlare account.
+|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|:---------:|
-- global api-key
+| -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    |
-   You can get your Global API-key by going to your CloudFlare dashboard,
+| -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     |
-   clicking on your profile picture in the upper-right and opening your profile.
+| -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     |
-   Scroll down to to the API Keys section.  Click on the 'View' button next to
+| -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     |
-   Global API Key.
+| -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     |
-- zone identifier
+|                                                |                                                                                                                                                                                                                                                                                                                                                                                                        |                                   |           |
-   You should be able to find this on the Overview page of your CloudFlare dashboard.
+| --log-file                                     | Generate a log file and save it in the specified location. Only specify this option if you want to save the log file in a non-default location. If you want to save the log in the default location, omit this option. Recommend */var/log/scriptName.log*                                                                                                                                             | scriptPath/scriptName.log         |    NO     |
-  
+| --log-journal                                  | Log to the system journal (journald) instead of a log file. Log entries are automatically tagged 'CFDDNS' for easier filtering. Format tags do NOT apply when using this option. Use `json` or `pretty-json` with `journalctl` to see all logged properties.                                                                                                                                           | Disabled, write to log file       |    NO     |
-Your completed file should look like (these are not real credentials):
+| --log-console                                  | Write log entries to the console (stdout) instead of a log file. Using `--fmt-syslog` with this option is strongly recommended since JSON is difficult to read on the console.                                                                                                                                                                                                                         | Disabled, write to log file       |    NO     |
+| --no-log                                       | Do *not* write a log file, write to the journal, 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     |
+|                                                |                                                                                                                                                                                                                                                                                                                                                                                                        |                                   |           |
+| --fmt-json                                     | Write the log file or console output in a structured *Compact Log Event Format (CLEF)* JSON format. You will probably need a log viewer to meaningfully parse the logs.                                                                                                                                                                                                                                | Enabled                           |    NO     |
+| --fmt-syslog                                   | Write the log file or console output in a modified plain-text *syslog* style. This option is recommended when using `--log-console` or if you need easily readable log files. While all log entries are *consistent* using this format, they are not *structured*.                                                                                                                                     | Disabled, just JSON format        |    NO     |
+|                                                |                                                                                                                                                                                                                                                                                                                                                                                                        |                                   |           |
+| -h<br>--help<br>-?                             | Display built-in help screen explaining these same parameters.                                                                                                                                                                                                                                                                                                                                         |                                   |           |
+| --examples                                     | Display some usage examples. Sometimes it's 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
 
 ```
-johndoe@example.com
+
-e7882db52804aca6fab22780e055b97056466
+You can save the file as anything you like and anywhere you’d like as long as you inform the script of its location
-492af8aa69f8c44baf043342c74319fd
+using the `--credentials` parameter. By default, the script will look for a file named *cloudflare.credentials* at the
+same path as the script.
+
+Please remember that this file basically contains a password! As a result, it should be protected and access limited to
+the root account:
+
+```bash
+chown root:root /path/to/cloudflare.credentials
+chmod 600 /path/to/cloudflare.credentials
 ```
 
-Your global API-key is equivalent to your account password, so you should
+### Bearer token
-secure this file by changing the owner of the file to root
 
-```Bash
+I chose to use an API bearer token instead of a username/password or Global API token for security reasons. Your
-chown root:root path/to/filename
+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, only permits actions you explicitly authorize when
+you create it, 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.
 
-and then restricting access to only the root user
+> N.B. This is a breaking change from previous versions of this script!
 
-```Bash
+### Zone ID
-chmod 600 path/to/filename
-```
 
-**-r: target DNS entry to update (REQUIRED)**
+This is required by the Cloudflare API so it knows which zone you are editing and can check the permissions of the
-At least one entry here is *required*.  This is the A or AAAA record you want to
+bearer token. This script only caters to one zone, so likely only one domain per configuration file. If you need to
-update the IP address for in your DNS zone file.  If you have multiple A or AAAA
+update multiple zones, you can have multiple configuration files and call them as required on separate invocations of
-records you want to update, simply specifiy multiple -r parameters.
+the script.
 
-*Note: You can only specify *either* A records *or* AAAA records.  You have to
+To get your Zone ID, log into your Cloudflare account and open the domain in question. On the overview page, scroll down
-update IP4 and IP6 records separately by running this script multiple times
+a bit and look to the right. You will see your Zone ID listed there. Copy that string into your configuration file.
-(once for A records, once for AAAA records even if the hostname is the same).*
 
-**-4 or -6: type of record to update**
+## cfddns systemd service unit
-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).
 
-**-i: use the specified IP address**
+For the easiest implementation, this file should be copied to your */etc/systemd/system* directory. If you change the
-The script will auto-detect the IP address of the machine it's being run on by
+name of the *cfddns.sh* file, you must update the filename in the `ExecStart` line as shown below:
-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 address will be requested for echo.
-
-This parameter let's you bypass auto-detection and specify a particular address
-to be used instead.  This parameter is most useful if running the script
-manually to update a particular DNS record.  In most cases, you'd want your
-current IP address auto-detected (i.e. omit this parameter).
-
-*NOTE: The address you supply is NOT checked for correctness.  Ensure you're
-supplying a valid address of the correct type based on your choice of -4 or -6
-parameter!*
-
-**-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&#46;sh* then the generated log file name will be *something.log*.
-
-This can be messy if you store the script in /usr/local/bin/ as recommended.
-Therefore, it's recommended you choose a different location for
-the log file (*/var/log/cfddns.log* is recommended).
-
-```Ini
-[Service]
-...
-ExecStart=/usr/local/bin/cfddns.sh -l /var/log/cfddns.log ...
-```
-
-**-h: display help**
-Displays the help screen, which is an abbreviated version of this section you
-are currently reading.
-
-**-x: display examples**
-This is the best way to learn how this script works.  Several examples are
-provided
-
-## cfddns.service
-
-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
 ...
@@ -157,66 +191,68 @@ ExecStart=/full/path/to/your/renamed.file -parameter1 -parameter2 -parameter...
 ...
 ````
 
-### IP4 and/or IP6
+### IP4 or IP6
 
-The cfddns.service file includes two *ExecStart* lines, one without a specified
+The cfddns.service file includes two *ExecStart* lines, one without a specified IP-protocol parameter (default IP4) and
-IP-protocol parameter (default IP4) and the other with the -6 (IP6) parameter.
+the other with the -6 (IP6) parameter. The service will run the cfddns&#46;sh script in default (IP4) mode with
-The service will run the cfddns&#46;sh script in default (IP4) mode with specified
+specified parameters first and then will run the script again in IP6 mode with specified parameters.
-parameters first and then will run the script again in IP6 mode with specified
-parameters.
 
 *Note: The parameters *can be different* in each case.*
 
+> **N.B.** This is a `oneshot` type systemd unit-file, so we can have multiple `ExecStart` lines.
+
 #### Examples
 
 1. **Only update A records**
-  Update *mail<span>.example.com* A record with the current IP of this machine and log
+   Update the `A` record for *mail.example.com* with the current auto-detected public IP4 address of this machine and
-  results to */var/log/cfddns.log*.
+   log in JSON format (default) to */var/log/cfddns.log*. Note our Cloudflare credentials file is located in the *root
+   user's home* directory.
 
-   ```Ini
+    ```Ini
    [Service]
    Type=oneshot
-   ExecStart=/usr/local/bin/cfddns.sh -f /root/accountDetails.cloudflare -r mail.example.com -l /var/log/cfddns.log
+   ExecStart=/usr/local/bin/cfddns.sh -c /root/cloudflare.credentials -r mail.example.com --log-file /var/log/cfddns.log
    ...
    ```
 
 2. **Only update AAAA records**
-  Update *git<span>.example.com* and *mail<span>.example.com* AAAA records with the current
+   Update `AAAA` records for *git.example.com* and *mail.example.com* with the current auto-detected public IP6 address
-  IP6 address of this machine. Log will be stored in the same directory as the
+   of this machine. The log will be stored in the same directory as the script file (default) and will be
-  script file (/usr/local/bin).
+   JSON-formatted (default). In this case, the Cloudflare credentials file is located in */home/johndoe*.
 
-   ```Ini
+    ```Ini
-   [Service]
+    [Service]
-   Type=oneshot
+    Type=oneshot
-   ExecStart=/usr/local/bin/cfddns.sh -6 -f /home/johndoe/account.details -r git.example.com -r mail.example.com
+    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 current IP address of this machine and
+   Update the `A` record for *mail.example.com* with the auto-detected public IP4 address of this machine. Then, update
-   write to log file stored at */var/log/DDNS_IP4.log*.  Then, update both
+   `AAAA` records for both *mail.example.com* and *git.example.com* with the *specified IP6 address*. In both cases, we
-   *mail<span>.example.com* and *git<span>.example.com* AAAA records with current IP address
+   are logging to the system journal (journald). Also notice that the Cloudflare credentials file is located in
-   of this machine and write to log file at */var/log/DDNS_IP6.log*.
+   different
+   places for each script call.
 
    ```Ini
    [Service]
    Type=oneshot
-   ExecStart=/usr/local/bin/cfddns.sh -f /dir1/account.cf -r mail.example.com -l /var/log/DDNS_IP4.log
+   # update IP4 addresses
-   ExecStart=/usr/local/bin/cfddns.sh -6 -f /dir2/cloudflare.details -r mail.example.com -r git.example.com -l /var/log/DDNS_IP6.log
+   ExecStart=/usr/local/bin/cfddns.sh -c /dir1/account.cf -r mail.example.com --log-journal
+   # 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 --log-journal
    ...
    ```
 
-## cfddns.timer
+## cfddns systemd timer unit
 
-This is the timer file that tells your system how often to call the
+Again, for the easiest configuration, this file should be copied to your */etc/systemd/system* directory. This timer
-cfddns.service file which runs the cfddns&#46;sh script.  By default, the timer is
+file unit tells your system how often to call the *cfddns.service* file which runs the *cfddns.sh* script. By default,
-set for 5 minutes after the system boots up (to allow for other processes to
+the timer is set for 5 minutes after the system boots up (to allow for other processes to initialize even on slower
-initialize even on slower systems like a RasPi) and is then run every 15
+systems like a RasPi) and is then run every 15 minutes thereafter. Remember when setting your timer that Cloudflare
-minutes thereafter.  Remember when setting your timer that CloudFlare limits
+limits API calls to 1200 every 5 minutes.
-API calls to 1200 every 5 minutes.
 
-You can change the timer by modifying the relevant section of the cfddns.timer
+You can change the timer by modifying the relevant section of the *cfddns.timer* file:
-file:
 
 ```Ini
 [Timer]
@@ -224,22 +260,27 @@ OnBootSec=5min
 OnUnitActiveSec=15min
 ```
 
-*OnBootSec* is how long to wait after the system boots up before executing
+*OnBootSec* is how long to wait after the system boots up before executing the *cfddns.service*.  *OnUnitActiveSec* will
-the cfddns.service.  *OnUnitActiveSec* will then wait the specified time from that
+then wait the specified time from that first (after boot) call or after the timer is explicitly started before calling
-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
-cfddns.service again.  I recommend setting OnUnitActiveSec to a low value (like
+to a more reasonable time (like 15 minutes) after everything is working.
-2 minutes) for testing then setting it to a more reasonable time (like 15
+
-minutes) after everything is working.
+Remember to reload `systemd` after you’ve copied both the systemd unit and this timer unit. Run the following as root or
+via sudo:
+
+```sh
+systemctl daemon-reload
+```
 
 ### Activation
 
-You can start the timer system immediately via systemctl
+You can start the timer system immediately via *systemctl*
 
 ```Bash
 systemctl start cfddns.timer
 ```
 
-and can enable it to start automatically on system start up by typing
+and can enable it to start automatically on boot by typing
 
 ```Bash
 systemctl enable cfddns.timer
@@ -251,55 +292,80 @@ You can check the status of the timer via systemctl also
 systemctl status cfddns.timer
 ```
 
-It is NOT necessary to enable/start the *cfddns.service*, only the timer needs
+It is NOT necessary to enable/start the *cfddns.service*, only the timer needs to be active.
-to be active.
 
-## The log file
+Also remember that if you make changes to settings like `OnUnitActiveSec` while testing, or after testing is complete,
+you *must* reload the systemd daemon! It will restart the appropriate units for you, and your new settings will take
+effect immediately.
 
-The script logs every major action it takes and provides details on any errors
+## Logging
-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
+The script logs every major action it takes and provides details on any errors it encounters in the log file. Refer
-configure any log-watch programs to further filter things for you so you don't
+to the [parameters section](#parameters) for details about setting log location and name. Starting in version 3.0, the
-have to review this log as part of your daily routine.  To make that easier, the
+entire logging system outputs structured **JSON** by default.
-following conventions are observed in the log file and can be used to program
-your log-watch system:
 
-- Errors always appear as **-- [ERROR] text and error code here --**
+> PLEASE remember to review your current log review/parsing system if upgrading from previous versions since this is a
-- Errors are followed by an explanation of the specific error code on a new line
+> **major** change to how logging works.
-- A clean exit appears as **-- [SUCCESS] some text here --**
+
-- The script always starts a new set of log entries with **-- Start CloudFlare
+**IMPORTANT:** This script uses the same log file for its output (unless you specify a different log file each time it
-  DDNS script execution --**
+is run) therefore, you should avoid switiching formats within existing log files. For example, if you are using the
-- All log file entries start with a time-stamp in **[square brackets]**
+default log file, and run the script once with `--fmt-syslog` then switch to the default `--fmt-json`, parsing your log
+will become very difficult. If you are switching log formats, it is best to start with a fresh log file.
+
+### JSON format
+
+This is the default logging format since it allows for easy parsing and filtering of log entries while still retaining a
+structured format. I chose to implement a modified [Compact Log Event Format (CLEF)](https://clef-json.org) with the
+following format for every message (expanded for readability, the log file is not 'pretty-printed'):
+
+```json
+{
+  "@t": "ISO-8601 timestamp",
+  "@m": "message describing the event",
+  "@l": "log level",
+  "hostname": "hostname of the machine executing the script",
+  "programName": "CFDDNS",
+  "pid": "PID of the process executing the script",
+  "status": "status of the operation being logged",
+  "operation": "short-name of the operation being logged",
+  "code": "numeric 'exit code' of the operation being logged"
+}
+```
+
+### SYSLOG format
+
+The SYSLOG format (`--fmt-syslog`) is a modified version of the typical plain-text *nix syslog format. This format is
+useful when outputting the log to the console or when you need a very human-friendly format for the log files since you
+will be manually parsing them. While the plain-text format is not *structured*, it is *consistent*:
+
+```text
+ISO-8601 timestamp hostname CFDDNS[pid]: LOG_LEVEL STATUS MESSAGE (OPERATION:CODE)
+```
+
+### Systemd journal (journald)
+
+When using the `--log-journal` option, all logging will be sent to `journald` using its format. All log messages are
+tagged `CFDDNS` to make filtering easier. Additional information logged with each entry can be exposed using the `json`
+or `json-pretty` output options for `journalctl`.
 
 ### Using Logwatch to monitor this script
 
-If you are using the Logwatch package to monitor your system, **see the README
+If you are using the Logwatch package to monitor your system, see the README in the */etc/logwatch* folder for details
-in the /etc/logwatch folder** for details about the pre-configured service files
+about the pre-configured service files already done for you :-)
-already done for you :-)
 
 ### Using Logrotate to control log file size
 
-Logrotate is pre-installed on standard Debian/Ubuntu distributions and is a great
+Logrotate is pre-installed on most linux distributions and is a great way to automatically rotate your log
-way to automatically rotate your log files and control how many old logs you
+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
-keep on your system so they don't accumulate and eat up your disk space.
+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
-I've included a sample configuration file you can copy to your
+is located in this git archive at */etc/logrotate.d/cfddns* and is fully commented to help you customize it to suit your
-*/etc/logrotate.d/* folder.  This file is set up to rotate your logs once a
+needs.
-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
+Hopefully, this helps you with an easy and reliable way to update your Cloudflare DNS entries with a dynamic IP address.
-when I find stuff that irritates me and no other good solutions seem easily
+Please feel free to comment and provide feedback and suggestions to make this script better!
-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
+Please check out my blog at [https://mytechiethoughts.com](https://mytechiethoughts.com) where I tackle problems like
-[https://mytechiethoughts.com](https://mytechiethoughts.com) where I tackle
+this all the time and find free/inexpensive solutions to tech problems.
-problems like this all the time and find free/cheap solutions to tech problems.

cfddns.service

@@ -4,8 +4,8 @@ After=network.target
 
 [Service]
 Type=oneshot
-ExecStart=/usr/local/bin/cfddns.sh -f /path/to/account.details -r server.domain.tld -l /var/log/cfddns.log
+ExecStart=/usr/local/bin/cfddns.sh -c /path/to/account.details -r server.domain.tld --log-journal
-ExecStart=/usr/local/bin/cfddns.sh -6 -f /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 --log-journal
 
 [Install]
 WantedBy=multi-user.target

cfddns.sh

@@ -1,359 +1,654 @@
-#!/bin/bash
+#!/bin/sh
 
+#
+# update Cloudflare DNS records with current (dynamic) IP address
+#    Script by Asif Bacchus <asif@bacchus.cloud>
+#    Last modified: July 19, 2026
+#    Version 3.0
+#
 
-### Define functions
+### text formatting presets using tput
+if command -v tput >/dev/null; then
+  [ -z "$TERM" ] && export TERM=xterm
+  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
+  bold=""
+  cyan=""
+  err=""
+  magenta=""
+  norm=""
+  ok=""
+  warn=""
+  yellow=""
+  width=80
+fi
 
-function scriptHelp {
+badParam() {
-echo -e "\e[1;39mUsage:"
+  if [ "$1" = "null" ]; then
-echo -e "\e[1;36m$(basename "${0}")" \
+    printf "\n%sERROR: '%s' cannot have a NULL (empty) value.\n" "$err" "$2"
-    "\e[1;35m-f /path/to/account/details.file"
+    printf "%sPlease use '--help' for assistance.%s\n\n" "$cyan" "$norm"
-echo -e "\t\e[1;33m-r record.to.update [-r another.record.to.update -r ...]"
+    ([ "$logToConsole" -eq 0 ]) && writeLog \
-echo -e "\t\e[0;92m[optional parameters]\e[0m\n"
+      "${2} cannot have a NULL (empty) value" "critical" "fail" "preexec" 1
-echo -e "\e[1;39mNotes:\e[0m"
+    exit 1
-echo -e "-f and -r parameters are REQUIRED."
+  elif [ "$1" = "dne" ]; then
-echo -e "Multiple A/AAAA records to update can be specified by supplying"
+    printf "\n%sERROR: '%s %s'\n" "$err" "$2" "$3"
-echo -e "\tmultiple -r parameters (see examples below)."
+    printf "file or directory does not exist or is empty.%s\n\n" "$norm"
-echo "This script can operate only in either IP4 OR IP6 mode. See below."
+    ([ "$logToConsole" -eq 0 ]) && writeLog \
-echo "This script will NOT verify the format or validity of supplied IP"
+      "${3}: file or directory does not exist or is empty" "critical" "fail" "preexec" 1
-echo -e "\taddresses."
+    exit 1
-echo -e "\n\e[1;39mOptional parameters\e[0m"
+  elif [ "$1" = "errMsg" ]; then
-echo -e "-i\tUse this IP address when updating DNS records"
+    printf "\n%sERROR: %s%s\n\n" "$err" "$2" "$norm"
-echo -e "\tIf NOT supplied, the script will attempt to auto-detect this"
+    ([ "$logToConsole" -eq 0 ]) && writeLog \
-echo -e "\tmachine's IP address (depending on -4 or -6 parameters) and"
+      "${2%%\Exit*}" "fatal" "fail" "preexec" 1
-echo -e "\tuse that address for DNS updates.  The script does NOT check"
+    exit 1
-echo -e "\tthe validity of an address supplied using this parameter nor"
+  fi
-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.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"
 }
 
-
+getHostname() {
-function scriptExamples {
+  (hostname -s)
-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
 }
 
-
+getTimeStamp() {
-function quit {
+  (date -u +"%Y-%m-%dT%H:%M:%SZ")
-    if [ -z "$1" ]; then
-        # exit cleanly
-        echo -e "${bold}${note}${stamp} -- Script completed --${normal}" \
-            >> "$logFile"
-        exit 0
-    elif [ "$1" = "none" ]; then
-        if [ -z "$2" ]; then
-            # exit cleanly
-            exit 0
-        else
-            # exit with error code but don't log/display it
-            exit "$2"
-        fi
-    elif [ "$1" = "199" ]; then
-        # list DNS entries that were not updated
-        for failedName in "${failedDNS[@]}"; do
-            echo -e "${bold}${err}${stamp}" \
-            "-- [ERROR] $failedName was NOT updated --${normal}" >> "$logFile"
-        done
-        exit "$1"
-    else
-        # notify use that error has occurred and provide exit code
-        echo -e "${bold}${err}${stamp}" \
-        "-- [ERROR] ${errorExplain[$1]} (code: $1) --${normal}" >> "$logFile"
-        exit "$1"
-    fi
 }
 
-### end of functions
+lowercase() {
+  echo "$1" | tr '[:upper:]' '[:lower:]'
+}
 
+uppercase() {
+  echo "$1" | tr '[:lower:]' '[:upper:]'
+}
 
-### unset environment variables used in this script and initialize arrays
+# 1: cloudflare error object, 2: operation identifier
-unset PARAMS
+listCFErrors() {
-unset accountFile
+  # extract error codes and messages in separate variables, replace newlines with underscores
-unset ipAddress
+  codes="$(printf "%s" "$1" | jq -r '.errors | .[] | .code' | tr '\n' '_')"
-errorExplain=()
+  messages="$(printf "%s" "$1" | jq -r '.errors | .[] | .message' | tr '\n' '_')"
-dnsRecords=()
+
-cfDetails=()
+  # iterate codes and messages, assemble into a coherent log message
-cfRecords=()
+  while [ -n "$codes" ] && [ -n "$messages" ]; do
-currentIP=()
+    # get the first code and message in respective sets
-recordID=()
+    code="${codes%%_*}"
-failedDNS=()
+    message="${messages%%_*}"
+
+    # update sets of codes and messages by removing the first item (above) in each set
+    codes="${codes#*_}"
+    messages="${messages#*_}"
+
+    # output to log
+    writeLog "${message}" "err" "fail" "$2:CF-ERR" "$code"
+  done
+}
+
+standardizeLogLevels() {
+  LEVEL_TO_STANDARDIZE="$(lowercase "$1")"
+  case "$LEVEL_TO_STANDARDIZE" in
+  "critical" | "crit" | "fatal")
+    echo "CRIT"
+    ;;
+  "error" | "err")
+    echo "ERR"
+    ;;
+  "warning" | "warn")
+    echo "WARN"
+    ;;
+  "information" | "info")
+    echo "INFO"
+    ;;
+  "debug" | "verbose")
+    echo "DEBUG"
+    ;;
+  *)
+    echo "INFO"
+    ;;
+  esac
+}
+
+translateLogLevelsToJournalD() {
+  LEVEL_TO_TRANSLATE="$(standardizeLogLevels "$1")"
+  case "$LEVEL_TO_TRANSLATE" in
+  "CRIT")
+    echo 2
+    ;;
+  "ERR")
+    echo 3
+    ;;
+  "WARN")
+    echo 4
+    ;;
+  "INFO")
+    echo 6
+    ;;
+  "DEBUG")
+    echo 7
+    ;;
+  *)
+    echo 6
+  esac
+}
+
+# $1: message, $2: level, $3: status, [$4: operation], [$5: code]
+writeJournalDLog() {
+  # not enough information to generate a meaningful log message
+  if [ -z "$1" ] || [ $# -lt 3 ]; then
+    return
+  fi
+
+  J_TIMESTAMP="$(getTimeStamp)"
+  J_PID="$$"
+  J_PRIO="$(translateLogLevelsToJournalD "$2")"
+  J_STAT="$(uppercase "$3")"
+
+  logger --journald <<end
+SYSLOG_TIMESTAMP=${J_TIMESTAMP}
+SYSLOG_FACILITY=3
+SYSLOG_IDENTIFIER=${LOG_PROGRAM_NAME}
+SYSLOG_PID=${J_PID}
+PRIORITY=${J_PRIO}
+STATUS=${J_STAT}
+MESSAGE=$1
+OPERATION=${4:-UNSPECIFIED}
+ERRNO=${5:-0}
+end
+
+  return
+}
+
+# $1: message, $2: level, $3: status, [$4: operation], [$5: code]
+writeJsonLog() {
+  # not enough information to generate a meaningful log message
+  if [ -z "$1" ] || [ $# -lt 3 ]; then
+    return
+  fi
+
+  JSON_PROPS="$(
+    jq --null-input -c \
+      --arg timestamp "$(getTimeStamp)" \
+      --arg hostname "$(getHostname)" \
+      --arg pName "$LOG_PROGRAM_NAME" \
+      --arg pid "$$" \
+      --arg level "$(standardizeLogLevels "$2")" \
+      --arg status "$(uppercase "$3")" \
+      --arg message "$1" \
+      --arg operation "${4:-UNSPECIFIED}" \
+      --arg code "${5:-0}" \
+      '{"@t":$timestamp, "@m":$message, "@l":$level, "hostname":$hostname, "programName":$pName, "pid":$pid, "status":$status, "operation":$operation, "code":$code}' \
+  )"
+
+  printf "%s\n" "$JSON_PROPS" >>"$logFile"
+  return
+}
+
+# modified syslog fmt: <ISO-8601 timestamp> <hostname> <tag>[pid]: [LEVEL:$2] [STATUS:$3] <MESSAGE:$1> (<OPERATION:$4>:<CODE:$5>)
+writePlainTextLog() {
+  # not enough information to generate a meaningful log message
+  if [ -z "$1" ] || [ $# -lt 3 ]; then
+    return
+  fi
+
+  printf "%s %s %s[%s]: [%s] [%s] %s (%s:%s)\n" \
+    "$(getTimeStamp)" "$(getHostname)" "$LOG_PROGRAM_NAME" "$$" \
+    "$(standardizeLogLevels "$2")" "$(uppercase "$3")" "$1" "${4:-UNSPECIFIED}" "${5:-0}" \
+    >>"$logFile"
+}
+
+writeLog() {
+  ([ "$logToNone" -eq 1 ]) && return
+
+  PT_LOG_LEVEL="$(standardizeLogLevels "$2")"
+  ([ "$logDebug" -eq 0 ] && [ "$PT_LOG_LEVEL" = "DEBUG" ]) && return
+
+  ([ "$logToJournal" -eq 1 ]) && writeJournalDLog "$@" && return
+  ([ "$useJsonLogFmt" -eq 1 ]) && writeJsonLog "$@" && return
+  ([ "$useSyslogLogFmt" -eq 1 ]) && writePlainTextLog "$@" && return
+}
+
+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. The log will be written to the default location in the default JSON format."
+  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 --fmt-syslog"
+  textBlock "Same as the first example, but the log file will be written in plain-text format instead of JSON."
+  newline
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net --log-console --fmt-syslog"
+  textBlock "Same as the first example, but the log will be written to the console (stdout) in plain-text instead of a log file."
+  newline
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net --log-journal"
+  textBlock "Same as the first example, but the log will be written to the journal (journald) instead of a log file. A tag of 'CFDDNS' is automatically applied to make filtering easier."
+  newline
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net,myserver2.mydomain.net --log-file /var/log/cfddns.log"
+  textBlock "Update DNS entries for both listed hosts using the auto-detected IP4 address. Write the log file to the specified location."
+  newline
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net,myserver2.mydomain.net --log-file /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 the log to the location specified."
+  newline
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net --ip 1.2.3.4 -c /root/cloudflare.creds --log-file /var/log/cfddns.log --fmt-syslog"
+  textBlock "Update DNS A entry for 'myserver.mydomain.net' with the *specified* IP address. Read the Cloudflare credentials file from the specified location. Save a plain-text (syslog-style) log in the specified location."
+  newline
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net -6 -i fd21:7a62:2737:9c3a::a151 -c /root/cloudflare.creds --log-file /var/log/cfddns.log --fmt-syslog"
+  textBlock "Exact same as above, but change the AAAA record. This is an example of 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 the file containing your Cloudflare *token* credentials. Please refer to the repo README for more information on format, etc."
+  textBlockDefaults "(${accountFile})"
+  newline
+  textBlockSwitches "--log-file"
+  textBlock "Path where the log file should be written. Script will use file-based logging."
+  textBlockDefaults "(${logFile})"
+  newline
+  textBlockSwitches "--log-console"
+  textBlock "Switch value. Script will use console-based (stdout) logging."
+  textBlockDefaults "(disabled: use file-based logging)"
+  newline
+  textBlockSwitches "--log-journal"
+  textBlock "Switch value. Script will use journald-based logging."
+  textBlockDefaults "(disabled: use file-based logging)"
+  newline
+  textBlockSwitches "--log-none"
+  textBlock "Switch value. Script will not log anything. You will not have *any* output from the script if you choose this option, so you will not know if updates succeed or fail."
+  textBlockDefaults "(disabled: use file-based logging)"
+  newline
+  textBlockSwitches "--log-debug"
+  textBlock "Switch value. Log 'debug' level messages. This should normally remain disabled."
+  textBlockDefaults "(disabled: do not log 'debug' messages)"
+  newline
+  textBlockSwitches "--fmt-json"
+  textBlock "Switch value. Use JSON formatted key-value pair structured logging format. Best when using a log parsing tool or log management system to read your log files. Does not apply when using '--log-journal'."
+  textBlockDefaults "(enabled)"
+  newline
+  textBlockSwitches "--fmt-syslog"
+  textBlock "Switch value. Use a modified syslog (plain-text) format for log messages. Ideal when logging to the console. Does not apply when using '--log-journal'."
+  textBlockDefaults "(disabled: use structured JSON logging)"
+  newline
+  textBlockSwitches "-h | --help | -?"
+  textBlock "Display this information 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. N.B. IP addresses are *not* parsed for correctness."
+  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
+}
+
+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"
+}
+
+### default variable values
+LOG_PROGRAM_NAME="CFDDNS"
+scriptPath="$(CDPATH='' \cd -- "$(dirname -- "$0")" && pwd -P)"
+scriptName="$(basename "$0")"
+logFile="$scriptPath/${scriptName%.*}.log"
+logToJournal=0
+logToConsole=0
+logToNone=0
+logDebug=0
+useJsonLogFmt=1
+useSyslogLogFmt=0
+accountFile="$scriptPath/cloudflare.credentials"
+dnsRecords=""
+dnsSeparator=","
+ipAddress=""
 ip4=1
 ip6=0
+ip4DetectionSvc="https://ipv4.icanhazip.com"
+ip6DetectionSvc="https://ipv6.icanhazip.com"
+invalidDomainCount=0
+failedHostCount=0
 
-
+### process startup parameters
-### define script variables
-# timestamp
-stamp="[`date +%Y-%m-%d` `date +%H:%M:%S`]"
-# formatting
-normal="\e[0m"
-bold="\e[1m"
-ok="\e[32m"
-err="\e[31m"
-info="\e[96m"
-lit="\e[93m"
-note="\e[35m"
-
-
-## 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
+  scriptHelp
 fi
-
+while [ $# -gt 0 ]; do
-while getopts ':f:r:i:46hxl:' PARAMS; do
+  case "$1" in
-    case "$PARAMS" in
+  -h | -\? | --help)
-        f)
+  # display help
-            # path to file with CloudFlare account details
+    scriptHelp
-            accountFile="${OPTARG}"
+    ;;
-            ;;
+  --examples)
-        r)
+  # display sample commands
-            # DNS records to update
+    scriptExamples
-            dnsRecords+=("$OPTARG")
+    ;;
-            ;;
+  --log-file)
-        i)
+  # use file-based logging at the specified location
-            # IP address to use -- NOT parsed for correctness
+    if [ -n "$2" ]; then
-            ipAddress="$OPTARG"
+      logFile="${2%/}"
-            ;;
+      shift
-        4)
-            # Put script in IP4 mode (default)
-            ip4=1
-            ip6=0
-            ;;
-        6)
-            # Put script in IP6 mode
-            ip4=0
-            ip6=1
-            ;;
-        h)
-            # Display info on script usage
-            scriptHelp
-            ;;
-        x)
-            # Show examples of script usage
-            scriptExamples
-            ;;
-        l)
-            # Path to write log file
-            logFile="${OPTARG}"
-            ;;
-        ?)
-            scriptHelp 1
-            ;;
-    esac
-done
-
-# Log beginning of script
-echo -e "${bold}${note}${stamp} -- Start CloudFlare" \
-    "DDNS script execution --${normal}" >> "$logFile"
-
-# Check validity of parameters
-if [ -z "$accountFile" ] || [[ $accountFile == -* ]]; then
-    quit 101
-elif [ ! -s "$accountFile" ]; then
-    quit 102
-elif [ -z "${dnsRecords}" ]; then
-    quit 103
-fi
-
-# Check if curl is installed
-command -v curl >> /dev/null
-curlResult="$?"
-if [ "$curlResult" -ne 0 ]; then
-    quit 2
-fi
-
-# Log operating mode
-if [ $ip4 -eq 1 ]; then
-    echo -e "${info}${stamp} Script running in" \
-        "IP4 mode${normal}" >> "$logFile"
-elif [ $ip6 -eq 1 ]; then
-    echo -e "${info}${stamp} Script running in" \
-        "IP6 mode${normal}" >> "$logFile"
-fi
-
-
-## Extract needed information from accountDetails file
-mapfile -t cfDetails < "$accountFile"
-
-## Get current IP address, if not provided in parameters
-if [ -z "$ipAddress" ]; then
-    echo -e "${info}${stamp} No IP address for" \
-        "update provided.  Detecting this machine's IP address...${normal}" \
-        >> "$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="$?"
-    if [ "$ipLookupResult" -ne 0 ]; then
-        quit 201
-    fi
-fi
-echo -e "${info}${stamp} -- [INFO] Using IP address:" \
-    "$ipAddress" >> "$logFile"
-
-
-## Check if desired record(s) exist at CloudFlare
-# perform checks on A or AAAA records based on invocation options
-if [ $ip4 -eq 1 ]; then
-    echo -e "${normal}${stamp} -- [INFO] Updating A records: ${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 "${normal}${stamp} -- [INFO] Updating AAAA records:"\
-        "${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
-fi
-# check for curl errors
-cfLookupResult="$?"
-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 "${err}${stamp} -- [INFO]" \
-            "${dnsRecords[recordIdx]} not found in your" \
-            "CloudFlare DNS records --${normal}" >> "$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
-else
-    for recordIdx in "${!cfRecords[@]}"; do
-        echo -e "${normal}${stamp} Found" \
-            "${dnsRecords[recordIdx]} (Index: $recordIdx)" \
-            >> "$logFile"
-    done
-fi
-
-
-## 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 "${normal}${stamp} Index $recordIdx:" \
-        "For record ${lit}${dnsRecords[recordIdx]}${normal}" \
-        "with ID: ${recordID[recordIdx]}" \
-        "the current IP is ${lit}${currentIP[recordIdx]}" \
-        "${normal}" >> "$logFile"
-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 "${bold}${ok}${stamp} -- [STATUS]" \
-        "${dnsRecords[recordIdx]} is up-to-date.${normal}" \
-            >> "$logFile"
     else
-        echo -e "${info}${stamp} -- [STATUS]" \
+      badParam null "$@"
-        "${dnsRecords[recordIdx]} needs updating...${normal}" \
-            >> "$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\"}")
-        fi
-        # check for success code from CloudFlare
-        if [[ $update == *"\"success\":true"* ]]; then
-            echo -e "${bold}${ok}${stamp} -- [SUCCESS]" \
-                "${dnsRecords[recordIdx]} updated.${normal}" >> "$logFile"
-        else
-            failedDNS+=("${dnsRecords[recordIdx]}")
-        fi        
     fi
+    ;;
+  --log-console)
+  # use console-based logging
+    logFile="/dev/stdout"
+    logToConsole=1
+    ;;
+  --log-journal)
+  # use journald-based logging
+    logToJournal=1
+    ;;
+  --log-none)
+  # do not log anything
+    logFile="/dev/null"
+    logToNone=1
+    ;;
+  --log-debug)
+  # log debugging messages
+    logDebug=1
+    ;;
+  --fmt-json)
+  # use JSON log formatting
+    useJsonLogFmt=1
+    useSyslogLogFmt=0
+    ;;
+  --fmt-syslog)
+  # use modified syslog plain-text log formatting
+    useSyslogLogFmt=1
+    useJsonLogFmt=0
+    ;;
+  -c | --cred* | -f)
+  # path to the 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"
+    ([ "$logToConsole" -eq 0 ]) && writeLog \
+      "Unknown script parameter: '${1}'" "critical" "fail" "preexec" 1
+    exit 1
+    ;;
+  esac
+  shift
 done
 
-# Check if failedDNS array contains entries and exit with error, else exit 0
+### pre-flight checks
-if [ -z "${failedDNS}" ]; then
+if ! command -v curl >/dev/null; then
-    quit
+  printf "\n%sThis script requires that 'curl' is installed and accessible. Exiting.%s\n\n" "$err" "$norm"
-else
+  ([ "$logToConsole" -eq 0 ]) && writeLog "'curl' must be installed and accessible" "fatal" "fail" "preexec" 2
-    quit 199
+  exit 2
+fi
+if ! command -v jq >/dev/null; then
+  printf "\n%sThis script requires that 'jq' is installed and accessible. Exiting.%s\n\n" "$err" "$norm"
+  ([ "$logToConsole" -eq 0 ]) && writeLog "'jq' must be installed and accessible" "fatal" "fail" "preexec" 2
+  exit 2
+fi
+if [ -z "$dnsRecords" ]; then
+  badParam errMsg "You must specify at least one DNS record to update. Exiting."
+fi
+# verify the credentials file exists and is not empty (default check)
+if [ ! -f "$accountFile" ] || [ ! -s "$accountFile" ]; then
+  badParam errMsg "Cannot find the Cloudflare credentials file (${accountFile}) or it is empty. Exiting."
+fi
+if [ "$logToJournal" -eq 1 ] && ! command -v logger >/dev/null 2>&1; then
+  printf "\n%sThis script requires that 'logger' is installed to write journald entries. Exiting.%s\n\n" "$err" "$norm"
+  exit 2
 fi
 
-# this code should never be executed
+### initial log entries
-exit 99
+writeLog "starting '${scriptName}'" "info" "ok" "script"
+writeLog "script path: ${scriptPath}/${scriptName}" "debug" "ok" "startup"
+writeLog "credentials file: ${accountFile}" "debug" "ok" "startup"
+
+if [ "$ip4" -eq 1 ]; then
+  writeLog "mode: IPv4" "debug" "ok" "startup"
+elif [ "$ip6" -eq 1 ]; then
+  writeLog "mode: IPv6" "debug" "ok" "startup"
+fi
+
+# detect and report IP address
+if [ -z "$ipAddress" ]; then
+  # detect public ip address
+  if [ "$ip4" -eq 1 ]; then
+    if ! ipAddress="$(curl -s $ip4DetectionSvc)"; then
+      writeLog \
+        "Unable to auto-detect this machine's public IP address; try again later or supply the IP address to be used" "err" "fail" "detectip" 10
+      exit 10
+    fi
+  fi
+  if [ "$ip6" -eq 1 ]; then
+    if ! ipAddress="$(curl -s $ip6DetectionSvc)"; then
+      writeLog \
+        "Unable to auto-detect this machine's public IP address; try again later or supply the IP address to be used" "err" "fail" "detectip" 10
+      exit 10
+    fi
+  fi
+  writeLog "DDNS IP address (detected): $ipAddress" "info" "ok" "startup"
+else
+  writeLog "DDNS IP address (supplied): $ipAddress" "info" "ok" "startup"
+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}}"
+
+  if [ -z "$record" ]; then
+    continue
+  fi
+  writeLog "DNS host record '${record}' queued for update" "info" "ok" "startup"
+done
+
+### read 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 "Cloudflare authorized API key (cfKey) is either null or undefined; please check your Cloudflare credentials file" "err" "fail" "creds" 21
+  exit 21
+fi
+if [ -z "$cfZoneId" ]; then
+  writeLog "Cloudflare zone id (cfZoneId) is either null or undefined; please check your Cloudflare credentials file" "err" "fail" "creds" 22
+  exit 22
+fi
+writeLog "Cloudflare credentials file read successfully" "debug" "ok" "creds"
+
+### 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
+
+  # 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 "Unable to connect to Cloudflare servers; please try again later." "err" "fail" "cflogin" 3
+    exit 3
+  fi
+
+  # an API error on this GET request likely indicates an authentication error that would affect all remaining operations
+  # no reason to continue processing other dns records and pile-up errors which might look like a DoS attempt
+  cfSuccess="$(printf "%s" "$cfLookup" | jq -r '.success')"
+  if [ "$cfSuccess" = "false" ]; then
+    listCFErrors "$cfLookup" "cflogin"
+    writeLog "Cloudflare API error; review any previously logged 'CF-ERR:' lines for details." "err" "fail" "cflogin" 25
+    exit 25
+  fi
+
+  resultCount="$(printf "%s" "$cfLookup" | jq '.result_info.count')"
+
+  # skip to the next host if an existing host record cannot be found (this script *updates* only, does not create!)
+  if [ "$resultCount" = "0" ]; then
+    writeLog "Cannot find an existing record matching '${record}' to update" "warn" "warn" "ddns"
+    invalidDomainCount=$((invalidDomainCount + 1))
+    continue
+  fi
+
+  objectId=$(printf "%s" "$cfLookup" | jq -r '.result | .[] | .id')
+  currentIpAddr=$(printf "%s" "$cfLookup" | jq -r '.result | .[] | .content')
+  writeLog "The current IP address for '${record}' is ${currentIpAddr}" "debug" "ok" "ddns"
+
+  # skip to next hostname if record already up to date
+  if [ "$currentIpAddr" = "$ipAddress" ]; then
+    writeLog "The IP address for '${record}' is already up to date" "info" "ok" "ddns"
+    continue
+  fi
+
+  # update 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 "Unable to connect to Cloudflare servers; please try again later." "err" "fail" "ddns" 3
+    exit 3
+  fi
+
+  # note update success or failure
+  cfSuccess="$(printf "%s" "$cfResult" | jq '.success')"
+  if [ "$cfSuccess" = "true" ]; then
+    writeLog "The IP address for '${record}' successfully updated" "info" "success" "ddns"
+  else
+    listCFErrors "$cfResult" "ddns"
+    writeLog "Unable to update the IP address for '${record}'" "err" "fail" "ddns"
+    # 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
+
+# exit
+if [ "$invalidDomainCount" -ne 0 ]; then
+  writeLog "${invalidDomainCount} invalid host(s) were supplied for updating" "warn" "warn" "ddns"
+fi
+if [ "$failedHostCount" -ne 0 ]; then
+  writeLog \
+    "${failedHostCount} host update(s) failed; review 'CF-ERR:' lines in this log to help determine what may have gone wrong" "err" "fail" "ddns" 26
+  exit 26
+else
+  writeLog "${scriptName} completed successfully" "info" "ok" "script"
+fi
+
+### 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

cloudflare.credentials

@@ -0,0 +1,6 @@
+#
+# CloudFlare token for my.domain.tld
+#
+
+cfKey=_dLuyyRNaKN8SLG4-csmNYYfC39nnCmPVA7aYUJj
+cfZoneId=83d564234134513245311b23412331dd

etc/logwatch/README.md

@@ -1,44 +1,66 @@
-# Using Logwatch to monitor Cloudflare DDNS updater script <!-- omit in toc -->
+# Using Logwatch to monitor the Cloudflare DDNS updater script
 
-The Cloudflare DDNS update script's log file has been set up so that utilities
+The Cloudflare DDNS update script's log file has been set up so that utilities like Logwatch can easily parse it. To
-like Logwatch can easily parse it.  In order to make that happen, a LogFile
+make that happen, a LogFile Group file, Service and Script have to be created for Logwatch to generate reports.
-Group file, Service and Script have to be created for Logwatch to generate
+The correct (general) directory structure has been created in this git archive already. Below are the details of each
-reports.  The correct (general) directory structure has been created in this git
+file.
-archive already.  Below are the details of each file.
 
-## Contents <!-- omit in toc -->
+You can implement this setup easily by copying it into your */etc/logwatch* directory and then modifying the files as
+necessary:
 
-- [LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)](#logfile-group-file-etclogwatchconflogfilescfddnsconf)
+```bash
-    - [Log file location](#log-file-location)
+cd /etc/logwatch
-    - [Archive location and name format](#archive-location-and-name-format)
+cp -R /path/to/CloudflareDDNS_repo/etc/logwatch/* ./
-    - [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)
-- [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)
 
-## LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)
+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/).
+
+> **IMPORTANT:** Starting with version 3.0 of the `cfddns` script, you *MUST* use the `--fmt-syslog` parameter when
+> running the `cfddns` script. Otherwise, your log file will be in JSON format, and the supplied templates will not
+> work.
+
+## Contents
+
+<!-- TOC -->
+
+* [Using Logwatch to monitor the Cloudflare DDNS updater script](#using-logwatch-to-monitor-the-cloudflare-ddns-updater-script)
+    * [Contents](#contents)
+    * [LogFile Group file](#logfile-group-file)
+        * [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](#service-definition-file)
+        * [LogFile Group file definition](#logfile-group-file-definition)
+        * [Report title](#report-title)
+        * [Detail level](#detail-level)
+    * [Service script](#service-script)
+        * [Detail levels](#detail-levels)
+    * [Timestamp processing script](#timestamp-processing-script)
+        * [The time format specification](#the-time-format-specification)
+        * [The search REGEX](#the-search-regex)
+    * [Testing](#testing)
+    * [Final thoughts](#final-thoughts)
+
+<!-- TOC -->
+
+## LogFile Group file
+
+> This file is located within the repo at */etc/logwatch/conf/logfiles/cfddns.conf*
 
 ### Log file location
 
-Update this as needed to point to the location and name of the log file
+Update this as needed to point to the location and name of the log file generated by the updater script. Remember, by
-generated by the updater script.  Remember, by default, the log file is created
+default, the log file is created in the same directory as the script itself.
-in the same directory as the script itself.
 
 ```Ini
 LogFile = /path/to/your/cfddns.log
 ...
 ```
 
-Best practices suggest you use the *-l*
+Best practices suggest you use the `--log-file` flag to change this location to something like */var/log/cfddns.log*,
-flag to change this location to something like */var/log/cfddns.log*, for
+for
-example.  In that case, the entry would look like:
+example. In that case, the entry would look like:
 
 ```Ini
 LogFile = /var/log/cfddns.log
@@ -47,12 +69,10 @@ LogFile = /var/log/cfddns.log
 
 ### Archive location and name format
 
-If you want Logwatch to process old (archived) log files generated by something
+If you want Logwatch to process old (archived) log files generated by something like *Logrotate*, then you have to
-like *Logrotate*, then you have to specify the location and file name format of
+specify the location and file name format of those files. I've included the generalized compressed format of such
-those files.  I've included the generalized compressed format of such rotated
+rotated files as the default in the script. Suppose you store your log files in the recommended location (*/var/log/*)
-files as the default in the script.  Suppose you store your log files in the
+and are using *Logrotate* with compression enabled, the archive line would look like:
-recommended location (*/var/log/*) and are using *Logrotate* with compression
-enabled, the archive line would look like:
 
 ```Ini
 ...
@@ -60,52 +80,49 @@ Archive = /var/log/cfddns.log.?.gz
 ...
 ```
 
-This would tell Logwatch, when the archive option is set to true, that your
+This would tell Logwatch, when the archive option is set to true, that your *cfddns.log* files are archived as:
-*cfddns.log* files are archived as: *cfddns.log.1.gz*, *cfddns.log.2.gz*, etc.
+*cfddns.log.1.gz*, *cfddns.log.2.gz*, etc. and are all located in */var/log/*.
-and are all located in */var/log/*.
 
-**Note: This line is totally optional and only used if you set the archive
+> Note: This line is totally optional and only used if you set the archive option in Logwatch to true. You can
-option in Logwatch to true.  You can comment/delete this line if you wish.**
+> 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
+Since the log file uses a non-standard (according to Logwatch) method of date-stamping, a custom filter had to be
-datestamping, a custom filter had to be created.  See the
+created. See the [relevant](#timestamp-processing-script) section of this
-[relevant](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere)
+document for more information.
-section of this document for more information.
 
-The script file is called with an *\** before the filename.
+The script file is called with an asterisk (*) before the filename.
 
 ```Ini
 ...
-*sqFullStampAnywhere
+*iso8601timestamp
 ...
 ```
 
-If you change the name of this file, you will have to change this line.
+If you change the name of this file, you will have to change this line. Remember that whatever you type here as a name
-Remember that whatever you type here as a name is converted to all-lowercase
+is converted to all-lowercase so your filename should be all lowercase also.
-so your filename should be all lowercase also.
 
-## Service definition file (/etc/logwatch/conf/services/cfddns.conf)
+## Service definition file
+
+> This file is located within the repo at */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
+The service file needs to know what group of log files it is responsible for processing. This MUST match the name of
-processing.  This MUST match the name of your *LogFile Group file*:
+your *LogFile Group file*:
 
 ```Ini
 LogFile = cfddns
 ...
 ```
 
-If you change your LogFile Group filename, then update it here too without the
+If you change your LogFile Group filename, then update it here also without the *.conf* extension.
-*.conf* extension.
 
 ### Report title
 
-The Logwatch output file (html or text) is divided into sections.  You can
+The Logwatch output file (HTML or text) is divided into sections. You can define the title to be anything that has
-define the title to be anything that has meaning for you.  I have arbitrarily
+meaning for you. I have arbitrarily chosen *"CloudFlare DDNS update"* but you can change it to anything you want by
-chosen *"CloudFlare DDNS update"* but you can change it to anything you want by
 modifying the line:
 
 ```Ini
@@ -113,86 +130,112 @@ modifying the line:
 Title = "CloudFlare DDNS update"
 ```
 
-## Service script (/etc/logwatch/scripts/services/cfddns)
+### Detail level
 
-Logwatch calls any script with a name that **matches the service name**.  You'll
+If you want to set the *detail* level of this service differently from your other services (which will use the
-notice that I just named everything *cfddns* to keep things simple.  You can
+*--detail* switch value or the value in your *logwatch.conf*), then you can define that level here. By default, it
-change this to whatever you want, however.  If you changed the service name to
+appears like this in the service configuration file:
-*"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
+```Ini
-file as standard input (STDIN) for the script and then takes whatever is output
+...
-(STDOUT) from the script to assemble into it's report.
+# 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
+
+> This file is located within the repo at */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 an aggregate total of certain logged elements.  It will
+    - This will display a simple aggregate of status message categories over the reporting period:
-    display the total number of hostnames (A and AAAA) that are already
+        - Entries successfully updated
-    up-to-date, those that needed updating, those successfully updated and the
+        - Entries already up to date
-    total number of errors (of any type) encountered by the script.  All totals
+        - Hosts failed to update
-    are relative to the reporting period Logwatch is using (--range parameter).
+        - 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
+    - **This is the recommended reporting level.**  It does not take up much space and is quick to read. If you see
-    and is quick to read.  If you see successful updates match the number of
+      successful updates and/or up-to-date numbers match what you expect and no errors logged, then you can assume
-    needed updates and no errors logged, then things are working properly.  If
+      things are working properly. If the numbers aren’t right or you see errors/warnings, then you can investigate the
-    you notice errors, you should consult the full logs.
+      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 actual text of any generated errors.
-- **Level 5: Verbose (debugging) output**
-  - Like the previous level, this outputs the actual messages found in the log
-    file.  However, it also includes *[INFO] tags* which contain logged messages
-    such as the detected IP address and the specific names of any hostnames not
-    found in your Cloudflare account, etc.  This level of reporting is useful in
-    diagnosing why errors are occurring or if you just want more insight into
-    how the script works.
 
-    **This level of output will make your Logwatch reports longer and consume
+    - This uses the data which is summarized by Level 0 but outputs the *actual messages* in the log file. For example,
-    more of your time to review. You should not use this level day-to-day.**
+      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
+    - Any number greater than 5 passed as a detail level will trigger the script to dump the entire log file out to
-    to dump the entire log file out to Logwatch line-by-line.  This is useful
+      Logwatch line-by-line. This is really only useful during debugging or dealing with serious issues where you do not
-    only if you are debugging an issue and cannot get access to the actual raw
+      have access to the actual log file.
-    log file itself.  The actual log file is colour-coded which makes it much
+    - **Use this detail level only when you need to see the entire log file and cannot otherwise access the log file.**
-    easier to read for debugging purposes.
 
-    **Use this detail level only when you need to see the entire log file and
+## Timestamp processing script
-    cannot otherwise access the log file.**
 
-## Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere)
+> This file is located within the repo at */etc/logwatch/scripts/shared/iso8601timestamp*
 
-This is basically a modified version of the '*applyeurodate*' script that comes
+This is a modified version of the '*applyeurodate*' script that comes with Logwatch. If you change
-with Logwatch.  It had to be modified to search within [square brackets] and to
+the '**stamp**' variable in the `cfddns` script to modify the timestamp to your liking (which is totally fine!) then
-accept characters coming before the stamp (i.e. ANSI colour codes).  If you
+you'll probably have to update this file. There are two lines you need to modify to suit your new '**stamp**' variable.
-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
+> This entire section is only applicable if you are an inquisitive person or if you change the hard-coded ‘stamp’
-file.  There are two lines you need to modify to suit your new '**stamp**'
+> function in the script. If you did not make any changes and you like a little mystery in your life, you can safely
-variable.
+> skip this entire section.
 
 ### The time format specification
 
-'*$SearchDate*' is the variable used in the PERL script to do exactly what it
+'*$SearchDate*' is the variable used in the PERL script to do exactly what it says, search for the date stamp. I have it
-says, search for the date stamp.  I have it set up to look for the format
+set up to look for the format '*year-month-dateThour:minute:secondZ*', which is the ISO-8601 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');
+$SearchDate = TimeFilter('%Y-%m-%dT%H:%M:%SZ');
 ...
 ```
 
-If you changed the '**stamp**' variable so it was formatted as '*month/day/year
+If you changed the '**stamp**' variable so it was formatted as '*month/day/year hour:minute*'
-hour:minute*' (ex: '*[09/27/2018 18:38]*') then you'd update the **$SearchDate**
+(ex: '*09/27/2018 18:38*') then you'd update the **$SearchDate** variable as follows:
-variable as follows (note: no mention of the square brackets!):
 
 ```Perl
 ...
@@ -202,37 +245,8 @@ $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
+The PERL script uses a '*regular expression*' (REGEX) to search within the log file for '*$SearchDate*'. For the default
-'*$SearchDate*'.  For the default datestamp, this specification looks like:
+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 datestamp in the default
-log file.  If you have modified this so that your datestamp 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
 ...
@@ -240,18 +254,34 @@ if ($ThisLine =~ m/^$SearchDate /o) {
 ...
 ```
 
+The REGEX appears between '*m/*' and '*/o*'. In this case, it searches for '*$SearchDate*' appearing at the
+beginning (^) of the line. If you want to search anywhere in the line instead of the beginning, remove the caret (^):
+
+```Perl
+...
+if ($ThisLine =~ m/$SearchDate /o) {
+...
+```
+
+or maybe you changed the date stamp to appear in square brackets at the start of the line:
+
+```Perl
+...
+if ($ThisLine =~ m/^\[$SearchDate\] /o) {
+...
+```
+
 ## Testing
 
-Run *logwatch --help* and note the options.  You can test just this service
+Run *logwatch --help* and note the options. You can test just this service locally on your screen with the following
-locally on your screen with the following command (assuming you kept default
+command (assuming you kept default names for everything):
-names for everything):
 
 ```Bash
-# Summary output, entire duration of log file
+# Summary output, entire duration of the 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 3
+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
@@ -259,7 +289,6 @@ 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
+That's it!  I'm a horrible PERL programmer, so if anyone can optimize/improve the script file used for Logwatch, then
-script file used for Logwatch then please do it!  Otherwise, I hope this made
+please do it!  Otherwise, I hope this made sense and helped you integrate the updater script with Logwatch for easy
-sense and helped you integrate the updater script with Logwatch for easy
 monitoring :-)

etc/logwatch/conf/logfiles/cfddns.conf

@@ -1,11 +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
+*iso8601timestamp

etc/logwatch/conf/services/cfddns.conf

@@ -1,2 +1,9 @@
+# Name of the logfile group without any extension
 LogFile = cfddns
-Title = "CloudFlare DDNS update"
+
+# 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

etc/logwatch/scripts/services/cfddns

@@ -4,7 +4,7 @@
 # $Id$
 #############################################################################
 # Log: CloudFlare updater script (cfddns)
-# Revision 1.0  2018/09/26
+# Revision 3.0  2026/07/25
 # Written by Asif Bacchus
 #############################################################################
 
@@ -17,9 +17,11 @@ my $detailLevel = $ENV{'LOGWATCH_DETAIL_LEVEL'} || 0;
 
 ### Declare variables
 my $summaryErr;
-my $summaryStatusUpToDate;
+my $summaryFailedUpdate;
-my $summaryStatusNeedsUpdating;
+my $summaryInvalidHost;
-my $summarySuccess;
+my $summaryUpdated;
+my $summaryUpToDate;
+my $summaryWarning;
 
 my %reportHash = ();
 my $key;
@@ -29,32 +31,44 @@ my $key;
 if ($detailLevel == 0) {
     ### process logfile and summarize message types
     while (defined(my $ThisLine = <STDIN>)) {
-        if ($ThisLine =~ /\-- \[ERROR\] /) {
+        if ($ThisLine =~ /[FAIL] Unable to update the IP address for/) {
+            $summaryFailedUpdate++;
+        }
+        elsif ($ThisLine =~ /[FAIL] /) {
             $summaryErr++;
         }
-        elsif ($ThisLine =~ /up-to-date./) {
+        elsif ($ThisLine =~ /[WARN] Cannot find an existing record matching/) {
-            $summaryStatusUpToDate++;
+            $summaryInvalidHost++;
         }
-        elsif ($ThisLine =~ /needs updating.../) {
+        elsif ($ThisLine =~ /[WARN] /){
-            $summaryStatusNeedsUpdating++;
+            $summaryWarning++;
         }
-        elsif ($ThisLine =~ /\-- \[SUCCESS\] /) {
+        elsif ($ThisLine =~ /[SUCCESS] /) {
-            $summarySuccess++;
+            $summaryUpdated++;
+        }
+        elsif ($ThisLine =~ /already up to date/) {
+            $summaryUpToDate++;
         }
     }
 
     ### fill hash table with headings and summary counts
-    if ($summaryStatusNeedsUpdating > 0) {
+    if ($summaryUpdated > 0) {
-        $reportHash{"Entries needing updates"} = $summaryStatusNeedsUpdating;
+        $reportHash{"Entries successfully updated"} = $summaryUpdated;
     }
-    if ($summarySuccess > 0) {
+    if ($summaryUpToDate > 0) {
-        $reportHash{"Entries successfully updated"} = $summarySuccess;
+        $reportHash{"Entries already up to date"} = $summaryUpToDate;
     }
-    if ($summaryStatusUpToDate > 0) {
+    if ($summaryFailedUpdate > 0) {
-        $reportHash{"Entries already up-to-date"} = $summaryStatusUpToDate;
+        $reportHash{"Hosts failed to update"} = $summaryFailedUpdate;
+    }
+    if ($summaryInvalidHost > 0) {
+        $reportHash{"Undefined hosts"} = $summaryInvalidHost;
+    }
+    if ($summaryWarning > 0) {
+        $reportHash{"Total warnings"} = $summaryWarning;
     }
     if ($summaryErr > 0) {
-        $reportHash{"Errors encountered"} = $summaryErr;
+        $reportHash{"Total errors"} = $summaryErr;
     }
 
     ### print hash table
@@ -66,48 +80,53 @@ if ($detailLevel == 0) {
 ### a summary count
 elsif ($detailLevel >= 1 && $detailLevel <= 4) {
     while (defined(my $ThisLine = <STDIN>)) {
-        if ($ThisLine =~ /\-- \[ERROR\] /) {
+        if ($ThisLine =~ /[ERR] /) {
             print $ThisLine;
         }
-        elsif ($ThisLine =~ /\-- \[STATUS\] /) {
+        elsif ($ThisLine =~ /[WARN] /) {
             print $ThisLine;
         }
-        elsif ($ThisLine =~ /\-- \[SUCCESS\] /) {
+        elsif ($ThisLine =~ /[SUCCESS] /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /already up to date/) {
             print $ThisLine;
         }
     }
 }
-### Level 5 is similiar to levels 1-4 except it also reports informational
+### Level 5 includes warning and error tally count messages and Cloudflare
-### messages such as the current working IP address and hostnames being
+### debugging messages
-### checked.  This is useful when verifying the cfddns.sh script's operation.
 elsif ($detailLevel == 5) {
     while (defined(my $ThisLine = <STDIN>)) {
-        if ($ThisLine =~ /\-- \[ERROR\] /) {
+        if ($ThisLine =~ /[ERR] /) {
             print $ThisLine;
         }
-        elsif ($ThisLine =~ /\-- \[STATUS\] /) {
+        elsif ($ThisLine =~ /CF-ERR: /) {
             print $ThisLine;
         }
-        elsif ($ThisLine =~ /\-- \[SUCCESS\] /) {
+        elsif ($ThisLine =~ /[WARN] /) {
             print $ThisLine;
         }
-        elsif ($ThisLine =~ /\-- \[INFO\] /) {
+        elsif ($ThisLine =~ /[SUCCESS] /) {
+            print $ThisLine;
+        }
+        elsif ($ThisLine =~ /already up to date/) {
             print $ThisLine;
         }
     }
 }
-### Any level above 5 will echo the entire log including the debugging notes
+### Any level 6 or above will echo the entire log. The log itself is purposefully terse
-### within the script meant for troubleshooting.  Using this level of detail
+### so while this level of detail is likely rarely needed, it is still not an overwhelming
-### should only be done if you cannot view the actual log file directly for
+### level of detail.
-### whatever reason.  The actual log file is colour-coded for easier debugging.
+### 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);
 
@@ -116,4 +135,4 @@ exit (0);
 # mode: perl
 # perl-indent-level: 3
 # indent-tabs-mode: nil
-# End:
+# End:

etc/logwatch/scripts/shared/iso8601timestamp

@@ -5,9 +5,8 @@
 ##########################################################################
 
 ###############################################################################
-## Filter dates in full-date-time international format, surrounded by square
+## Filter dates in ISO-8601 format located at the start of a given line
-## brackets located anywhere on a given line
+## Format: '%Y-%m-%dT%H:%M:%SZ'
-## Format: '[%Y-%m-%d %H:%M:%S]'
 ###############################################################################
 
 use Logwatch ':dates';
@@ -15,7 +14,7 @@ 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');
+$SearchDate = TimeFilter('%Y-%m-%dT%H:%M:%SZ');
 
 if ( $Debug > 5 ) {
    print STDERR "DEBUG: Inside FullDateTime...\n";
@@ -24,7 +23,7 @@ if ( $Debug > 5 ) {
 
 while (defined($ThisLine = <STDIN>)) {
    ### specify the regex that defines how to find 'SearchDate'
-   if ($ThisLine =~ m/\[$SearchDate\] /o) {
+   if ($ThisLine =~ m/^$SearchDate /o) {
       print $ThisLine;
    }
 }