doc/setup/README.org

   1 #+TITLE:Ninfacyzga-1 Main 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-16T22:26Z~.
   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 ***** Change time zone
 201 The time zone should be set to "UTC" for simplicity.
 202
 203 : $ sudo raspi-config
 204
 205 Navigate to ~4 Localisation Options~, ~I2 Change Time Zone~, ~None of the above~, ~UTC~.
 206
 207 ***** Update hostname
 208 A unique hostname is required to uniquely identify the device on the
 209 network.
 210
 211 Start up the Raspberry Pi Software Configuration Tool by running:
 212 : $ sudo raspi-config
 213
 214 - Select `2 Network Options`
 215 - Select `N1 Hostname`
 216
 217 This document recommends a hostname beginning with the prefix:
 218 : ninfacyzga-1-
 219
 220 An example hostname would be ~ninfacyzga-1-2~.
 221
 222 ***** Install software
 223 ****** ~unattended-upgrades~
 224 Make sure to install the ~unattended-upgrades~ package to make sure
 225 the latest security patches for packages are installed. See [[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][this page]]
 226 for a description of how ~unattended-upgrades~ works.
 227
 228 The configuration file is located at:
 229 ~/etc/apt/apt.conf.d/50unattended-upgrades~ ([[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][ref]]). Make sure that the
 230 following lines are present and not commented out.
 231
 232 #+BEGIN_EXAMPLE
 233 Unattended-Upgrade::Automatic-Reboot "true";
 234 #+END_EXAMPLE
 235
 236 ****** ~syncthing~
 237 Install ~syncthing~ for log file transfer capability.
 238
 239 : $ sudo apt install syncthing
 240
 241 Enable automatic startup. (See [[https://docs.syncthing.net/users/autostart.html][ref]]).
 242
 243 : $ sudo systemctl enable syncthing@pi.service
 244 : $ sudo systemctl start syncthing@pi.service
 245
 246 The WebUI of the local instance of syncthing (port 8384) can be
 247 accessed by running the following command from a separate machine:
 248
 249 : $ ssh -L 127.0.0.1:8390:127.0.0.1:8384 pi@ninfacyzga-1-x
 250
 251 Then, the separate machine should navigate to ~localhost:8390~ in a
 252 web browser in order to change the ninfacyzga-1 device's
 253 configuration. The separate machine's Syncthing configuration options
 254 are accessible via its own web browser via ~localhost:8384~.
 255
 256 ****** ~git~
 257 ~git~ facilitates downloading files from this repository to the
 258 device. It may be installed via:
 259
 260 : $ sudo apt install git
 261
 262 ****** ninfacyzga-01 git repository
 263 Create the directory ~/git-OC/~ . Within this directory, run the
 264 following commands to clone the ~ninfacyzga-01~ git repository:
 265 : $ git clone https://zdv2.bktei.com/gitweb/ninfacyzga-01.git
 266 : $ cd ninfacyzga-01
 267
 268 Check out the ~develop~ branch (if the latest changes are desired over
 269 those of the ~master~ branch).
 270 : $ git checkout --track origin/develop
 271
 272 ****** ~age~
 273 ~age~ is required for encrypting data at rest.
 274
 275 Place ~age~ binary (the one compiled for ARM CPU architecture for
 276 Linux) in ~$HOME/.local/bin~. A copy of binary may be found within the
 277 ~exec~ directory.
 278
 279 : $ mkdir ~/.local/bin
 280 : $ cp exec/age ~/.local/bin/
 281
 282 ***** Disable Swap File
 283 Since standard Raspberry OS 10 install involves copying unencrypted
 284 file system image to SD card which is mounted by the Raspberry Pi,
 285 system memory may be written to disk in the form of a Swap file as
 286 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
 287 is ever written to disk, swap file functionality must be
 288 disabled[fn:ideaheap_20130731_disableswap].
 289
 290 Raspbian 10 uses dphys-swapfile to manage a swap file. It may be
 291 disabled persistently[fn:rpf_20190702_disableswappersist] by running
 292 the following command:
 293
 294 : sudo systemctl disable dphys-swapfile.service
 295
 296 To view the status of the swap file in Raspbian 10, run ~free -m~:
 297
 298 #+BEGIN_EXAMPLE
 299 pi@ninfacyzga-01:~$ free -m
 300           total    used    free  shared  buff/cache   available
 301 Mem:        432      86      36      21         309         268
 302 Swap:        99       0      99
 303 #+END_EXAMPLE
 304
 305 After disabling the swap file and rebooting:
 306
 307 #+BEGIN_EXAMPLE
 308 pi@ninfacyzga-01:~$ free -m
 309           total    used    free  shared  buff/cache   available
 310 Mem:        432      89     214       3         128         289
 311 Swap:         0       0       0
 312 #+END_EXAMPLE
 313
 314 [fn:ideaheap_20130731_disableswap] Explanation:
 315 https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/
 316
 317 [fn:rpf_20190702_disableswappersist] Persistant disabling of swap in
 318 Raspbian 10 Buster:
 319 https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692
 320
 321 ***** Disable Bluetooth
 322 In order to reduce power consumed by bluetooth transmissions,
 323 bluetooth functionality should be disabled (see [[https://di-marco.net/blog/it/2020-04-18-tips-disabling_bluetooth_on_raspberry_pi/][link]]).
 324
 325 Modify the ~/boot/config.txt~ file (the Pi's equivalent to BIOS
 326 settings; see [[https://www.raspberrypi.org/documentation/configuration/config-txt/][link]]) to make sure the following lines are added:
 327
 328 #+BEGIN_EXAMPLE
 329 # Disable Bluetooth
 330 dtoverlay=disable-bt
 331 #+END_EXAMPLE
 332
 333 The ~hciuart~ service is associated with bluetooth functionality via
 334 UART which may conflict with location and time data provided via
 335 ~/dev/ttyAMA0~. It should be disabled like so:
 336
 337 #+BEGIN_EXAMPLE
 338 $ sudo systemctl disable hciuart
 339 #+END_EXAMPLE
 340
 341 ***** Disable login console via serial port
 342 Some ~ninfacyzga~ functions (location and time) require data transfer
 343 via ~/dev/ttyAMA0~. In order to prevent serial login programs from
 344 interfering with such functions, it is necessary to disable them.
 345
 346 Run the following commands to disable login via ~ttyAMA0~:
 347
 348 #+BEGIN_EXAMPLE
 349 $ sudo systemctl stop serial-getty@ttyAMA0.service
 350 $ sudo systemctl disable serial-getty@ttyAMA0.service
 351 $ sudo systemctl disable hciuart
 352 #+END_EXAMPLE
 353
 354 Modify ~/boot/cmdline.txt~ to remove the console:
 355
 356 #+BEGIN_EXAMPLE
 357 $ sudo nano /boot/cmdline.txt
 358 #+END_EXAMPLE
 359
 360 Remove ~console=serial0,115200~
 361
 362 ***** Log Transfer Configuration
 363 Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
 364 manual for how to set up a shared folder and add Ninfacyzga-01 as a
 365 device. Syncthing's directory synchronization capability allows a
 366 remote machine to delete files from Ninfacyzga-01 by deleting from the
 367 shared folder that they both share.
 368
 369 When log files are removed from Ninfacyzga-01 is not within the scope
 370 of this document.
 371 ***** Key Generation
 372 An ~age~ encryption key may be generated like so:
 373 #+BEGIN_EXAMPLE
 374 $ umask          # Gets current umask
 375 0022             # Note: This is the default umask for Raspbian 10
 376 $ umask 066      # So key.txt will have no perms except for owner (you)
 377 $ umask          # Confirm umask set to 066
 378 0066
 379 $ age-keygen > key.txt
 380 Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
 381 $ ls -al key.txt
 382 -rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
 383 $ umask 0022     # Return umask to default value
 384 $ umask
 385 0022
 386 #+END_EXAMPLE
 387
 388 The resulting public/private keypair data looks like:
 389 #+BEGIN_EXAMPLE
 390 $ cat key.txt
 391 # created: 2020-06-29T18:01:56Z
 392 # public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
 393 AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
 394 #+END_EXAMPLE
 395
 396 The file ~key.txt~ is not password-protected by default and should be
 397 secured like an SSH public key should. The ~$ umask 066~ command run
 398 before the ~$ age-keygen > key.txt~ command ensures ~key.txt~ will not
 399 be readable, writeable, or executable to anyone except the owner
 400 (you).
 401
 402 *** Normal Startup
 403 *** Normal Operation
 404 *** Normal Shutdown
 405 *** Unscheduled Shutdown
 406 *** End of Life Disposal
 407 See [[file:../setup/README.org][Main Setup]] procedures.
 408
 409 LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of
 410 properly with their potential ignitability in mind, especially if they
 411 are not fully discharged.
 412
 413 Consult your local municipality for its "E-Waste Disposal" (or
 414 equivalent) policy. Metals used in the Raspberry Pi and related
 415 components may be recycled.
 416
 417 Take extra precuation if lead solder was used in assembling the
 418 electronics. Consumer electronics in early 21st century should use
 419 lead-free solder.
 420
 421
 422