docs(script): Update embedded script examples

Proofreading. Add examples of using new log backends and formats.

.idea/misc.xml

@@ -2,7 +2,7 @@
 <project version="4">
   <component name="com.itcodebox.notebooks.projectservice.ProjectUIState">
     <option name="selectedNotebookId" value="1" />
-    <option name="selectedChapterId" value="1" />
+    <option name="selectedChapterId" value="2" />
-    <option name="selectedNoteId" value="1" />
+    <option name="selectedNoteId" value="2" />
   </component>
 </project>

cfddns.sh

@@ -113,6 +113,56 @@ standardizeLogLevels() {
   esac
 }
 
+translateLogLevelsToJournalD() {
+  LEVEL_TO_TRANSLATE="$(standardizeLogLevels "$1")"
+  case "$LEVEL_TO_TRANSLATE" in
+  "CRIT")
+    echo 2
+    ;;
+  "ERR")
+    echo 3
+    ;;
+  "WARN")
+    echo 4
+    ;;
+  "INFO")
+    echo 6
+    ;;
+  "DEBUG")
+    echo 7
+    ;;
+  *)
+    echo 6
+  esac
+}
+
+# $1: message, $2: level, $3: status, [$4: operation], [$5: code]
+writeJournalDLog() {
+  # not enough information to generate a meaningful log message
+  if [ -z "$1" ] || [ $# -lt 3 ]; then
+    return
+  fi
+
+  J_TIMESTAMP="$(getTimeStamp)"
+  J_PID="$$"
+  J_PRIO="$(translateLogLevelsToJournalD "$2")"
+  J_STAT="$(uppercase "$3")"
+
+  logger --journald <<end
+SYSLOG_TIMESTAMP=${J_TIMESTAMP}
+SYSLOG_FACILITY=3
+SYSLOG_IDENTIFIER=${LOG_PROGRAM_NAME}
+SYSLOG_PID=${J_PID}
+PRIORITY=${J_PRIO}
+STATUS=${J_STAT}
+MESSAGE=$1
+OPERATION=${4:-UNSPECIFIED}
+ERRNO=${5:-0}
+end
+
+  return
+}
+
 # $1: message, $2: level, $3: status, [$4: operation], [$5: code]
 writeJsonLog() {
   # not enough information to generate a meaningful log message
@@ -157,9 +207,9 @@ writeLog() {
   PT_LOG_LEVEL="$(standardizeLogLevels "$2")"
   ([ "$logDebug" -eq 0 ] && [ "$PT_LOG_LEVEL" = "DEBUG" ]) && return
 
-  ([ "$logToJournal" -eq 1 ]) && return # TODO: replace this with function when implemented
+  ([ "$logToJournal" -eq 1 ]) && writeJournalDLog "$@" && return
-  ([ "$useJsonLogFmt" -eq 1 ]) && writeJsonLog "$@"
+  ([ "$useJsonLogFmt" -eq 1 ]) && writeJsonLog "$@" && return
-  ([ "$useSyslogLogFmt" -eq 1 ]) && writePlainTextLog "$@"
+  ([ "$useSyslogLogFmt" -eq 1 ]) && writePlainTextLog "$@" && return
 }
 
 scriptExamples() {
@@ -169,22 +219,31 @@ scriptExamples() {
   textBlock "${magenta}--- usage examples ---${norm}"
   newline
   textBlockSwitches "${scriptName} -r myserver.mydomain.net"
-  textBlock "Update Cloudflare DNS records for myserver.mydomain.net with the auto-detected public IP4 address. Credentials will be expected in the default location and the log will be written in the default location also."
+  textBlock "Update Cloudflare DNS records for 'myserver.mydomain.net' with the auto-detected public IP4 address. Credentials will be expected in the default location. The log will be written to the default location in the default JSON format."
   newline
   textBlockSwitches "${scriptName} -r myserver.mydomain.net -6"
   textBlock "Same as above, but update AAAA host records with the auto-detected public IP6 address."
   newline
-  textBlockSwitches "${scriptName} -r myserver.mydomain.net,myserver2.mydomain.net -l /var/log/cfddns.log --nc"
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net --fmt-syslog"
-  textBlock "Update DNS entries for both listed hosts using auto-detected IP4 address. Write a non-coloured log to '/var/log/cfddns.log'."
+  textBlock "Same as the first example, but the log file will be written in plain-text format instead of JSON."
+  newline
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net --log-console --fmt-syslog"
+  textBlock "Same as the first example, but the log will be written to the console (stdout) in plain-text instead of a log file."
+  newline
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net --log-journal"
+  textBlock "Same as the first example, but the log will be written to the journal (journald) instead of a log file. A tag of 'CFDDNS' is automatically applied to make filtering easier."
+  newline
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net,myserver2.mydomain.net -l /var/log/cfddns.log"
+  textBlock "Update DNS entries for both listed hosts using the auto-detected IP4 address. Write the log file to the specified location."
   newline
   textBlockSwitches "${scriptName} -r myserver.mydomain.net,myserver2.mydomain.net -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 the log to the location specified."
   newline
-  textBlockSwitches "${scriptName} -r myserver.mydomain.net -c /root/cloudflare.creds -l /var/log/cfddns.log --ip 1.2.3.4"
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net --ip 1.2.3.4 -c /root/cloudflare.creds -l /var/log/cfddns.log --fmt-syslog"
-  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 'myserver.mydomain.net' with the *specified* IP address. Read the Cloudflare credentials file from the specified location. Save a plain-text (syslog-style) log in the specified location."
   newline
-  textBlockSwitches "${scriptName} -r myserver.mydomain.net -c /root/cloudflare.creds -l /var/log/cfddns.log -6 -i fd21:7a62:2737:9c3a::a151"
+  textBlockSwitches "${scriptName} -r myserver.mydomain.net -6 -i fd21:7a62:2737:9c3a::a151 -c /root/cloudflare.creds -l /var/log/cfddns.log --fmt-syslog"
-  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 an example of how you run the script once for IP4 and again for IP6."
   exit 0
 }