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