Welcome to the Fortanix Confidential Computing Manager (CCM) User Guide. This document describes the Nitro Overlay File System Persistence feature in the Fortanix Confidential Computing Manager.
The Fortanix Confidential Computing Manager (CCM) Nitro File Persistence feature provides the encryption keys necessary for the Nitro converter to allow a filesystem to be created, mounted, unmounted, and saved for a Nitro Enclave using the Nitro node agent.
The Nitro File Persistence feature allows you to save the filesystem state of a Nitro Enclave after the enclave has been stopped. Typically, due to the short-lived nature of the Nitro Enclave, all data is lost unless exported. When enabled (ON by default in the CCM UI), this mechanism will allow a user to follow a set of instructions to save the filesystem of a converted container and to restart a container image with the filesystem.
2.0 Enabling Nitro File Persistence
The primary and recommended way of creating a file persistence-enabled Nitro Enclave is using the Fortanix CCM UI as described in Section 2.1: Using the Fortanix CCM UI. The File persistence option can be enabled when creating a Fortanix CCM application (app) and an image.
You can also enable this using the Fortanix CCM REST API as described in Section 2.2: Using the Fortanix CCM REST API.
2.1 Using the Fortanix CCM UI
The File Persistence feature can be enabled in the Fortanix CCM UI by creating a new application or image, selecting the enclave type as AWS Nitro, and making sure the File persistence check box is enabled.
For steps to enable or disable the File persistence option during the CCM App creation workflow, refer to the Users’ Guide: Add and Edit an Application.
For steps to enable or disable the File persistence option during the CCM image creation workflow, refer to the Users’ Guide: Create an Image.
2.2 Using the Fortanix CCM REST API
- Create a Fortanix CCM image (standalone conversion) using the CCM REST API and register the image as a build using the following endpoint:
- Pass the
CreateBuildRequestobject as data in the above request as shown below.
- The above request will have an
enable_overlay_filesystem_persistencefield. This field will default to
falseif not present, but you can provide a value of true to enable the Nitro File Persistence for this Image.
3.0 Creating a Persistence Blockfile
If the Nitro File Persistence feature is enabled for each running instance of a Fortanix CCM image container, it will create a LUKS2 blockfile for use with this system.
3.1 Automatic Creation
- To create a File Persistence blockfile, run the container with the
docker runcommand as shown below.
docker run -it --privileged -v /run/nitro_enclaves:/run/nitro_enclaves -e RUST_LOG=debug -e NODE_AGENT=http://<NODE_AGENT_IP>:9092/v1/ -p 8081:80 -p 6061:443 <container_name>
- Subsequently, after the container stops or is stopped with the
docker stop, it will be possible to extract the blockfile for later use with the following command.
docker cp <container_name>:/opt/fortanix/enclave-os/Blockfile-rw.ext4 <destination_filename>
4.0 Using the File Persistence Blockfile
After the Nitro Persistence File is obtained, it must also be mounted into a container for use. This will allow a container to start with the same filesystem state as it had during the shutdown.
To use the Nitro Persistence File, it must be mounted during normal container startup with the following command:
docker run -it --privileged -v /run/nitro_enclaves:/run/nitro_enclaves -v <path_to_persistence_file>:/opt/fortanix/enclave-os/Blockfile-rw.ext4 -e RUST_LOG=debug -e NODE_AGENT=http://<NODE_AGENT_IP>:9092/v1/ -p 8081:80 -p 6061:443 <container_name>