DOCSEARCHbyAlgolia
Submit Docs

Hyperlight Project Documentation

website·Indexed 30 days ago

https://hyperlight-draft.vercel.app

An open source micro-virtual machine manager designed for virtual machine-based security for functions at scale. Hyperlight provides a fast, secure, and OS-free execution environment capable of achieving 0.0009-second micro-VM execution time, supporting guests built in Rust, C, and Wasm.

Tokens
11.3K
Snippets
28
Records
77
Agent score
75%

What's inside Hyperlight

  1. Overview of Hyperlight micro-VM security

    Hyperlight is an open-source Rust library designed to execute small, embedded functions with hypervisor-based protection at scale. It addresses the trade-off between security (traditional VMs) and speed (sandboxed runtimes like Wasmtime) by providing micro-VMs with cold start times of 1-2 milliseconds. This allows developers to run untrusted code in isolated environments for scenarios such as IoT gateway functions, industrial automation, and high-throughput cloud services, while enabling 'scale to zero' architectures.

  2. Overview of Hyperlight micro-VM library

    Hyperlight is a Rust library that allows developers to execute untrusted code within micro virtual machines using hypervisor technologies such as KVM (Kernel-based Virtual Machine) or Hyper-V. It is designed to eliminate the overhead of a full operating system, enabling cold start performance in the microsecond to low-millisecond range. It supports the execution of x86_64 native ELF binaries, WebAssembly, and JavaScript.

  3. Overview of Hyperlight hypervisor-isolated workloads

    Hyperlight is a library designed to run hypervisor-isolated workloads without the overhead of booting a full guest operating system. It is optimized for functions-as-a-service (FaaS) workloads where high density and fast execution of user code are required.

  4. Overview of Hyperlight Wasm

    Hyperlight Wasm is a virtual machine (VM) "micro-guest" designed to run Wasm component workloads. Unlike traditional VMs, it does not load a full operating system or virtual devices, instead exposing only a linear slice of memory and a CPU to the guest. This architecture enables startup times of 1-2 milliseconds. It provides two layers of security: a software-defined runtime sandbox via the Wasmtime runtime and a hardware-protected VM boundary.

  5. Overview of Hyperlight micro-VM manager

    Hyperlight is an open-source micro-virtual machine (micro-VM) manager designed to execute untrusted code quickly and safely at scale. It is characterized by cross-platform support, a sandboxed environment, no requirement for a guest OS, and the ability to scale to zero with cold starts as fast as 1ms.

  6. Understand Hyperlight's Isolation Architecture

    Hyperlight uses the following architectural components to achieve isolated execution:

    • Host Application: The application that consumes the Hyperlight library to execute code in an isolated environment.
    • Host: The physical or virtual machine running the host application. If the host is a virtual machine, nested virtualization is required.
    • Hypervisor: Software that creates and manages micro virtual machines (microVMs) and executes guests within them. Supported hypervisors include Hyper-V (Windows and Linux/MSHV) and KVM (Linux).
    • Driver: A component that manages the interaction between Hyperlight and a specific supported hypervisor.
    • Micro Virtual Machine (microVM): A lightweight execution environment that isolates a guest from the host's resources (memory, filesystem, CPU, devices). Unlike traditional VMs, microVMs contain no full operating system to ensure low latency and high density.
    • Guest: A standalone executable binary run inside a microVM. Guests are purpose-fit (e.g., for Wasm or specific languages) to avoid the overhead of booting a full OS, enabling low-latency startup.
    • Workload: The specific code that the host application intends to execute within the isolated microVM.
    • Sandbox: The Hyperlight abstraction used to create, configure, execute, and destroy a microVM that runs a guest workload.

  7. Understand Hyperlight VM paging and memory layout

    Hyperlight VMs use standard 4-level paging. All addresses inside the VM are treated as virtual addresses. The VM is limited to 1GB of addressable memory because only the first entry of the PML4 and PDPT tables are initialized (requiring bits 47:30 of a linear address to be zero).

    Control Register Settings:

    • CR0.PG = 1: Enables paging
    • CR4.PAE = 1: Enables Physical Address Extension (PAE)
    • IA32_EFER.LME = 1: Enables Long Mode (64-bit)
    • CR4.LA57 = 0: Disables 5-level paging

    Memory Mapping: Host memory is mapped into the VM as physical memory starting at address 0x200_000 and extending linearly.

  8. Hyperlight Project Overview

    Hyperlight is a library designed to be embedded within a host application to provide hypervisor-isolated execution support. It allows a host application to execute code (workloads) in an isolated environment using micro virtual machines.

  9. Hyperlight benchmarking CI/CD pipeline

    Hyperlight automates benchmarking in two primary scenarios:

    1. Branch Pushes: Triggered via ValidatePullRequest.yml $\rightarrow$ dep_rust.yml. It compares the current branch against the dev-latest release (the most recent push to main). Results are visible only in GitHub action logs and are not persisted.
    2. Releases: Triggered via CreateRelease.yml $\rightarrow$ Benchmarks.yml. Results are compared to the previous release and uploaded as "Release assets" on the GitHub release page.

    Environment Details:

    • Platforms: Windows, Linux-KVM (Ubuntu), and Linux-HyperV (Mariner).
    • Build Type: Only release builds are benchmarked.

  10. Manage signal handling for SIGSYS and SIGRTMIN in Hyperlight

    Hyperlight implements custom signal handlers for SIGSYS and SIGRTMIN to manage syscall enforcement and inter-thread signaling.

    • SIGSYS: Captures disallowed syscalls enforced by seccomp. If the signal originates from a hyperlight thread, the syscall details are logged; otherwise, the signal is delegated to the original handler.
    • SIGRTMIN: Used for inter-thread signaling, such as execution cancellation. It distinguishes between application and non-hyperlight threads to determine the handling logic.
    • Thread Identification: Hyperlight uses thread-local storage (IS_HYPERLIGHT_THREAD) to identify if the current thread is a hyperlight thread.
    • Handler Preservation: To avoid breaking existing functionality, Hyperlight retrieves and stores the original signal handler using OnceCell before registering its own, allowing it to delegate signals back to the original handler when necessary.

  11. Develop and compile binaries for Hyperlight

    Hyperlight removes all operating system functionality from inside the virtual machine. Consequently, guest binaries must meet two requirements:

    1. They must be compiled for the target vCPU's architecture.
    2. They must be statically linked to specialized Hyperlight guest libraries (available in Rust and a C-compatible wrapper) because no syscalls are available in the VM environment. This approach is similar to Unikernel technology.

  12. Understand Hyperlight VM architecture and constraints

    Hyperlight is designed for executing small, short-running functions using micro virtual machines. To achieve high efficiency, it provides hardware isolation (vCPU and virtual memory) and shared memory between the host and guest, but explicitly omits several standard VM features.

    Key Omissions:

    • No Bootloader or OS kernel
    • No Virtual networking
    • No Virtual filesystem