Quick Start

Prerequisites

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.

If your system doesn’t meet these requirements, please refer to more detailed descriptions in Custom-Build Gramine.

We supply a tool is-sgx-available – Check environment for SGX compatibility, which you can use to check your hardware and system. It’s installed together with the respective gramine package you install from the options below.

Install Gramine

On Ubuntu 18.04 or 20.04 distributions (for 18.04, in intel-sgx.list, replace focal with bionic), run the following:

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

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
# (if you're on Ubuntu 18.04, remember to write "bionic" instead of "focal")

Next, select one of the three options below. You will get pre-packaged gramine binaries from an Ubuntu repo:

sudo apt-get update

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 RHEL-8-like distributions (like AlmaLinux 8, CentOS 8, Rocky Linux 8, …) run the following:

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

Prepare a signing key

Only for SGX, and if you haven’t already, enter the following:

gramine-sgx-gen-private-key

This command generates an RSA 3072 key suitable for signing SGX enclaves and stores it in HOME/.config/gramine/enclave-key.pem. Protect this key and do not disclose it to anyone.

Run the sample application

The core Gramine repository contains several sample applications. Thus, to test the Gramine installation, clone the Gramine repo:

git clone --depth 1  https://github.com/gramineproject/gramine.git

Don’t build Gramine as it is already installed on the system. Instead, build and run the HelloWorld example. To build the HelloWorld application, access the gcc compiler and the make build system by entering the following:

sudo apt-get install gcc make  # for Ubuntu distribution
sudo dnf install gcc make      # for RHEL-8-like distribution

Go to the HelloWorld example directory:

cd gramine/CI-Examples/helloworld

Build and run without SGX:

make
gramine-direct helloworld

Build and run with SGX:

make SGX=1
gramine-sgx helloworld

Other sample applications

Several applications that demonstrate Gramine usability are avaliable in the CI-Examples directory in the repository. Each application contains a short README file with instructions how to test it. We recommend starting with a simpler, thoroughly documented example of Redis in order to understand manifest options and Gramine features.

Additional sample configurations for applications enabled in Gramine are available in a separate repository https://github.com/gramineproject/examples.

Note that these sample applications are tested on Ubuntu 18.04 and 20.04. Most of these applications 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).

glibc vs musl

Most of the examples we provide use GNU C Library (glibc). If your application is built against musl libc, you can pass 'musl' to gramine.runtimedir() when generating the manifest from a template; this will mount musl libc (instead of the default glibc).