This user guide provides the steps to run Occlum with Docker and OCI Runtime rune.

rune is a novel OCI Runtime used to run trusted applications in containers with the hardware-assisted enclave technology.

Occlum is a memory-safe, multi-process library OS for Intel SGX.

Requirements

Ensure that you have one of the following required operating systems to build a Occlum container image:
- CentOS 8.1
- Ubuntu 18.04-server
Please follow Intel SGX Installation Guide to install Intel SGX driver, Intel SGX SDK & PSW for Linuxw.
- For CentOS 8.1, UAE service libraries are needed but may not installed if SGX PSW installer is used. Please manually install it:
```
rpm -i libsgx-uae-service-2.11.100.2-1.el8.x86_64.rpm
```
  - Install enable_rdfsbase kernel module, allowing to use FSGSBASE instructions in Occlum.
  - Install rune and occlum-pal from Inclavare Container release page.
  - For CentOS 8.1:
  - Add the repository to your sources.
```
cat >/etc/yum.repos.d/inclavare-containers.repo <<EOF
[inclavare-containers]
name=inclavare-containers
enabled=1
baseurl=https://mirrors.openanolis.org/inclavare-containers/rpm-repo/
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://mirrors.openanolis.org/inclavare-containers/rpm-repo/RPM-GPG-KEY-rpm-sign
gpgcakey=https://mirrors.openanolis.org/inclavare-containers/rpm-repo/RPM-GPG-KEY-rpm-sign-ca
EOF
```
1. Install the RPM packages.
```
yum install rune occlum-pal
```
  - For Ubuntu 18.04-server:
  - Add the repository to your sources. shell echo 'deb [arch=amd64] https://mirrors.openanolis.org/inclavare-containers/deb-repo bionic main' | tee /etc/apt/sources.list.d/inclavare-containers.list
2. Add the key to the list of trusted keys used by the apt to authenticate packages.
```
wget -qO - https://mirrors.openanolis.org/inclavare-containers/deb-repo/DEB-GPG-KEY.key | apt-key add -
```
  1. Update the apt and install the packages. shell apt-get update apt-get install rune occlum-pal

Building Occlum container image

Launch Occlum SDK container image

mkdir "$HOME/rune_workdir"
version=0.16.0-centos8.1
docker run -it --privileged --device /dev/isgx \
  -v "$HOME/rune_workdir":/root/rune_workdir \
  occlum/occlum:${version}

Prepare “hello world” demo program

This tutorial can help you to create your first occlum build.

Assuming “hello world” demo program is built, execute the following command:

cp -a occlum_instance /root/rune_workdir

Create Occlum container image

Now you can build your occlum container image in the $HOME/rune_workdir directory of your host system.

Type the following commands to create a Dockerfile:

cd "$HOME/rune_workdir"
cat >Dockerfile <<EOF
FROM centos:8.1.1911

RUN mkdir -p /run/rune/occlum_instance
WORKDIR /run/rune

COPY occlum_instance occlum_instance

ENTRYPOINT ["/bin/hello_world"]
EOF

then build the Occlum container image with the command:

docker build . -t occlum-app

Configuring OCI Runtime rune for Docker

Add the assocated configuration for rune in dockerd config file, e.g, /etc/docker/daemon.json, on your system.

{
    "runtimes": {
        "rune": {
            "path": "/usr/bin/rune",
            "runtimeArgs": []
        }
    }
}

then restart dockerd on your system.

You can check whether rune is correctly enabled or not with:

docker info | grep rune

The expected result would be:

Runtimes: rune runc

Running Occlum container image

You need to specify a set of parameters to docker run to run:

docker run -it --rm --runtime=rune \
  -e ENCLAVE_TYPE=intelSgx \
  -e ENCLAVE_RUNTIME_PATH=/opt/occlum/build/lib/libocclum-pal.so \
  -e ENCLAVE_RUNTIME_ARGS=occlum_instance \
  occlum-app

where:
@ENCLAVE_TYPE: specify the type of enclave hardware to use, such as intelSgx.
@ENCLAVE_PATH: specify the path to enclave runtime PAL to launch.
@ENCLAVE_ARGS: specify the specific arguments to enclave runtime PAL, separated by the comma.

Quick Start