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:46Z~.
   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 ** Operating Procedures
 125 *** Initial Startup
 126 **** Physical Setup
 127 **** Software Setup
 128 ***** Install Operating System
 129 Install Raspberry Pi OS onto an SD card image. See the Raspberry Pi
 130 Foundation [[https://www.raspberrypi.org/documentation/installation/installing-images/README.md][installation instructions]].
 131
 132 Note: "Raspberry Pi OS" is the name used by the Raspberry Pi
 133 Foundation to refer to their operating system images to be installed
 134 on Raspberry Pi hardware. The change was made in order to facilitate
 135 education of beginners not familiar with the wordplay between
 136 "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
 137 plugwash.
 138
 139 ***** Configure Wireless
 140 Configure WiFi in order to permit file transfer and remote
 141 administration. For a Raspberry Pi W, the WiFi settings may be
 142 programmed via a specific text file in the `boot` partition of a
 143 freshly installed image of Raspberry OS. Raspberry Pi Foundation
 144 instructions [[https://www.raspberrypi.org/documentation/configuration/wireless/headless.md][here]].
 145
 146 In summary, create a ~wpa_supplicant.conf~ file containing the
 147 following text:
 148 #+BEGIN_EXAMPLE
 149 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
 150 update_config=1
 151 country=US
 152
 153 network={
 154  ssid="<Name of your wireless LAN>"
 155  psk="<Password for your wireless LAN>"
 156 }
 157 #+END_EXAMPLE
 158
 159 Replace ~<Name of your wireless LAN>~ with your WiFi network's SSID.
 160
 161 Replace ~<Password for your wireless LAN>~ with your WiFi network's
 162 passphrase.
 163 ***** Enable Remote SSH Login
 164 Configure SSH to permit remote administration via the command line
 165 interface. Raspberry Pi Foundation instructions [[https://www.raspberrypi.org/documentation/remote-access/ssh/README.md][here]].
 166
 167 In summary, remote SSH access may be enabled upon initial startup of a
 168 freshly installed image of Raspberry Pi OS by making sure an empty
 169 file named ~ssh~ is present on the ~boot~ partition.
 170
 171 ***** Add SSH public key
 172 If the use has an SSH public key, it may be added as a line in
 173 ~~/.ssh/authorized_keys~.
 174
 175 Follow [[https://superuser.com/a/925859/][these]] directions to set permissions.
 176
 177 : $ chmod 700 ~/.ssh
 178 : $ chmod 644 ~/.ssh/authorized_keys
 179
 180 ***** Change default passphrase
 181 The default username is ~pi~ and the default passphrase is
 182 ~raspberry~. Change them to something unique.
 183
 184 : $ passwd
 185
 186 ***** Update software
 187 Update software with distribution repository.
 188
 189 : $ sudo apt update
 190 : $ sudo apt upgrade -y
 191 : $ sudo apt dist-upgrade -y
 192
 193 ***** Update hostname
 194 A unique hostname is required to uniquely identify the device on the
 195 network.
 196
 197 Start up the Raspberry Pi Software Configuration Tool by running:
 198 : $ sudo raspi-config
 199
 200 - Select `2 Network Options`
 201 - Select `N1 Hostname`
 202
 203 This document recommends a hostname beginning with the prefix:
 204 : ninfacyzga-1-
 205
 206 An example hostname would be ~ninfacyzga-1-2~.
 207
 208 ***** Install software
 209 ****** ~unattended-upgrades~
 210 Make sure to install the ~unattended-upgrades~ package to make sure
 211 the latest security patches for packages are installed. See [[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][this page]]
 212 for a description of how ~unattended-upgrades~ works.
 213
 214 The configuration file is located at:
 215 ~/etc/apt/apt.conf.d/50unattended-upgrades~ ([[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][ref]]). Make sure that the
 216 following lines are present and not commented out.
 217
 218 #+BEGIN_EXAMPLE
 219 Unattended-Upgrade::Automatic-Reboot "true";
 220 #+END_EXAMPLE
 221
 222 ****** ~syncthing~
 223 Install ~syncthing~ for log file transfer capability.
 224
 225 : $ sudo apt install syncthing
 226
 227 ****** ~git~
 228 ~git~ facilitates downloading files from this repository to the
 229 device. It may be installed via:
 230
 231 : $ sudo apt install git
 232
 233 ****** ninfacyzga-01 git repository
 234 Create the directory ~/git-OC/~ . Within this directory, run the
 235 following commands to clone the ~ninfacyzga-01~ git repository:
 236 : $ git clone https://zdv2.bktei.com/gitweb/ninfacyzga-01.git
 237 : $ cd ninfacyzga-01
 238
 239 Check out the ~develop~ branch (if the latest changes are desired over
 240 those of the ~master~ branch).
 241 : $ git checkout --track origin/develop
 242
 243 ****** ~age~
 244 ~age~ is required for encrypting data at rest.
 245
 246 Place ~age~ binary (the one compiled for ARM CPU architecture for
 247 Linux) in ~$HOME/.local/bin~. A copy of binary may be found within the
 248 ~exec~ directory.
 249
 250 : $ mkdir ~/.local/bin
 251 : $ cp exec/age ~/.local/bin/
 252
 253 ***** Disable Swap File
 254 Since standard Raspberry OS 10 install involves copying unencrypted
 255 file system image to SD card which is mounted by the Raspberry Pi,
 256 system memory may be written to disk in the form of a Swap file as
 257 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
 258 is ever written to disk, swap file functionality must be
 259 disabled[fn:ideaheap_20130731_disableswap].
 260
 261 Raspbian 10 uses dphys-swapfile to manage a swap file. It may be
 262 disabled persistently[fn:rpf_20190702_disableswappersist] by running
 263 the following command:
 264
 265 : sudo systemctl disable dphys-swapfile.service
 266
 267 To view the status of the swap file in Raspbian 10, run ~free -m~:
 268
 269 #+BEGIN_EXAMPLE
 270 pi@ninfacyzga-01:~$ free -m
 271           total    used    free  shared  buff/cache   available
 272 Mem:        432      86      36      21         309         268
 273 Swap:        99       0      99
 274 #+END_EXAMPLE
 275
 276 After disabling the swap file and rebooting:
 277
 278 #+BEGIN_EXAMPLE
 279 pi@ninfacyzga-01:~$ free -m
 280           total    used    free  shared  buff/cache   available
 281 Mem:        432      89     214       3         128         289
 282 Swap:         0       0       0
 283 #+END_EXAMPLE
 284
 285 [fn:ideaheap_20130731_disableswap] Explanation:
 286 https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/
 287
 288 [fn:rpf_20190702_disableswappersist] Persistant disabling of swap in
 289 Raspbian 10 Buster:
 290 https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692
 291
 292 ***** Log Transfer Configuration
 293 Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
 294 manual for how to set up a shared folder and add Ninfacyzga-01 as a
 295 device. Syncthing's directory synchronization capability allows a
 296 remote machine to delete files from Ninfacyzga-01 by deleting from the
 297 shared folder that they both share.
 298
 299 When log files are removed from Ninfacyzga-01 is not within the scope
 300 of this document.
 301 ***** Key Generation
 302 An ~age~ encryption key may be generated like so:
 303 #+BEGIN_EXAMPLE
 304 $ umask          # Gets current umask
 305 0022             # Note: This is the default umask for Raspbian 10
 306 $ umask 066      # So key.txt will have no perms except for owner (you)
 307 $ umask          # Confirm umask set to 066
 308 0066
 309 $ age-keygen > key.txt
 310 Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
 311 $ ls -al key.txt
 312 -rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
 313 $ umask 0022     # Return umask to default value
 314 $ umask
 315 0022
 316 #+END_EXAMPLE
 317
 318 The resulting public/private keypair data looks like:
 319 #+BEGIN_EXAMPLE
 320 $ cat key.txt
 321 # created: 2020-06-29T18:01:56Z
 322 # public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
 323 AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
 324 #+END_EXAMPLE
 325
 326 The file ~key.txt~ is not password-protected by default and should be
 327 secured like an SSH public key should. The ~$ umask 066~ command run
 328 before the ~$ age-keygen > key.txt~ command ensures ~key.txt~ will not
 329 be readable, writeable, or executable to anyone except the owner
 330 (you).
 331
 332 *** Normal Startup
 333 *** Normal Operation
 334 *** Normal Shutdown
 335 *** Unscheduled Shutdown
 336 *** End of Life Disposal
 337 See [[file:../setup/README.org][Main Setup]] procedures.
 338
 339 LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of
 340 properly with their potential ignitability in mind, especially if they
 341 are not fully discharged.
 342
 343 Consult your local municipality for its "E-Waste Disposal" (or
 344 equivalent) policy. Metals used in the Raspberry Pi and related
 345 components may be recycled.
 346
 347 Take extra precuation if lead solder was used in assembling the
 348 electronics. Consumer electronics in early 21st century should use
 349 lead-free solder.
 350
 351
 352