refactor(log): Use CLEF for JSON logs

Use Compact Log Event Format (CLEF) for JSON logs along with custom properties.
perf(log): Use compact JSON for logging
2026-07-24 04:41:23 -06:00 · 2026-07-24 04:36:26 -06:00 · 2026-07-24 04:02:21 -06:00 · 2026-07-24 04:01:35 -06:00 · 2026-07-24 03:52:30 -06:00 · 2026-07-24 03:28:49 -06:00
16 changed files with 1083 additions and 728 deletions
@@ -55,6 +55,23 @@
 *.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
@@ -76,6 +93,8 @@
 # Exclude files from exporting
 #
-.gitattributes export-ignore
+.gitattributes  export-ignore
-.gitignore     export-ignore
+.gitignore      export-ignore
-.gitkeep       export-ignore
+.gitkeep        export-ignore
 .idea           export-ignore
 .vscode         export-ignore
@@ -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
@@ -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>
@@ -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>
@@ -0,0 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="UserContentModel">
    <attachedFolders />
    <explicitIncludes />
    <explicitExcludes />
  </component>
 </project>
@@ -0,0 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="com.itcodebox.notebooks.projectservice.ProjectUIState">
    <option name="selectedNotebookId" value="1" />
    <option name="selectedChapterId" value="1" />
    <option name="selectedNoteId" value="1" />
  </component>
 </project>
@@ -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>
@@ -0,0 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="VcsDirectoryMappings">
    <mapping directory="" vcs="Git" />
  </component>
 </project>
@@ -0,0 +1,4 @@
 <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/=mydomain/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=myserver/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>
@@ -1,39 +1,53 @@
 # CloudflareDDNS <!-- omit in toc -->
-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) shell script.
 systemd timers and a bash script.
 **NOTE: You can rename *cfddns.sh* to anything you want, the script will
 auto-update itself.  However, you MUST update the systemd service file
 *(cfddns.service)* *ExecStart* line manually as explained below.**
 ## Contents <!-- omit in toc -->
- [cfddns&#46;sh](#cfddns46sh)
+<!-- toc -->
-        - [Installation:](#installation)
+
-        - [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)
 - [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)
  * [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
+<!-- tocstop -->
-### 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 used to efficiently and reliably construct/deconstruct the JSON strings and arrays which is how the Cloudflare API communicates. In most cases you can install these programs using your package manager running as root or via sudo. On Debian/Ubuntu, for example, you would run:
-else in your path so it's easy to run.
+
 ```bash
 apt install -y curl jq
 ```
 While the script does *not* require root privileges, you will need sudo/root access to install the *systemd* service and timer.
 ## cfddns 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 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 +56,84 @@ 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 auto-update itself. 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 only one (1) being required.  The parameters are summarized below.  You can access the help screen and example usage screens by running:
 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.
+|-l<br>--log|Full path where the script should save its log. Recommend */var/log/scriptName.log*|scriptPath/scriptName.log|NO|
-  
+|--nc<br>--no-color<br>--no-colour|Do not use ANSI colour-coding when writing to the log. This is useful if you review the logs using a reader that does not support ANSI colour-coding and instead displays control symbols which makes your log difficult to read.|Disabled, do colourful logs|NO|
-Your completed file should look like (these are not real credentials):
+|--log-console|Output the log to the console instead of a log file. You may use `--nc` with this option also.|Disabled, write to log file|NO|
 |--no-log|Do not write a log file or output to the console. You will not have **any** feedback from the script if you run in this mode so you will not know if updates were successful or not. I’m not really sure why you’d want this option, but it’s available.|Disabled, write to log file|NO|
 |-h<br>--help<br>-?|Display built-in help screen explaining these same parameters.|||
 |--examples|Display some usage examples. Sometimes it's just easier to understand by seeing rather than reading.|||
 ## Cloudflare credentials file
 This repo includes a sample credentials file (*cloudflare.credentials* at the root of the repo) with pretty self-explanatory variable names. The script reads this file to get the credentials it needs to connect to your Cloudflare account and update DNS entries. It should be noted that the script is designed to use a *bearer token* and **not** your username/password or your Global API token! Let’s break this down in case things are a little fuzzy still...
 ### File structure
 The file is a basic shell script variables file. Make sure you **do not** put spaces between the variable name, equal sign and the value. Also, **do not** add any executable code since it will be run! The file should contain values for the following two variables:
 | Variable | Value                                                        |
 | -------- | ------------------------------------------------------------ |
 | cfKey    | The bearer token granting access to *edit* the DNS records of the zone (domain) in question. |
 | cfZoneId | The Cloudflare Zone ID of the zone (domain) you wish to update. |
 You can add comments if you’d like since the script will ignore them. In the end, your file should look something like this, but obviously with your data instead of this nonsense sample information:
 ```ini
 #
 # Cloudflare token for my.domain.tld
 #
 cfKey=_dLuyyRNaKN8SLG4-csmNYYfC39nnCmPVA7aYUJj
 cfZoneId=83d564234134513245311b23412331dd
 ```
-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 using the `--credentials` parameter. By default, the script will look for a file named *cloudflare.credentials* in the same path as the script.
-492af8aa69f8c44baf043342c74319fd
+
 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 username/password and Global API token provide unfettered access to your account so if anyone gets hold of them, they can do anything to your account. An API bearer token, by contrast, can only do what you authorize it to do and you can revoke it at any time. Therefore, I suggest making a bearer token that is based on the “Edit zone DNS” template and restricted to the specific domain/zone you wish to update. Cloudflare provides an [excellent article](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys) on how to generate this token.
 chown root:root path/to/filename
 ```
-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 bearer token. This script only caters to one zone so likely only one domain per configuration file. If you need to update multiple zones, you can have multiple configuration files and call them as required on separate invocations of the script.
 At least one entry here is *required*.  This is the A or AAAA record you want to
 update the IP address for in your DNS zone file.  If you have multiple A or AAAA
 records you want to update, simply specifiy multiple -r parameters.
-*Note: You can only specify *either* A records *or* AAAA records.  You have to
+To get your Zone ID, log into your Cloudflare account and open the domain in question. On the overview page, scroll down a bit and look to the right. You will see your Zone ID listed there. Copy that string into your configuration file.
 update IP4 and IP6 records separately by running this script multiple times
 (once for A records, once for AAAA records even if the hostname is the same).*
 **-4 or -6: type of record to update**
 The default option is -4 and it does not need to be specified.  This will update
 *A records* specified by the -r parameter(s).  If you specify -6, then *AAAA
 records* will updated as specified by the -r parameter(s).
-**-i: use the specified IP address**
+## cfddns systemd service unit
 The script will auto-detect the IP address of the machine it's being run on by
 accessing an external service and asking for that service to echo the machine's
 IP address.  If running with -4, then the IP4 will be requested for echo.  If
 running with -6, then the IP6 address will be requested for echo.
-This parameter let's you bypass auto-detection and specify a particular address
+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:
 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 +143,52 @@ 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 the other with the -6 (IP6) parameter. The service will run the cfddns&#46;sh script in default (IP4) mode with specified parameters first and then will run the script again in IP6 mode with specified parameters.
 IP-protocol parameter (default IP4) and the other with the -6 (IP6) parameter.
 The service will run the cfddns&#46;sh script in default (IP4) mode with specified
 parameters first and then will run the script again in IP6 mode with specified
 parameters.
 *Note: The parameters *can be different* in each case.*
 #### Examples
 1. **Only update A records**
-  Update *mail<span>.example.com* A record with the current IP of this machine and log
+    Update *mail<span>.example.com* A record with the current auto-detected public IP4 address of this machine and log results to */var/log/cfddns.log*.
-  results to */var/log/cfddns.log*.
+  
-
+    ```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 -l /var/log/cfddns.log
   ...
   ```
 2. **Only update AAAA records**
-  Update *git<span>.example.com* and *mail<span>.example.com* AAAA records with the current
+    Update *git<span>.example.com* and *mail<span>.example.com* AAAA records with the current auto-detected public IP6 address of this machine. Log will be stored in the same directory as the script file (/usr/local/bin).
  IP6 address of this machine. Log will be stored in the same directory as the
  script file (/usr/local/bin).
-   ```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 *mail<span>.example.com* A record with auto-detected public IP4 address of this machine and write to log file stored at */var/log/DDNS_IP4.log*.  Then, update both *mail<span>.example.com* and *git<span>.example.com* AAAA records with the specified IP6 address and write to log file at */var/log/DDNS_IP6.log*.
-   write to log file stored at */var/log/DDNS_IP4.log*.  Then, update both
+   
   *mail<span>.example.com* and *git<span>.example.com* AAAA records with current IP address
   of this machine and write to log file at */var/log/DDNS_IP6.log*.
   ```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 -l /var/log/DDNS_IP4.log
   # update IP6 addresses
   ExecStart=/usr/local/bin/cfddns.sh -6 -c /dir2/cloudflare.details -r mail.example.com,git.example.com --ip fd3f:e6db:9817:df84::a001 -l /var/log/DDNS_IP6.log
   ...
   ```
-## cfddns.timer
+## cfddns systemd timer unit
-This is the timer file that tells your system how often to call the
+Just like the service file unit, this file **must** be copied to your */etc/systemd/system* directory (or equivalent directory if you're not running Debian/Ubuntu). This timer file unit tells your system how often to call the *cfddns.service* file which runs the *cfddns&#46;sh* script.  By default, the timer is set for 5 minutes after the system boots up (to allow for other processes to initialize even on slower systems like a RasPi) and is then run every 15 minutes thereafter.  Remember when setting your timer that Cloudflare limits API calls to 1200 every 5 minutes.
 cfddns.service file which runs the cfddns&#46;sh script.  By default, the timer is
 set for 5 minutes after the system boots up (to allow for other processes to
 initialize even on slower systems like a RasPi) and is then run every 15
 minutes thereafter.  Remember when setting your timer that CloudFlare limits
 API calls to 1200 every 5 minutes.
-You can change the timer by modifying the relevant section of the cfddns.timer
+You can change the timer by modifying the relevant section of the *cfddns.timer* file:
 file:
 ```Ini
 [Timer]
@@ -224,22 +196,24 @@ 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 then wait the specified time from that first (after boot) call or after the timer is explicitly started before calling *cfddns.service* again.  I recommend setting OnUnitActiveSec to a low value (like 2 minutes) for testing then setting it to a more reasonable time (like 15
 the cfddns.service.  *OnUnitActiveSec* will then wait the specified time from that
 first (after boot) call or after the timer is explicitly started before calling
 cfddns.service again.  I recommend setting OnUnitActiveSec to a low value (like
 2 minutes) for testing then setting it to a more reasonable time (like 15
 minutes) after everything is working.
 After you’ve copied both the systemd unit and this timer unit, don’t forget to reload the systemd daemon so they are recognized by the system! On most systems you can do this by running the following as root or via sudo:
 ```bash
 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 +225,47 @@ 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 (see the [parameters section](#parameters) for details about setting log location and name).  If errors are encountered, they are colour coded red and an explanation of the error code is provided.
 configure any log-watch programs to further filter things for you so you don't
 have to review this log as part of your daily routine.  To make that easier, the
 following conventions are observed in the log file and can be used to program
 your log-watch system:
- Errors always appear as **-- [ERROR] text and error code here --**
+While the log file is as terse as I felt reasonable, you may still want to configure any log-watch programs to further filter things for you so you don't have to review this log as part of your daily routine.  To make that easier, the following conventions are observed in the log file and can be used to program your log-watch system:
- Errors are followed by an explanation of the specific error code on a new line
+
- A clean exit appears as **-- [SUCCESS] some text here --**
+- Specific update process errors: **[TIMESTAMP] ERR: message**
- The script always starts a new set of log entries with **-- Start CloudFlare
+  - These can be counted/filtered separately if you only care about update errors and not any other errors.
-  DDNS script execution --**
+- Error messages: **[TIMESTAMP] ERROR: message (code: number)**
- All log file entries start with a time-stamp in **[square brackets]**
+  - Only one summary error message will be displayed for any/all update errors. This message contains a tally of failed updates. If you want to count individual update errors, filter for the above process error message format.
  - While process error messages only relate to updates, these general error messages are logged for a variety of error conditions so it’s a good idea to include them in any filters.
 - Cloudflare API error messages:  **[TIMESTAMP] CF-ERR: message (code: cf-error-code)**
  - These are only logged when update process errors occur so that you can see exactly what the Cloudflare API is complaining about.
 - Specific update process warnings: **[TIMESTAMP] WARN: message**
  - These can be counted/filtered separately from general warning messages. Presently, there are *no* general warning messages.
 - Warning messages: **[TIMESTAMP] WARNING: message**
  - Summary of each type of warning. Contains a tally of the specific warning.
  - Currently, warnings are only issued for hostnames that are not found (i.e. update process warnings).
 - Success messages: **[TIMESTAMP] SUCCESS: message**
  - Each successful update generates a success message. There is no process or tally message.
 - Already up-to-date: **[TIMESTAMP] IP address for {fqdn} is already up-to-date**
  - Already up-to-date host entries generate a success message but you may still want to filter for them separately using this criteria.
 - A session log always starts with **[TIMESTAMP] -- Cloudflare DDNS update-script: starting --**
 - A successful session log always ends with **[TIMESTAMP] -- Cloudflare DDNS update-script: completed successfully --**
 - A session ending with errors always ends with **[TIMESTAMP] -- Cloudflare DDNS update-script: completed with error(s) --**
 ### Using Logwatch to monitor this script
-If you are using the Logwatch package to monitor your system, **see the README
+If you are using the Logwatch package to monitor your system, see the README in the */etc/logwatch* folder for details about the pre-configured service files already done for you :-)
 in the /etc/logwatch folder** for details about the pre-configured service files
 already done for you :-)
 ### Using Logrotate to control log file size
-Logrotate is pre-installed on standard Debian/Ubuntu distributions and is a great
+Logrotate is pre-installed on standard Debian/Ubuntu distributions and is a great way to automatically rotate your log files and control how many old logs you keep on your system so they don't accumulate and eat up your disk space. I've included a sample configuration file you can copy to your */etc/logrotate.d/* folder.  This file is set up to rotate your logs once a week, keep 3 weeks worth of history (compressed) and delete all logs older than that.  The configuration file is located in this git archive at
-way to automatically rotate your log files and control how many old logs you
+*/etc/logrotate.d/cfddns* and is fully commented to help you customize it to suit your needs.
 keep on your system so they don't accumulate and eat up your disk space.
 I've included a sample configuration file you can copy to your
 */etc/logrotate.d/* folder.  This file is set up to rotate your logs once a
 week, keep 3 weeks worth of history (compressed) and delete all logs older than
 that.  The configuration file is located in this git archive at
 */etc/logrotate.d/cfddns* and is fully commented to help you customize it to
 suit your needs.
 ## Final thoughts
-I'm by no means an expert in BASH scripting and I only program/script as a hobby
+Hopefully this helps you with an easy and reliable way to  update your Cloudflare DNS entries with a dynamic IP address. Please feel free to comment and provide feedback and suggestions to make this script better!
 when I find stuff that irritates me and no other good solutions seem easily
 available.  So, by all means, please comment, provide feedback and suggestions
 to make this script better!  Thanks, I hope this helps someone else out!
-Please check out my blog at
+Please check out my blog at [https://mytechiethoughts.com](https://mytechiethoughts.com) where I tackle problems like this all the time and find free/cheap solutions to tech problems.
 [https://mytechiethoughts.com](https://mytechiethoughts.com) where I tackle
 problems like this all the time and find free/cheap solutions to tech problems.
@@ -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 -l /var/log/cfddns.log
-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 -l /var/log/cfddns.log
 [Install]
 WantedBy=multi-user.target
@@ -1,457 +1,595 @@
 #!/bin/sh
 #
-# update CloudFlare DNS records with current (dynamic) IP address
+# update Cloudflare DNS records with current (dynamic) IP address
 #    Script by Asif Bacchus <asif@bacchus.cloud>
-#    Last modified: May 7, 2021
+#    Last modified: July 19, 2026
 #    Version 3.0
 #
 ### text formatting presets using tput
 if command -v tput >/dev/null; then
-    bold=$(tput bold)
+  [ -z "$TERM" ] && export TERM=xterm
-    cyan=$(tput setaf 6)
+  bold=$(tput bold)
-    err=$(tput bold)$(tput setaf 1)
+  cyan=$(tput setaf 6)
-    magenta=$(tput setaf 5)
+  err=$(tput bold)$(tput setaf 1)
-    norm=$(tput sgr0)
+  magenta=$(tput setaf 5)
-    ok=$(tput setaf 2)
+  norm=$(tput sgr0)
-    warn=$(tput bold)$(tput setaf 3)
+  ok=$(tput setaf 2)
-    yellow=$(tput setaf 3)
+  warn=$(tput bold)$(tput setaf 3)
-    width=$(tput cols)
+  yellow=$(tput setaf 3)
  width=$(tput cols)
 else
-    bold=""
+  bold=""
-    cyan=""
+  cyan=""
-    err=""
+  err=""
-    magenta=""
+  magenta=""
-    norm=""
+  norm=""
-    ok=""
+  ok=""
-    warn=""
+  warn=""
-    yellow=""
+  yellow=""
-    width=80
+  width=80
 fi
 ### functions
 badParam() {
-    if [ "$1" = "null" ]; then
+  if [ "$1" = "null" ]; then
-        printf "\n%sERROR: '%s' cannot have a NULL (empty) value.\n" "$err" "$2"
+    printf "\n%sERROR: '%s' cannot have a NULL (empty) value.\n" "$err" "$2"
-        printf "%sPlease use '--help' for assistance.%s\n\n" "$cyan" "$norm"
+    printf "%sPlease use '--help' for assistance.%s\n\n" "$cyan" "$norm"
-        exit 1
+    ([ "$logToConsole" -eq 0 ]) && writeLog \
-    elif [ "$1" = "dne" ]; then
+      "${2} cannot have a NULL (empty) value" "critical" "fail" "preexec" 1
-        printf "\n%sERROR: '%s %s'\n" "$err" "$2" "$3"
+    exit 1
-        printf "file or directory does not exist or is empty.%s\n\n" "$norm"
+  elif [ "$1" = "dne" ]; then
-        exit 1
+    printf "\n%sERROR: '%s %s'\n" "$err" "$2" "$3"
-    elif [ "$1" = "errMsg" ]; then
+    printf "file or directory does not exist or is empty.%s\n\n" "$norm"
-        printf "\n%sERROR: %s%s\n\n" "$err" "$2" "$norm"
+    ([ "$logToConsole" -eq 0 ]) && writeLog \
-        exit 1
+      "${3}: file or directory does not exist or is empty" "critical" "fail" "preexec" 1
-    fi
+    exit 1
  elif [ "$1" = "errMsg" ]; then
    printf "\n%sERROR: %s%s\n\n" "$err" "$2" "$norm"
    ([ "$logToConsole" -eq 0 ]) && writeLog \
      "${2%%\Exit*}" "fatal" "fail" "preexec" 1
    exit 1
  fi
 }
-exitError() {
+getHostname() {
-    case "$1" in
+  (hostname -s)
    10)
        errMsg="Unable to auto-detect IP address. Try again later or supply the IP address to be used."
        ;;
    20)
        errMsg="CloudFlare authorized email address (cfEmail) is either null or undefined. Please check your CloudFlare credentials file."
        ;;
    21)
        errMsg="CloudFlare authorized API key (cfKey) is either null or undefined. Please check your CloudFlare credentials file."
        ;;
    22)
        errMsg="CloudFlare zone id (cfZoneId) is either null or undefined. Please check your CloudFlare credentials file."
        ;;
    25)
        errMsg="Unable to query CloudFlare account. Please re-check your credentials and try again later."
        ;;
    98)
        errMsg="One or more domain updates failed. Please review this log file for details."
        ;;
    *)
        printf "%s[%s] ERROR: An unspecified error occurred. Exiting.%s\n" "$err" "$(stamp)" "$norm" >>"$logFile"
        exit 99
        ;;
    esac
    printf "%s[%s] ERROR: %s (code: %s)%s\n" "$err" "$(stamp)" "$errMsg" "$1" "$norm" >>"$logFile"
    printf "%s[%s] -- CloudFlare DDNS update-script: execution completed with error(s) --%s\n" "$err" "$(stamp)" "$norm" >>"$logFile"
    exit "$1"
 }
-exitOK() {
+getTimeStamp() {
-    printf "%s[%s] -- CloudFlare DDNS update-script: execution complete --%s\n" "$ok" "$(stamp)" "$norm" >>"$logFile"
+  (date -u +"%Y-%m-%dT%H:%M:%SZ")
    exit 0
 }
-stamp() {
+lowercase() {
-    (date +%F" "%T)
+  echo "$1" | tr '[:upper:]' '[:lower:]'
 }
-scriptHelp() {
+uppercase() {
-    newline
+  echo "$1" | tr '[:lower:]' '[:upper:]'
-    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."
+# 1: cloudflare error object, 2: operation identifier
-    textblock "Paramters 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)."
+listCFErrors() {
-    newline
+  # extract error codes and messages in separate variables, replace newlines with underscores
-    textblock "${magenta}--- script related parameters ---${norm}"
+  codes="$(printf "%s" "$1" | jq -r '.errors | .[] | .code' | tr '\n' '_')"
-    newline
+  messages="$(printf "%s" "$1" | jq -r '.errors | .[] | .message' | tr '\n' '_')"
-    textblockSwitches "-c | --cred | --creds | --credentials | -f (deprecated, backward-compatability)"
+
-    textblock "Path to file containing your CloudFlare *token* credentials. Please refer to the repo README for more information on format, etc."
+  # iterate codes and messages, assemble into a coherent log message
-    textblockDefaults "(${accountFile})"
+  while [ -n "$codes" ] && [ -n "$messages" ]; do
-    newline
+    # get the first code and message in respective sets
-    textblockSwitches "-l | --log"
+    code="${codes%%_*}"
-    textblock "Path where the log file should be written."
+    message="${messages%%_*}"
-    textblockDefaults "(${logFile})"
+
-    newline
+    # update sets of codes and messages by removing the first item (above) in each set
-    textblockSwitches "--nc | --no-color | --no-colour"
+    codes="${codes#*_}"
-    textblock "Switch value. Disables ANSI colours in the log. Useful if you review the logs using a reader that does not parse ANSI colour codes."
+    messages="${messages#*_}"
-    textblockDefaults "(disabled: print logs in colour)"
+
-    newline
+    # output to log
-    textblockSwitches "--log-console"
+    writeLog "${message}" "err" "fail" "$2:CF-ERR" "$code"
-    textblock "Switch value. Output log to console (stdout) instead of a log file. Can be combined with --nc if desired."
+  done
-    textblockDefaults "(disabled: output to log file)"
+}
-    newline
+
-    textblockSwitches "--no-log"
+standardizeLogLevels() {
-    textblock "Switch value. Do not create a log (i.e. no console, no file). You will not have *any* output from the script if you choose this option, so you will not know if updates succeeded or failed."
+  LEVEL_TO_STANDARDIZE="$(lowercase "$1")"
-    textblockDefaults "(disabled: output to log file)"
+  case "$LEVEL_TO_STANDARDIZE" in
-    newline
+  "critical" | "crit" | "fatal")
-    textblockSwitches "-h | --help | -?"
+    echo "CRIT"
-    textblock "Display this help screen."
+    ;;
-    newline
+  "error" | "err")
-    textblockSwitches "--examples"
+    echo "ERR"
-    textblock "Show some usage examples."
+    ;;
-    newline
+  "warning" | "warn")
-    textblock "${magenta}--- DNS related parameters ---${norm}"
+    echo "WARN"
-    newline
+    ;;
-    textblockSwitches "-r | --record | --records"
+  "information" | "info")
-    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."
+    echo "INFO"
-    newline
+    ;;
-    textblockSwitches "-i | --ip | --ip-address | -a | --address"
+  "debug" | "verbose")
-    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."
+    echo "DEBUG"
-    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."
+    echo "INFO"
-    textblockDefaults "(enabled: update A records)"
+    ;;
-    newline
+  esac
-    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)"
+# $1: message, $2: level, $3: status, [$4: operation], [$5: code]
-    newline
+writeJsonLog() {
-    textblock "Please refer to the repo README for more detailed information regarding this script and how to automate and monitor it."
+  # not enough information to generate a meaningful log message
-    newline
+  if [ -z "$1" ] || [ $# -lt 3 ]; then
-    exit 0
+    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 ]) && return # TODO: replace this with function when implemented
  ([ "$useJsonLogFmt" -eq 1 ]) && writeJsonLog "$@"
  ([ "$useSyslogLogFmt" -eq 1 ]) && writePlainTextLog "$@"
 }
 scriptExamples() {
-    newline
+  newline
-    printf "Update CloudFlare DNS host A/AAAA records with current IP address.\n"
+  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"
+  printf "%sUsage: %s --records host.domain.tld[,host2.domain.tld,...] [parameters]%s\n\n" "$bold" "$scriptName" "$norm"
-    textblock "${magenta}--- usage examples ---${norm}"
+  textBlock "${magenta}--- usage examples ---${norm}"
-    newline
+  newline
-    textblockSwitches "${scriptName} -r myserver.mydomain.net"
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net"
-    textblock "Update CloudFlare DNS records for myserver.mydomain.net with the auto-detected public IP4 address. Credentials will be expected in the default location and the log will be written in the default location also."
+  textBlock "Update Cloudflare DNS records for myserver.mydomain.net with the auto-detected public IP4 address. Credentials will be expected in the default location and the log will be written in the default location also."
-    newline
+  newline
-    textblockSwitches "${scriptName} -r myserver.mydomain.net -6"
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net -6"
-    textblock "Same as above, but update AAAA host records with the auto-detected public IP6 address."
+  textBlock "Same as above, but update AAAA host records with the auto-detected public IP6 address."
-    newline
+  newline
-    textblockSwitches "${scriptName} -r myserver.mydomain.net,otherserver.mydomain.net -l /var/log/cfddns.log --nc"
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net,myserver2.mydomain.net -l /var/log/cfddns.log --nc"
-    textblock "Update DNS entries for both listed hosts using auto-detected IP4 address. Write a non-coloured log to '/var/log/cfddns.log'."
+  textBlock "Update DNS entries for both listed hosts using auto-detected IP4 address. Write a non-coloured log to '/var/log/cfddns.log'."
-    newline
+  newline
-    textblockSwitches "${scriptName} -r myserver.mydomain.net,otherserver.mydomain.net -l /var/log/cfddns.log --ip6 --ip fd21:7a62:2737:9c3a::a151"
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net,myserver2.mydomain.net -l /var/log/cfddns.log --ip6 --ip fd21:7a62:2737:9c3a::a151"
-    textblock "Update DNS AAAA entries for listed hosts using the *specified* IP address. Write a colourful log to the location specified."
+  textBlock "Update DNS AAAA entries for listed hosts using the *specified* IP address. Write a colourful log to the location specified."
-    newline
+  newline
-    textblockSwitches "${scriptName} -r myserver.mydomain.net -c /root/cloudflare.creds -l /var/log/cfddns.log --ip 1.2.3.4"
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net -c /root/cloudflare.creds -l /var/log/cfddns.log --ip 1.2.3.4"
-    textblock "Update DNS A entry for listed hostname with the provided IP address. Read cloudflare credentials file from specified location, save log in specified location."
+  textBlock "Update DNS A entry for listed hostname with the provided IP address. Read cloudflare credentials file from specified location, save log in specified location."
-    newline
+  newline
-    textblockSwitches "${scriptName} -r myserver.mydomain.net -c /root/cloudflare.creds -l /var/log/cfddns.log -6 -i fd21:7a62:2737:9c3a::a151"
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net -c /root/cloudflare.creds -l /var/log/cfddns.log -6 -i fd21:7a62:2737:9c3a::a151"
-    textblock "Exact same as above, but change the AAAA record. This is how you run the script once for IP4 and again for IP6."
+  textBlock "Exact same as above, but change the AAAA record. This is how you run the script once for IP4 and again for IP6."
-    exit 0
+  exit 0
 }
-textblock() {
+scriptHelp() {
-    printf "%s\n" "$1" | fold -w "$width" -s
+  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"
-textblockDefaults() {
+  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."
-    printf "%s%s%s\n" "$yellow" "$1" "$norm"
+  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}"
-textblockSwitches() {
+  newline
-    printf "%s%s%s\n" "$cyan" "$1" "$norm"
+  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"
+  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"
 colourizeLogFile=1
 dnsRecords=""
 dnsSeparator=","
 ipAddress=""
 ip4=1
 ip6=0
-ip4DetectionSvc="http://ipv4.icanhazip.com"
+ip4DetectionSvc="https://ipv4.icanhazip.com"
-ip6DetectionSvc="http://ipv6.icanhazip.com"
+ip6DetectionSvc="https://ipv6.icanhazip.com"
 invalidDomainCount=0
-failedDomainCount=0
+failedHostCount=0
 ### process startup parameters
 if [ -z "$1" ]; then
-    scriptHelp
+  scriptHelp
 fi
 while [ $# -gt 0 ]; do
-    case "$1" in
+  case "$1" in
-    -h | -\? | --help)
+  -h | -\? | --help)
-        # display help
+  # display help
-        scriptHelp
+    scriptHelp
-        ;;
+    ;;
-    --examples)
+  --examples)
-        # display sample commands
+  # display sample commands
-        scriptExamples
+    scriptExamples
-        ;;
+    ;;
-    -l | --log)
+  --log-file)
-        # set log file location
+  # use file-based logging at the specified location
-        if [ -n "$2" ]; then
+    if [ -n "$2" ]; then
-            logFile="${2%/}"
+      logFile="${2%/}"
-            shift
+      shift
-        else
+    else
-            badParam null "$@"
+      badParam null "$@"
-        fi
+    fi
-        ;;
+    ;;
-    --log-console)
+  --log-console)
-        # log to the console instead of a file
+  # use console-based logging
-        logFile="/dev/stdout"
+    logFile="/dev/stdout"
-        ;;
+    logToConsole=1
-    --no-log)
+    ;;
-        # do not log anything
+  --log-journal)
-        logFile="/dev/null"
+  # use journald-based logging
-        ;;
+    logToJournal=1
-    --nc | --no-color | --no-colour)
+    ;;
-        # do not colourize log file
+  --log-none)
-        colourizeLogFile=0
+  # do not log anything
-        ;;
+    logFile="/dev/null"
-    -c | --cred* | -f)
+    logToNone=1
-        # path to CloudFlare credentials file
+    ;;
-        if [ -n "$2" ]; then
+  --log-debug)
-            if [ -f "$2" ] && [ -s "$2" ]; then
+  # log debugging messages
-                accountFile="${2%/}"
+    logDebug=1
-                shift
+    ;;
-            else
+  --fmt-json)
-                badParam dne "$@"
+  # use JSON log formatting
-            fi
+    useJsonLogFmt=1
-        else
+    useSyslogLogFmt=0
-            badParam null "$@"
+    ;;
-        fi
+  --fmt-syslog)
-        ;;
+  # use modified syslog plain-text log formatting
-    -r | --record | --records)
+    useSyslogLogFmt=1
-        # DNS records to update
+    useJsonLogFmt=0
-        if [ -n "$2" ]; then
+    ;;
-            dnsRecords=$(printf "%s" "$2" | sed -e 's/ //g')
+  -c | --cred* | -f)
-            shift
+  # path to the Cloudflare credentials file
-        else
+    if [ -n "$2" ]; then
-            badParam null "$@"
+      if [ -f "$2" ] && [ -s "$2" ]; then
-        fi
+        accountFile="${2%/}"
-        ;;
+        shift
-    -i | --ip | --ip-address | -a | --address)
+      else
-        # IP address to use (not parsed for correctness)
+        badParam dne "$@"
-        if [ -n "$2" ]; then
+      fi
-            ipAddress="$2"
+    else
-            shift
+      badParam null "$@"
-        else
+    fi
-            badParam null "$@"
+    ;;
-        fi
+  -r | --record | --records)
-        ;;
+  # DNS records to update
-    -4 | --ip4 | --ipv4)
+    if [ -n "$2" ]; then
-        # operate in IP4 mode (default)
+      dnsRecords=$(printf "%s" "$2" | sed -e 's/ //g')
-        ip4=1
+      shift
-        ip6=0
+    else
-        ;;
+      badParam null "$@"
-    -6 | --ip6 | --ipv6)
+    fi
-        # operate in IP6 mode
+    ;;
-        ip6=1
+  -i | --ip | --ip-address | -a | --address)
-        ip4=0
+  # IP address to use (not parsed for correctness)
-        ;;
+    if [ -n "$2" ]; then
-    *)
+      ipAddress="$2"
-        printf "\n%sUnknown option: %s\n" "$err" "$1"
+      shift
-        printf "%sUse '--help' for valid options.%s\n\n" "$cyan" "$norm"
+    else
-        exit 1
+      badParam null "$@"
-        ;;
+    fi
-    esac
+    ;;
-    shift
+  -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
 ### pre-flight checks
 if ! command -v curl >/dev/null; then
-    printf "\n%sThis script requires 'curl' be installed and accessible. Exiting.%s\n\n" "$err" "$norm"
+  printf "\n%sThis script requires that 'curl' is installed and accessible. Exiting.%s\n\n" "$err" "$norm"
-    exit 2
+  ([ "$logToConsole" -eq 0 ]) && writeLog "'curl' must be installed and accessible" "fatal" "fail" "preexec" 2
  exit 2
 fi
 if ! command -v jq >/dev/null; then
-    printf "\n%sThis script requires 'jq' be installed and accessible. Exiting.%s\n\n" "$err" "$norm"
+  printf "\n%sThis script requires that 'jq' is installed and accessible. Exiting.%s\n\n" "$err" "$norm"
-    exit 2
+  ([ "$logToConsole" -eq 0 ]) && writeLog "'jq' must be installed and accessible" "fatal" "fail" "preexec" 2
  exit 2
 fi
-[ -z "$dnsRecords" ] && badParam errMsg "You must specify at least one DNS record to update. Exiting."
+if [ -z "$dnsRecords" ]; then
-# verify credentials file exists and is not empty (default check)
+  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 CloudFlare credentials file (${accountFile}). Exiting."
+  badParam errMsg "Cannot find the Cloudflare credentials file (${accountFile}) or it is empty. Exiting."
 fi
-# turn off log file colourization if parameter is set
+if [ "$logToJournal" -eq 1 ] && ! command -v logger >/dev/null 2>&1; then
-if [ "$colourizeLogFile" -eq 0 ]; then
+  printf "\n%sThis script requires that 'logger' is installed to write journald entries. Exiting.%s\n\n" "$err" "$norm"
-    bold=""
+  exit 2
    cyan=""
    err=""
    magenta=""
    norm=""
    ok=""
    warn=""
    yellow=""
 fi
 ### initial log entries
-{
+writeLog "starting '${scriptName}'" "info" "ok" "script"
-    printf "%s[%s] -- CloudFlare DDNS update-script: execution starting --%s\n" "$ok" "$(stamp)" "$norm"
+writeLog "script path: ${scriptPath}/${scriptName}" "debug" "ok" "startup"
-    printf "%sParameters:\n" "$magenta"
+writeLog "credentials file: ${accountFile}" "debug" "ok" "startup"
    printf "script path: %s\n" "$scriptPath/$scriptName"
    printf "credentials file: %s\n" "$accountFile"
 } >>"$logFile"
 if [ "$ip4" -eq 1 ]; then
-    printf "mode: IP4\n" >>"$logFile"
+  writeLog "mode: IPv4" "debug" "ok" "startup"
 elif [ "$ip6" -eq 1 ]; then
-    printf "mode: IP6\n" >>"$logFile"
+  writeLog "mode: IPv6" "debug" "ok" "startup"
 fi
 # detect and report IP address
 if [ -z "$ipAddress" ]; then
-    # detect public ip address
+  # detect public ip address
-    if [ "$ip4" -eq 1 ]; then
+  if [ "$ip4" -eq 1 ]; then
-        if ! ipAddress="$(curl -s $ip4DetectionSvc)"; then
+    if ! ipAddress="$(curl -s $ip4DetectionSvc)"; then
-            printf "ddns ip address: %serror%s\n" "$err" "$norm" >>"$logFile"
+      writeLog \
-            exitError 10
+        "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
-        fi
+      exit 10
    fi
-    if [ "$ip6" -eq 1 ]; then
+  fi
-        if ! ipAddress="$(curl -s $ip6DetectionSvc)"; then
+  if [ "$ip6" -eq 1 ]; then
-            printf "ddns ip address: %serror%s\n" "$err" "$norm" >>"$logFile"
+    if ! ipAddress="$(curl -s $ip6DetectionSvc)"; then
-            exitError 10
+      writeLog \
-        fi
+        "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
-    printf "ddns ip address (detected): %s\n" "$ipAddress" >>"$logFile"
+  fi
  writeLog "DDNS IP address (detected): $ipAddress" "info" "ok" "startup"
 else
-    printf "ddns ip address (supplied): %s\n" "$ipAddress" >>"$logFile"
+  writeLog "DDNS IP address (supplied): $ipAddress" "info" "ok" "startup"
 fi
 # iterate DNS records to update
-dnsRecordsToUpdate="$dnsRecords$dnsSeparator"
+dnsRecordsToUpdate="$(printf '%s' "${dnsRecords}" | sed "s/${dnsSeparator}*$//")$dnsSeparator"
-while [ "$dnsRecordsToUpdate" != "${dnsRecordsToUpdate#*${dnsSeparator}}" ] && { [ -n "${dnsRecordsToUpdate%%${dnsSeparator}*}" ] || [ -n "${dnsRecordsToUpdate#*${dnsSeparator}}" ]; }; do
+while [ -n "$dnsRecordsToUpdate" ] && [ "$dnsRecordsToUpdate" != "$dnsSeparator" ]; do
-    record="${dnsRecordsToUpdate%%${dnsSeparator}*}"
+  record="${dnsRecordsToUpdate%%${dnsSeparator}*}"
-    dnsRecordsToUpdate="${dnsRecordsToUpdate#*${dnsSeparator}}"
+  dnsRecordsToUpdate="${dnsRecordsToUpdate#*${dnsSeparator}}"
-    printf "updating record: %s\n" "$record" >>"$logFile"
+
  if [ -z "$record" ]; then
    continue
  fi
  writeLog "DNS host record '${record}' queued for update" "info" "ok" "startup"
 done
-printf "(end of parameter list)%s\n" "$norm" >>"$logFile"
+### read Cloudflare credentials
 ### read CloudFlare credentials
 printf "[%s] Reading CloudFlare credentials... " "$(stamp)" >>"$logFile"
 case "$accountFile" in
 /*)
-    # absolute path, use as-is
+# absolute path, use as-is
-    # shellcheck source=./cloudflare.credentials
+# shellcheck source=./cloudflare.credentials
-    . "$accountFile"
+  . "$accountFile"
-    ;;
+  ;;
 *)
-    # relative path, rewrite
+# relative path, rewrite
-    # shellcheck source=./cloudflare.credentials
+# shellcheck source=./cloudflare.credentials
-    . "./$accountFile"
+  . "./$accountFile"
-    ;;
+  ;;
 esac
-if [ -z "$cfEmail" ]; then
+if [ -z "$cfKey" ]; then
-    printf "%sERROR%s\n" "$err" "$norm" >>"$logFile"
+  writeLog "Cloudflare authorized API key (cfKey) is either null or undefined; please check your Cloudflare credentials file" "err" "fail" "creds" 21
-    exitError 20
+  exit 21
 elif [ -z "$cfKey" ]; then
    printf "%sERROR%s\n" "$err" "$norm" >>"$logFile"
    exitError 21
 elif [ -z "$cfZoneId" ]; then
    printf "%sERROR%s\n" "$err" "$norm" >>"$logFile"
    exitError 22
 fi
-printf "DONE%s\n" "$norm" >>"$logFile"
+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"
-### check if records to be updated exist and if they need updating, update as required
+### connect to Cloudflare and do what needs to be done!
 dnsRecordsToUpdate="$dnsRecords$dnsSeparator"
 if [ "$ip4" -eq 1 ]; then
-    recordType="A"
+  recordType="A"
 elif [ "$ip6" -eq 1 ]; then
-    recordType="AAAA"
+  recordType="AAAA"
 fi
-while [ "$dnsRecordsToUpdate" != "${dnsRecordsToUpdate#*${dnsSeparator}}" ] && { [ -n "${dnsRecordsToUpdate%%${dnsSeparator}*}" ] || [ -n "${dnsRecordsToUpdate#*${dnsSeparator}}" ]; }; do
+
-    record="${dnsRecordsToUpdate%%${dnsSeparator}*}"
+# iterate hosts to update
-    dnsRecordsToUpdate="${dnsRecordsToUpdate#*${dnsSeparator}}"
+while [ -n "$dnsRecordsToUpdate" ] && [ "$dnsRecordsToUpdate" != "$dnsSeparator" ]; do
-    printf "[%s] Processing %s... " "$(stamp)" "$record" >>"$logFile"
+  record="${dnsRecordsToUpdate%%${dnsSeparator}*}"
-    # check for existing record, else exit with error (this script does NOT create new records, only updates them!)
+  dnsRecordsToUpdate="${dnsRecordsToUpdate#*${dnsSeparator}}"
-    if ! cfResult="$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones/${cfZoneId}/dns_records?name=${record}&type=${recordType}" \
+
-        -H "Authorization: Bearer ${cfKey}" \
+  if [ -z "$record" ]; then
-        -H "Content-Type: application/json")"; then
+    continue
-        printf "%sERROR%s\n" "$err" "$norm" >>"$logFile"
+  fi
-        exitError 25
+
-    fi
+  # exit if curl/network error
-    resultCount="$(printf "%s" "$cfResult" | jq '.result_info.count')"
+  if ! cfLookup="$(
-    if [ "$resultCount" = "0" ]; then
+    curl -s -X GET "https://api.cloudflare.com/client/v4/zones/${cfZoneId}/dns_records?name=${record}&type=${recordType}" \
-        printf "%sNOT FOUND%s\n" "$warn" "$norm" >>"$logFile"
+      -H "Authorization: Bearer ${cfKey}" \
-        printf "%s[%s] WARNING: Cannot find existing record to update for DNS entry: %s%s\n" "$warn" "$(stamp)" "$record" "$norm" >>"$logFile"
+      -H "Content-Type: application/json"
-        invalidDomainCount=$((invalidDomainCount + 1))
+  )"; then
-    else
+    writeLog "Unable to connect to Cloudflare servers; please try again later." "err" "fail" "cflogin" 3
-        objectId=$(printf "%s" "$cfResult" | jq -r '.result | .[] | .id')
+    exit 3
-        currentIpAddr=$(printf "%s" "$cfResult" | jq -r '.result | .[] | .content')
+  fi
-        printf "FOUND: IP = %s\n" "$currentIpAddr" >>"$logFile"
+
-        # check if record needs updating
+  # an API error on this GET request likely indicates an authentication error that would affect all remaining operations
-        if [ "$currentIpAddr" = "$ipAddress" ]; then
+  # no reason to continue processing other dns records and pile-up errors which might look like a DoS attempt
-            printf "%s[%s] IP address for %s is already up-to-date%s\n" "$ok" "$(stamp)" "$record" "$norm" >>"$logFile"
+  cfSuccess="$(printf "%s" "$cfLookup" | jq -r '.success')"
-        else
+  if [ "$cfSuccess" = "false" ]; then
-            # update record
+    listCFErrors "$cfLookup" "cflogin"
-            printf "%s[%s] Updating IP address for %s... " "$cyan" "$(stamp)" "$record" >>"$logFile"
+    writeLog "Cloudflare API error; review any previously logged 'CF-ERR:' lines for details." "err" "fail" "cflogin" 25
-            updateJSON="$(jq -n --arg key0 content --arg value0 "${ipAddress}" '{($key0):$value0}')"
+    exit 25
-            if ! cfResult="$(curl -s -X PATCH "https://api.cloudflare.com/client/v4/zones/${cfZoneId}/dns_records/${objectId}" \
+  fi
-                -H "Authorization: Bearer ${cfKey}" \
+
-                -H "Content-Type: application/json" \
+  resultCount="$(printf "%s" "$cfLookup" | jq '.result_info.count')"
-                --data "${updateJSON}")"; then
+
-                printf "%sERROR%s\n" "$err" "$norm" >>"$logFile"
+  # skip to the next host if an existing host record cannot be found (this script *updates* only, does not create!)
-                exitError 25
+  if [ "$resultCount" = "0" ]; then
-            fi
+    writeLog "Cannot find an existing record matching '${record}' to update" "warn" "warn" "ddns"
-            updateSuccess="$(printf "%s" "$cfResult" | jq '.success')"
+    invalidDomainCount=$((invalidDomainCount + 1))
-            if [ "$updateSuccess" = "true" ]; then
+    continue
-                printf "DONE%s\n" "$norm" >>"$logFile"
+  fi
-                printf "%s[%s] SUCCESS: IP address for %s updated%s\n" "$ok" "$(stamp)" "$record" "$norm" >>"$logFile"
+
-            else
+  objectId=$(printf "%s" "$cfLookup" | jq -r '.result | .[] | .id')
-                printf "%sFAILED%s\n" "$err" "$norm" >>"$logFile"
+  currentIpAddr=$(printf "%s" "$cfLookup" | jq -r '.result | .[] | .content')
-                printf "%s[%s] ERROR: Unable to update IP address for %s%s\n" "$err" "$(stamp)" "$record" "$norm" >>"$logFile"
+  writeLog "The current IP address for '${record}' is ${currentIpAddr}" "debug" "ok" "ddns"
-                failedDomainCount=$((failedDomainCount + 1))
+
-            fi
+  # skip to next hostname if record already up to date
-        fi
+  if [ "$currentIpAddr" = "$ipAddress" ]; then
-    fi
+    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" "ok" "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
-    printf "%s[%s] -- WARNING: %s invalid domain(s) were supplied for updating --%s\n" "$warn" "$(stamp)" "$invalidDomainCount" "$norm" >>"$logFile"
+  writeLog "${invalidDomainCount} invalid host(s) were supplied for updating" "warn" "warn" "ddns"
 fi
-if [ "$failedDomainCount" -ne 0 ]; then
+if [ "$failedHostCount" -ne 0 ]; then
-    exitError 98
+  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
-    exitOK
+  writeLog "${scriptName} completed successfully" "info" "ok" "script"
 fi
 ### exit return codes
-# 0:    normal exit, no errors
+# 0: normal exit, no errors
-# 1:    invalid or unknown parameter
+# 1: invalid or unknown parameter
-# 2:    cannot find or access required external program(s)
+# 2: cannot find or access required external program(s)
-# 10:   cannot auto-detect IP address
+# 3: curl error (probably connection)
-# 20:   accountFile has a null or missing cfEmail variable
+# 10: cannot auto-detect IP address
-# 21:   accountFile has a null or missing cfKey variable
+# 21: accountFile has a null or missing cfKey variable
-# 22:   accountFile has a null or missing cfZoneId variable
+# 22: accountFile has a null or missing cfZoneId variable
-# 25:   unable to query CloudFlare account
+# 25: Cloudflare API error
-# 97:   script completed with warnings
+# 26: one or more updates failed
-# 98:   one or more updates failed
+# 99: unspecified error occurred
 # 99:   unspecified error occurred
@@ -2,6 +2,5 @@
 # CloudFlare token for my.domain.tld
 #
 cfEmail=email@server.tld
 cfKey=_dLuyyRNaKN8SLG4-csmNYYfC39nnCmPVA7aYUJj
 cfZoneId=83d564234134513245311b23412331dd
@@ -1,45 +1,52 @@
 # Using Logwatch to monitor Cloudflare DDNS updater script <!-- omit in toc -->
-The Cloudflare DDNS update script's log file has been set up so that utilities
+The Cloudflare DDNS update script's log file has been set up so that utilities like Logwatch can easily parse it.  In order to make that happen, a LogFile Group file, Service and Script have to be created for Logwatch to generate reports.  The correct (general) directory structure has been created in this git archive already.  Below are the details of each file.
-like Logwatch can easily parse it.  In order to make that happen, a LogFile
+
-Group file, Service and Script have to be created for Logwatch to generate
+You can implement this setup easily by copying it into your */etc/logwatch* directory and then modifying the files as necessary:
-reports.  The correct (general) directory structure has been created in this git
+
-archive already.  Below are the details of each file.
+```bash
 cd /etc/logwatch
 cp -R /path/to/CloudflareDDNS_repo/etc/logwatch/* ./
 ```
 If you need help getting logwatch installed and set-up, please [check out my blog post](#https://mytechiethoughts.com/linux/easily-monitor-your-logs-using-logwatch/).
 ## Contents <!-- omit in toc -->
- [LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)](#logfile-group-file-etclogwatchconflogfilescfddnsconf)
+<!-- toc -->
-    - [Log file location](#log-file-location)
+
-    - [Archive location and name format](#archive-location-and-name-format)
+- [LogFile Group file](#logfile-group-file)
-    - [External script for timestamp processing](#external-script-for-timestamp-processing)
+  * [Log file location](#log-file-location)
- [Service definition file (/etc/logwatch/conf/services/cfddns.conf)](#service-definition-file-etclogwatchconfservicescfddnsconf)
+  * [Archive location and name format](#archive-location-and-name-format)
-    - [LogFile Group file definition](#logfile-group-file-definition)
+  * [External script for timestamp processing](#external-script-for-timestamp-processing)
-    - [Report title](#report-title)
+- [Service definition file](#service-definition-file)
-    - [Detail level](#detail-level)
+  * [LogFile Group file definition](#logfile-group-file-definition)
- [Service script (/etc/logwatch/scripts/services/cfddns)](#service-script-etclogwatchscriptsservicescfddns)
+  * [Report title](#report-title)
-    - [Detail levels](#detail-levels)
+  * [Detail level](#detail-level)
- [Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere)](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere)
+- [Service script](#service-script)
-    - [The time format specification](#the-time-format-specification)
+  * [Detail levels](#detail-levels)
-    - [The search REGEX](#the-search-regex)
+- [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)
-## LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)
+<!-- tocstop -->
 ## 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 default, the log file is created in the same directory as the script itself.
 generated by the updater script.  Remember, by default, the log file is created
 in the same directory as the script itself.
 ```Ini
 LogFile = /path/to/your/cfddns.log
 ...
 ```
-Best practices suggest you use the *-l*
+Best practices suggest you use the `--log` flag to change this location to something like */var/log/cfddns.log*, for example.  In that case, the entry would look like:
 flag to change this location to something like */var/log/cfddns.log*, for
 example.  In that case, the entry would look like:
 ```Ini
 LogFile = /var/log/cfddns.log
@@ -48,12 +55,7 @@ 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 specify the location and file name format of those files.  I've included the generalized compressed format of such rotated files as the default in the script.  Suppose you store your log files in the recommended location (*/var/log/*) and are using *Logrotate* with compression enabled, the archive line would look like:
 like *Logrotate*, then you have to specify the location and file name format of
 those files.  I've included the generalized compressed format of such rotated
 files as the default in the script.  Suppose you store your log files in the
 recommended location (*/var/log/*) and are using *Logrotate* with compression
 enabled, the archive line would look like:
 ```Ini
 ...
@@ -61,21 +63,15 @@ 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.1.gz*, *cfddns.log.2.gz*, etc. and are all located in */var/log/*.
 *cfddns.log* files are archived as: *cfddns.log.1.gz*, *cfddns.log.2.gz*, etc.
 and are all located in */var/log/*.
-**Note: This line is totally optional and only used if you set the archive
+> Note: This line is totally optional and only used if you set the archive option in Logwatch to true.  You can comment/delete this line if you wish.
 option in Logwatch to true.  You can comment/delete this line if you wish.**
 ### External script for timestamp processing
-Since the log file uses a non-standard (according to Logwatch) method of
+Since the log file uses a non-standard (according to Logwatch) method of date-stamping, a custom filter had to be created.  See the [relevant](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere) section of this document for more information.
 datestamping, a custom filter had to be created.  See the
 [relevant](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere)
 section of this document for more information.
-The script file is called with an *\** before the filename.
+The script file is called with an asterisk (*\**) before the filename.
 ```Ini
 ...
@@ -83,31 +79,26 @@ The script file is called with an *\** before the filename.
 ...
 ```
-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 is converted to all-lowercase so your filename should be all lowercase also.
 Remember that whatever you type here as a name is converted to all-lowercase
 so your filename should be all lowercase also.
-## Service definition file (/etc/logwatch/conf/services/cfddns.conf)
+## 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 your *LogFile Group file*:
 processing.  This MUST match the name of your *LogFile Group file*:
 ```Ini
 LogFile = cfddns
 ...
 ```
-If you change your LogFile Group filename, then update it here 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 meaning for you.  I have arbitrarily chosen *"CloudFlare DDNS update"* but you can change it to anything you want by modifying the line:
 define the title to be anything that has meaning for you.  I have arbitrarily
 chosen *"CloudFlare DDNS update"* but you can change it to anything you want by
 modifying the line:
 ```Ini
 ...
@@ -115,10 +106,7 @@ Title = "CloudFlare DDNS update"
 ```
 ### Detail level
-If you want to set the *detail* level of this service differently from your
+If you want to set the *detail* level of this service differently from your other services (which will use the *--detail* switch value or the value in your *logwatch.conf*), then you can define that level here.  By default, it appears like this in the service configuration file:
 other services (which will use the *--detail* switch value or the value in your
 *logwatch.conf*), then you can define that level here.  By default, it appears
 like this in the service configuration file:
 ```Ini
 ...
@@ -127,8 +115,7 @@ like this in the service configuration file:
 # Detail = 0
 ```
-Simply change it to the value you want enforced.  For example, here I'm setting
+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.
 it to output level 5 regardless of whatever settings everything else is using.
 ```Ini
 # Override the detail level for this service
@@ -136,76 +123,60 @@ it to output level 5 regardless of whatever settings everything else is using.
 Detail = 5
 ```
-## Service script (/etc/logwatch/scripts/services/cfddns)
+## Service script
-Logwatch calls any script with a name that **matches the service name**.  You'll
+> This file is located within the repo at */etc/logwatch/scripts/services/cfddns*
-notice that I just named everything *cfddns* to keep things simple.  You can
+
-change this to whatever you want, however.  If you changed the service name to
+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
 *"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
+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.
 file as standard input (STDIN) for the script and then takes whatever is output
 (STDOUT) from the script to assemble into it's 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
-    **This is the recommended reporting level.**  It does not take up much space
+    - Total errors
-    and is quick to read.  If you see successful updates match the number of
+    
-    needed updates and no errors logged, then things are working properly.  If
+  - **This is the recommended reporting level.**  It does not take up much space and is quick to read.  If you see successful updates and/or up-to-date numbers match what you expect and no errors logged, then you can assume things are working properly. If the numbers aren’t right or you see errors/warnings, then you can investigate the situation by consulting the actual logs or increasing the detail level in logwatch.
-    you notice errors, you should consult the full logs.
+  
  - 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
+  - This uses the data which is summarized by Level 0 but outputs the *actual messages* in the log file.  For example, you will see the actual text of the errors logged instead of just a total number of errors.  This level of reporting is useful when *initially* monitoring the script's operation since you can see the text of any generated errors.
-    errors logged instead of just a total number of errors.  This level of
+  - Levels 1, 2, 3 & 4 are identical so pick your favourite number.
-    reporting is useful when *initially* monitoring the script's operation since
+- **Level 5: Verbose output**
-    you can see the actual text of any generated errors.
+  - 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.
- **Level 5: Verbose (debugging) output**
+  - 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.
-  - Like the previous level, this outputs the actual messages found in the log
+  - 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.
-    file.  However, it also includes *[INFO] tags* which contain logged messages
+  - This is *not* recommended for day-to-day or routine reports.
    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
    more of your time to review. You should not use this level day-to-day.**
 - **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 Logwatch line-by-line.  This is really only useful during debugging or dealing with serious issues where you do not have access to the actual log file. While this is an exact ‘echo’ of the log file, it likely will not be colour-coded which makes it harder to review.
-    to dump the entire log file out to Logwatch line-by-line.  This is useful
+  - **Use this detail level only when you need to see the entire log file and cannot otherwise access the log file.**
-    only if you are debugging an issue and cannot get access to the actual raw
+  - Depending on how your logwatch treats this log dump, you may see gibberish control codes like *\e[0m;]*. If this is the case, run the script with the `--no-colour` or `--nc` option to remove ANSI colour formatting.
    log file itself.  The actual log file is colour-coded which makes it much
    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/sqfullstampanywhere*
-This is basically a modified version of the '*applyeurodate*' script that comes
+This is basically a modified version of the '*applyeurodate*' script that comes with Logwatch.  It had to be modified to search within [square brackets] and to accept characters coming before the stamp (i.e. ANSI colour codes).  If you change the '**stamp**' variable in the updater script to update the timestamp to your liking (which to totally fine!) then you'll probably have to update this file.  There are two lines you need to modify to suit your new '**stamp**' variable.
-with Logwatch.  It had to be modified to search within [square brackets] and to
+
-accept characters coming before the stamp (i.e. ANSI colour codes).  If you
+> This entire section is only applicable if you are a very curious person or if you change the hard-coded ‘stamp’ function in the script. If you did not make any changes and you like a little mystery in your life, you can safely skip this entire section.
 change the '**stamp**' variable in the updater script to update the timestamp to
 your liking (which to totally fine!) then you'll probably have to update this
 file.  There are two lines you need to modify to suit your new '**stamp**'
 variable.
 ### 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 set up to look for the format '*year-month-date hour:minute:second*'.  Note, we don't care about brackets or anything here, we're just defining the format of the date/time stamp.
 says, search for the date stamp.  I have it set up to look for the format
 '*year-month-date hour:minute:second*'.  Note, we don't care about brackets or
 anything here, we're just defining the format of the date/time stamp.
 ```Perl
 ...
@@ -213,9 +184,7 @@ $SearchDate = TimeFilter('%Y-%m-%d %H:%M:%S');
 ...
 ```
-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*' (ex: '*[09/27/2018 18:38]*') then you'd update the **$SearchDate** variable as follows (note: no mention of the square brackets!):
 hour:minute*' (ex: '*[09/27/2018 18:38]*') then you'd update the **$SearchDate**
 variable as follows (note: no mention of the square brackets!):
 ```Perl
 ...
@@ -225,8 +194,7 @@ $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 date stamp, this specification looks like:
 '*$SearchDate*'.  For the default datestamp, this specification looks like:
 ```Perl
 ...
@@ -234,12 +202,7 @@ if ($ThisLine =~ m/\[$SearchDate\] /o) {
 ...
 ```
-The REGEX appears between '*m/*' and '*/o*'.  In this case, it searches for
+The REGEX appears between '*m/*' and '*/o*'.  In this case, it searches for '*$SearchDate*' inside [square brackets] appearing anywhere on the line.  This is because ANSI colour-codes often appear before the date stamp in the default log file.  If you have modified this so that your date stamp appears at the beginning of the line and in the example format in the section above (using slashes instead of dashes) then you'd rewrite this REGEX as follows:
 '*$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
 ...
@@ -265,16 +228,14 @@ 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 command (assuming you kept default names for everything):
 locally on your screen with the following command (assuming you kept default
 names for everything):
 ```Bash
 # Summary output, entire duration of log file
 logwatch --service cfddns --output stdout --format text --range all --detail 0
 # Minimal detail, yesterday only
-logwatch --service cfddns --output stdout --format text --range yesterday --detail 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
@@ -282,7 +243,4 @@ 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 please do it!  Otherwise, I hope this made sense and helped you integrate the updater script with Logwatch for easy monitoring :-)
 script file used for Logwatch then please do it!  Otherwise, I hope this made
 sense and helped you integrate the updater script with Logwatch for easy
 monitoring :-)
@@ -4,7 +4,7 @@
 # $Id$
 #############################################################################
 # Log: CloudFlare updater script (cfddns)
-# Revision 1.0  2018/09/26
+# Revision 2.1  2021/05/08
 # 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 =~ /ERR: Unable to update IP address/) {
            $summaryFailedUpdate++;
        }
        elsif ($ThisLine =~ /ERROR: /) {
            $summaryErr++;
        }
-        elsif ($ThisLine =~ /up-to-date./) {
+        elsif ($ThisLine =~ /WARN: Cannot find existing record/) {
-            $summaryStatusUpToDate++;
+            $summaryInvalidHost++;
        }
-        elsif ($ThisLine =~ /needs updating.../) {
+        elsif ($ThisLine =~ /WARNING: /){
-            $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,59 @@ 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 =~ /ERROR: /) {
            print $ThisLine;
        }
-        elsif ($ThisLine =~ /\-- \[SUCCESS\] /) {
+        elsif ($ThisLine =~ /CF-ERR: /) {
            print $ThisLine;
        }
-        elsif ($ThisLine =~ /\-- \[INFO\] /) {
+        elsif ($ThisLine =~ /WARN: /) {
            print $ThisLine;
        }
        elsif ($ThisLine =~ /WARNING: /) {
            print $ThisLine;
        }
        elsif ($ThisLine =~ /SUCCESS: /) {
            print $ThisLine;
        }
        elsif ($ThisLine =~ /already up-to-date/) {
            print $ThisLine;
        }
    }
 }
-### Any level 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 +141,4 @@ exit (0);
 # mode: perl
 # perl-indent-level: 3
 # indent-tabs-mode: nil
-# End:
+# End:
@@ -0,0 +1,161 @@
 #!/bin/sh
 getTimeStamp() {
  (date -u +"%Y-%m-%dT%H:%M:%SZ")
 }
 getHostname() {
  (hostname -s)
 }
 lowercase() {
  echo "$1" | tr '[:upper:]' '[:lower:]'
 }
 uppercase() {
  echo "$1" | tr '[:lower:]' '[:upper:]'
 }
 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
 }
 # 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:-999}"
 }
 # $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
  PROPS="$(
    jq --null-input \
      --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:-999}" \
      '{"timestamp":$timestamp, "hostname":$hostname, "programName":$pName, "pid":$pid, "level":$level, "status":$status, "message":$message, "operation":$operation, "code":$code}' \
  )"
  echo "$PROPS" | jq "."
  return
 }
 # $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:-999}
 end
  return
 }
 LOG_PROGRAM_NAME="cfddns"
 if [ "$1" = "text" ]; then
  writePlainTextLog # this will do nothing
  writePlainTextLog "Testing plain-text logging output" # this will also do nothing
  writePlainTextLog "Informational plain-text log message" "information" "ok" # info message
  writePlainTextLog "Plain-text message forced to info level" "whoops" "ok" # level translated to default
  writePlainTextLog "Warning! This is plain-text." "warning" "flagged" # warning level with 'flagged' status
  writePlainTextLog "Error sample! This is plain-text." "err" "error" # error level message
  writePlainTextLog "Unable to continue, critical failure. (This is plain-text)" "fatal" "exit" "startup" "2" # critical level error with operation and error code
 elif [ "$1" = "json" ]; then
  writeJsonLog # this will do nothing
  writeJsonLog "This is a test message" # this will also do nothing
  writeJsonLog "Informational JSON log message" "information" "ok" # info message
  writeJsonLog "JSON message forced to info level" "whoops" "ok" # level translated to default
  writeJsonLog "Warning! This is JSON." "warning" "flagged" # warning level with 'flagged' status
  writeJsonLog "Error sample! This is JSON." "err" "error" # error level message
  writeJsonLog "Unable to continue, critical failure. (This is JSON)" "fatal" "exit" "startup" "2" # critical level error with operation and error code
 elif [ "$1" = "journal" ]; then
  writeJournalDLog # this will do nothing
  writeJournalDLog "This is a test message" # this will also do nothing
  writeJournalDLog "Informational JOURNALD log message" "information" "ok" # info message
  writeJournalDLog "JOURNALD message forced to info level" "whoops" "ok" # level translated to default
  writeJournalDLog "Warning! This is a JOURNALD message." "warning" "flagged" # warning level with 'flagged' status
  writeJournalDLog "Error sample! This is a JOURNALD." "err" "error" # error level message
  writeJournalDLog "Unable to continue, critical failure. (This is JOURNALD message)" "fatal" "exit" "startup" "2" # critical level error with operation and error code
 else
  printf "\nPlease specify either 'text', 'json', or 'journal' after the script name. Exiting.\n\n"
  exit 1
 fi
 exit 0
Author	SHA1	Message	Date
asif	08a5c823d5	refactor(log): Use CLEF for JSON logs Use Compact Log Event Format (CLEF) for JSON logs along with custom properties.	2026-07-24 04:41:23 -06:00
asif	eafba0d67d	perf(log): Use compact JSON for logging	2026-07-24 04:36:26 -06:00
asif	e25bd9fb4d	feat(func): Add JSON logging func Update central logging steering function to reference this new JSON logging backend function.	2026-07-24 04:02:21 -06:00
asif	bff59f5c1f	chore(ide): Save custom dictionary	2026-07-24 04:01:35 -06:00
asif	539b80e4ec	feat(script): Use HTTPS ip discovery links	2026-07-24 03:52:30 -06:00
asif	58520b3567	refactor(log): Remove redundant debug log handling Debug-level logging is handled by the central logging steering function. Remove redundant code in backend plaint-text logging function.	2026-07-24 03:28:49 -06:00
asif	51bd6160f3	feat(func): Use centralized log func Create single logging function that can be called and then forwards the request to the appropriate logging backend function for completion.	2026-07-24 03:25:29 -06:00
asif	8d3489ba00	fix(vars): Add missing LOG_PROGRAM_NAME var	2026-07-24 02:48:26 -06:00
asif	3b97d112ad	feat(log): Add CF-ERR to operation attr Update 'listCFErrors' function so that 'CF-ERR' is appended to the 'operation' field of the error log.	2026-07-24 02:44:22 -06:00
asif	1506d77ee9	refactor(func): Remove no-colourize functions	2026-07-24 02:17:06 -06:00
asif	e4e967e227	feat(params): Cleanup journald pre-req fail msg	2026-07-24 02:16:08 -06:00
asif	aebf8042e3	feat(params): Use badparam func to manage logging	2026-07-24 02:15:14 -06:00
asif	02e3e8d391	feat(log): Log parameter errors	2026-07-24 01:59:10 -06:00
asif	95682314de	fix(params): Fix pre-flight console log dedup	2026-07-24 01:46:51 -06:00
asif	5bc3e7d587	feat(log): Enable debug level filtering	2026-07-24 01:18:16 -06:00
asif	fca36ac119	feat(params): Add debug logging toggle	2026-07-24 01:13:40 -06:00
asif	2b0128d0c1	fix(log): Prevent preflight duplicate logging Prevent writing preflight error messages to the console twice when using console logging mode.	2026-07-24 01:08:54 -06:00
asif	c792ec8a0a	feat(params): Add log type, fmt params Add log type and format parameters. Update defaults. Update help script.	2026-07-24 01:03:28 -06:00
asif	1732de343d	refactor(func): Remove unused functions Remvoe the logging functions replaced by the new structured implementation.	2026-07-23 23:22:17 -06:00
asif	51b2b455a2	feat(log): Use plain-text logging for all messages Convert all logging output to plain-text structured messages using new function.	2026-07-23 23:16:12 -06:00
asif	f8f3bf1539	refactor(func): Change default err code to 0	2026-07-23 22:17:15 -06:00
asif	f8908d7830	feat(func): Write modified syslog fmt msg Take input parameters and generate a modified syslog-style log entry.	2026-07-23 21:59:58 -06:00
asif	8a5a72e15a	feat(func): Convert to uniform log levels Take input text with various references to log levels and return a standardized uppercase log level name.	2026-07-23 21:57:30 -06:00
asif	1da49b06db	feat(func): Convert text ucase, lcase	2026-07-23 21:56:19 -06:00
asif	1336c8e63b	feat(func): Retrieve machine host name	2026-07-23 21:55:56 -06:00
asif	450733a8d5	feat(func): Generate ISO-8601 timestamp	2026-07-23 21:55:25 -06:00
asif	92e69d1b85	fix(logger): Fix JournalD log levels Log levels were reversed in the translation function.	2026-07-23 00:20:30 -06:00
asif	00ea88780d	feat(logger): Echo vs return values from Translate func	2026-07-23 00:18:03 -06:00
asif	d9aa8973a3	fix(logger): Perform cmd subst outside heredoc Perform function and command value substitution outside the heredoc forwarded to logger for JournalD entries.	2026-07-23 00:17:42 -06:00
asif	ec75cffbf1	fix(logger): Ensure log levels are lcase before standardization	2026-07-23 00:16:19 -06:00
asif	b8fb744623	fix(logger): Fix error in json logger Assignment to 'pid' argument was incorrect.	2026-07-22 23:50:33 -06:00
asif	d0b2c781bf	feat(logger): Update test cases Update JSON and JOURNALD tests to match text tests and use new functions.	2026-07-22 23:48:16 -06:00
asif	c4d28d1f8c	fix(logger): Fix default subst Default parameter substitution in all functions was incorrect.	2026-07-22 23:44:08 -06:00
asif	f085838781	feat(logger): Add test with operation, error code	2026-07-22 23:42:52 -06:00
asif	4a6c339a07	fix(logger): Fix default subst Default variable substitution in plain-text function was incorrect.	2026-07-22 23:42:33 -06:00
asif	c94f12e976	fix(logger): Fix error in uppercase func 'upper' and 'lower' translate strings were not supplied separately.	2026-07-22 23:38:45 -06:00
asif	5443612381	feat(logger): Add plain-text test output	2026-07-22 23:35:08 -06:00
asif	df144a5211	fix(logger): Remove errant 'fi' statements Remove 'fi' statements left over from previous logic checks.	2026-07-22 23:33:49 -06:00
asif	04811805c3	feat(logger): Remove unused global vars	2026-07-22 23:25:28 -06:00
asif	aa446c00e6	feat(logger): Update journal logging function Use new standardized format fields.	2026-07-22 23:24:52 -06:00
asif	56a5ad59fe	refactor(logger): Rename writeJournalLog function Rename from 'writeJournalLog' to 'writeJournalDLog' for specificity.	2026-07-22 23:19:51 -06:00
asif	ce1ab86d22	fix(logger): Fix JSON logger Level and status were swapped. JSON output was missing new prefix information (timestamp, hostname, etc.)	2026-07-22 23:18:36 -06:00
asif	cae57ccf6b	feat(logger): Use standardized log levels for JSON	2026-07-22 23:15:44 -06:00
asif	0fcd0d9c13	refactor(logger): Use standardized log levels for plain-text	2026-07-22 23:15:11 -06:00
asif	e411a35b93	feat(logger): Add log level translator functions	2026-07-22 23:13:58 -06:00
asif	0e787be456	feat(logger): Add lowercase function	2026-07-22 23:06:34 -06:00
asif	17c33d237f	fix(logger): Ensure plain-text status is uppercase	2026-07-22 22:54:25 -06:00
asif	5b55ac95a3	feat(logger): Update JSON logger Require message, level, and status. Reorganize JSON output to mirror modified syslog-style structure.	2026-07-22 22:53:38 -06:00
asif	f4dc8f44b1	feat(logger): Handle plain-text insufficient information Return without logging if message, level and/or status is not supplied.	2026-07-22 22:49:13 -06:00
asif	3792881529	feature(logger): Add plain-text logger function	2026-07-22 22:42:49 -06:00
asif	c1f54a619c	refactor(logger): Use ISO8601 timestamp	2026-07-22 21:52:53 -06:00
asif	4c997a6b7d	feature [logger] add status logging param	2026-07-22 18:34:14 -06:00
asif	1824d9f139	feat(logger): Framework test file	2026-07-22 17:33:46 -06:00
asif	50b4cf105f	chore(ide): Update IDE settings	2026-07-22 17:33:36 -06:00
asif	1e3b545a23	chore(ide): JetBrains IDE configuration files	2026-07-19 23:37:13 -06:00
asif	380509c966	chore(git): Update git control files	2026-07-19 23:36:58 -06:00
asif	71da487aa8	style(fmt): Reformat shell script	2026-07-19 23:33:56 -06:00
asif	3be6eaee0c	[preflight] Add check for logger dependency 'logger' is required to facilitate logging to the journaling system.	2026-07-19 18:52:34 -06:00
asif	5c6c8ec4ea	[params] Create journal logging switch Create boolean variable to store journal logging preference. Set to 'false' by default. Add parameter to activate this preference. Update help to include this new parameter.	2026-07-19 18:49:34 -06:00
asif	c7297a512c	[version] Update version, modified date	2026-07-19 15:44:40 -06:00
Asif Bacchus	fddb406717	fix error in hyperlink	2021-05-10 03:22:22 -06:00
Asif Bacchus	4ec190af47	update readme	2021-05-10 03:18:49 -06:00
Asif Bacchus	57ce2d1ac3	fixed headings so TOC links work	2021-05-10 03:09:30 -06:00
Asif Bacchus	1ffd374a4f	fix: set TERM for tput if not set - stop warning messages in syslog from systemd invocation	2021-05-10 02:55:16 -06:00
Asif Bacchus	0cd84a3711	update logwatch readme	2021-05-09 23:43:41 -06:00
Asif Bacchus	d8fe395a19	update readme files	2021-05-09 14:39:28 -06:00
Asif Bacchus	ac4cf940ff	refactor(SAMPLE): remove un-needed email address	2021-05-09 10:44:21 -06:00
Asif Bacchus	dc13e1d412	refactor(LOGWATCH): use new log tags - update to reference new log tags - adjust count to separate tally messages - add CF-ERR tag reports - re-add level 5 reporting detail	2021-05-09 10:43:05 -06:00
Asif Bacchus	e344b027f9	refactor: remove err label on code 99	2021-05-09 10:28:17 -06:00
Asif Bacchus	8801e55e30	style: fix typo, invalid hosts warning summary	2021-05-09 10:24:15 -06:00
Asif Bacchus	b05192a613	fix: wrong pipeline variable ref in writelog	2021-05-09 09:49:47 -06:00
Asif Bacchus	d796bf6f63	fix: wrong variable referenced for list to update	2021-05-09 09:47:41 -06:00
Asif Bacchus	db8a615d36	refactor: use function to write to log - much more consistent - one place to change all entries	2021-05-09 09:46:15 -06:00
Asif Bacchus	31eb503245	style: change 'domain' to 'host' terminology is more correct and less potentially confusing	2021-05-09 08:48:56 -06:00
Asif Bacchus	3f9d164285	style: rename functions to clear spellcheck	2021-05-09 08:45:24 -06:00
Asif Bacchus	39f5445c28	perf: simpler iteration condition checking - less complex conditions - easier code to understand - cleans up extraneous delimiters - skips null entries immediately	2021-05-09 08:44:47 -06:00
Asif Bacchus	220263c1f9	refactor: change log tags - separate tags for summary vs individual messages for accurate logwatch counting - update code 99 exit to match other errors - change CF error tags to match new format	2021-05-09 07:08:44 -06:00
Asif Bacchus	fe0f9caef1	feature: process multiple CF API errors - handle multiple CF API errors properly by grouping and reporting - update error messages - unify CF error tags in log to CF-ERROR	2021-05-09 06:49:49 -06:00
Asif Bacchus	d9600c822f	style: alphabetize functions	2021-05-09 06:39:55 -06:00
Asif Bacchus	5569bbc535	refactor: remove cfEmail - authorized email not required by CF when using bearer token	2021-05-09 04:35:46 -06:00
Asif Bacchus	f4f3c89e5e	refactor: reduce nesting, update err codes - detect curl vs CF API errors separately - error 25 changed to error 3 (curl/network) - error 25 reservedfor CF API errors - add CF error messages to all err 25s - change error 98 (updates) to error 26 - remove error code for exit with warning - add CF error messages on update failures - drastically reduce if/else nesting	2021-05-09 04:33:41 -06:00
Asif Bacchus	a7064805c3	style: log params in default colour vs magenta	2021-05-09 03:58:35 -06:00
Asif Bacchus	c1c7fd5149	style: correct spelling of Cloudflare	2021-05-09 00:42:53 -06:00
Asif Bacchus	d9224b5791	refactor(LOGWATCH): match new script structure - update keyword filters - update reporting detail levels - better targeting of useful information at summary detail level	2021-05-08 04:40:31 -06:00
Asif Bacchus	2805f560d7	docs: fix typos in comments, help, etc	2021-05-08 04:24:26 -06:00
Asif Bacchus	e7935dbd99	refactor(SYSTEMD): update service file switches	2021-05-08 04:06:04 -06:00