doc(bkgpslog): Update usage

[EVA-2020-02.git] / exec / bkgpslog

diff --git a/exec/bkgpslog b/exec/bkgpslog
index 9210e159407a5a7917fb7ee9da7ac3a5ae666875..2eed9ba7a7755b61d85348d75a04ab64687d3bc1 100755 (executable)
--- a/exec/bkgpslog
+++ b/exec/bkgpslog
@@ -2,18 +2,19 @@
 
 # Desc: Records gps data until midnight
 # Author: Steven Baltakatei Sandoval; License: GPLv3+
 
 # Desc: Records gps data until midnight
 # Author: Steven Baltakatei Sandoval; License: GPLv3+

-# Usage: bkgpslog --output [output dir]
+# Usage: bkgpslog -o [output dir]

 
 #==BEGIN Define script parameters==
 ## Logging Behavior parameters
 BUFFER_TTL="60"; # time between file writes
 SCRIPT_TTL="day"; # (day|hour)
 
 #==BEGIN Define script parameters==
 ## Logging Behavior parameters
 BUFFER_TTL="60"; # time between file writes
 SCRIPT_TTL="day"; # (day|hour)

-TZ="UTC"; export TZ; # Default time zone; overridden by '--time-zone=[str]' option
+#### TZ="UTC"; export TZ; # Default time zone; overridden by '--time-zone=[str]' option
+DIR_TMP_DEFAULT="/dev/shm"; # Default parent of working directory

 
 

-PATH="$HOME/.local/bin:$PATH"   # Add "$(systemd-path user-binaries)" path in case apps saved there
-SCRIPT_HOSTNAME=$(hostname)     # Save hostname of system running this script.
-SCRIPT_VERSION="bkgpslog 0.1.0" # Define version of script.
-DIR_TMP="/dev/shm/$(timeStart)..bkgpslog"     # Define working directory for temproary files
+SCRIPT_TIME_START=$(date +%Y%m%dT%H%M%S.%N);
+PATH="$HOME/.local/bin:$PATH";   # Add "$(systemd-path user-binaries)" path in case apps saved there
+SCRIPT_HOSTNAME=$(hostname);     # Save hostname of system running this script.
+SCRIPT_VERSION="bkgpslog 0.1.0"; # Define version of script.

 
 declare -Ag appRollCall # Associative array for storing app status
 declare -Ag fileRollCall # Associative array for storing file status
 
 declare -Ag appRollCall # Associative array for storing app status
 declare -Ag fileRollCall # Associative array for storing file status


@@ -21,6 +22,9 @@ declare -Ag dirRollCall # Associative array for storing dir status
 declare -a recPubKeys # for processArguments function
 declare recipients # for main function
 
 declare -a recPubKeys # for processArguments function
 declare recipients # for main function
 

+## Initialize variables
+OPTION_VERBOSE=""; OPTION_ENCRYPT=""; OPTION_COMPRESS=""; OPTION_TMPDIR="";
+

 #===BEGIN Declare local script functions===
 checkapp() {
     # Desc: If arg is a command, save result in assoc array 'appRollCall'
 #===BEGIN Declare local script functions===
 checkapp() {
     # Desc: If arg is a command, save result in assoc array 'appRollCall'


@@ -150,7 +154,8 @@ showUsage() {
     echoerr "            Encrypt output."
     echoerr
     echoerr "    -r, --recipient [ pubkey string ]"
     echoerr "            Encrypt output."
     echoerr
     echoerr "    -r, --recipient [ pubkey string ]"

-    echoerr "            Specify recipient."
+    echoerr "            Specify recipient. May be age or ssh pubkey."
+    echoerr "            See https://github.com/FiloSottile/age"

     echoerr
     echoerr "    -o, --output [ directory ]"
     echoerr "            Specify output directory to save logs."
     echoerr
     echoerr "    -o, --output [ directory ]"
     echoerr "            Specify output directory to save logs."


@@ -158,6 +163,13 @@ showUsage() {
     echoerr "    -c, --compress"
     echoerr "            Compress output with gzip (before encryption if enabled)."
     echoerr
     echoerr "    -c, --compress"
     echoerr "            Compress output with gzip (before encryption if enabled)."
     echoerr

+    echoerr "    -z, --time-zone"
+    echoerr "            Specify time zone. (ex: \"America/New_York\")"
+    echoerr
+    echoerr "    -t, --temp-dir"
+    echoerr "            Specify parent directory for temporary working directory."
+    echoerr "            Default: \"/dev/shm\""
+    echoerr

     echoerr "EXAMPLE: (bash script lines)"
     echoerr "/bin/bash bkgpslog -e -c \\"
     echoerr "-r age1mrmfnwhtlprn4jquex0ukmwcm7y2nxlphuzgsgv8ew2k9mewy3rs8u7su5 \\"
     echoerr "EXAMPLE: (bash script lines)"
     echoerr "/bin/bash bkgpslog -e -c \\"
     echoerr "-r age1mrmfnwhtlprn4jquex0ukmwcm7y2nxlphuzgsgv8ew2k9mewy3rs8u7su5 \\"


@@ -203,6 +215,7 @@ processArguments() {
                recPubKeys+=("$2"); vbm "pubkey added:""$2"; shift;;
            -c | --compress) OPTION_COMPRESS="true"; vbm "DEBUG:Compressed output mode enabled.";;
            -z | --time-zone) try setTimeZoneEV "$1";;
                recPubKeys+=("$2"); vbm "pubkey added:""$2"; shift;;
            -c | --compress) OPTION_COMPRESS="true"; vbm "DEBUG:Compressed output mode enabled.";;
            -z | --time-zone) try setTimeZoneEV "$1";;

+           -t | --temp-dir) OPTION_TMPDIR="true" && TMP_DIR_PRIORITY="$1";;

            *) echoerr "ERROR: Unrecognized argument."; exit 1;; # Handle unrecognized options.
        esac
        shift
            *) echoerr "ERROR: Unrecognized argument."; exit 1;; # Handle unrecognized options.
        esac
        shift


@@ -601,7 +614,32 @@ setScriptTTL() {
 } # Seconds until next (day|hour).
 main() {
     processArguments "$@" # Process arguments.
 } # Seconds until next (day|hour).
 main() {
     processArguments "$@" # Process arguments.

+    
+    # Determine working directory
+    ## Set DIR_TMP_PARENT to user-specified value if specified
+    if [[ "$OPTION_TMPDIR" = "true" ]]; then
+           if [[ -d "$TMP_DIR_PRIORITY" ]]; then
+           DIR_TMP_PARENT="$OPTION_TMPDIR"; 
+       else
+           yell "WARNING:Specified temporary working directory not valid:$OPTION_TMP_DIR";
+           exit 1;
+       fi
+    fi

 
 

+    ## Set DIR_TMP_PARENT to default or fallback otherwise
+    if [[ -d "$DIR_TMP_DEFAULT" ]]; then
+       DIR_TMP_PARENT="$DIR_TMP_DEFAULT";
+    elif [[ -d /tmp ]]; then
+       yell "WARNING:/dev/shm not available. Falling back to /tmp .";
+       DIR_TMP_PARENT="/tmp";
+    else
+       yell "ERROR:No valid working directory available. Exiting.";
+       exit 1;
+    fi
+
+    ## Set DIR_TMP using DIR_TMP_PARENT and nonce (SCRIPT_TIME_START)
+    DIR_TMP="$DIR_TMP_PARENT"/"$SCRIPT_TIME_START""..bkgpslog"; # Note: removed at end of main().
+    

     # Set output encryption and compression option strings
     if [[ "$OPTION_ENCRYPT" = "true" ]]; then # Check if encryption option active.
        if checkapp age; then # Check that age is available.
     # Set output encryption and compression option strings
     if [[ "$OPTION_ENCRYPT" = "true" ]]; then # Check if encryption option active.
        if checkapp age; then # Check that age is available.


@@ -661,7 +699,7 @@ main() {
     ## Write bkgpslog version to DIR_TMP/VERSION
     echo "$0"" Version:""$SCRIPT_VERSION" >> "$DIR_TMP/VERSION" && vbm "DEBUG:VERSION created."
     ## Create empty tar archive at PATHOUT_TAR
     ## Write bkgpslog version to DIR_TMP/VERSION
     echo "$0"" Version:""$SCRIPT_VERSION" >> "$DIR_TMP/VERSION" && vbm "DEBUG:VERSION created."
     ## Create empty tar archive at PATHOUT_TAR

-    try tar --create --directory="$DIR_TMP" --file="$PATHOUT_TAR" --files-from=/dev/null && vbm "DEBUG:bufferRam.tar created."
+    try tar --create --directory="$DIR_TMP" --file="$PATHOUT_TAR" --files-from=/dev/null && vbm "DEBUG:""$PATHOUT_TAR"" created."

     ## Append VERSION file to PATHOUT_TAR
     try tar --append --directory="$DIR_TMP" --file="$PATHOUT_TAR" "VERSION" && vbm "DEBUG:VERSION added to $PATHOUT_TAR"
     
     ## Append VERSION file to PATHOUT_TAR
     try tar --append --directory="$DIR_TMP" --file="$PATHOUT_TAR" "VERSION" && vbm "DEBUG:VERSION added to $PATHOUT_TAR"
     


@@ -671,7 +709,7 @@ main() {
     while [[ "$SECONDS" -lt "$scriptTTL" ]]; do
        # Determine file paths (time is start of buffer period)
        FILEOUT_BASENAME="$timeStart""--""$bufferTTL_STR""..""$SCRIPT_HOSTNAME""_location" ; # ISO-8601 YYYYmmddTHHMMSS+zzP[$bufferTTL]S
     while [[ "$SECONDS" -lt "$scriptTTL" ]]; do
        # Determine file paths (time is start of buffer period)
        FILEOUT_BASENAME="$timeStart""--""$bufferTTL_STR""..""$SCRIPT_HOSTNAME""_location" ; # ISO-8601 YYYYmmddTHHMMSS+zzP[$bufferTTL]S

-       ## Files saved to tmpfs memory (DIR_TMP)
+       ## Files saved to DIR_TMP

        PATHOUT_NMEA="$DIR_TMP"/"$FILEOUT_BASENAME".nmea"$CMD_COMPRESS_SUFFIX""$CMD_ENCRYPT_SUFFIX" ; 
        PATHOUT_GPX="$DIR_TMP"/"$FILEOUT_BASENAME".gpx"$CMD_COMPRESS_SUFFIX""$CMD_ENCRYPT_SUFFIX" ;
        PATHOUT_KML="$DIR_TMP"/"$FILEOUT_BASENAME".kml"$CMD_COMPRESS_SUFFIX""$CMD_ENCRYPT_SUFFIX" ;
        PATHOUT_NMEA="$DIR_TMP"/"$FILEOUT_BASENAME".nmea"$CMD_COMPRESS_SUFFIX""$CMD_ENCRYPT_SUFFIX" ; 
        PATHOUT_GPX="$DIR_TMP"/"$FILEOUT_BASENAME".gpx"$CMD_COMPRESS_SUFFIX""$CMD_ENCRYPT_SUFFIX" ;
        PATHOUT_KML="$DIR_TMP"/"$FILEOUT_BASENAME".kml"$CMD_COMPRESS_SUFFIX""$CMD_ENCRYPT_SUFFIX" ;


@@ -702,6 +740,9 @@ main() {
        unset bufferBash FILEOUT_BASENAME PATHOUT_NMEA PATHOUT_GPX PATHOUT_KML PATHOUT_TAR;
        ((debugCounter++))
     done
        unset bufferBash FILEOUT_BASENAME PATHOUT_NMEA PATHOUT_GPX PATHOUT_KML PATHOUT_TAR;
        ((debugCounter++))
     done

+
+    # Remove DIR_TMP
+    try rm -r "$DIR_TMP";

 } # Main function.
 #===END Declare local script functions===
 #==END Define script parameters==
 } # Main function.
 #===END Declare local script functions===
 #==END Define script parameters==