[Docs] Edit build and install docs for upcoming 1.4 release

Signed-off-by: Wojtek Porczyk <[email protected]>
gramineproject · Jan 31, 2023 · 5fb3154 · 5fb3154
1 parent f128bc4
commit 5fb3154
Show file tree

Hide file tree

Showing 5 changed files with 122 additions and 122 deletions.
diff --git a/Documentation/cloud-deployment.rst b/Documentation/cloud-deployment.rst
@@ -24,28 +24,19 @@ VM instances. The description below uses a *DCsv3 VM* running Ubuntu
 Install Gramine
 ^^^^^^^^^^^^^^^
 
-On Ubuntu 20.04::
+On Ubuntu 20.04 LTS and 18.04 LTS::
 
    sudo curl -fsSLo /usr/share/keyrings/gramine-keyring.gpg https://packages.gramineproject.io/gramine-keyring.gpg
-   echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg] https://packages.gramineproject.io/ focal main' | sudo tee /etc/apt/sources.list.d/gramine.list
+   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg] https://packages.gramineproject.io/ $(lsb_release -sc) main" \
+   | sudo tee /etc/apt/sources.list.d/gramine.list
 
-   curl -fsSL https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add -
-   echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu focal main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
+   sudo curl -fsSLo /usr/share/keyrings/intel-sgx-deb.asc https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
+   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-sgx-deb.asc] https://download.01.org/intel-sgx/sgx_repo/ubuntu $(lsb_release -sc) main" \
+   | sudo tee /etc/apt/sources.list.d/intel-sgx.list
 
    sudo apt-get update
    sudo apt-get install gramine
 
-On Ubuntu 18.04::
-
-   sudo curl -fsSLo /usr/share/keyrings/gramine-keyring.gpg https://packages.gramineproject.io/gramine-keyring.gpg
-   echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg] https://packages.gramineproject.io/ bionic main' | sudo tee /etc/apt/sources.list.d/gramine.list
-
-   curl -fsSL https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add -
-   echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu bionic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
-
-   sudo apt-get update
-   sudo apt-get install gramine-dcap
-
 Prepare a signing key
 ^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/Documentation/devel/building.rst b/Documentation/devel/building.rst
@@ -42,7 +42,8 @@ Run the following command on Ubuntu LTS to install dependencies::
 
 You can also install Meson, python3-tomli and python3-tomli-w from apt instead
 of pip, but only if your distro is new enough to have Meson >= 0.56,
-python3-tomli >= 1.1.0 and python3-tomli-w >= 0.4.0 (e.g. Ubuntu 22.04).
+python3-tomli >= 1.1.0 and python3-tomli-w >= 0.4.0 (e.g. Ubuntu 22.04 or Debian
+11 with ``bullseye-backports`` repo enabled).
 
 For GDB support and to run all tests locally you also need to install::
 
@@ -57,70 +58,34 @@ Dependencies for SGX
 ^^^^^^^^^^^^^^^^^^^^
 
 The build of Gramine with SGX support requires the corresponding SGX software
-infrastructure to be installed on the system. In particular, the FSGSBASE
-functionality must be enabled in the Linux kernel, the Intel SGX driver must be
-running, and Intel SGX SDK/PSW/DCAP must be installed.
+infrastructure to be installed on the system. We require Linux kernel with SGX
+driver built in (``CONFIG_X86_SGX=y``, which is the case for most of available
+distribution kernels), which is available since version 5.11 (and also as
+backported patches to older kernels in certain distros). Note this requires CPU
+with :term:`FLC`.
 
-.. note::
-
-   We recommend to use Linux kernel version 5.11 or higher: starting from this
-   version, Linux has the FSGSBASE functionality as well as the Intel SGX driver
-   built-in. If you have Linux 5.11+, skip steps 2 and 3.
-
-1. Required packages
-""""""""""""""""""""
-Run the following commands on Ubuntu to install SGX-related dependencies::
-
-    sudo apt-get install -y libprotobuf-c-dev protobuf-c-compiler \
-        protobuf-compiler python3-cryptography python3-pip python3-protobuf
-
-2. Install Linux kernel with patched FSGSBASE
-"""""""""""""""""""""""""""""""""""""""""""""
-
-FSGSBASE is a feature in recent processors which allows direct access to the FS
-and GS segment base addresses. For more information about FSGSBASE and its
-benefits, see `this discussion <https://lwn.net/Articles/821719>`__. Note that
-if your kernel version is 5.9 or higher, then the FSGSBASE feature is already
-supported and you can skip this step. Kernel version can be checked using the
-following command::
+Kernel version can be checked using the following command::
 
        uname -r
 
-If your current kernel version is lower than 5.9, then you have two options:
+If your current kernel version is lower than 5.11, then you have two options:
 
-- Update the Linux kernel to at least 5.9 in your OS distro. If you use Ubuntu,
+- Update the Linux kernel to at least 5.11 in your OS distro. If you use Ubuntu,
   you can follow e.g. `this tutorial
   <https://itsfoss.com/upgrade-linux-kernel-ubuntu/>`__.
 
-- Use our provided patches to the Linux kernel version 5.4. See section
-  :ref:`FSGSBASE` for the exact steps.
-
-3. Install the Intel SGX driver
-"""""""""""""""""""""""""""""""
-
-This step depends on your hardware and kernel version. Note that if your kernel
-version is 5.11 or higher, then the Intel SGX driver is already installed and
-you can skip this step.
+- Install out-of-tree driver and use our provided patches to the Linux kernel
+  version 5.4. See section :ref:`legacy-kernel-and-hardware` for the exact
+  steps.
 
-If you have an older CPU without :term:`FLC` support, you need to download and
-install the the following out-of-tree (OOT) Intel SGX driver:
-
-- https://github.com/intel/linux-sgx-driver
-
-For this driver, you need to set ``vm.mmap_min_addr=0`` in the system (*only
-required for the legacy SGX driver and not needed for newer DCAP/in-kernel
-drivers*)::
-
-   sudo sysctl vm.mmap_min_addr=0
-
-Note that this is an inadvisable configuration for production systems.
-
-Alternatively, if your CPU supports :term:`FLC`, you can choose to install the
-DCAP version of the Intel SGX driver from:
+1. Required packages
+""""""""""""""""""""
+Run the following commands on Ubuntu to install SGX-related dependencies::
 
-- https://github.com/intel/SGXDataCenterAttestationPrimitives
+    sudo apt-get install -y libprotobuf-c-dev protobuf-c-compiler \
+        protobuf-compiler python3-cryptography python3-pip python3-protobuf
 
-4. Install Intel SGX SDK/PSW
+2. Install Intel SGX SDK/PSW
 """"""""""""""""""""""""""""
 
 Follow the installation instructions from the "Intel SGX Software Installation
@@ -137,7 +102,7 @@ Additional information, package descriptions, etc. can be found in the official
 
 - https://github.com/intel/linux-sgx
 
-5. Install dependencies for DCAP
+3. Install dependencies for DCAP
 """"""""""""""""""""""""""""""""
 
 If you plan on enabling ``-Ddcap`` option, you need to install
@@ -299,8 +264,6 @@ Additional build options
   take a long time: unfortunately, the only supported way of building
   ``libgomp`` is as part of a complete GCC build.
 
-.. _FSGSBASE:
-
 Prepare a signing key
 ---------------------
 
@@ -368,14 +331,37 @@ Proceed with compiling and installing as usual.
     meson compile -C build/
     meson install -C build/
 
-Advanced: installing Linux kernel with FSGSBASE patches
--------------------------------------------------------
 
-FSGSBASE patchset was merged in Linux kernel version 5.9. For older kernels it
-is available as `separate patches
+.. _legacy-kernel-and-hardware:
+
+Legacy kernel and hardware
+--------------------------
+
+Although we recommend kernel version 5.11 or later, Gramine can be run on older
+kernels with out-of-tree SGX driver. OOT driver is also the only possibility to
+run Gramine on non-FLC hardware. In this configuration, we require kernel at
+least 5.4, and for kernels between 5.4 (inclusive) and 5.9 (exclusive) we
+additionally require FSGSBASE patchset (see below).
+
+Beware that some enterprise distributions provide kernels that report some old
+version, but actually provide upstream SGX driver that has been backported (like
+RHEL and derivatives since version 8, which has nominally kernel 4.18). If you
+have one of those enterprise kernels, this section does not apply. If in doubt,
+check kernel's ``.config`` and consult your distro documentation.
+
+1. Install Linux kernel with patched FSGSBASE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+FSGSBASE is a feature in recent processors which allows direct access to the FS
+and GS segment base addresses. For more information about FSGSBASE and its
+benefits, see `this discussion <https://lwn.net/Articles/821719>`__.
+
+FSGSBASE patchset was merged in Linux kernel version 5.9, so if your kernel
+version is 5.9 or higher, then the FSGSBASE feature is already supported and you
+can skip this step. For older kernels it is available as `separate patches
 <https://github.com/oscarlab/graphene-sgx-driver/tree/master/fsgsbase_patches>`__.
-(Note that Gramine was prevously called *Graphene* and was hosted under a
-different organization, hence the name of the linked repository.)
+(Note that Gramine was prevously called *Graphene* and was hosted under
+a different organization, hence the name of the linked repository.)
 
 The following instructions to patch and compile a Linux kernel with FSGSBASE
 support below are written around Ubuntu 18.04 LTS (Bionic Beaver) with a Linux
@@ -424,3 +410,28 @@ instructions ensure that the resulting kernel has FSGSBASE support.
 After the patched Linux kernel is installed, you may proceed with installations
 of other SGX software infrastructure: the Intel SGX Linux driver, the Intel SGX
 SDK/PSW, and Gramine itself.
+
+2. Install the Intel SGX driver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This step depends on your hardware and kernel version. Note that if your kernel
+version is 5.11 or higher, then the Intel SGX driver is already installed and
+you can skip this step.
+
+If you have an older CPU without :term:`FLC` support, you need to download and
+install the following out-of-tree (OOT) Intel SGX driver:
+
+- https://github.com/intel/linux-sgx-driver
+
+For this driver, you need to set ``vm.mmap_min_addr=0`` in the system (*only
+required for the legacy SGX driver and not needed for newer DCAP/in-kernel
+drivers*)::
+
+   sudo sysctl vm.mmap_min_addr=0
+
+Note that this is an inadvisable configuration for production systems.
+
+Alternatively, if your CPU supports :term:`FLC`, you can choose to install the
+DCAP version of the Intel SGX driver from:
+
+- https://github.com/intel/SGXDataCenterAttestationPrimitives
diff --git a/Documentation/devel/coding-style.rst b/Documentation/devel/coding-style.rst
@@ -169,7 +169,7 @@ Python
    python3`` shebang, Gramine would not be able to locate system-wide-installed
    Python packages.
 
-   Since Gramine currently supports only Debian/Ubuntu and CentOS/RHEL/Fedora
+   Since Gramine currently supports only Debian/Ubuntu and RHEL/AlmaLinux/Fedora
    distros, the shebang must always be ``#!/usr/bin/python3``.
 
 Meson

diff --git a/Documentation/devel/packaging.rst b/Documentation/devel/packaging.rst
@@ -2,13 +2,14 @@ Packaging and distributing
 ==========================
 
 Gramine project aims to support two most recent releases of the long-lived
-distributions (e.g. Debian, Ubuntu LTS, [the CentOS replacement that will
-hopefully emerge soon], ...).
+distributions (e.g. Debian, Ubuntu LTS, AlmaLinux and other CentOS replacements,
+...).
 
 Currently officially supported distributions:
 
-- Ubuntu (20.04 LTS, 18.04 LTS).
-- RHEL-8-like distributions (like AlmaLinux 8, CentOS 8, Rocky Linux 8, ...).
+- Ubuntu (22.04 LTS, 20.04 LTS, 18.04 LTS);
+- RHEL-8-like distributions (like AlmaLinux 8, Rocky Linux 8, ...);
+- experimentally, RHEL-9-like distros (packages are not fully validated).
 
 Exceptions
 ----------

diff --git a/Documentation/quickstart.rst b/Documentation/quickstart.rst
@@ -10,9 +10,8 @@ Gramine without SGX has no special requirements.
 
 Gramine with SGX support requires several features from your system:
 
-- the FSGSBASE feature of recent processors must be enabled in the Linux kernel;
-- the Intel SGX driver must be built in the Linux kernel;
-- Intel SGX SDK/PSW and (optionally) Intel DCAP must be installed.
+- Linux kernel version at least 5.11 (with SGX driver enabled);
+- Intel SGX PSW and (optionally) Intel DCAP must be installed and configured.
 
 If your system doesn't meet these requirements, please refer to more detailed
 descriptions in :doc:`devel/building`.
@@ -24,52 +23,50 @@ package (see below).
 Install Gramine
 ---------------
 
-On Ubuntu 22.04 and Debian 11::
+Debian 11
+^^^^^^^^^
+
+::
 
    sudo curl -fsSLo /usr/share/keyrings/gramine-keyring.gpg https://packages.gramineproject.io/gramine-keyring.gpg
-   echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg] https://packages.gramineproject.io/ stable main' | sudo tee /etc/apt/sources.list.d/gramine.list
+   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg] https://packages.gramineproject.io/ $(lsb_release -sc) main" \
+   | sudo tee /etc/apt/sources.list.d/gramine.list
 
-   curl -fsSL https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add -
-   echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu focal main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
+   sudo curl -fsSLo /usr/share/keyrings/intel-sgx-deb.asc https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
+   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-sgx-deb.asc] https://download.01.org/intel-sgx/sgx_repo/ubuntu focal main" \
+   | sudo tee /etc/apt/sources.list.d/intel-sgx.list
 
    sudo apt-get update
+   sudo apt-get install gramine
 
-   sudo apt-get install gramine      # for 5.11+ upstream, in-kernel driver
-   sudo apt-get install gramine-oot  # for out-of-tree SDK driver
-   sudo apt-get install gramine-dcap # for out-of-tree DCAP driver
+Ubuntu 22.04 LTS, 20.04 LTS or 18.04 LTS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-On Ubuntu 20.04::
+::
 
    sudo curl -fsSLo /usr/share/keyrings/gramine-keyring.gpg https://packages.gramineproject.io/gramine-keyring.gpg
-   echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg] https://packages.gramineproject.io/ focal main' | sudo tee /etc/apt/sources.list.d/gramine.list
+   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg] https://packages.gramineproject.io/ $(lsb_release -sc) main" \
+   | sudo tee /etc/apt/sources.list.d/gramine.list
 
-   curl -fsSL https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add -
-   echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu focal main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
+   sudo curl -fsSLo /usr/share/keyrings/intel-sgx-deb.asc https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
+   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-sgx-deb.asc] https://download.01.org/intel-sgx/sgx_repo/ubuntu $(lsb_release -sc) main" \
+   | sudo tee /etc/apt/sources.list.d/intel-sgx.list
 
    sudo apt-get update
+   sudo apt-get install gramine
 
-   sudo apt-get install gramine      # for 5.11+ upstream, in-kernel driver
-   sudo apt-get install gramine-oot  # for out-of-tree SDK driver
-   sudo apt-get install gramine-dcap # for out-of-tree DCAP driver
-
-On Ubuntu 18.04::
-
-   sudo curl -fsSLo /usr/share/keyrings/gramine-keyring.gpg https://packages.gramineproject.io/gramine-keyring.gpg
-   echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg] https://packages.gramineproject.io/ bionic main' | sudo tee /etc/apt/sources.list.d/gramine.list
-
-   curl -fsSL https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add -
-   echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu bionic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
+RHEL-like distributions version 8 (and experimentally also version 9)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-   sudo apt-get update
+(like AlmaLinux, Rocky Linux, ...)
 
-   sudo apt-get install gramine      # for 5.11+ upstream, in-kernel driver
-   sudo apt-get install gramine-oot  # for out-of-tree SDK driver
-   sudo apt-get install gramine-dcap # for out-of-tree DCAP driver
+1. Install EPEL repository as described here:
+   https://docs.fedoraproject.org/en-US/epel/
 
-On RHEL-8-like distribution (like AlmaLinux 8, CentOS 8, Rocky Linux 8, ...)::
+2. Install Gramine::
 
-   sudo curl -fsSLo /etc/yum.repos.d/gramine.repo https://packages.gramineproject.io/rpm/gramine.repo
-   sudo dnf install gramine          # only the default, distro-provided kernel is supported
+      sudo curl -fsSLo /etc/yum.repos.d/gramine.repo https://packages.gramineproject.io/rpm/gramine.repo
+      sudo dnf install gramine
 
 Prepare a signing key
 ---------------------
@@ -97,7 +94,7 @@ we want to build and run the HelloWorld example. To build the HelloWorld
 application, we need the ``gcc`` compiler and the ``make`` build system::
 
    sudo apt-get install gcc make  # for Ubuntu distribution
-   sudo dnf install gcc make      # for RHEL-8-like distribution
+   sudo dnf install gcc make      # for RHEL-like distribution
 
 Go to the HelloWorld example directory::
 
@@ -125,12 +122,12 @@ understand manifest options and features of Gramine.
 Additional sample configurations for applications enabled in Gramine can be
 found in a separate repository https://github.com/gramineproject/examples.
 
-Please note that these sample applications are tested on Ubuntu 18.04 and 20.04.
-Most of these applications are also known to run correctly on
-Fedora/RHEL/CentOS, but with caveats. One caveat is that Makefiles should be
-invoked with ``ARCH_LIBDIR=/lib64 make``. Another caveat is that applications
-that rely on specific versions/builds of Glibc may break (our GCC example is
-known to work only on Ubuntu).
+Please note that these sample applications are tested on Ubuntu. Most of these
+applications are also known to run correctly on Fedora/RHEL/AlmaLinux/Rocky
+Linux, but with caveats. One caveat is that Makefiles should be invoked with
+``ARCH_LIBDIR=/lib64 make``. Another caveat is that applications that rely on
+specific versions/builds of Glibc may break (our GCC example is known to work
+only on Ubuntu).
 
 glibc vs musl
 -------------