diff --git a/base-notebook/start.sh b/base-notebook/start.sh index b5a972ee..05c10376 100755 --- a/base-notebook/start.sh +++ b/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.