X-Git-Url: https://zdv2.bktei.com/gitweb/EVA-2020-02.git/blobdiff_plain/170f63baf5a56d9ece11b31924a9f4a81cd92812..6c30388ff903fe9c9f2c31ced53f1f7003031fac:/doc/location/README.org diff --git a/doc/location/README.org b/doc/location/README.org index d626dd0..397968f 100644 --- 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 -<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>. +~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 @@ -53,17 +56,230 @@ encrypted with ~age~, and then written to disk. ***** 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 -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 -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 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 \ +-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 Commands +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 +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~. + +***** 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 +0 * * * * /bin/bash ~/bkgpslog --output ~/dir + +@reboot /bin/bash ~/bkgpslog --output ~/dir +#+END_EXAMPLE + +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. + +~/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 +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 # So key.txt will have no perms 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 +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 +The system may be shutdown via SSH by running: + +: $ sudo shutdown -r 0 + *** 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 +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.