Introduction to Gramine

Gramine is a lightweight guest OS, designed to run a single Linux application with minimal host requirements. Gramine can run applications in an isolated environment with benefits comparable to running a complete OS in a virtual machine – including guest customization, ease of porting to different host OSes, and process migration.

Gramine supports running Linux applications using the Intel SGX (Software Guard Extensions) technology (we sometimes call this version Gramine-SGX). With Intel SGX, applications are secured in hardware-encrypted memory regions (called SGX enclaves). SGX protects code and data in the enclave against privileged software attacks and against physical attacks on the hardware off the CPU package (e.g., cold-boot attacks on RAM). Gramine is able to run unmodified applications inside SGX enclaves, without the toll of manually porting the application to the SGX environment.

External documentation

This website contains the official documentation of Gramine. For external contributions and additional resources, please visit https://gramine-contrib.readthedocs.io. Note that this link contains unofficial documents; these documents are not guaranteed to always be up-to-date and correct.

GSC documentation

For GSC (Gramine Shielded Containers) documentation please visit https://gramine.readthedocs.io/projects/gsc.

Building and running Gramine

See Quick start for instructions how to quickly install and run Gramine. For full build instructions, see Building. To deploy Gramine in the cloud, see Cloud Deployment.

Contacts and Contributing

For bug reports, post an issue on our GitHub repository: https://github.com/gramineproject/gramine/issues.

For any questions, please send an email to users@gramineproject.io (public archive).

If you want to contribute to the project, please see Contributing to Gramine and Onboarding. Thank you for your interest!

Table of Contents

User Manual

• Quick start
  • Prerequisites
  • Install Gramine
  • Prepare a signing key
  • Run sample application
  • Other sample applications
  • glibc vs musl
• Manifest syntax
  • Common syntax
  • SGX syntax
  • Deprecated options
• Attestation and Secret Provisioning
  • Remote Attestation flows for EPID and DCAP
  • Low-level /dev/attestation interface
  • Mid-level RA-TLS interface
  • High-level Secret Provisioning interface
  • Third-Party Solutions
• Performance tuning and analysis
  • Enabling per-thread and process-wide SGX stats
  • Effects of system calls / ocalls
  • Exitless feature
  • Optional CPU features (AVX, AVX512, MPX, PKRU, AMX)
  • Multi-threaded workloads
  • Multi-process workloads
  • Choice of SGX machine
  • Glibc malloc tuning
  • Other considerations
  • Profiling with perf
  • SGX profiling
  • Profiling SGX hotspots with Intel VTune Profiler
  • Other useful tools for profiling
• Cloud Deployment
  • Azure confidential computing VMs
• Users of Gramine
• Container integration
  • Gramine Docker image
  • GSC (Gramine Shielded Containers)
• Introduction to SGX
  • Introductory reading
  • Official Documentation
  • Academic Research
  • Installation Instructions
  • SGX terminology
• Glossary

Tutorials

• PyTorch PPML Framework Tutorial
  • Introduction
  • Prerequisites
  • Executing Native PyTorch
  • Executing PyTorch with Gramine
  • End-To-End Confidential PyTorch Workflow
• Confidential Computing Zoo project

Manual pages

• gramine-direct, gramine-sgx – Run something
• gramine-argv-serializer – Serialize command line arguments
• gramine-manifest – Gramine manifest preprocessor
• gramine-sgx-gen-private-key – Gramine SGX key generator
• gramine-sgx-get-token – Gramine SGX token generator
• gramine-sgx-ias-request – Submit Intel Attestation Service request
• gramine-sgx-ias-verify-report – Verify Intel Attestation Service report
• gramine-sgx-quote-dump – Display SGX quote structure
• gramine-sgx-sign – Gramine SIGSTRUCT generator
• is-sgx-available – Check environment for SGX compatibility

Developing Gramine

• Building
• Onboarding
• Contributing to Gramine
• Management Team (Maintainers)
• Developer Certificate of Origin
• How to write documentation
• Coding style guidelines
• Development setup
• Debugging Gramine with GDB
• Implementing new system call
• Packaging and distributing

LibOS

• LibOS documentation

PAL

• PAL host ABI
  • PAL as loader
    • Manifest and executable loading
  • Data types and variables
    • Data types
      • PAL handles
      • Basic types
    • PAL public state
      • PAL public state - topology information
  • PAL APIs
    • Memory allocation
    • Process creation
    • Stream creation/connect/open
      • Flags used for stream manipulation
    • Socket handling
    • Thread creation
    • Exception handling
    • Synchronization
    • Objects
    • Miscellaneous

Python

• Python API

Indices and tables

• Index
• Module Index
• Search Page