How canonical/tdx works
Project Type and Purpose
• This is an orchestration and tooling project (not a web app) that automates:
– Host OS preparation for Intel TDX
– Trust Domain (TD) image creation and configuration
– Booting TDs via QEMU or libvirt
– GPU passthrough for NVIDIA H100
– Remote attestation (host and guest)
– Package building and testing (snap, deb, CI workflows)
• Intended for system administrators, DevOps engineers, and security researchers who need a repeatable workflow to deploy and validate Intel TDX environments on Ubuntu.
File Structure
• Top-level directories:
– .github (CI and issue templates)
– attestation (host & guest attestation scripts)
– gpu-cc (scripts for GPU discovery and VFIO setup)
– guest-tools (create-td-image.sh, setup-tdx-guest.sh, run_td, tdvirsh, XML templates)
– tests (functional, performance, stress tests; QEMU wrapper; Python utilities; snapcraft hooks)
• Key configuration files and build scripts:
– setup-tdx-config (global config for both host & guest)
– Snapcraft.yaml (for snap packaging)
– tox.ini / pytest.ini (test runners)
• Patterns:
– Modular shell-script toolkit for each phase (host, guest, boot, attestation)
– Templates for cloud-init and libvirt XML
– CI pipelines (GitHub Actions, snap hooks)
README for Additional Insights
• Confirms the sequence: install host prerequisites → create TD image → boot TD → verify TDX → add GPU → setup attestation → run tests
• External services: Canonical PPA, Intel PCS (PCCS), Intel Tiber Trust Services (Trust Authority API)
• Technologies: bash, Python (tests), Go (trustauthority-cli), QEMU, libvirt, cloud-init, VFIO, Snapcraft
Main Components and Their Interactions
A. User/CI Initiation Layer
• Operator / Admin / CI jobs
• GitHub Actions / Snapcraft build triggers
B. Host Orchestration Layer
• setup-tdx-host.sh
• system-report.sh
• check-production.sh
• attestation/setup-attestation-host.sh
• PCCS + QGS services
• BIOS configuration (TDX, SGX, TME)
C. Guest Image Layer
• guest-tools/image: create-td-image.sh (+ cloud-init meta-data templates)
• setup-tdx-guest.sh
• cloud-init processing inside TD image
D. Boot & Runtime Layer
• guest-tools/run_td (QEMU wrapper)
• guest-tools/tdvirsh (libvirt wrapper + XML templates)
• QEMU / libvirt <-> Linux KVM <-> TDX module (kernel)
• VFIO-based GPU passthrough (gpu-cc/h100/setup-gpus.sh + vfio rules)
E. Attestation Layer
• Host side: DCAP libraries → /dev/sgx_* → PCCS, QGS → MPA registration
• Guest side: trustauthority-cli (Go) → Intel Trust Authority API → network
F. Testing & Packaging Layer
• tests/ (pytest suites, checkbox provider, performance scripts)
• tests/snap (snapcraft.yaml + hooks)
• GitHub Actions workflows
G. External Services
• Canonical PPA (apt packages for TDX, DCAP, kernels)
• Intel PCS (PCCS ↔ Intel provisioning)
• Intel Tiber Trust Services (attestation API)
• GitHub (source, CI triggers)
Architectural Patterns and Technologies
• Layered orchestration: host setup → guest image → run → attest → test
• Modular CLI scripts and templates
• External configuration via setup-tdx-config
• Separation of concerns: host vs. guest vs. external attestation
• Use of industry standards: cloud-init, libvirt XML, VFIO, PSKless APIs