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