Merge pull request SensorsIot#192 from Paraphraser/20201207-sudo-protection

Try to head off problems created by unnecessary use of sudo

Author: Slyke

docs/Getting-Started.md

@@ -6,6 +6,54 @@ Andreas Spiess video #295
 
 [![#295 Raspberry Pi Server](http://img.youtube.com/vi/a6mjt8tWUws/0.jpg)](https://www.youtube.com/watch?v=a6mjt8tWUws)
 
+## A word about the `sudo` command
+
+Many first-time users of IOTstack get into difficulty by misusing the `sudo` command. The problem is best understood by example. In the following, you would expect `~` (tilde) to expand to `/home/pi`. It does:
+
+```
+$ echo ~/IOTstack
+/home/pi/IOTstack
+```
+
+The command below sends the same `echo` command to `bash` for execution. This is what happens when you type the name of a shell script. You get a new instance of `bash` to run the script:
+
+```
+$ bash -c 'echo ~/IOTstack'
+/home/pi/IOTstack
+```
+
+Same answer. Again, this is what you expect. But now try it with `sudo` on the front:
+
+```
+$ sudo bash -c 'echo ~/IOTstack'
+/root/IOTstack
+```
+
+The answer is different. It is different because `sudo` means "become root, and then run the command". The process of becoming root changes the home directory, and that changes the definition of `~`.
+
+Any script designed for working with IOTstack assumes `~` (or the equivalent `$HOME` variable) expands to `/home/pi`. That assumption is invalidated if the script is run by `sudo`.
+
+Of necessity, any script designed for working with IOTstack will have to invoke `sudo` **inside** the script **when it is required**. You do not need to second-guess the script's designer.
+
+Please try to minimise your use of `sudo` when you are working with IOTstack. Here are some rules of thumb:
+
+1. Is what you are about to run a script? If yes, check whether the script already contains `sudo` commands. Using `menu.sh` as the example:
+
+	```
+	$ grep -c 'sudo' ~/IOTstack/menu.sh
+	28
+	```
+	
+	There are 28 separate uses of `sudo` within `menu.sh`. That means the designer thought about when `sudo` was needed.
+	
+2. Did the command you **just executed** work without `sudo`? Note the emphasis on the past tense. If yes, then your work is done. If no, and the error suggests elevated privileges are necessary, then re-execute the last command like this:
+
+	```
+	$ sudo !!
+	```
+
+It takes time, patience and practice to learn when `sudo` is **actually** needed. Over-using `sudo` out of habit, or because you were following a bad example you found on the web, is a very good way to find that you have created so many problems for yourself that will need to reinstall your IOTstack. *Please* err on the side of caution!
+
 ## Download the project
 
 You may need to install these support tools first:

menu.sh

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# should not run as root
+[ "$EUID" -eq 0 ] && echo "This script should NOT be run using sudo" && exit -1
+
 #get path of menu correct
 pushd ~/IOTstack
 

scripts/backup_influxdb.sh

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# should not run as root
+[ "$EUID" -eq 0 ] && echo "This script should NOT be run using sudo" && exit -1
+
 #first move the contents of the old backup out and clear the directory
 echo "Moving old influxdb backups if they exist"
 [ -d ~/IOTstack/backups/influxdb/db_old ] || sudo mkdir ~/IOTstack/backups/influxdb/db_old

scripts/docker_backup.sh

@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# should not run as root
+[ "$EUID" -eq 0 ] && echo "This script should NOT be run using sudo" && exit -1
+
 pushd ~/IOTstack
 USER=$(whoami)
 

scripts/prune-images.sh

@@ -1 +1,6 @@
+#!/bin/bash
+
+# should not run as root
+[ "$EUID" -eq 0 ] && echo "This script should NOT be run using sudo" && exit -1
+
 docker image prune -a

scripts/prune-volumes.sh

@@ -1,2 +1,6 @@
-docker system prune --volumes
+#!/bin/bash
+
+# should not run as root
+[ "$EUID" -eq 0 ] && echo "This script should NOT be run using sudo" && exit -1
 
+docker system prune --volumes

scripts/restart.sh

@@ -1 +1,6 @@
+#!/bin/bash
+
+# should not run as root
+[ "$EUID" -eq 0 ] && echo "This script should NOT be run using sudo" && exit -1
+
 docker-compose restart

scripts/start.sh

@@ -1 +1,6 @@
-docker-compose up -d
+#!/bin/bash
+
+# should not run as root
+[ "$EUID" -eq 0 ] && echo "This script should NOT be run using sudo" && exit -1
+
+docker-compose up -d

scripts/stop-all.sh

@@ -1 +1,6 @@
+#!/bin/bash
+
+# should not run as root
+[ "$EUID" -eq 0 ] && echo "This script should NOT be run using sudo" && exit -1
+
 docker container stop $(docker container ls -aq)

scripts/stop.sh

@@ -1 +1,6 @@
-docker-compose down
+#!/bin/bash
+
+# should not run as root
+[ "$EUID" -eq 0 ] && echo "This script should NOT be run using sudo" && exit -1
+
+docker-compose down