Deprecate GSC_PAL and use instead GRAMINE_MODE

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
 =======

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 %}