Command line restore of Hyper-V VM using vsshyv and nbksrv (only for backups stored in GIR disk pool) for 8.2.1 and newer:
Note: The method detailed in this KB article has only been tested using DataCenter 8.2.1 for Windows and newer. The backups were taken using DataCenter 8.2.1 and newer versions and the restore is being attempted with those versions. The process will likely not work exactly the same for earlier versions, which may require a different method.
The vsshyv command line restore method can be used for instance if you are unable to see your Hyper-V VM backup listed as an entry in DataCenter GUI and now need to restore it, for instance it was retented and no longer exists as a backup set on any disk pool device seen as a disk pool/media pool in DataCenter, as viewed in the Storage Management > Backup Servers > Disk Pool details area of the GUI, where it lists all of your backups as dated entries with the name of the VM. It can also be utilized if the VM in question does not list itself as a VM that can be restored in the "Restore" area of DataCenter GUI. For instance if your backup was retented and no longer exists as an item to restore either in the Restore area or listed as a backup in any disk pool, but you had a copy of the backup folders on an external hard drive or the cloud, and now you want to be able to restore it in DataCenter to either original Hypervisor location or as an extracted VM contents to pull the VHD/VHDX file from to attach it to a Hyper-V VM in Hyper-V Manager.
Note: The vsshyv tool only works for Hyper-V backups located in a GIR disk pool, if the original backup was not stored in a GIR disk pool you cannot restore it this way and have to use the nbksrv command line method for that. The vsshyv tool comes with DataCenter 8.2.0 and newer, located in the '%ProgramFiles%\NovaStor\DataCenter\modules\vsshyv\' folder.
1. In order to restore the VM backup to either the original location, or alternate folder path extract, using the vsshyv command line method, you will need to know the GIR disk pool device, VM ID, pool ID, and VM name for the VM backup. They are all required as command line parameters for the vsshyv tool. You can get these identifiers from the backup log viewed in Report Manager for the VM backup, if it still exists in Report Manager, for the actual log of the VM backup you are attempting to restore now, and the identifiers there have to match the backup set you are now trying to restore exactly. You can also get the identifiers by viewing the pool.db file (in notepad) located in the existing GIR disk pool folder location. You will be rebuilding the GIR disk pool anyways in a step below, using the rcmd-send command, and that rebuilt pool.db file also contains the identifier strings required to restore each VM backup via this vsshyv command line method. *The example Hyper-V backup log and pool.db files, used in all of the command parameter examples in the article, are attached as files here.
2. You will need to copy the backup from the GIR pool folder location on the backup media that you have it on, which is not seen in DataCenter currently, to the existing GIR disk pool where it originally existed before now. If the file was retented from '$ag-hvcluster2*xdisk|GIRClone2' disk pool then you need to copy the folder contents to '$ag-hvcluster2*xdisk|GIRClone2''s disk pool folder.
3. You will now need to rebuild the GIR disk pool database file using the nbksrv.exe executable that comes with DataCenter 8.2.1 and newer (the commands to perform the GIR disk pool database rebuild using nbksrv.exe is only compatible with DataCenter v8.2.1 and newer), so that it can read the backup sets that you just copied in place to the GIR pool folder.
- Using Windows Explorer navigate to your GIR pool folder on the backup server in question, browse to the GIR disk pool folder location where the VM backups existed originally and now have been copied to (the backups are stored under the GIR pool folder). Disable "Hide extensions for known file types" in Windows Explorer's View > Options screen, as we need to be able to see files by extension in Step 2. In the root of the GIR disk pool will be a pool.db file, this is where the GIR pool database and config files exist. Rebuilding a GIR pool requires running the nbksrv command which comes with all clients/backup servers/Command Servers, from the machine where the Backup Server's GIR pool actually exists on where you want to be able to restore the backups from using the Restore area of the GUI.
- Start an Admin Command Prompt on the node which is the Backup Server enabled node, where the GIR disk pool exists that you want to restore the backups to.
- In Admin Command Prompt, change directory to the nbksrv folder which is: cd %ProgramFiles%\NovaStor\DataCenter\nbksrv\.
nbksrv.exe rebuildpooldb --pool "GIR Pool"
- Note: "GIR Pool" = the actual GIR-disk pool's Pool name (not the Internal pool name). This can be seen from DataCenter Java GUI > Storage Management > Backup Servers > expand the Backup Server node and then select your GIR disk pool from the list, on the right side it will show the "Pool name:" value.
- For example, the screenshot below shows a new GIR disk pool that was just created on Backup Server "ag-hvcluster2", we then copy all of the VM backups that existed under the "VM_Test" folder on the original Backup Server "ag-hvcluster1". In the first screenshot you can see the selected VM folders under the original GIR disk pool, highlighted in yellow, which will be copied over to "ag-hvcluster2" which is highlighted in orange. The GIR-Disk Pool Details screen prior to running the rebuildpooldb command shows that the new GIR disk pool has no backups currently in it. The rebuildpooldb command will take care of rebuilding that pool.db so that it will know that all of the copied VM backup folders that were copied are present and restorable via the GUI.
The target "ag-hvcluster2" Backup Server machine is where we will run the nbksrv rebuildpooldb command. This will rebuild the pool.db that currently contains no backups in the database, so that after it is rebuilt it will then know that all of the VM backup folders that we copied earlier are now present. In this second screenshot we see that the VM folders that existed inside the original "ag-hvcluster1" Backup Server GIR disk pool folder, were copied over to the new "ag-hvcluster2" Backup Server GIR disk pool folder, then we ran the nbksrv rebuildpooldb command from Step 5 earlier, which rebuilt the pool.db so that it can show the full amount of VM backups that were copied in place, so that they all show in the GIR-Disk Pool details screen and are all now restorable via the GUI.
- The nbksrv rebuildpooldb command should show that it rebuilt the pool.db successfully. In this case now that the pool.db has been rebuilt and recreated with all of the backup folders that have been copied to that location contained in it, it will now show be able to show those backups inside the GUI in the GIR-Disk Pool Details screen. It will require refreshing the disk pool which you will do next.
- Now refresh the GIR-Pool via Storage Management, to display the rebuilt GIR disk pool details. Right-click on the GIR pool in question and click the "Refresh" function.
- The GIR Pool Details should now list all of the VM backup sets that you copied in place, with the name of each "Client" which equates to each Virtual Machine name, and the date of that VM backup. Note: It is important to remember and note the date for each VM backup here in this listing as it will be required later in Step 5 and 6.
4. Start an Admin Command Prompt and change directory to DC's modules\vsshyv folder (standard in 8.1+):
You can run this command either from the Command Server node or from a client node, in order to restore directly to Hyper-V Manager you will need to run the command from a node that contains the original Hyper-V server that the backup was taken from originally, otherwise you may run in to issues restoring it directly to Hyper-V as it relies on some properties of Hyper-V environment to be the same such as Network Adapters, etc.. You can also restore the Hyper-V backup as extracted contents which will output the virtual hard disk file(s) from the backup set, which you can use to attach to an existing or new VM later. Either method can work.
5. Here the vsshyv (DC Hyper-V backup/restore/mount command line executable, for backups in GIR pools only) command to use when issuing it from a client node (not the Command Server node) that has Hyper-V installed, it will restore to the client node you are currently on and relies on Hyper-V component to be in place on this node. Keep in mind that if your Hyper-V backup existing on one Hyper-V server and now you are attempting to restore it directly to another Hyper-V server that has differences in configuration in Hyper-V Manager then this restore method may not work for you as it relies on the version of Hyper-V Server to be similar as far as Hyper-V 2008/2012/2016/2019, etc., and if items such as the Network Adapter/Virtual Switch configuration in Hyper-V Manager is not the same as it was stored in the original VM backup it will take issue with that if found different when it goes to restore to a different Hyper-V Server than prior. With this restore method you do not need to reconfigure anything with the restored VM, it should just show up as an additional new VM in Hyper-V manager using the original VM name + a short ID string at the end of the original VM name:
vsshyv.exe --device "$ag-hvcluster2*xdisk|GIRClone2" --jobid a22870a4-250c-4981-95dc-57fbb39fbe14.fb915ae0-bc2b-4c8b-9d50-793ac1261a9d --poolid a22870a4-250c-4981-95dc-57fbb39fbe14.fb915ae0-bc2b-4c8b-9d50-793ac1261a9d --vmname JF-Ubuntu --vmuuid 39E15188-AE9A-4A74-8AD2-45F2802CBE06 restore
6. This is a break down of the parameters that are required for input for the rcmd-send tool:
The --device is the GIR disk pool device seen near the bottom of the VM backup log as "deviceString : $ag-hvcluster2*xdisk|GIRClone2", and in the Restore > Hyper-V area, listed on the most right hand column labeled as "Device". It will show the exact string to use there, to note it manually in notepad, etc. The --jobid and the --poolid parameter values will be the same for both values, and it relates to the actual identifier seen in the VM backup log seen at the top as "JobID : a22870a4-250c-4981-95dc-57fbb39fbe14.fb915ae0-bc2b-4c8b-9d50-793ac1261a9d" and "GirID : a22870a4-250c-4981-95dc-57fbb39fbe14.fb915ae0-bc2b-4c8b-9d50-793ac1261a9d" strings, and in the VM backup log again as "Nbkgirid : a22870a4-250c-4981-95dc-57fbb39fbe14.fb915ae0-bc2b-4c8b-9d50-793ac1261a9d", and finally as seen in the rebuilt pool.db file as "full uuid="a22870a4-250c-4981-95dc-57fbb39fbe14.fb915ae0-bc2b-4c8b-9d50-793ac1261a9d". The --vmuuid is the "Nbkvmid : 39E15188-AE9A-4A74-8AD2-45F2802CBE06" string found in the VM backup log, and seen in the rebuilt pool.db file as "uuid="39E15188-AE9A-4A74-8AD2-45F2802CBE06"
7. Here the vsshyv command is issued on either a Windows client node or the Windows Command Server directly to get it to restore the contents of the VM (VHD/VHDX) to an alternate folder on that node (I'm not able to figure out how to make it extract files to another node, possibly a mapped drive would be allowed to put X:\Restore in the --dest path), so it will create the folder on whatever node you are running the vsshyv command from in that case:
vsshyv.exe --device "$ag-hvcluster2*xdisk|GIRClone2" --jobid a22870a4-250c-4981-95dc-57fbb39fbe14.fb915ae0-bc2b-4c8b-9d50-793ac1261a9d --poolid a22870a4-250c-4981-95dc-57fbb39fbe14.fb915ae0-bc2b-4c8b-9d50-793ac1261a9d --vmname JF-Ubuntu --vmuuid 39E15188-AE9A-4A74-8AD2-45F2802CBE06 restore --mode vm --dest D:\HVRestore
Once this alternate folder / extract method restore is done you can then navigate to the folder where you told it to restore using --dest folder parameter (in this example 'D:\HVRestore'), and attempt to mount the .vhd or .vhdx file directly using right-click Mount method (if your Server OS supports that directly, Server 2008 and 2008 R2 will not but newer Server OS's should), if the drives mount for this VM you can inspect them in Explorer, and if they mount then the VHD/VHDX file is good and go ahead and disconnect the mounted drive. You would then copy the vhd/vhdx file to where it needs to be located and then attach it to either an existing Hyper-V VM or a new Hyper-V VM in Hyper-V Manager on whatever Hyper-V Server you want to use it on.
The full example Hyper-V backup log (viewed and then copied from the main tab of the log contents in the VM backup log via Report Manager) for the 'JF-Ubuntu' VM backup and the example pool.db, used in this article to reference are attached as files below, to know how the parameters can work for your case, to make it easier. The file attachments are 'JF-Ubuntu_VM_backup.log' and 'pool.db'.