From 3fb58326725e07a78fa486765374ebb0cb9f299c Mon Sep 17 00:00:00 2001 From: hustliyilin Date: Tue, 30 Jun 2020 20:29:16 +0800 Subject: [PATCH] docs: Update rune 0.2.0 release docs - Add docs/running_rune_with_occlum_bundle.md - Remove docs/running_rune_with_docker.md - Update skeleton README.md to add way to run rune with skeleton bundle - Update README.md of inclavare-containers - Add docs/running_rune_with_occlum.md Signed-off-by: Yilin Li --- README.md | 8 +- docs/running_rune_with_docker.md | 51 ------- docs/running_rune_with_occlum.md | 139 ++++++++++++++++++ docs/running_rune_with_occlum_bundle.md | 67 +++++++++ .../internal/runtime/pal/skeleton/README.md | 68 ++++++++- 5 files changed, 270 insertions(+), 63 deletions(-) delete mode 100644 docs/running_rune_with_docker.md create mode 100644 docs/running_rune_with_occlum.md create mode 100644 docs/running_rune_with_occlum_bundle.md diff --git a/README.md b/README.md index 5261d73..eb9bb69 100644 --- a/README.md +++ b/README.md @@ -45,14 +45,14 @@ In addition, you can write your own enclave runtime with any programming languag ## Using rune ### Run Occlum -Please refer to [this guide](https://github.com/occlum/occlum/blob/master/docs/rune_quick_start.md) to run `Occlum` with `rune`. - -### Run Docker -Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_docker.md) to run `Docker` with `rune`. +Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum_bundle.md) to run `Occlum` with `rune`. ### Run skeleton Skeleton is an example of enclave runtime, interfacing with Enclave Runtime PAL API for easy interfacing with `rune`. Skeleton sample code is helpful to write your own enclave runtime. Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/skeleton/README.md) to run skeleton with `rune`. +### Run OCI bundle +Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum_bundle.md) to run `occlum bundle` with `rune`. + For more information about Enclave Runtime PAL API, please refer to [Enclave Runtime PAL API Specification](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/spec.md). diff --git a/docs/running_rune_with_docker.md b/docs/running_rune_with_docker.md deleted file mode 100644 index 3ecc602..0000000 --- a/docs/running_rune_with_docker.md +++ /dev/null @@ -1,51 +0,0 @@ -# Quick Start: Running rune with Docker -## Build and install rune -`rune` is a CLI tool for spawning and running enclaves in containers according to the OCI specification. - -Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/README.md#rune) to build `rune` from scratch. - ---- - -## Configure Docker runtimes -Add the `rune` OCI runtime configuration in dockerd config file (`/etc/docker/daemon.json`) in your system. - -``` JSON -{ - "runtimes": { - "rune": { - "path": "/usr/local/sbin/rune", - "runtimeArgs": [] - } - } -} -``` - -then restart docker service on your system. -> e.g. `sudo systemctl restart docker` for CentOS, or `sudo service docker restart` for Ubuntu - -You can check whether `rune` is correctly added to container runtime or not with -``` shell -sudo docker info | grep rune -Runtimes: rune runc -``` - ---- - -## Running Docker using rune -You need to specify a set of parameters to `docker run` in order to use `rune`, e.g, - -``` shell -docker run -it --rm --runtime=rune \ - -e ENCLAVE_TYPE=intelSgx \ - -e ENCLAVE_RUNTIME_PATH=/run/rune/liberpal-skeleton.so \ - -e ENCLAVE_RUNTIME_ARGS=skeleton,debug \ - $image -``` - -where: -- @runtime: choose the runtime (`rune`, `runc` or others) to use for this container. -- @ENCLAVE_TYPE: specify the type of enclave hardware to use, such as `intelSgx`. -- @ENCLAVE_PATH: specify the path to enclave runtime to launch. -- @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, seperated by the comma. - -Note that the skeleton is a sample enclave runtime. Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/skeleton/README.md) to run skeleton with `rune`. In addition, refer to [this guide]() to run more useful Occlum library OS. diff --git a/docs/running_rune_with_occlum.md b/docs/running_rune_with_occlum.md new file mode 100644 index 0000000..ea9258e --- /dev/null +++ b/docs/running_rune_with_occlum.md @@ -0,0 +1,139 @@ +# Quick Start: rune on Occlum + +[rune](https://github.com/alibaba/inclavare-containers) is a set of tools for running trusted applications in containers with the hardware-assisted enclave technology. + +## Hardware requirements +- Install [Intel SGX driver for Linux](https://github.com/intel/linux-sgx-driver#build-and-install-the-intelr-sgx-driver), required by Intel SGX SDK && PSW. +- Install [enable_rdfsbase kernel module](https://github.com/occlum/enable_rdfsbase#how-to-build), allowing to use `rdfsbase` -family instructions in Occlum. + +--- + +## Build Occlum application Docker image +### Download Occlum sdk image +``` shell +docker pull occlum/occlum:0.13.0-centos7.5 +docker run -it --privileged --device /dev/isgx \ + occlum/occlum:0.13.0-centos7.5 +``` + +### Prepare the materials +Before Occlum build, execute the following command to set your Occlum instance dir: +``` shell +export OCCLUM_INSTANCE_DIR=occlum-app +``` +You can build a "hello world" demo application or your own product with an [Occlum CentOS Docker image](https://hub.docker.com/r/occlum/occlum/tags). + +[This guide](https://github.com/occlum/occlum#hello-occlum) can help you to create your first occlum build. + +After Occlum build, execute the following commands in Occlum sdk container environment: + +``` shell +yum install -y libseccomp-devel +mkdir /root/rune_workdir +cp -a ${OCCLUM_INSTANCE_DIR} /root/rune_workdir +cd /root/rune_workdir +cp ${OCCLUM_INSTANCE_DIR}/build/lib/libocclum-pal.so /usr/lib/liberpal-occlum.so +``` + +### Build occlum application image +Now you can build your occlum application image in the same Occlum sdk container environment. + +You need to [download docker](https://docs.docker.com/engine/install/centos/) in the Occlum sdk container environment. And type the following command to start your docker service. +``` shell +dockerd -b docker0 --storage-driver=vfs & +``` + +Type the following commands to create a `Dockerfile`: +``` Dockerfile +cat >Dockerfile < e.g. `sudo systemctl restart docker` for CentOS, or `sudo service docker restart` for Ubuntu + +You can check whether `rune` is correctly added to container runtime or not with +``` shell +sudo docker info | grep rune +Runtimes: rune runc +``` + +--- + +## Run Occlum application image using rune +You need to specify a set of parameters to `docker run` in order to use `rune`, e.g, + +``` shell +docker run -it --rm --runtime=rune \ + -e ENCLAVE_TYPE=intelSgx \ + -e ENCLAVE_RUNTIME_PATH=/usr/lib/liberpal-occlum.so \ + -e ENCLAVE_RUNTIME_ARGS=${OCCLUM_INSTANCE_DIR} \ + ${Occlum_application_image} +``` + +where: +- @runtime: choose the runtime (`rune`, `runc`, or others) to use for this container. +- @ENCLAVE_TYPE: specify the type of enclave hardware to use, such as `intelSgx`. +- @ENCLAVE_PATH: specify the path to enclave runtime to launch. For an Occlum application, you need to specify the path of `liberpal-occlum.so` which is a soft link to `libocclum-pal.so` of your Occlum instance dir (`OCCLUM_INSTANCE_DIR`). +- @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, separated by the comma. For an Occlum application, you need to specify the name of your Occlum instance dir (`OCCLUM_INSTANCE_DIR`) in this parameter. diff --git a/docs/running_rune_with_occlum_bundle.md b/docs/running_rune_with_occlum_bundle.md new file mode 100644 index 0000000..9c00449 --- /dev/null +++ b/docs/running_rune_with_occlum_bundle.md @@ -0,0 +1,67 @@ +# Quick Start: Running rune with Occlum bundle +## Build and install rune +`rune` is a CLI tool for spawning and running enclaves in containers according to the OCI specification. + +Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/README.md#rune) to build `rune` from scratch. + +--- + +## Build Occlum application docker image +Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum_bundle.md) to build the Occlum application Docker image. + +## Create Occlum application bundle +In order to use `rune` you must have your container in the format of an OCI bundle. If you have Docker installed you can use its `export` method to acquire a root filesystem from an existing Occlum application Docker container. + +``` shell +# create the top most bundle directory +mkdir -p "$HOME/rune_workdir" +cd "$HOME/rune_workdir" +mkdir rune-container +cd rune-container + +# create the rootfs directory +mkdir rootfs + +# export Occlum application image via Docker into the rootfs directory +docker export $(docker create ${Occlum_application_image}) | sudo tar -C rootfs -xvf - +``` + +After a root filesystem is populated you just generate a spec in the format of a config.json file inside your bundle. `rune` provides a spec command which is similar to `runc` to generate a template file that you are then able to edit. + +``` shell +rune spec +``` + +To find features and documentation for fields in the spec please refer to the [specs](https://github.com/opencontainers/runtime-spec) repository. + +In order to run the hello world demo program in Occlum with `rune`, you need to change the entrypoint from `sh` to `/bin/hello_world` +``` json + "process": { + "args": [ + "/bin/hello_world" + ], + } +``` + +and then configure enclave runtime as following: +``` json + "annotations": { + "enclave.type": "intelSgx", + "enclave.runtime.path": "/usr/lib/liberpal-occlum.so", + "enclave.runtime.args": "$OCCLUM_INSTANCE_DIR" + } +``` + +where: +- @enclave.type: specify the type of enclave hardware to use, such as `intelSgx`. +- @enclave.runtime.path: specify the path to enclave runtime to launch. For an Occlum application, you need to specify the path of `liberpal-occlum.so` which is a soft link to `libocclum-pal.so` of your Occlum instance dir (`OCCLUM_INSTANCE_DIR`). +- @enclave.runtime.args: specify the specific arguments to enclave runtime, separated by the comma. For an Occlum application, you need to specify the name of your Occlum instance dir (`OCCLUM_INSTANCE_DIR`) in this parameter. +--- + +## Run Occlum application +Assuming you have an OCI bundle from the previous step you can execute the container in this way. + +``` shell +cd "$HOME/rune_workdir/rune-container" +sudo rune run ${Occlum_application_container_name} +``` diff --git a/rune/libenclave/internal/runtime/pal/skeleton/README.md b/rune/libenclave/internal/runtime/pal/skeleton/README.md index bf5dd34..2664891 100644 --- a/rune/libenclave/internal/runtime/pal/skeleton/README.md +++ b/rune/libenclave/internal/runtime/pal/skeleton/README.md @@ -8,35 +8,32 @@ Refer to [this guide](https://github.com/alibaba/inclavare-containers/tree/maste ```shell cd "${path_to_inclavare_containers}/rune/libenclave/internal/runtime/pal/skeleton" make +cp liberpal-skeletion.so /usr/lib ``` # Build skeleton docker image ```shell cd "${path_to_inclavare_containers}/rune/libenclave/internal/runtime/pal/skeleton" cat >Dockerfile <