Merge pull request #1595 from maresb/envvar-comments

Envvar comments

base-notebook/start.sh

@@ -168,12 +168,33 @@ if [ "$(id -u)" == 0 ] ; then
         PATH="${PATH}" \
         PYTHONPATH="${PYTHONPATH:-}" \
         "${cmd[@]}"
-        # Note on the purpose of "PATH=${PATH}":
-        #   In case "${cmd[@]}" is "bash", then PATH will be used by this bash shell.
-        #   However, PATH is irrelevant to how the above sudo command resolves the
-        #   path of "${cmd[@]}". Sudo's path resolution is done via the "secure_path"
-        #   variable set above in /etc/sudoers.d/path.
-
+        # Notes on how we ensure that the environment that this container is started
+        # with is preserved (except vars listed in JUPYTER_ENV_VARS_TO_UNSET) when
+        # we transition from running as root to running as NB_USER.
+        #
+        # - We use `sudo` to execute the command as NB_USER. What then
+        #   happens to the environment will be determined by configuration in
+        #   /etc/sudoers and /etc/sudoers.d/* as well as flags we pass to the sudo
+        #   command. The behavior can be inspected with `sudo -V` run as root.
+        #
+        #   ref: `man sudo`    https://linux.die.net/man/8/sudo
+        #   ref: `man sudoers` https://www.sudo.ws/man/1.8.15/sudoers.man.html
+        #
+        # - We use the `--preserve-env` flag to pass through most environment
+        #   variables, but understand that exceptions are caused by the sudoers
+        #   configuration: `env_delete` and `env_check`.
+        #
+        # - We use the `--set-home` flag to set the HOME variable appropriately.
+        #
+        # - To reduce the default list of variables deleted by sudo, we could have
+        #   used `env_delete` from /etc/sudoers. It has higher priority than the
+        #   `--preserve-env` flag and the `env_keep` configuration.
+        #
+        # - We preserve PATH and PYTHONPATH explicitly. Note however that sudo
+        #   resolves `${cmd[@]}` using the "secure_path" variable we modified
+        #   above in /etc/sudoers.d/path. Thus PATH is irrelevant to how the above
+        #   sudo command resolves the path of `${cmd[@]}`. The PATH will be relevant
+        #   for resolving paths of any subprocesses spawned by `${cmd[@]}`.
 
 # The container didn't start as the root user, so we will have to act as the
 # user we started as.