Update Readme

README.md

@@ -19,52 +19,74 @@ Useful links
 
 Quick Start Guide
 --------------
-
-1. Install Rust:
-   Follow [this](https://www.rust-lang.org/tools/install) guide.
-
-
-2. Install Docker:
-   Follow [this](https://docs.docker.com/engine/install/) guide.
-
-
-3. Set up your Nitro-enabled AWS EC2 instance:
+This guide allows you to build salmiac from source and convert your docker application into a one that can run in a nitro enclave. 
+
+1. Set up your Ubuntu based build system:
+    - Install Rust:
+      Follow [this](https://www.rust-lang.org/tools/install) guide.
+    - Install Docker:
+      Follow [this](https://docs.docker.com/engine/install/) guide to install version 24.0.x
+      OR
+      ```bash
+      apt-get install docker-ce=5:24.0.1-1~ubuntu.20.04~focal docker-ce-cli=5:24.0.1-1~ubuntu.20.04~focal  containerd.io
+      ```
+    - Install tools needed to build the linux kernel:
+      Follow [this](https://kernelnewbies.org/KernelBuild) guide.
+    - Install additional dependencies:
+      ```bash
+      apt-get install pkg-config libclang-dev cmake libpcap-dev
+      ```
+
+2. Set up your Nitro-enabled AWS EC2 instance:
     - Install docker on your EC2:
-      Follow step #2
+      Follow [this](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-docker.html) guide.
     - Install nitro-cli on your EC2:
       Follow [this](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave-cli-install.html) guide.
 
 
-4. Build requisite docker images needed to run container converter
+3. Build requisite docker images needed to run container converter
    ```bash
    # Run from the root of the repository
    # build enclave-base image
    cd salmiac/docker/enclave-base
    docker build -t enclave-base .
 
    # build parent-base image
-   cd ..//parent-base
+   cd ../parent-base
    docker build -t parent-base .
     ```
 
-5. Compile container converter:
+4. Build the enclave kernel. This step takes a long time and needs to be done only once. The artifacts produced by this step need not be cleaned up unless the kernel config is updated.
+   ```bash
+   cd amzn-linux-nbd
+   ./build-enclave-kernel.sh build
+    ```
+
+5. Build the converter image. To produce a debug build of the converter, ensure the release flag is removed from the step below.
     ```bash
       # Run from the root of the repository
       cd salmiac
-      ./build-converter.sh   
+      # To produce a debug build of the converter, ensure the release flag is removed from the step below.
+      ./build-converter.sh --release
+
+      cd docker
+      # If a debug build of the converter was produced, use debug as an argument to the below script
+      ./build-conv-container.sh release
     ```
 
-6. Create a simple conversion request json file
+6. Create a simple conversion request json file (say /tmp/req.json)
+   More details about each field of the conversion request can be found in /salmiac/api-model/src/converter.rs
    ```javascript
     {
       "input_image": {
-         "name": "<your application image tag>",         
+         "name": "hello-world", 
       },
       "output_image": {
-         "name": "<your output image tag>",            
+         "name": "hello-world-nitro",
       },
       "converter_options": {
-         "debug": true
+         "push_converted_image": false,
+         "enable_overlay_filesystem_persistence": false
       },
       "nitro_enclaves_options": {
          "cpu_count": 2,
@@ -73,19 +95,19 @@ Quick Start Guide
    }
    ```
 
-7. Make your application Nitro VM-capable by running container converter with the file from previous step
+7. Make your application Nitro VM-capable by running container converter with the file from previous step.
+   The converter by default pulls the input image and pushes the output image to remote repositories. These images are then cleaned up from the local docker cache. In our example, the output image push is disabled in the request json and to preserve the images in the docker cache, 'PRESERVE_IMAGES' environment variable is specified.
    ```bash
-      # Run from the root of the repository
-      cd tools/container-converter/target/debug
-      ./container-converter --request-file <path to file from step 4>
+      docker run --rm --name converter --user 0 --privileged -v /var/run/docker.sock:/var/run/docker.sock -e PRESERVE_IMAGES=input,result -v /tmp/req-files:/app converter --request-file /app/req.json
     ```
 
-8. Copy converted image into your EC2 instance and run the image
+8. Copy converted image into your EC2 instance and run the image.
+   Note the use of the environment variable which disables the use of default certificates, which allows you to skip access to Fortanix CCM. Read more about environment variables used in salmiac here - /salmiac/ENV_VARS.md
    ```bash
       # Copy your converted image from step #7 into your EC2 isntance
       # ...       
       # Run copied image inside EC2
-      docker run -it --rm --privileged -v /run/nitro_enclaves:/run/nitro_enclaves <your image name>
+      docker run -it --rm --privileged -v /run/nitro_enclaves:/run/nitro_enclaves -e ENCLAVEOS_DISABLE_DEFAULT_CERTIFICATE=true hello-world-nitro
     ```
 
 # Contributing
@@ -122,4 +144,4 @@ this project or the open source license(s) involved.
 
 # License
 
-This project is primarily distributed under the terms of the Mozilla Public License (MPL) 2.0, see [LICENSE](./LICENSE) for details.
+This project is primarily distributed under the terms of the Mozilla Public License (MPL) 2.0, see [LICENSE](./LICENSE) for details.

docker/amzn-linux-nbd/build-enclave-kernel.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+
+set -exo pipefail
+
+clonelinux() {
+
+  # Clone the amazon linux kernel repository and checkout
+  # the branch which is used for nitro enclaves
+  # You can find out the kernel version used by nitro-enclaves
+  # by running uname -a in a converted app. In this case, we
+  # use version 4.14.246
+  # For more details about supported nitro enclave kernel
+  # versions, refer to the aws-nitro-enclaves-cli github repository.
+
+  if [ -d "linux" ]; then
+    cd linux
+    git fetch
+  else
+    git clone https://github.com/amazonlinux/linux.git
+    cd linux
+  fi
+
+  git checkout microvm-kernel-4.14.246-198.474.amzn2
+
+}
+
+buildkernel() {
+
+  # Copy the enclave kernel config file into the kernel repository
+  # The original file is available here:
+  # https://github.com/aws/aws-nitro-enclaves-cli/blob/main/blobs/x86_64/bzImage.config
+  # The config file available in this directory has been updated to
+  # support salmiac features.
+  cp ../bzImage.config .config
+
+  # Build the enclave kernel
+  make prepare
+  make modules_prepare
+  make modules -j
+  make -j
+  make bzImage
+
+  # Once build is complete, we would need a copy of the bzImage file
+  cp ./arch/x86/boot/bzImage ../
+  cp .config ../bzImage.config
+
+  cd ../
+}
+
+cleankernel() {
+  if [ -d "linux" ]; then
+    rm -rf linux
+  fi
+}
+
+if [ $1 == "build" ]; then
+  clonelinux;
+  buildkernel;
+elif [ $1 == "clean" ]; then
+ cleankernel;
+else
+  echo "Provide input arguments - build or clean"
+fi
+