Skip to content

Commit 304a739

Browse files
v-sissondanv-sissondan
committed
new content for TVM backup/restore
1 parent 5b36b0c commit 304a739

File tree

2 files changed

+143
-88
lines changed

2 files changed

+143
-88
lines changed

‎azure-local/manage/trusted-launch-vm-import-key.md

Lines changed: 124 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,193 @@
11
---
2-
title: Manage Trusted launch for Azure Local VM enabled by Azure Arc guest state protection key
3-
description: Learn how to manage a Trusted launch for Azure Local VM enabled by Azure Arc guest state protection key.
2+
title: Manual backup and recovery of VM guest state protection key
3+
description: Learn how to perform a manual backup and recovery of a VM guest state protection key.
44
author: alkohli
55
ms.author: alkohli
66
ms.topic: how-to
77
ms.service: azure-local
88
ms.reviewer: alkohli
9-
ms.date: 03/27/2025
9+
ms.date: 07/10/2025
1010
---
1111

12-
# Manage backup and recovery of Trusted launch for Azure Local VMs enabled by Azure Arc
12+
# Manual backup and recovery of VM guest state protection key
1313

1414
[!INCLUDE [applies-to](../includes/hci-applies-to-23h2.md)]
1515

16-
This article describes how to manually back up and restore a Trusted launch for Azure Local VM enabled by Azure Arc.
16+
You can backup and restore the VM guest state protection key of each Trusted launch VM on an Azure Local instance using one of the following approaches.
1717

18-
Unlike standard Azure Local VMs, Trusted launch for Azure Local VMs use a VM guest state protection (GSP) key to protect the VM guest state, including the virtual TPM (vTPM) state, while at rest. The VM GSP key is stored in a local key vault in the Azure Local system where the VM resides.
18+
**Approach 1** (recommended): Backup/restore VM guest state protection keys to/from a file system folder. You can use this approach starting with Azure Local 2505 release and onwards. If your Azure Local instance uses an earlier Azure Local release, you can instead use approach 2.
1919

20-
Trusted launch for Azure Local VMs store the VM guest state in two files, VM Guest state (VMGS) and VM Runtime state (VMRS). If the VM GSP key is lost, you can't boot up a Trusted launch for Azure Local VM.
20+
**Approach 2**: Backup/restore VM guest state protection keys to/from a key vault in another Azure Local instance. Use this approach only if your Azure Local instance uses an earlier Azure Local release earlier than 2505.
2121

22-
It is important that you back up your Trusted launch for Azure Local VM periodically, so you can recover your VM in the event of a data loss. To back up a Trusted launch VM, back up all the VM files, including VMGS and VMRS files. Additionally, back up the VM GSP key to a backup key vault.
22+
## Backup and restore VM guest state protection keys using file system folder
2323

24-
Similarly, to restore a Trusted launch for Azure Local VM to a target Azure Local system, restore all the VM files, including VMGS and VMRS files. Additionally, restore the VM GSP key from the backup key vault to another key vault on the target Azure Local system.
24+
To backup, this approach copies VM guest state protection keys from the local key vault of your Azure Local instance to a folder that is backed up periodically.
2525

26-
The following sections describe how you can back up the Trusted launch for Azure Local VM and restore it in the event of a data loss.
26+
To restore, this approach restores VM guest state protection keys from a folder (containing the backup copy) to the local key vault of an Azure Local instance where the VMs need to be restored.
2727

28-
## Back up the VM
28+
### Backup
2929

30-
You can use [Export-VM](/powershell/module/hyper-v/export-vm) to obtain a copy of all the VM files, including VMGS and VMRS files, for your Trusted launch for Azure Local VM. You can then back up those VM files.
30+
The steps below involve copying VM guest state protection keys from the local key vault of your Azure Local instance to a folder that is backed up periodically.
3131

32-
Follow these steps to copy the VM GSP key from the key vault on the Azure Local system (where the VM resides) to a backup key vault on a different Azure Local system:
32+
> [!NOTE]
33+
> You can only use this approach starting with Azure Local 2505 release and onwards. If your Azure Local instance uses an earlier Azure Local release, you can instead use approach 2.
34+
35+
1. On a secure computer using PowerShell 7, generate a wrapping key:
3336

37+
```azurepowershell
38+
$rsa = [System.Security.Cryptography.RSA]::Create(2048)
3439
35-
### 1. On the Azure Local system with the backup key vault
40+
$privateKeyPem = $rsa.ExportPkcs8PrivateKeyPem()
3641
37-
Run the following commands on the Azure Local system with the backup key vault.
42+
$privateKeyPem | Out-File -FilePath .\private.pem
3843
39-
1. Create a wrapping key in the backup key vault.
44+
$publicKeyPem = $rsa.ExportRSAPublicKeyPem()
4045
41-
```azurecli
42-
New-MocKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type RSA -size 2048
46+
$publicKeyPem | Out-File -FilePath .\public.pem
4347
```
4448
45-
1. Download the Privacy Enhanced Mail (PEM) file.
49+
1. Copy the `.\public.pem` file to your Azure Local instance.
4650
47-
```azurecli
48-
Get-MocKeyPublicKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -outputFile wrappingKey.pem
49-
```
51+
1. Copy VM guest state protection keys from the local key vault of your Azure Local instance to a folder that is backed up periodically:
5052
51-
### 2. On the Azure Local system where the VM resides
53+
1. Download `TvmBackupUtils.psm1` script file on GitHub repo `Azure-Samples/AzureLocal` to your Azure Local instance.
5254
53-
Run the following commands on the Azure Local system.
55+
1. Run `import-module .\TvmBackupUtils.psm1 -force`.
5456
55-
1. Copy the PEM file to the Azure Local system.
57+
1. Run `Backup-TVMKeys -WrappingKeyPath <path to public.pem> -BackupRootPath` (path to backup root folder where the timestamped backup folder will be stored).
5658
57-
1. Confirm the owner node of the VM.
59+
1. Make note of the timestamped backup folder created under the backup root folder. You will need this later during recovery.
5860
59-
```azurecli
60-
Get-ClusterGroup <VM name>
61-
```
61+
1. Make sure to periodically backup the backup root folder.
6262
63-
1. Run the following cmdlet on the owner node to determine the VM ID.
63+
### Restore
6464
65-
```azurecli
66-
(Get-VM -Name <VM name>).vmid
67-
```
65+
The steps below involve restoring VM guest state protection keys from a folder (containing the backup copy) to the local key vault of an Azure Local instance where the VMs need to be restored.
6866
69-
1. Export the GSP key for the VM.
67+
> [!NOTE]
68+
> You can only use this approach starting Azure Local 2505 release and onwards. If your Azure Local instance is on an earlier Azure Local release, you can instead use approach 2.
7069
71-
```azurecli
72-
Export-MocKey -name <VM ID> -wrappingKeyName wrappingKey -wrappingPubKeyFile wrappingKey.pem -outFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -size 256
73-
```
70+
1. Copy both private and public key files for the wrapping key (which you had created during backup step 1) to the Azure Local instance.
7471
75-
### 3. On the Azure Local system with the backup key vault
72+
1. Copy the timestamped backup folder to the Azure Local instance. Pick the folder (under the backup root folder) with the latest timestamp as that folder will have the most recent copy.
7673
77-
Run the following steps on the Azure Local system.
74+
> [!NOTE]
75+
>Don't modify the backup folder.
7876
79-
1. Copy the `<VM ID>` and `<VM ID>.json` file to the Azure Local system.
77+
1. Import the wrapping key (which you had created during backup step 1) to the Azure Local instance:
8078
81-
1. Import the GSP key for the VM to the backup key vault.
79+
1. Download the `TvmBackupUtils.psm1` script file (link to file on GitHub repo Azure-Samples/AzureLocal: Contains scripts, code samples, for Azure Stack HCI) to your Azure Local instance.
8280
83-
```azurecli
84-
Import-MocKey -name <VM ID> -importKeyFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type AES -size 256
85-
```
81+
1. Run `Import-Module .\TvmBackupUtils.psm1 -force`.
8682
87-
## Restore the VM
83+
> [!NOTE]
84+
> Make sure the WrappingKeyName you specify does not match the name of a key already existing in the backup (timestamped backup folder). Otherwise, this will cause a failure during import (restore step 4).
8885
89-
In the event of a data loss, use the backup copy of your VM files, and restore the VM to a target Azure Local system using [Import-VM](/powershell/module/hyper-v/import-vm). This restores all the VM files, including VMGS and VMRS files.
86+
1. Run `Import-TvmWrappingKeyFromPem -KeyName <WrappingKeyName>  -PublicKeyPath <path to public.pem> -PrivateKeyPath <path to private.pem> -KeySize <size of key generated 2048>`
9087
91-
Follow these steps to copy the VM GSP key from the backup key vault in the Azure Local system (where the backup copy of the VM GSP key was stored) to the key vault on the target Azure Local system (where the VM needs to be restored).
88+
1. Restore the keys from backup:
9289
93-
> [!NOTE]
94-
> Trusted launch for Azure Local VMs restored on an alternate Azure Local system (different from the Azure Local system where the VM originally resided) can't be managed from the Azure control plane.
90+
`Import-TVMKeys -WrappingKeyName  <WrappingKeyName> -BackupPath <path to timestamped backup folder>`.
9591
92+
> [NOTE!]
93+
> If the local key vault of the Azure Local instance already has a VM guest state protection key with the same name, you will receive an InvalidVersion error for that key. You can ignore this, as the key is already in the key vault.
9694
97-
### 1. On the source Azure Local system where the VM needs to be restored
95+
1. Cleanup files and keys
9896
99-
Run the following commands on the Azure Local system.
97+
1. Delete both public.pem and private.pem files from the Azure Local instance.
10098
101-
1. Create a wrapping key in the key vault.
99+
> [!IMPORTANT]
100+
> Remove the wrapping key from the local key vault of the Azure Local instance using Remove-MocKey. This will help avoid collisions later.
102101
103-
```azurecli
104-
New-MocKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type RSA -size 2048
105-
```
102+
1. Run `Remove-MocKey -name WrappingKeyName -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault`.
106103
107-
1. Download the Privacy Enhanced Mail (PEM) file.
104+
> [!NOTE]
105+
> You should start a VM on the Azure Local instance only after you have successfully restored both its VM files and its VM guest state protection key. If you had inadvertently attempted to start a VM before restoring its VM guest state protection key, you must delete the AzureStackTvmAKRootKey (which would have been auto generated) from the local key vault of the Azure Local instance.
108106
109-
```azurecli
110-
Get-MocKeyPublicKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -outputFile wrappingKey.pem
111-
```
107+
1. Run `Remove-MocKey -name  AzureStackTvmAKRootKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault`.
112108
113-
### 2. On the Azure Local system with the backup key vault
109+
## Backup or restore VM guest state protection keys via a key vault in another Azure Local instance
114110
115-
Run the following commands on the Azure Local system.
111+
To backup, this approach copies VM guest state protection keys from the local key vault of your Azure Local instance to the local key vault (backup key vault) of another Azure Local instance (which is used for key backup purposes).
116112
117-
1. Copy the PEM file to the Azure Local system.
113+
To restore, this approach restores VM guest state protection keys from the local key vault (backup key vault) of the Azure Local instance (which is used for key backup purposes) to the local key vault of an Azure Local instance where the VMs need to be restored.
118114
119-
1. Get the `<VM ID>` from the VM files stored on disk (wherever this is located). There will be a VM config file (.xml) that has the `<VM ID>` as its name. You can also use the following command to obtain the `<VM ID>` if you know the VM name. You need to do this step on a Hyper-V host that has the VM files.
115+
### Backup
120116
121-
```azurecli
122-
(Get-VM -Name <VM name>).vmid
123-
```
117+
Follow these steps to copy the VM guest state protection key from the local key vault of the Azure Local instance (where the VM resides) to a backup key vault on another Azure Local instance:
124118
125-
1. Export the VM GSP key for the VM.
119+
1. On the Azure Local system with the backup key vault, run the following commands on the Azure Local system with the backup key vault:
126120
127-
```azurecli
128-
Export-MocKey -name <VM ID> -wrappingKeyName wrappingKey -wrappingPubKeyFile wrappingKey.pem -outFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -size 256
129-
```
121+
1. Create a wrapping key in the backup key vault:
130122
131-
### 3. On the Azure Local system where the VM needs to be restored
123+
`New-MocKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type RSA -size 2048`
132124
133-
Run the following commands from the target Azure Local system.
125+
1. Download the Privacy Enhanced Mail (PEM) file:
134126
135-
1. Copy the `<VM ID>` and `<VM ID>.json` file to the Azure Local system.
127+
`Get-MocKeyPublicKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -outputFile wrappingKey.pem`
136128
137-
1. Import the VM GSP key for the VM.
129+
1. On the Azure Local system where the VM resides, run the following commands on the Azure Local system:
138130
139-
```azurecli
140-
Import-MocKey -name <VM ID> -importKeyFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type AES -size 256
141-
```
131+
1. Copy the PEM file to the Azure Local system.
142132
143-
> [!NOTE]
144-
> Restore the VM GSP key (complete the steps above) before you start the VM on the Azure Local system (where the VM needs to be restored). This ensures that the VM uses the restored VM GSP key. Otherwise, the VM creation fails, and a new VM GSP key is created by the system. If this happens by mistake (human error), delete the VM GSP key and then repeat the steps to restore the VM GSP key.
133+
1. Confirm the owner node of the VM:
145134
146-
```azurecli
147-
Remove-MocKey -name <vm id> -group AzureStackHostAttestation -keyvaultName > AzureStackTvmKeyVault
148-
```
135+
`Get-ClusterGroup <VM name>`
136+
137+
1. Run the following cmdlet on the owner node to determine the VM ID:
138+
139+
1. `(Get-VM -Name <VM name>).vmid`
140+
141+
1. Export the VM guest state protection key:
142+
143+
`Export-MocKey -name <VM ID> -wrappingKeyName wrappingKey -wrappingPubKeyFile wrappingKey.pem -outFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -size 256`
144+
145+
1. On the Azure Local system with the backup key vault, run the following steps on the Azure Local system:
146+
147+
1. Copy the <VM ID> and <VM ID>.json file to the Azure Local system.
148+
149+
1. Import the VM guest state protection key to the backup key vault:
150+
151+
`Import-MocKey -name <VM ID> -importKeyFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type AES -size 256`.
152+
153+
### Restore
154+
155+
Follow these steps to copy the VM guest state protection key from the backup key vault of the Azure Local instance (which was used for key backup purposes) to the local key vault of the target Azure Local system (where the VM needs to be restored):
156+
157+
1. On the source Azure Local system where the VM needs to be restored, run the following commands on the Azure Local system:
158+
159+
1. Create a wrapping key in the key vault:
160+
161+
`New-MocKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type RSA -size 2048`
162+
163+
1. Download the Privacy Enhanced Mail (PEM) file:
164+
165+
`Get-MocKeyPublicKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -outputFile wrappingKey.pem`
166+
167+
1. On the Azure Local system with the backup key vault, run the following commands on the Azure Local system.
168+
169+
1. Copy the PEM file to the Azure Local system.
170+
171+
1. Get the <VM ID> from the VM files stored on disk (wherever this is located). There will be a VM config file (.xml) that has the <VM ID> as its name. You can also use the following command to obtain the <VM ID> if you know the VM name. You need to do this step on a Hyper-V host that has the VM files.
172+
173+
`(Get-VM -Name <VM name>).vmid`
174+
175+
1. Export the VM guest state protection key.
176+
177+
`Export-MocKey -name <VM ID> -wrappingKeyName wrappingKey -wrappingPubKeyFile wrappingKey.pem -outFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -size 256`.
178+
179+
1. On the Azure Local system where the VM needs to be restored, run the following commands from the target Azure Local system:
180+
181+
1. Copy the <VM ID> and <VM ID>.json file to the Azure Local system.
182+
183+
1. Import the VM guest state protection key:
184+
185+
`Import-MocKey -name <VM ID> -importKeyFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type AES -size 256`.
186+
187+
> [!NOTE]
188+
> Restore the VM guest state key (complete the steps above) before you start the VM on the Azure Local instance (where the VM needs to be restored). This ensures that the VM uses the restored VM GSP key. Otherwise, the VM creation fails, and a new VM GSP key is created by the system. If this happens by mistake (human error), delete the VM GSP key and then repeat the steps to restore the VM GSP key.
189+
190+
`Remove-MocKey -name <vm id> -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault`.
149191
150192
## Next steps
151193

0 commit comments

Comments
 (0)