GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/openvmm

Public

mirrored fromhttps://github.com/microsoft/openvmmAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
228c1982009ec3e6c9150539cf17f92e05e2f52f

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

openvmm/Guide/src/dev_guide/dev_tools

Guide/src/dev_guide/dev_tools/vmgstool.md

118lines · modecode

RawDownload
Latest commit unavailable.
1# VmgsTool
2
3OpenHCL VMs store their firmware state and attributes (UEFI variables) in a special VM
4Guest State (VMGS) file. The OpenHCL interacts with and persists data in the VMGS file
5on behalf of the VM. The VMGS file is packaged as a VHD which the host OS interacts with.
6For Confidential OpenHCL VMs, this VHD can be encrypted before VM deployment, so that the
7host only interacts with an encrypted VHD and hence the file's contents are kept confidential from the host.
8
9The VMGS file contains several elements called "files" (these are not strictly files, simply
10"chunks of data”, logical groupings of data). Each "file" has a unique, well known index;
11for example, vTPM state is stored in file id "3".
12
13The VmgsTool is a tool that allows for offline manipulation of a VMGS (version 3) file
14for provisioning and debugging purposes. Basically, it's a tool to interact with the VMGS
15file, and it can help you perform operations such as reading, creating, modifying and
16removing "files" from the VMGS file and even creating an encrypted datastore to
17allow certain "files" to be encrypted as the scenario requires it.
18
19## Alternatively: Pre-Built Binaries
20
21If you would prefer to use VmgsTool without building it from scratch, you can
22download pre-built copies of the binary from
23[OpenVMM CI](https://github.com/microsoft/openvmm/actions/workflows/openvmm-ci.yaml).
24
25Simply select a successful pipeline run (should have a Green checkbox), and
26scroll down to select an appropriate `*-vmgstool` artifact for your particular
27architecture and operating system.
28
29## Running
30
31```admonish tip
32Note: The examples in this section use the Windows executable `vmgstool.exe`,
33which can be replaced with the Linux executable `vmgstool`.
34
35Developers who have already setup their development environment may also use
36the appropriate `cargo run` command. For more details on building,
37
38see the [build](#building) section below.
39```
40
41The VmgsTool commands are always evolving, so use `vmgstool.exe --help` to see the
42most up to date information about the available commands. Options for each command
43and subcommand are also available. For example: `vmgstool.exe uefi-nvram dump --help`
44
45### Read and Write Raw Data
46
47To read raw data from a VMGS file, use the `dump` command. For example, to
48export the decrypted binary contents of the BIOS_NVRAM (`--fileid 1`) to a file:
49
50`vmgstool.exe dump --filepath <vmgs file path> --keypath <key file path> --datapath <data file path> --fileid 1`
51
52To write raw data to a VMGS file, use the `write` command. For example, to write
53those NVRAM variables to a different, unencrypted VMGS file:
54
55`vmgstool.exe write --filepath <vmgs file path> --datapath <data file path> --fileid 1`
56
57### Read and Parse UEFI NVRAM Variables
58
59Furthermore, the VmgsTool contains parsers to help debug issues with the UEFI NVRAM
60variables stored in the VMGS FileId 1 (BIOS_NVRAM). For example, to dump the NVRAM
61variables for an encrypted VMGS file, truncating the binary data contents of
62variables without parsers:
63
64`vmgstool.exe uefi-nvram dump --filepath <vmgs file path> --keypath <key file path> --truncate`
65
66### Read DLL File to Write IGVMfile to VMGS
67
68Additionally, the VmgsTool contains a tool to read the IGVMfile from a DLL (passed in as a data file)
69and write it to VMGS FileId 8 (GUEST_FIRMWARE). To do this pass one of five resource codes
70(NONCONFIDENTIAL, SNP, TDX, SNP_NO_HCL, TDX_NO_HCL) into the cmdline tool:
71
72`vmgstool.exe test copy-igvmfile --filepath <vmgs file path> --datapath <dll path> --resource-code <code>`
73
74### Delete Boot Variables to Recover a VM that Fails to Boot
75
76A VM may fail to boot if the disk configuration changes and
77UEFI's `DefaultBootAlwaysAttempt` setting is disabled.
78Deleting the existing (invalid) boot entries using VmgsTool
79will trigger a default boot (which attempts to boot all available partitions and devices).
80
81To print the boot entries in an encrypted VMGS file:
82`vmgstool.exe uefi-nvram remove-boot-entries --filepath <vmgs file path> --keypath <key file path> --dry-run`
83
84To actually remove the boot entries from the VMGS file, remove `--dry-run`.
85This will remove all `Boot####` variables and the `BootOrder` variable.
86
87If you would like to remove a specific boot entry or any other UEFI NVRAM variable,
88use `remove-entry`. For example, to remove `Boot0000`:
89
90`vmgstool.exe uefi-nvram remove-entry --filepath <vmgs file path>--keypath <key file path> --name Boot0000 --vendor 8be4df61-93ca-11d2-aa0d-00e098032b8c`
91
92## Troubleshooting
93
94### Expected at least N more bytes, but only found M
95
96If you get an error similar to the one below, it is likely that you are trying
97to read an encrypted VMGS file and haven't provided the correct decryption key.
98
99```text
100ERROR: remove_boot_entries error
101Caused by:
102 0: error loading data from Nvram storage
103 1: unexpected EOF. expected at least 2330702412 more bytes, but only found 30067
104```
105
106## Building
107
108Prior to building VmgsTool, please ensure you have built either OpenVMM or
109OpenHCL at least once, to ensure you have all necessary build dependencies
110installed.
111
112VmgsTool can be built with `cargo build -p vmgstool` for Windows and Linux.
113To interact with encrypted VMGS files, you will need to compile with the
114appropriate encryption feature.
115
116Windows: `cargo build --features "encryption_win" -p vmgstool`
117
118Linux/WSL2: `cargo build --features "encryption_ossl" -p vmgstool`
119