test(bkgpslog): Test 'tee /dev/null' as passthrough-function

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

diff --git a/doc/location/README.org b/doc/location/README.org
index d626dd0b0078e02f526a117a5a4e64fa5be01212..92e73b7958d718c56dc7c2a2da832642a25706de 100644 (file)
--- a/doc/location/README.org
+++ b/doc/location/README.org
@@ -1,7 +1,7 @@
 * 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
 * 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 16:05>.
+was updated by Steven Baltakatei Sandoval on <2020-06-29 Mon 18:39>.

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


@@ -53,17 +53,168 @@ encrypted with ~age~, and then written to disk.
 ***** NMEA
 See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page]] for this.
 ***** GPX
 ***** NMEA
 See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page]] for this.
 ***** GPX

-See the [[https://en.wikipedia.org/wiki/GPS_Exchange_Format][Wikipedia page]] for this.
+See the [[https://en.wikipedia.org/wiki/GPS_Exchange_Format][Wikipedia page]] for this. [[http://wiki.gis.com/wiki/index.php/WGS84][WGS84]] is the datum used.

 ***** KML
 ***** KML

-See the [[https://en.wikipedia.org/wiki/Keyhole_Markup_Language][Wikipedia page]] for this.
+See the [[https://en.wikipedia.org/wiki/Keyhole_Markup_Language][Wikipedia page]] for this. [[http://wiki.gis.com/wiki/index.php/WGS84][WGS84]] is the datum used.

 **** Encryption Method
 Files produced by the bkgpslog script are encrypted against a set of
 **** Encryption Method
 Files produced by the bkgpslog script are encrypted against a set of

-public keys using [[https://github.com/FiloSottile/age][age]]. The public keys are bech32 strings supplied as
-options to bkgpslog when called.
+public keys using [[https://github.com/FiloSottile/age][~age~]], a simple command line encryption tool
+selected over ~gpg~ because of ~age~'s deliberate lack of
+configurability.
+
+The public keys are bech32 strings supplied as options to bkgpslog
+when called. The secret key should *NOT* be stored in Ninfacyzga-01.
+
+If a key pair was generated using ~age-keygen~, then it is an [[https://en.wikipedia.org/wiki/Curve25519][~X25519~]]
+key pair. See the [[https://age-encryption.org/v1][~age~ Version 1 specification]].
+
+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~.
+***** Encryption
+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 \
+-r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
+-r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
+-r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \
+> location.gpx.age
+#+END_EXAMPLE
+
+In this example, the strings beginning with ~age1...~ are
+bech32-formatted public key strings. 
+
+
+***** Decryption
+Files may be decrypted using a command similar to:
+
+#+BEGIN_EXAMPLE
+cat location.gpx.age | age -d -i key.txt > location.gpx
+#+END_EXAMPLE
+
+The version of ~age~ used to perform the encryption 

 ** Operating Procedures
 *** Initial Startup
 ** Operating Procedures
 *** Initial Startup

+See OEM (Ozzmaker) [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][quickstart guide for the BerryGPS-IMU]].
+
+**** Physical Setup
+
+BerryGPS-IMU must be electrically connected to the correct pins on the
+GPIO header of a Raspberry Pi Zero W.
+
+*Optional*: stack together with PiZ Uptime 2.0 module. No GPIO pins
+conflict so a simple stacking and soldering with long header pins is
+possible.
+
+**** Software Setup
+
+***** Install Executables
+
+Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi
+Foundation [[https://www.raspberrypi.org/documentation/installation/installing-images/README.md][installation instructions]]. Configure WiFi to permit log
+file transfer. Configure SSH to permit remote administration via the
+command line interface.
+
+Make sure to install the ~unattended-upgrades~ package to make sure
+the latest security patches for packages are installed. See [[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][this page]]
+for a description of how ~unattended-upgrades~ works.
+
+Install ~gpsd~, ~gpspipe~, ~git~, and this repository for location
+logging capability.
+
+Install ~syncthing~ for log file transfer capability.
+
+Place ~age~ binary (the one compiled for ARM CPU architecture for
+Linux) in ~$HOME/.local/bin~.
+
+***** 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
+
+@reboot /bin/bash /path/to/bkgpslog --output $HOME/Sync/example_dir
+#+END_EXAMPLE
+
+The first line will run ~bkgpslog~ at the start of every hour.
+
+The second line will run ~bkgpslog~ when the system starts up.
+
+***** 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
+device. Syncthing's directory synchronization capability allows a
+remote machine to delete files from Ninfacyzga-01 by deleting from the
+shared folder that they both share.
+
+When log files are removed from Ninfacyzga-01 is not within the scope
+of this document.
+
+***** Key Generation
+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
+$ umask 066      # Sets umask so key.txt will have no permissions except for owner (you)
+$ umask          # Confirm umask set to 066
+0066
+$ age-keygen > key.txt
+Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
+$ ls -al key.txt
+-rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
+$ umask 0022     # Return umask to default value
+$ umask          
+0022
+#+END_EXAMPLE
+
+The resulting public/private keypair data looks like:
+#+BEGIN_EXAMPLE
+$ cat key.txt
+# created: 2020-06-29T18:01:56Z
+# public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
+AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
+#+END_EXAMPLE
+
+The file ~key.txt~ is not password-protected by default and should be
+secured like an SSH public key should. The ~$ umask 066~ command run
+before the ~$ age-keygen > key.txt~ command ensures ~key.txt~ will not
+be readable, writeable, or executable to anyone except the owner
+(you).
+

 *** Normal Startup
 *** Normal Startup

+Turn on Ninfacyzga-01 by supplying 5VDC power to the Raspberry Pi. No
+further interaction should be required.
+*** Normal Operation
+No interaction beyond continually supplying approximately 100mA of
+5VDC power and occasionally removing log files to conserve disk space
+is required.
+**** Log Transfer
+Log files may be transferred by use of ~syncthing~ shared folders.
+**** Automatic Updates
+The ~automatic-upgrades~ package, if installed, should automatically
+install security patches to packages installed via ~apt~.

 *** Normal Shutdown
 *** Normal Shutdown

+The system may be shutdown via SSH by running:
+
+: $ sudo shutdown -r 0
+

 *** Unscheduled Shutdown
 *** Unscheduled Shutdown

+Ninfacyzga-01 as described and setup should tolerate unscheduled power
+loss. Log files being written every 60 seconds means, at most, 60
+seconds worth of location data may be lost.

 *** End of Life Disposal
 *** End of Life Disposal

+LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of
+properly with their potential ignitability in mind, especially if they
+are not fully discharged.
+
+Consult your local municipality for its "E-Waste Disposal" (or
+equivalent) policy. Metals used in the Raspberry Pi and related
+components may be recycled.
+
+Take extra precuation if lead solder was used in assembling the
+electronics. Consumer electronics in early 21st century should use
+lead-free solder.