fix(bkgpslog):Clarify echoed newlines per Shellcheck

[EVA-2020-02.git] / doc / location / README.org

diff --git a/doc/location/README.org b/doc/location/README.org
index 92e73b7958d718c56dc7c2a2da832642a25706de..397968f9e2a3de5ba0bf7d525fbe8e2cce9d7029 100644 (file)
--- a/doc/location/README.org
+++ b/doc/location/README.org
@@ -1,7 +1,10 @@
 * Location Logging
 This document was created by Steven Baltakatei Sandoval on
 * Location Logging
 This document was created by Steven Baltakatei Sandoval on

-<2020-06-29 Mon 12:14> under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It
-was updated by Steven Baltakatei Sandoval on <2020-06-29 Mon 18:39>.
+~2020-06-29T12:14Z~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It
+was updated by Steven Baltakatei Sandoval on ~2020-06-30T19:44Z~
+#+TITLE: Ninfacyzga-01 Manual
+#+AUTHOR: Steven Baltakatei Sandoval
+#+EMAIL: baltakatei@gmail.com

 ** Narrative
 Ninfacyzga-01 records (logs) its position in time and space using a
 [[https://en.wikipedia.org/wiki/Satellite_navigation_device][GPS receiver]]. The NMEA location data produced by the receiver is
 ** Narrative
 Ninfacyzga-01 records (logs) its position in time and space using a
 [[https://en.wikipedia.org/wiki/Satellite_navigation_device][GPS receiver]]. The NMEA location data produced by the receiver is


@@ -72,7 +75,7 @@ An ~ssh-rsa~ or ~ssh-ed25519~ SSH public key string may be used instead of
 the bech32 public key string produced by ~age-keygen~ for convenience.
 
 Help information for ~age~ is available by running ~$ age --help~.
 the bech32 public key string produced by ~age-keygen~ for convenience.
 
 Help information for ~age~ is available by running ~$ age --help~.

-***** Encryption
+***** Encryption Commands

 Files may be encrypted to several recipients using a command similar to:
 #+BEGIN_EXAMPLE
 timeout "60s" gpspipe -r | gpsbabel -i nmea -f - -o gpx -F | age \
 Files may be encrypted to several recipients using a command similar to:
 #+BEGIN_EXAMPLE
 timeout "60s" gpspipe -r | gpsbabel -i nmea -f - -o gpx -F | age \


@@ -86,7 +89,7 @@ In this example, the strings beginning with ~age1...~ are
 bech32-formatted public key strings. 
 
 
 bech32-formatted public key strings. 
 
 

-***** Decryption
+***** Decryption Commands

 Files may be decrypted using a command similar to:
 
 #+BEGIN_EXAMPLE
 Files may be decrypted using a command similar to:
 
 #+BEGIN_EXAMPLE


@@ -108,7 +111,6 @@ conflict so a simple stacking and soldering with long header pins is
 possible.
 
 **** Software Setup
 possible.
 
 **** Software Setup

-

 ***** Install Executables
 
 Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi
 ***** Install Executables
 
 Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi


@@ -128,21 +130,84 @@ Install ~syncthing~ for log file transfer capability.
 Place ~age~ binary (the one compiled for ARM CPU architecture for
 Linux) in ~$HOME/.local/bin~.
 
 Place ~age~ binary (the one compiled for ARM CPU architecture for
 Linux) in ~$HOME/.local/bin~.
 

+***** Disable Swap File
+Since standard Raspbian 10 (Buster) install involves copying
+unencrypted file system image to SD card which is mounted by the
+Raspberry Pi, system memory may be written to disk in the form of a
+Swap file as described [[https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/][here]]. In order to reduce the chance that
+location log data is ever written to disk, swap file functionality
+must be disabled[fn:ideaheap_20130731_disableswap].
+
+Raspbian 10 uses dphys-swapfile to manage a swap file. It may be
+disabled persistently[fn:rpf_20190702_disableswappersist] by running
+the following command:
+
+: sudo systemctl disable dphys-swapfile.service
+
+To view the status of the swap file in Raspbian 10, run ~free -m~:
+
+#+BEGIN_EXAMPLE
+pi@ninfacyzga-01:~$ free -m
+          total    used    free  shared  buff/cache   available
+Mem:        432      86      36      21         309         268
+Swap:        99       0      99
+#+END_EXAMPLE
+
+After disabling the swap file and rebooting:
+
+#+BEGIN_EXAMPLE
+pi@ninfacyzga-01:~$ free -m
+          total    used    free  shared  buff/cache   available
+Mem:        432      89     214       3         128         289
+Swap:         0       0       0
+#+END_EXAMPLE
+
+[fn:ideaheap_20130731_disableswap] Explanation:
+https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/
+
+[fn:rpf_20190702_disableswappersist] Persistant disabling of swap in
+Raspbian 10 Buster:
+https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692
+

 ***** Automatic Start Configuration
 
 Edit the user cron job list with ~$ crontab -e~ to add the following
 lines:
 
 #+BEGIN_EXAMPLE
 ***** Automatic Start Configuration
 
 Edit the user cron job list with ~$ crontab -e~ to add the following
 lines:
 
 #+BEGIN_EXAMPLE

-0 * * * * /bin/bash /path/to/bkgpslog --output $HOME/Sync/example_dir
+0 * * * * /bin/bash ~/bkgpslog --output ~/dir

 
 

-@reboot /bin/bash /path/to/bkgpslog --output $HOME/Sync/example_dir
+@reboot /bin/bash ~/bkgpslog --output ~/dir

 #+END_EXAMPLE
 
 #+END_EXAMPLE
 

-The first line will run ~bkgpslog~ at the start of every hour.
+The first line will run ~bkgpslog~ at the start of every hour and save
+output files to the ~dir~ directory in your home folder.

 
 The second line will run ~bkgpslog~ when the system starts up.
 
 
 The second line will run ~bkgpslog~ when the system starts up.
 

+~/bin/bash~ tells ~cron~ to run ~bkgpslog~ with Bash.
+
+If encryption and compression are required, then the appropriate
+options must be added. The lines that must be added via ~$ crontab -e~
+may resemble:
+
+#+BEGIN_EXAMPLE
+0 * * * * /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
+
+@reboot /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
+#+END_EXAMPLE
+
+The ~age1z2...qkv6p~ is an ~age~ public key string. Please see the
+[[*Key Generation][Key Generation]] section for an explanation.
+
+The options are:
+
+: -c : tells bkgpslog to compress output
+: -e : tells bkgpslog log to encrypt output
+: -r : tells bkgpslog to interpret the next argument as a pubkey string
+: -o : tells bkgpslog to write output files to the directory represented
+:        by the next argument
+

 ***** Log Transfer Configuration
 Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
 manual for how to set up a shared folder and add Ninfacyzga-01 as a
 ***** Log Transfer Configuration
 Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
 manual for how to set up a shared folder and add Ninfacyzga-01 as a


@@ -158,7 +223,7 @@ An ~age~ encryption key may be generated like so:
 #+BEGIN_EXAMPLE
 $ umask          # Gets current umask
 0022             # Note: This is the default umask for Raspbian 10
 #+BEGIN_EXAMPLE
 $ umask          # Gets current umask
 0022             # Note: This is the default umask for Raspbian 10

-$ umask 066      # Sets umask so key.txt will have no permissions except for owner (you)
+$ umask 066      # So key.txt will have no perms except for owner (you)

 $ umask          # Confirm umask set to 066
 0066
 $ age-keygen > key.txt
 $ umask          # Confirm umask set to 066
 0066
 $ age-keygen > key.txt