From 0a12622b37491d3f143ce8addd2ddaed5e1e3876 Mon Sep 17 00:00:00 2001
From: Dmitrii Kuvaiskii <dmitrii.kuvaiskii@intel.com>
Date: Fri, 10 May 2024 05:43:24 -0700
Subject: [PATCH] Deprecate `GSC_PAL` and use instead `GRAMINE_MODE`

Previously, to run `gramine-direct`, one had to specify `docker run ...
--env GSC_PAL=Linux`. This was cumbersome because (1) Gramine users
don't need to know the meaning of word "PAL", (2) the value "Linux"
doesn't correspond to known-to-users `gramine-direct`, (3) it requires
special logic in apploader code.

This commit introduces instead `GRAMINE_MODE` envvar with easier
semantics: the value is the one of `direct` and `sgx`, i.e. the mode in
which user wants to invoke Gramine.

Signed-off-by: Dmitrii Kuvaiskii <dmitrii.kuvaiskii@intel.com>
---
 Documentation/index.rst             | 33 +++++++++++++---------
 templates/apploader.common.template | 43 +++++++++++++++++++++++------
 2 files changed, 54 insertions(+), 22 deletions(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index dcd20d3e..781de0a8 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -396,26 +396,27 @@ executable arguments may be supplied to the :command:`docker run` command.
    :command:`gsc build`.
 
 
-Execute with Linux PAL (:program:`gramine-direct`)
---------------------------------------------------
+Execute with :program:`gramine-direct`
+--------------------------------------
 
-You may select the Linux PAL (:program:`gramine-direct`) at Docker run time
-instead of the Linux-SGX PAL (:program:`gramine-sgx`) by specifying the
-environment variable :envvar:`GSC_PAL` as an option to the
-:command:`docker run` command. When using the Linux PAL, it is not necessary
-to sign the image via a :command:`gsc sign-image` command.
+By default, the Docker container starts :program:`gramine-sgx`.
 
-.. envvar:: GSC_PAL
+You may choose to start :program:`gramine-direct` in the Docker container by
+specifying the environment variable :envvar:`GRAMINE_MODE` as a command-line
+option to :command:`docker run`.
 
-   This environment variable specifies the pal loader.
+.. envvar:: GRAMINE_MODE
 
-GSC requires a custom seccomp profile while running with Linux PAL, which has to be
-specified at Docker run time. There are two options:
+   This environment variable specifies the mode of Gramine to run. Currently
+   supported values are ``direct`` and ``sgx``. Default is ``sgx``.
+
+GSC requires a custom seccomp profile for the ``direct`` mode. There are two
+options:
 
 #. Pass `unconfined` to run the container without the default seccomp profile.
    This option is generally considered insecure, since this results in containers
    running with unrestricted system calls (all system calls are allowed which
-   increases the attack surface of the Linux Kernel).
+   increases the attack surface of the Linux kernel).
 
 #. Pass the custom seccomp profile
    https://github.com/gramineproject/gramine/blob/master/scripts/docker_seccomp.json.
@@ -426,7 +427,13 @@ specified at Docker run time. There are two options:
 
 .. code-block:: sh
 
-   docker run ... --env GSC_PAL=Linux --security-opt seccomp=<profile> gsc-<image-name> ...
+   docker run ... --env GRAMINE_MODE=direct \
+       --security-opt seccomp=<profile> \
+       gsc-<image-name> ...
+
+.. note::
+    Previously, to run in ``direct`` mode, one specified ``--env
+    GSC_PAL=Linux``. This is deprecated in GSC v1.8 and will be removed in v1.9.
 
 Example
 =======
diff --git a/templates/apploader.common.template b/templates/apploader.common.template
index 52f4bbec..767eb083 100644
--- a/templates/apploader.common.template
+++ b/templates/apploader.common.template
@@ -8,13 +8,38 @@ set -e
 # Export distro-specific paths (typically `PYTHONPATH` and `PKG_CONFIG_PATH`)
 {% block path %}{% endblock %}
 
-# Default to Linux-SGX if no PAL was specified
-if [ -z "$GSC_PAL" ] || [ "$GSC_PAL" == "Linux-SGX" ]
-then
-    exec gramine-sgx /gramine/app_files/entrypoint \
-        {% if insecure_args %}{{ binary_arguments | map('shlex_quote') | join(' ') }} \
-        "${@}"{% endif %}
-else
-    exec gramine-direct /gramine/app_files/entrypoint \
-    {{ binary_arguments | map('shlex_quote') | join(' ') }} "${@}"
+# Note: default to SGX if Gramine mode (`direct`, `sgx`) wasn't specified
+GRAMINE_EXEC=gramine-sgx
+
+# TODO: remove GSC_PAL in GSC v1.9
+if [ -n "$GSC_PAL" ] && [ -n "$GRAMINE_MODE" ]; then
+    echo "ERROR: GSC_PAL and GRAMINE_MODE environment variables cannot be set together."
+    exit 1
+fi
+
+if [ -n "$GSC_PAL" ]; then
+    echo "WARNING: GSC_PAL environment variable is deprecated in v1.8 and will be removed in v1.9."
+    echo "         Instead, use GRAMINE_MODE={direct|sgx}."
+
+    # legacy logic was peculiar: if GSC_PAL != Linux-SGX then we set Gramine to `gramine-direct`
+    if [ "$GSC_PAL" == "Linux-SGX" ]; then
+        GRAMINE_EXEC=gramine-sgx
+    else
+        GRAMINE_EXEC=gramine-direct
+    fi
 fi
+
+if [ -n "$GRAMINE_MODE" ]; then
+    if [ "$GRAMINE_MODE" == "sgx" ]; then
+        GRAMINE_EXEC=gramine-sgx
+    elif [ "$GRAMINE_MODE" == "direct" ]; then
+        GRAMINE_EXEC=gramine-direct
+    else
+        echo "ERROR: unrecognized GRAMINE_MODE; can only be 'direct' or 'sgx'."
+        exit 1
+    fi
+fi
+
+exec ${GRAMINE_EXEC} /gramine/app_files/entrypoint \
+    {% if insecure_args %}{{ binary_arguments | map('shlex_quote') | join(' ') }} \
+    "${@}"{% endif %}