X-Git-Url: https://zdv2.bktei.com/gitweb/EVA-2020-02.git/blobdiff_plain/aedd19f6b8743c5fbb923e552a961d0440ff8ff5..89de9fb6f72f1a0b3f6cafe0bc310509edccf53a:/doc/location/README.org diff --git a/doc/location/README.org b/doc/location/README.org index 1ffdccd..06860d2 100644 --- a/doc/location/README.org +++ b/doc/location/README.org @@ -1,10 +1,12 @@ * Location Logging -This document was created by Steven Baltakatei Sandoval on -~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-07-12T21:04Z~ #+TITLE: Ninfacyzga-01 Manual #+AUTHOR: Steven Baltakatei Sandoval #+EMAIL: baltakatei@gmail.com +** About +This document was created by Steven Baltakatei Sandoval on +~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-10-08T00:18Z~ + ** 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 @@ -64,8 +66,16 @@ Several output file formats have been tested with ~bklog~. **** File Formats ***** NMEA -See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page]] for this. This file format is the default -output of the ~gpspipe -r~ command. +~NMEA~ is an acronym for National marine Electronics Association. The +NMEA format described in this document follows the NMEA 0183 +standard. It is a newline-delimited streaming text format that encodes +global positioning system (GPS) data such as WGS84 location, time and +date information, satellite count, accuracy, and other +information. Each line is an "NMEA sentence". Descriptions of various +NMEA sentences can be found on [[http://aprs.gids.nl/nmea/][this]] webpage. + +See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page for NMEA 0183]] for this. This file format is the +default output of the ~gpspipe -r~ command. ***** GPX 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. An NMEA file may be converted to this format using ~gpsbabel~. @@ -74,75 +84,11 @@ See the [[https://en.wikipedia.org/wiki/Keyhole_Markup_Language][Wikipedia page] may be converted to this format using ~gpsbabel~. **** Encryption Method -Files produced by the bkgpslog script are encrypted against a set of -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 -****** Encryption through ~age~ -In order to illustrate how ~bklog~ encrypts files, below is an example -command illustrating how ~age~ may be used to encrypt a file. - -#+BEGIN_EXAMPLE -$ echo "asdf" | age -r \ -age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \ -> "$HOME/secret_file" -#+END_EXAMPLE - -The resulting ~secret-file~ is a binary blob with a plaintext header -indicating how the blob was encrypted (which version of age was used, -which public key was used). - -****** Encryption through ~bklog~ -~bklog~ may instructed to encrypt files via the ~-e~ and ~-r [pubkey -string]~ options. An example is shown below: - -#+BEGIN_EXAMPLE -$ gpspipe -r | bklog -e \ --r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \ --r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \ --r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \ --o "$HOME/Location" -#+END_EXAMPLE - -~bklog~ may be instructed via the ~-e~ and ~-R~ options to watch a -directory in order to locate public key strings in its files. ~bklog~ -reads the first line of each file and interprets it as a public key -string. - -In this example, the strings beginning with ~age1...~ are -bech32-formatted public key strings. Please see the [[*Key Generation][Key Generation]] -section for an explanation. - -Since ~age~ also accepts ~ssh~ public key strings, these may also be -used if they are of the following form (no comment). - -: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABA…AACAQDLnJbPs7CjwPT+OxXd - -***** 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 +See [[file:../setup/README.org][Main Setup]] procedures. ** 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 @@ -154,65 +100,14 @@ possible. **** Software Setup ***** Install Executables +Follow the [[file:../setup/README.org][Main Setup]] procedures to obtain required files from this +repository. -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. +Install ~gpsd~, ~gpsd-clients~. -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 +: $ sudo apt install gpsd gpsd-clients ***** Automatic Start Configuration - It is recommended to create a daily ~cron~ job that executes a bash script that starts ~bklog~ jobs to record location along with other types of data recording. An example of such a script is below: @@ -277,6 +172,8 @@ In the example script, the options are: : environment variable. ***** Log Transfer Configuration +See [[file:../setup/README.org][Main Setup]] procedures. + 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 @@ -287,35 +184,7 @@ 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). +See [[file:../setup/README.org][Main Setup]] procedures. *** Normal Startup Turn on Ninfacyzga-01 by supplying 5VDC power to the Raspberry Pi. No @@ -339,14 +208,4 @@ 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. +See [[file:../setup/README.org][Main Setup]] procedures.