doc/setup/README.org

   1 #+TITLE:Ninfacyzga-01 Setup
   2 #+AUTHOR:Steven Baltakatei Sandoval
   3 #+EMAIL:baltakatei@gmail.com
   4 * Main Setup
   5 ** About
   6 This document created by [[http://baltakatei.com][Steven Baltakatei Sandoval]] on
   7 ~2020-10-07T18:39Z~ under a [[http://creativecommons.org/licenses/by-sa/4.0/][CC BY-SA 4.0]] license and last updated on
   8 ~2020-10-07T23:08Z~.
   9
  10 This document contains information regarding setup of the
  11 ninfacyzga-01 hardware common to all operation modes. This includes:
  12
  13 - Raspberry OS installation
  14 - WiFi configuration
  15 - Remote SSH login configuration
  16
  17 ** Scope
  18 This document describes hardware and software installation steps
  19 common to the various environmental sensing functions of
  20 ninfacyzga-01.
  21
  22 ** Narrative
  23 The Raspberry Pi Zero W is the platform in which environment data is
  24 gathered, packaged, and stored for further forwarding to a remote
  25 repository. The Raspberry OS 10 operating system is used. The device
  26 may be equipped with a UPS module in order to allow it to function as
  27 a mobile device for short periods of time. The system may use
  28 executables such as ~bklog~ to append segments of observed compressed
  29 (~gzip~) encrypted (~age~) data to a ~tar~ archive to local disk. This
  30 document describes hardware and software configuration procedures
  31 generally required by all environment sensing operations.
  32
  33 ** Description
  34 *** Hardware
  35 **** Raspberry Pi Zero W
  36 See the [[https://www.raspberrypi.org/pi-zero-w/][OEM]] webpage for this product.
  37 **** PiZ UpTime 2.0
  38 See the [[https://alchemy-power.com/piz-uptime-2-0/][OEM]] webpage for this product.
  39
  40 *** Software
  41 ~bklog~ : A bash script that saves its stdin stream to a tar file. The
  42 file may be compressed by ~gzip~ and encrypted by ~age~. It is an
  43 executable file contained within this repository at ~exec/bklog~. It
  44 should be copied to ~$HOME/.local/bin~.
  45
  46 ~bkgpslog~ : A legacy bash script similar to ~bklog~ but narrower in
  47 scope in that it only records output from ~gpspipe~.
  48
  49 ~gzip~ : A simple command line app that compresses stdin into a
  50 smaller stdout stream.
  51
  52 ~age~ : A simple command line app that encrypts stdin against public
  53 keys specified in its options. Produces encrypted stdout. Is an
  54 executable file contained within this repository at ~exec/age~. It
  55 should be copied to ~$HOME/.local/bin~.
  56
  57 *** Output
  58 **** Encryption Method
  59 Files produced by the bklog script are encrypted against a set of
  60 public keys using [[https://github.com/FiloSottile/age][~age~]], a simple command line encryption tool
  61 selected over ~gpg~ because of ~age~'s deliberate lack of
  62 configurability.
  63
  64 The public keys are bech32 strings supplied as options to bkgpslog
  65 when called. The secret key should *NOT* be stored in Ninfacyzga-01.
  66
  67 If a key pair was generated using ~age-keygen~, then it is an [[https://en.wikipedia.org/wiki/Curve25519][~X25519~]]
  68 key pair. See the [[https://age-encryption.org/v1][~age~ Version 1 specification]].
  69
  70 An ~ssh-rsa~ or ~ssh-ed25519~ SSH public key string may be used instead of
  71 the bech32 public key string produced by ~age-keygen~ for convenience.
  72
  73 Help information for ~age~ is available by running ~$ age --help~.
  74 ***** Encryption Commands
  75 ****** Encryption through ~age~
  76 In order to illustrate how ~bklog~ encrypts files, below is an example
  77 command illustrating how ~age~ may be used to encrypt a file.
  78
  79 #+BEGIN_EXAMPLE
  80 $ echo "asdf" | age -r \
  81 age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
  82 > "$HOME/secret_file"
  83 #+END_EXAMPLE
  84
  85 The resulting ~secret-file~ is a binary blob with a plaintext header
  86 indicating how the blob was encrypted (which version of age was used,
  87 which public key was used).
  88
  89 ****** Encryption through ~bklog~
  90 ~bklog~ may instructed to encrypt files via the ~-e~ and ~-r [pubkey
  91 string]~ options. An example is shown below:
  92
  93 #+BEGIN_EXAMPLE
  94 $ gpspipe -r | bklog -e \
  95 -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
  96 -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
  97 -r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \
  98 -o "$HOME/Location"
  99 #+END_EXAMPLE
 100
 101 ~bklog~ may be instructed via the ~-e~ and ~-R~ options to watch a
 102 directory in order to locate public key strings in its files. ~bklog~
 103 reads the first line of each file and interprets it as a public key
 104 string.
 105
 106 In this example, the strings beginning with ~age1...~ are
 107 bech32-formatted public key strings. Please see the [[*Key Generation][Key Generation]]
 108 section for an explanation.
 109
 110 Since ~age~ also accepts ~ssh~ public key strings, these may also be
 111 used if they are of the following form (no comment).
 112
 113 : ssh-rsa AAAAB3NzaC1yc2EAAAADAQABA…AACAQDLnJbPs7CjwPT+OxXd
 114
 115 ***** Decryption Commands
 116 Files may be decrypted using a command similar to:
 117
 118 #+BEGIN_EXAMPLE
 119 cat location.gpx.age | age -d -i key.txt > location.gpx
 120 #+END_EXAMPLE
 121
 122 The version of ~age~ used to perform the encryption
 123
 124
 125 ** Operating Procedures
 126 *** Initial Startup
 127 **** Physical Setup
 128 **** Software Setup
 129 ***** Install Operating System
 130 Install Raspberry Pi OS onto an SD card image. See the Raspberry Pi
 131 Foundation [[https://www.raspberrypi.org/documentation/installation/installing-images/README.md][installation instructions]].
 132
 133 Note: "Raspberry Pi OS" is the name used by the Raspberry Pi
 134 Foundation to refer to their operating system images to be installed
 135 on Raspberry Pi hardware. The change was made in order to facilitate
 136 education of beginners not familiar with the wordplay between
 137 "Raspberry" and "Debian". See [[https://www.raspberrypi.org/forums/viewtopic.php?f=66&t=275380&sid=1a468f226394ccddf4654a3d3d90cb7d#p1668466][this]] forum post made on 2020-05-28 by
 138 plugwash.
 139
 140 ***** Configure Wireless
 141 Configure WiFi in order to permit file transfer and remote
 142 administration. For a Raspberry Pi W, the WiFi settings may be
 143 programmed via a specific text file in the `boot` partition of a
 144 freshly installed image of Raspberry OS. Raspberry Pi Foundation
 145 instructions [[https://www.raspberrypi.org/documentation/configuration/wireless/headless.md][here]].
 146
 147 In summary, create a ~wpa_supplicant.conf~ file containing the
 148 following text:
 149 #+BEGIN_EXAMPLE
 150 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
 151 update_config=1
 152 country=US
 153
 154 network={
 155  ssid="<Name of your wireless LAN>"
 156  psk="<Password for your wireless LAN>"
 157 }
 158 #+END_EXAMPLE
 159
 160 Replace ~<Name of your wireless LAN>~ with your WiFi network's SSID.
 161
 162 Replace ~<Password for your wireless LAN>~ with your WiFi network's
 163 passphrase.
 164 ***** Configure Remote SSH Login
 165 Configure SSH to permit remote administration via the command line
 166 interface. Raspberry Pi Foundation instructions [[https://www.raspberrypi.org/documentation/remote-access/ssh/README.md][here]].
 167
 168 In summary, remote SSH access may be enabled upon initial startup of a
 169 freshly installed image of Raspberry Pi OS by making sure an empty
 170 file named ~ssh~ is present on the ~boot~ partition.
 171
 172 ***** Change default passphrase
 173 The default username is ~pi~ and the default passphrase is
 174 ~raspberry~. Change them to something unique.
 175
 176 : $ passwd
 177
 178 ***** Update software
 179 Update software with distribution repository.
 180
 181 : $ sudo apt update
 182 : $ sudo apt upgrade -y
 183 : $ sudo apt dist-upgrade -y
 184
 185 ***** Install software
 186 ****** ~unattended-upgrades~
 187 Make sure to install the ~unattended-upgrades~ package to make sure
 188 the latest security patches for packages are installed. See [[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][this page]]
 189 for a description of how ~unattended-upgrades~ works.
 190
 191 The configuration file is located at:
 192 ~/etc/apt/apt.conf.d/50unattended-upgrades~ ([[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][ref]]). Make sure that the
 193 following lines are present and not commented out.
 194
 195 #+BEGIN_EXAMPLE
 196 Unattended-Upgrade::Automatic-Reboot "true";
 197 #+END_EXAMPLE
 198
 199 ****** ~syncthing~
 200 Install ~syncthing~ for log file transfer capability.
 201
 202 : $ sudo apt install syncthing
 203
 204 ****** ~git~
 205 Install ~git~ for downloading this repository to the device.
 206
 207 : $ sudo apt install git
 208
 209 ****** ninfacyzga-01 git repository
 210 Create the directory ~/git-OC/~ . Within this directory, run the
 211 following commands to clone the ~ninfacyzga-01~ git repository:
 212 : $ git clone https://gitlab.com/baltakatei/ninfacyzga-01.git
 213 : $ cd ninfacyzga-01
 214
 215 Check out the ~develop~ branch (if the latest changes are desired over
 216 those of the ~master~ branch).
 217 : $ git checkout --track origin/develop
 218
 219 ****** ~age~
 220 Place ~age~ binary (the one compiled for ARM CPU architecture for
 221 Linux) in ~$HOME/.local/bin~. A copy of binary may be found within the
 222 ~exec~ directory.
 223
 224 ***** Disable Swap File
 225 Since standard Raspbian 10 (Buster) install involves copying
 226 unencrypted file system image to SD card which is mounted by the
 227 Raspberry Pi, system memory may be written to disk in the form of a
 228 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
 229 location log data is ever written to disk, swap file functionality
 230 must be disabled[fn:ideaheap_20130731_disableswap].
 231
 232 Raspbian 10 uses dphys-swapfile to manage a swap file. It may be
 233 disabled persistently[fn:rpf_20190702_disableswappersist] by running
 234 the following command:
 235
 236 : sudo systemctl disable dphys-swapfile.service
 237
 238 To view the status of the swap file in Raspbian 10, run ~free -m~:
 239
 240 #+BEGIN_EXAMPLE
 241 pi@ninfacyzga-01:~$ free -m
 242           total    used    free  shared  buff/cache   available
 243 Mem:        432      86      36      21         309         268
 244 Swap:        99       0      99
 245 #+END_EXAMPLE
 246
 247 After disabling the swap file and rebooting:
 248
 249 #+BEGIN_EXAMPLE
 250 pi@ninfacyzga-01:~$ free -m
 251           total    used    free  shared  buff/cache   available
 252 Mem:        432      89     214       3         128         289
 253 Swap:         0       0       0
 254 #+END_EXAMPLE
 255
 256 [fn:ideaheap_20130731_disableswap] Explanation:
 257 https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/
 258
 259 [fn:rpf_20190702_disableswappersist] Persistant disabling of swap in
 260 Raspbian 10 Buster:
 261 https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692
 262
 263 ***** Log Transfer Configuration
 264 Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
 265 manual for how to set up a shared folder and add Ninfacyzga-01 as a
 266 device. Syncthing's directory synchronization capability allows a
 267 remote machine to delete files from Ninfacyzga-01 by deleting from the
 268 shared folder that they both share.
 269
 270 When log files are removed from Ninfacyzga-01 is not within the scope
 271 of this document.
 272 ***** Key Generation
 273 An ~age~ encryption key may be generated like so:
 274 #+BEGIN_EXAMPLE
 275 $ umask          # Gets current umask
 276 0022             # Note: This is the default umask for Raspbian 10
 277 $ umask 066      # So key.txt will have no perms except for owner (you)
 278 $ umask          # Confirm umask set to 066
 279 0066
 280 $ age-keygen > key.txt
 281 Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
 282 $ ls -al key.txt
 283 -rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
 284 $ umask 0022     # Return umask to default value
 285 $ umask
 286 0022
 287 #+END_EXAMPLE
 288
 289 The resulting public/private keypair data looks like:
 290 #+BEGIN_EXAMPLE
 291 $ cat key.txt
 292 # created: 2020-06-29T18:01:56Z
 293 # public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
 294 AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
 295 #+END_EXAMPLE
 296
 297 The file ~key.txt~ is not password-protected by default and should be
 298 secured like an SSH public key should. The ~$ umask 066~ command run
 299 before the ~$ age-keygen > key.txt~ command ensures ~key.txt~ will not
 300 be readable, writeable, or executable to anyone except the owner
 301 (you).
 302
 303 *** Normal Startup
 304 *** Normal Operation
 305 *** Normal Shutdown
 306 *** Unscheduled Shutdown
 307 *** End of Life Disposal
 308 See [[file:../setup/README.org][Main Setup]] procedures.
 309
 310 LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of
 311 properly with their potential ignitability in mind, especially if they
 312 are not fully discharged.
 313
 314 Consult your local municipality for its "E-Waste Disposal" (or
 315 equivalent) policy. Metals used in the Raspberry Pi and related
 316 components may be recycled.
 317
 318 Take extra precuation if lead solder was used in assembling the
 319 electronics. Consumer electronics in early 21st century should use
 320 lead-free solder.
 321
 322
 323