提交 627ff36f 编写于 作者: jia zhang's avatar jia zhang

docs: Refresh docs for 0.2.0 release

Signed-off-by: jia zhang's avatarJia Zhang <zhang.jia@linux.alibaba.com>
上级 3fb58326
# inclavare-containers # Inclavare Containers
## Introduction ## Introduction
`inclavare-containers` is a set of tools for running trusted applications in containers with the hardware-assisted enclave technology. Enclave, referred to as a protected execution environment, prevents the untrusted entity from accessing the sensitive and confidential assets in use. `inclavare-containers` is a set of tools for running trusted applications in containers with the hardware-assisted enclave technology. Enclave, referred to as a protected execution environment, prevents the untrusted entity from accessing the sensitive and confidential assets in use.
---
## Components ## Components
### rune ### rune
`rune` is a CLI tool for spawning and running enclaves in containers according to the OCI specification. The codebase of `rune` is a fork of [runc](https://github.com/opencontainers/runc), so `rune` can be used as `runc` if enclave is not configured or available. `rune` is a CLI tool for spawning and running enclaves in containers according to the OCI specification. The codebase of `rune` is a fork of [runc](https://github.com/opencontainers/runc), so `rune` can be used as `runc` if enclave is not configured or available.
...@@ -29,10 +31,10 @@ sudo make install ...@@ -29,10 +31,10 @@ sudo make install
`rune` will be installed to `/usr/local/sbin/rune` on your system. `rune` will be installed to `/usr/local/sbin/rune` on your system.
### shim-rune ### shim-rune
`shim-rune` resides in between `containerd` and `rune`, conducting enclave signing and management beyond the normal `shim` basis. `shim-rune` and `rune` can compose a basic enclave containerization stack for the cloud-native ecosystem. `shim-rune` resides in between `containerd` and `rune`, conducting enclave signing and management beyond the normal `shim` basis. `shim-rune` and `rune` can compose a basic enclave containerization stack for the cloud-native ecosystem. Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/shim/README.md) for the details.
### enclave runtime ### enclave runtime
The backend of `rune` is a component called enclave runtime, which is responsible for loading and running protected applications inside enclaves. The interface between `rune` and enclave runtime is [Enclave Runtime PAL API](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/spec.md), which allows invoking enclave runtime through well-defined functions. The software for confidential computing may benefit from this interface to interact with OCI runtime. The backend of `rune` is a component called enclave runtime, which is responsible for loading and running protected applications inside enclaves. The interface between `rune` and enclave runtime is [Enclave Runtime PAL API](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/spec_v2.md), which allows invoking enclave runtime through well-defined functions. The software for confidential computing may benefit from this interface to interact with OCI runtime.
One typical class of enclave runtime implementations is based on library OSes. Currently, the default enclave runtime interacting with `rune` is [Occlum](https://github.com/occlum/occlum), a memory-safe, multi-process library OS for Intel SGX. One typical class of enclave runtime implementations is based on library OSes. Currently, the default enclave runtime interacting with `rune` is [Occlum](https://github.com/occlum/occlum), a memory-safe, multi-process library OS for Intel SGX.
...@@ -45,14 +47,14 @@ In addition, you can write your own enclave runtime with any programming languag ...@@ -45,14 +47,14 @@ In addition, you can write your own enclave runtime with any programming languag
## Using rune ## Using rune
### Run Occlum ### Run Occlum
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`. Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum.md) to run `Occlum` with `rune`.
### Run skeleton ### 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. 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`. 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`.
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_v2.md).
### Run OCI bundle ### 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`. 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).
# Quick Start: rune on Occlum # Quick Start: running rune with Occlum
[rune](https://github.com/alibaba/inclavare-containers) is a new OCI runtime used to run trusted applications in containers with the hardware-assisted enclave technology.
[rune](https://github.com/alibaba/inclavare-containers) is a set of tools for running trusted applications in containers with the hardware-assisted enclave technology. ## Requirements
## 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 [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. - Install [enable_rdfsbase kernel module](https://github.com/occlum/enable_rdfsbase#how-to-build), allowing to use `rdfsbase` -family instructions in Occlum.
- Assume the host system is CentOS 7.5.
- You can also launch a CentOS 7.5 container as your host system with the following command:
```shell
```
If so, you need to run **another docker daemon** inside this CentOS 7.5 container. Please refer to [this guide](https://docs.docker.com/engine/install/centos) to install docker daemon, and type the following command to start dockerd.
```shell
dockerd -b docker0 --storage-driver=vfs &
```
--- ---
## Build Occlum application Docker image ## Build Occlum application container image
### Download Occlum sdk image ### Download Occlum SDK container image
``` shell ```shell
docker pull occlum/occlum:0.13.0-centos7.5 mkdir "$HOME/rune_workdir"
docker run -it --privileged --device /dev/isgx \ docker run -it --privileged --device /dev/isgx \
-v "$HOME/rune_workdir":/root/rune_workdir \
occlum/occlum:0.13.0-centos7.5 occlum/occlum:0.13.0-centos7.5
``` ```
### Prepare the materials ### Prepare the materials
Before Occlum build, execute the following command to set your Occlum instance dir: Before Occlum build, execute the following command to set your Occlum instance name:
``` shell
```shell
export OCCLUM_INSTANCE_DIR=occlum-app 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. [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: Assuming "hello world" demo program is built, execute the following commands in Occlum SDK container:
``` shell ```shell
yum install -y libseccomp-devel
mkdir /root/rune_workdir
cp -a ${OCCLUM_INSTANCE_DIR} /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 ### Prepare Occlum application image
Now you can build your occlum application image in the same Occlum sdk container environment. Now you can build your occlum application image in the $HOME/rune_workdir directory of your host system.
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`: Type the following commands to create a `Dockerfile`:
``` Dockerfile ``` Dockerfile
cd "$HOME/rune_workdir"
cat >Dockerfile <<EOF cat >Dockerfile <<EOF
FROM centos:7.5.1804 FROM centos:7.5.1804
...@@ -53,6 +54,7 @@ RUN mkdir -p /run/rune/${OCCLUM_INSTANCE_DIR} ...@@ -53,6 +54,7 @@ RUN mkdir -p /run/rune/${OCCLUM_INSTANCE_DIR}
WORKDIR /run/rune WORKDIR /run/rune
COPY ${OCCLUM_INSTANCE_DIR} ${OCCLUM_INSTANCE_DIR} COPY ${OCCLUM_INSTANCE_DIR} ${OCCLUM_INSTANCE_DIR}
COPY ${OCCLUM_INSTANCE_DIR}/build/lib/libocclum-pal.so /usr/lib/liberpal-occlum.so
ENTRYPOINT ["/bin/hello_world"] ENTRYPOINT ["/bin/hello_world"]
EOF EOF
...@@ -65,41 +67,39 @@ docker build . -t ${Occlum_application_image} ...@@ -65,41 +67,39 @@ docker build . -t ${Occlum_application_image}
--- ---
## Install rune binarys ## Install Inclavare Containers binary
You can download rune centos binarys from 0.2.0 release, it includes Download the binary release from [here](https://github.com/alibaba/inclavare-containers/releases/).
- `rune` : is a set of tools for running trusted applications in containers with the hardware-assisted enclave technology. You can install `rune` in `/usr/local/sbin` on your centos system.
- `liberpal-occlum.so` : is the path to occlum to launch. you can install it on `/usr/lib` on your centos system.
- `sgx_linux_x64_sdk_2.9.101.2.bin` : is a [SGX SDK](https://github.com/intel/linux-sgx#install-the-intelr-sgx-sdk-1) binary.
- `sgx_linux_x64_psw_2.9.101.2.bin` : is a [SGX PSW](https://github.com/intel/linux-sgx#install-the-intelr-sgx-psw) binary.
### Install `sgx_linux_x64_sdk_2.9.101.2.bin` ### Install `sgx_linux_x64_sdk_2.9.101.2.bin`
Type the following commands to Install `sgx_linux_x64_sdk_2.9.101.2.bin` on your centos system. Type the following commands to install `sgx_linux_x64_sdk_2.9.101.2.bin` on your host system.
``` shell ```shell
yum install -y make yum install -y make
mkdir -p /opt/intel echo -e "no\n/opt/intel\n" | ./sgx_linux_x64_sdk_2.9.101.2.bin
mv sgx_linux_x64_sdk_2.9.101.2.bin /opt/intel
cd /opt/intel
yes yes | ./sgx_linux_x64_sdk_2.9.101.2.bin
``` ```
### Install `sgx_linux_x64_psw_2.9.101.2.bin` ### Install `sgx_linux_x64_psw_2.9.101.2.bin`
Type the following commands to Install `sgx_linux_x64_psw_2.9.101.2.bin` on your centos system. Type the following commands to install `sgx_linux_x64_psw_2.9.101.2.bin` on your host system.
``` shell ```shell
yum install -y https://cbs.centos.org/kojifiles/packages/protobuf/3.6.1/4.el7/x86_64/protobuf-3.6.1-4.el7.x86_64.rpm yum install -y https://cbs.centos.org/kojifiles/packages/protobuf/3.6.1/4.el7/x86_64/protobuf-3.6.1-4.el7.x86_64.rpm
mv sgx_linux_x64_psw_2.9.101.2.bin /opt/intel
cd /opt/intel
./sgx_linux_x64_psw_2.9.101.2.bin ./sgx_linux_x64_psw_2.9.101.2.bin
source /opt/intel/sgxsdk/environment cd /opt/intel/sgxpsw/aesm
LD_LIBRARY_PATH="/opt/intel/sgxpsw/aesm:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH=$PWD
export AESM_PATH=$PWD
/opt/intel/sgxpsw/aesm/aesm_service /opt/intel/sgxpsw/aesm/aesm_service
``` ```
### Install rune and liberpal-occlum.so
```shell
cp ./rune /usr/local/sbin
cp ./liberpal-occlum.so /usr/lib
```
--- ---
## Config Docker Runtimes ## Config OCI Runtimes
Add the `rune` OCI runtime configuration in dockerd config file (`/etc/docker/daemon.json`) on your system. Add the `rune` OCI runtime configuration in dockerd config file, e.g, `/etc/docker/daemon.json`, on your system.
``` JSON ```JSON
{ {
"runtimes": { "runtimes": {
"rune": { "rune": {
...@@ -110,12 +110,11 @@ Add the `rune` OCI runtime configuration in dockerd config file (`/etc/docker/da ...@@ -110,12 +110,11 @@ Add the `rune` OCI runtime configuration in dockerd config file (`/etc/docker/da
} }
``` ```
then restart docker service on your system. then restart dockerd 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 You can check whether `rune` is correctly added to OCI runtime or not with
``` shell ```shell
sudo docker info | grep rune docker info | grep rune
Runtimes: rune runc Runtimes: rune runc
``` ```
...@@ -124,7 +123,9 @@ Runtimes: rune runc ...@@ -124,7 +123,9 @@ Runtimes: rune runc
## Run Occlum application image using rune ## Run Occlum application image using rune
You need to specify a set of parameters to `docker run` in order to use `rune`, e.g, You need to specify a set of parameters to `docker run` in order to use `rune`, e.g,
``` shell ```shell
export OCCLUM_INSTANCE_DIR=occlum-app
yum install -y libseccomp
docker run -it --rm --runtime=rune \ docker run -it --rm --runtime=rune \
-e ENCLAVE_TYPE=intelSgx \ -e ENCLAVE_TYPE=intelSgx \
-e ENCLAVE_RUNTIME_PATH=/usr/lib/liberpal-occlum.so \ -e ENCLAVE_RUNTIME_PATH=/usr/lib/liberpal-occlum.so \
...@@ -133,7 +134,6 @@ docker run -it --rm --runtime=rune \ ...@@ -133,7 +134,6 @@ docker run -it --rm --runtime=rune \
``` ```
where: 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_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_PATH: specify the path to enclave runtime to launch.
- @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. - @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, separated by the comma.
# Quick Start: Running rune with Occlum bundle # Quick Start: Running rune with Occlum bundle
## Build and install rune ## Build and install rune
`rune` is a CLI tool for spawning and running enclaves in containers according to the OCI specification. `rune` is a CLI tool for spawning and running enclaves in containers according to the OCI specification.
...@@ -6,13 +7,13 @@ Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blo ...@@ -6,13 +7,13 @@ Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blo
--- ---
## Build Occlum application docker image ## Build Occlum application container 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. Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum.md) to build the Occlum application container image.
## Create Occlum application bundle ## 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. In order to use `rune` you must have your container image 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 container image.
``` shell ```shell
# create the top most bundle directory # create the top most bundle directory
mkdir -p "$HOME/rune_workdir" mkdir -p "$HOME/rune_workdir"
cd "$HOME/rune_workdir" cd "$HOME/rune_workdir"
...@@ -28,7 +29,7 @@ docker export $(docker create ${Occlum_application_image}) | sudo tar -C rootfs ...@@ -28,7 +29,7 @@ docker export $(docker create ${Occlum_application_image}) | sudo tar -C rootfs
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. 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 ```shell
rune spec rune spec
``` ```
...@@ -56,12 +57,13 @@ where: ...@@ -56,12 +57,13 @@ where:
- @enclave.type: specify the type of enclave hardware to use, such as `intelSgx`. - @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.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. - @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 ## Run Occlum application
Assuming you have an OCI bundle from the previous step you can execute the container in this way. Assuming you have an OCI bundle from the previous step you can execute the container in this way.
``` shell ```shell
cd "$HOME/rune_workdir/rune-container" cd "$HOME/rune_workdir/rune-container"
sudo rune run ${Occlum_application_container_name} sudo rune run ${Occlum_application_container_name}
``` ```
The files in this directory are used to implement a skeleton enclave runtime, The files in this directory are used to implement a skeleton enclave runtime in order to help to write your own enclave runtime.
in order to help to write your own enclave runtime.
---
# Install runectl # Install runectl
Refer to [this guide](https://github.com/alibaba/inclavare-containers/tree/master/runectl) Refer to [this guide](https://github.com/alibaba/inclavare-containers/tree/master/runectl).
---
# Build liberpal-skeleton.so # Build liberpal-skeleton.so
```shell ```shell
...@@ -11,7 +14,9 @@ make ...@@ -11,7 +14,9 @@ make
cp liberpal-skeletion.so /usr/lib cp liberpal-skeletion.so /usr/lib
``` ```
# Build skeleton docker image ---
# Build skeleton container image
```shell ```shell
cd "${path_to_inclavare_containers}/rune/libenclave/internal/runtime/pal/skeleton" cd "${path_to_inclavare_containers}/rune/libenclave/internal/runtime/pal/skeleton"
cat >Dockerfile <<EOF cat >Dockerfile <<EOF
...@@ -25,19 +30,23 @@ COPY encl.elf . ...@@ -25,19 +30,23 @@ COPY encl.elf .
COPY encl.ss . COPY encl.ss .
COPY encl.token . COPY encl.token .
EOF EOF
docker build . -t liberpal-skeleton docker build . -t skeleton-enclave
``` ```
---
# Build and install rune # Build and install rune
`rune` is a CLI tool for spawning and running enclaves in containers according to the OCI specification. `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#rune) to build `rune` from scratch. Please refer to [this guide](https://github.com/alibaba/inclavare-containers#rune) to build `rune` from scratch.
# Run skeleton docker image ---
## Configure Docker runtimes
Add the `rune` OCI runtime configuration in dockerd config file (`/etc/docker/daemon.json`) in your system. # Run skeleton container image
## Configure OCI runtime
Add the `rune` OCI runtime configuration in dockerd config file, e.g, `/etc/docker/daemon.json`, in your system.
``` JSON ```json
{ {
"runtimes": { "runtimes": {
"rune": { "rune": {
...@@ -48,35 +57,38 @@ Add the `rune` OCI runtime configuration in dockerd config file (`/etc/docker/da ...@@ -48,35 +57,38 @@ Add the `rune` OCI runtime configuration in dockerd config file (`/etc/docker/da
} }
``` ```
then restart docker service on your system. then restart dockerd on your system.
> e.g. `sudo systemctl restart docker` for CentOS, or `sudo service docker restart` for Ubuntu > 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 You can check whether `rune` is correctly picked as supported OCI runtime or not with
``` shell ```shell
sudo docker info | grep rune docker info | grep rune
Runtimes: rune runc Runtimes: rune runc
``` ```
## Run skeleton docker image with rune ## Run skeleton container image with rune
```shell ```shell
docker run -it --rm --runtime=rune \ docker run -it --rm --runtime=rune \
-e ENCLAVE_TYPE=intelSgx \ -e ENCLAVE_TYPE=intelSgx \
-e ENCLAVE_RUNTIME_PATH=/usr/lib/liberpal-skeleton.so \ -e ENCLAVE_RUNTIME_PATH=/usr/lib/liberpal-skeleton.so \
-e ENCLAVE_RUNTIME_ARGS="debug" \ -e ENCLAVE_RUNTIME_ARGS="debug" \
liberpal-skeleton skeleton-enclave
``` ```
where: 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_TYPE: specify the type of enclave hardware to use, such as `intelSgx`.
- @ENCLAVE_PATH: specify the path to enclave runtime to launch. - @ENCLAVE_PATH: specify the path to enclave runtime to launch.
- @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, seperated by the comma. - @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, seperated by the comma.
---
# Run skeleton OCI bundle # Run skeleton OCI bundle
Note: The following method to launch skeleton with `rune` is usually provided for developmemt purpose.
## Create skeleton bundle ## Create skeleton 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 skeleton Docker container. In order to use `rune` you must have your container image 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 skeleton Docker container image.
``` shell ```shell
# create the top most bundle directory # create the top most bundle directory
cd "$HOME/rune_workdir" cd "$HOME/rune_workdir"
mkdir rune-container mkdir rune-container
...@@ -86,19 +98,19 @@ cd rune-container ...@@ -86,19 +98,19 @@ cd rune-container
mkdir rootfs mkdir rootfs
# export skeleton image via Docker into the rootfs directory # export skeleton image via Docker into the rootfs directory
docker export $(docker create liberpal-skeleton) | sudo tar -C rootfs -xvf - docker export $(docker create skeleton-enclave) | 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. 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 ```shell
rune spec rune spec
``` ```
To find features and documentation for fields in the spec please refer to the [specs](https://github.com/opencontainers/runtime-spec) repository. 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 skeleton bundle with `rune`, you need to configure enclave runtime as following: In order to run the skeleton bundle with `rune`, you need to configure enclave runtime as following:
``` json ```json
"annotations": { "annotations": {
"enclave.type": "intelSgx", "enclave.type": "intelSgx",
"enclave.runtime.path": "/usr/lib/liberpal-skeleton.so", "enclave.runtime.path": "/usr/lib/liberpal-skeleton.so",
...@@ -107,16 +119,14 @@ In order to run the skeleton bundle with `rune`, you need to configure enclave r ...@@ -107,16 +119,14 @@ In order to run the skeleton bundle with `rune`, you need to configure enclave r
``` ```
where: where:
- @enclave.type: specify the type of enclave hardware to use, such as intelSgx. - @enclave.type: specify the type of enclave hardware to use, such as intelSgx.
- @enclave.runtime.path: specify the path to enclave runtime to launch. - @enclave.runtime.path: specify the path to enclave runtime to launch.
- @enclave.runtime.args: specify the specific arguments to enclave runtime, seperated by the comma. - @enclave.runtime.args: specify the specific arguments to enclave runtime, seperated by the comma.
---
## Run skeleton application ## Run skeleton
Assuming you have an OCI bundle from the previous step you can execute the container in this way. Assuming you have an OCI bundle from the previous step you can execute the container in this way.
``` shell ```shell
cd "$HOME/rune_workdir/rune-container" cd "$HOME/rune_workdir/rune-container"
sudo rune run "liberpal-skeleton" sudo rune run skeleton-enclave-container
``` ```
...@@ -7,7 +7,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an ...@@ -7,7 +7,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | struct pal_attr_t {<br/> const char \*args;<br/> const char \*log_level;<br/>};<br/>int pal_init(const struct pal_attr_t *attr); | | **Prototype** | struct pal_attr_t {<br/> const char \*args;<br/> const char \*log_level;<br/>};<br/>int pal_init(const struct pal_attr_t *attr); |
| **Parameters** | @args: the enclave runtime specific argument string.<br/>@log_level: the output log level of enclave runtime. | | **Parameters** | @args: the enclave runtime specific argument string.<br/>@log_level: the output log level of enclave runtime. |
| **Return value** | 0: Success<br/>-ENOENT: Invalid instance path of enclave runtime<br/>Others: Enclave runtime specific error codes | | **Return value** | 0: Success<br/>-ENOENT: Invalid instance path of enclave runtime<br/>Others: Enclave runtime specific error codes |
| **Availability **| >=v1 |
## pal_exec() ## pal_exec()
| **Description** | Pass the path of the application to be executed, and synchronously wait for the end of the application to run and return the result. | | **Description** | Pass the path of the application to be executed, and synchronously wait for the end of the application to run and return the result. |
...@@ -15,7 +14,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an ...@@ -15,7 +14,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | struct pal_stdio_fds {<br/> int stdin, stdout, stderr;<br />};<br/>int pal_exec(char \*path, char \*argv[],<br/> struct pal_stdio_fds \*stdio,<br/> int \*exit_code); | | **Prototype** | struct pal_stdio_fds {<br/> int stdin, stdout, stderr;<br />};<br/>int pal_exec(char \*path, char \*argv[],<br/> struct pal_stdio_fds \*stdio,<br/> int \*exit_code); |
| **Parameters** | @path: The path of the application to be run<br/>@argv: The array of argument strings passed to the application, terminated by a NULL pointer<br/>@stdio: The stdio fds consumed by the application<br/>@exit_code: Return the exit code of an application | | **Parameters** | @path: The path of the application to be run<br/>@argv: The array of argument strings passed to the application, terminated by a NULL pointer<br/>@stdio: The stdio fds consumed by the application<br/>@exit_code: Return the exit code of an application |
| **Return value** | 0: success<br/>-ENOENT: The path does not exist<br/>-EACCES: Permission denied<br />-ENOEXEC: The path is not an executable file<br =/>-ENOMEM: <br />-EINVAL: Invalid argument | | **Return value** | 0: success<br/>-ENOENT: The path does not exist<br/>-EACCES: Permission denied<br />-ENOEXEC: The path is not an executable file<br =/>-ENOMEM: <br />-EINVAL: Invalid argument |
| **Availability **| >=v1 |
## pal_destroy() ## pal_destroy()
| **Description** | Destroy the enclave runtime instance | | **Description** | Destroy the enclave runtime instance |
...@@ -23,4 +21,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an ...@@ -23,4 +21,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | int pal_destroy(); | | **Prototype** | int pal_destroy(); |
| **Parameters** | N/A | | **Parameters** | N/A |
| **Return value** | 0: Success<br/>-ENOSYS: The function is not supported | | **Return value** | 0: Success<br/>-ENOSYS: The function is not supported |
| **Availability **| >=v1 |
...@@ -7,7 +7,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an ...@@ -7,7 +7,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | `int pal_version();` | | **Prototype** | `int pal_version();` |
| **Parameters** | N/A | | **Parameters** | N/A |
| **Return value** | N/A | | **Return value** | N/A |
| **Availability ** | >=v2 |
## 2.pal_init() ## 2.pal_init()
| **Description** | Do libos initialization according to the incoming attr parameters. | | **Description** | Do libos initialization according to the incoming attr parameters. |
...@@ -15,7 +14,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an ...@@ -15,7 +14,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | struct pal_attr_t {<br /> const char *args;<br /> const char *log_level;<br />};<br />int pal_init(struct palattrt *attr); | | **Prototype** | struct pal_attr_t {<br /> const char *args;<br /> const char *log_level;<br />};<br />int pal_init(struct palattrt *attr); |
| **Parameters** | @args: Pass the required parameters of libos (can be instance path etc.)<br />@log_level: Log level. | | **Parameters** | @args: Pass the required parameters of libos (can be instance path etc.)<br />@log_level: Log level. |
| **Return value** | 0: Success<br />-EINVAL: Invalid argument<br />-ENOSYS: The function is not supported | | **Return value** | 0: Success<br />-EINVAL: Invalid argument<br />-ENOSYS: The function is not supported |
| **Availability ** | >=v2 |
## 3. pal_create_process ## 3. pal_create_process
| **Description** | Create a new process, but do not run it; the real run is triggered by pal_exec(). | | **Description** | Create a new process, but do not run it; the real run is triggered by pal_exec(). |
...@@ -23,7 +21,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an ...@@ -23,7 +21,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | struct stdio_fds {<br /> int stdin, stdout, stderr;<br />};<br />struct pal_create_process_args {<br /> char *path;<br /> char *argv[];<br /> char *env[];<br /> struct stdio_fds *stdio;<br /> int *pid;<br />}__attribute__((packed));<br />int pal_create_process(struct pal_create_process_args *args); | | **Prototype** | struct stdio_fds {<br /> int stdin, stdout, stderr;<br />};<br />struct pal_create_process_args {<br /> char *path;<br /> char *argv[];<br /> char *env[];<br /> struct stdio_fds *stdio;<br /> int *pid;<br />}__attribute__((packed));<br />int pal_create_process(struct pal_create_process_args *args); |
| **Parameters** | @path: The path of the binary file to be run (relative path in the libos file system).<br />@argv: Binary parameters, ending with a null element.<br />@env: Binary environment variables, ending with a null element.<br />@stdio: The fd of stdio.<br />@pid: If the function return value is 0, pid stores the pid of the new process in libos. | | **Parameters** | @path: The path of the binary file to be run (relative path in the libos file system).<br />@argv: Binary parameters, ending with a null element.<br />@env: Binary environment variables, ending with a null element.<br />@stdio: The fd of stdio.<br />@pid: If the function return value is 0, pid stores the pid of the new process in libos. |
| **Return value** | 0: Success<br />-EINVAL: Invalid argument<br />-ENOSYS: The function is not supported | | **Return value** | 0: Success<br />-EINVAL: Invalid argument<br />-ENOSYS: The function is not supported |
| **Availability ** | >=v2 |
## 4. pal_exec ## 4. pal_exec
| **Description** | Execute the program corresponding to pid. | | **Description** | Execute the program corresponding to pid. |
...@@ -37,7 +34,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an ...@@ -37,7 +34,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | int pal_kill(int pid, int sig); | | **Prototype** | int pal_kill(int pid, int sig); |
| **Parameters** | @pid: Send to all processes if equal to -1, or send to current process if equal to 0, or send to the process that owns the pid if others. <br />@sig: Signal number to be sent | | **Parameters** | @pid: Send to all processes if equal to -1, or send to current process if equal to 0, or send to the process that owns the pid if others. <br />@sig: Signal number to be sent |
| **Return value** | 0: Success<br />-EINVAL: Invalid argument<br />-ENOSYS: The function is not supported | | **Return value** | 0: Success<br />-EINVAL: Invalid argument<br />-ENOSYS: The function is not supported |
| **Availability ** | >=v2 |
## 6.pal_destroy() ## 6.pal_destroy()
| **Description** | Destroy libos instance. | | **Description** | Destroy libos instance. |
...@@ -45,4 +41,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an ...@@ -45,4 +41,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | int pal_destroy(); | | **Prototype** | int pal_destroy(); |
| **Parameters** | NA. | | **Parameters** | NA. |
| **Return value** | 0: Success<br />-ENOSYS: The function is not supported | | **Return value** | 0: Success<br />-ENOSYS: The function is not supported |
| **Availability ** | >=v2 |
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册