trustlet

Learn about using trustlet to perform actions through a vHSM agent.

A trustlet is a built-in, internal component of the vHSM agent system which performs a specific, elevated action during VM setup, attestation, or provisioning. Examples include:

• Installing a root filesystem or parts of it using "installer" trustlet

• Unlocking encrypted disks using "luks" trustlet

• Writing cloud-init or cloud-config style files using "cloud-config" or similar

Trustlets are specified in the agent’s configuration and are run automatically as part of machine startup or initialization. They often expect particular arguments such as URLs for rootfs tarballs, checksum, target paths, and others.

Parameters

• source (string, required)

  • Defines the origin of the trustlet.

  • Commonly set to "internal" to indicate a built-in trustlet provided by the agent.

• name (string, required)

  • Identifies which trustlet logic to execute.

  • Examples:

    • "installer" – for installing software.

    • "luks" – for handling encrypted volumes.

    • "cloud-config" – for applying cloud-init–style configuration.

• arguments (list of strings, required for most trustlets)

  • Represents the inputs a trustlet needs to run.

  • Unlike named fields, trustlets consume these as positional arguments.

  • The exact values depend on the trustlet type, but commonly include:

    • Download URL / rootfs tarball – a URI, for example https://.../ubuntu-rootfs.tar.gz pointing to a root filesystem, binary, or package to fetch.

    • Checksum – usually a SHA256 hash of the downloaded content, used for integrity verification.

    • Target path – the directory where the content should be unpacked or installed. For example, /run/nextroot.

    • Shell or script commands – optional commands for additional tasks such as extraction, configuration, or installation.

    • Config file paths – file paths for cloud-config or configuration fragments that need to be written or applied.

Examples

trustlet {
  source = "internal"
  name   = "installer"
  arguments = [
    "<URL to Buckypaper VM rootfs>",
    "<checksum>",
    "/run/nextroot"
  ]
}

Limitations & Caveats

• Not all trustlets support running arbitrary shell commands or compilation. Trustlets may accept a string in arguments but might not execute complex build commands.

• There is sometimes an implicit expectation that the downloaded rootfs or binary contains everything needed, including binaries, libraries, proper paths, etc. If not, the exec part will fail.

• Race conditions: exec blocks may start before a trustlet is fully complete if not properly ordered. Some versions might have depends_on_trustlet or similar but not all do.