ESXi host configurations can easily be backed up and restored using either the vCLI's vicfg-cfgbackup or PowerCLI's Get-VMHostFirmware cmdlet. These commands along with others that perform "write" operations are only supported when you have a (paid) licensed version of ESXi. If you are using free ESXi, the remote commands are only available for "read-only" operations. For more details, please refer to this article here.
Note: In my personal opinion, it is much quicker and more efficient to re-install ESXi and apply your configurations using either a scripted deployment such as kickstart or a combination along with post configuration scripts. Re-installs become extremely trivial when you centralize your ESXi host configurations, even for small setups.
Having said that, if you are running free ESXi in a small shop or in a home lab and wish to backup your ESXi host configurations, you can still do so by leveraging a neat little tool called vim-cmd found within the ESXi Shell. There is a section under hostsvc/firmware which manages the ESXi host configuration which also uses the same vSphere APIs that both vicfg-cfgbackup & Get-VMHostFirmeware command uses.
Under this section of vim-cmd, there are four commands:
- backup_config
- reset_config
- restore_config
- sync_config
Prior to actually backing up your ESXi host configuration, run the following command which will flush the ESXi configuration changes:
vim-cmd hostsvc/firmware/sync_config
To backup the ESXi host configurations, run the following command which will generate a file that will be automatically stored in /scratch/downloads and can also be downloaded from a web browser using the URL shown from the output:
vim-cmd hostsvc/firmware/backup_config
Before restoring your ESXi host configurations, you will need to ensure the file is renamed to configBundle.tgz and stored under /tmp directory. You will also need to ensure the ESXi host is placed in maintenance mode by running the following command:
vim-cmd hostsvc/maintenance_mode_enter
To restore the ESXi host configurations, run the following command and specify the backup configuration file which should reside in /tmp/configBundle.tgz:
vim-cmd hostsvc/firmware/restore_config /tmp/configBundle.tgz
Note: Upon completing the restore, it will automatically reboot your ESXi host.
Here is a screenshot using the above commands to backup and then restore ESXi host:
Note: You can not restore an ESXi host using a configuration file backed up from a different host.
Anonymous says
Hello William,
I tried this for my home lab (Free ESXI 5.1) and I get the following error when I try to restore the config.
===============================
~ # vim-cmd hostsvc/firmware/restore_config /tmp/configBundle.tgz
(vmodl.fault.SystemError) {
dynamicType = ,
faultCause = (vmodl.MethodFault) null,
reason = "Internal error",
msg = "A general system error occurred: Internal error",
}
===========================================
Patrick says
Probably because the API's are read-only in the free ESXi version, so you can backup, but not retore.
Try restoring to a host with evaluation license activated. You may need to reinstall the host first, if your evaluation period has expired.
lgarc says
Hello William,
Is not possible to restore one ESXi host from another? It would be interesting. Imagine that your ESXi host crash and is not possible to use the machine and you want to export this configuration to another ESXi.
Regards.
William Lam says
I've not done this personally, so I can't comment but I assume this *should* be possible ...
Anonymous says
I backed up the ESXi config using vim-cmd hostsvc/firmware/backup_config and then restored to a different ESXi host running the same version (5.0 update 2), and the restore fails with this error. Can you verify restoring a configuration that was backed up from a different host would work?
vim-cmd hostsvc/firmware/restore_config /tmp/configBundle.tgz
(vim.fault.MismatchedBundle) {
dynamicType = ,
faultCause = (vmodl.MethodFault) null,
bundleUuid = "00000000-0000-0000-0000-002590882A6C",
hostUuid = "00000000-0000-0000-0000-002590882A48",
bundleBuildNumber = 1,
hostBuildNumber = 1,
msg = "fault.MismatchedBundle.summary",
Samir says
I was able to restore config file of Server A to Server B using the below steps. Basically you just have to update the UUID # under Manifest.txt file.
Part 1
(1) Backup host config of Server B using this article. This will create a file named configBundle.tgz.
(2) Copy the tgz file to /tmp folder using cp command. Change directory to /tmp: cd /tmp
(3) Extract configBundle.tgz file: tar zxvf configBundle.tgz
(4) Open Manifest.txt file and write down the UUID: cat Manifest.txt
(5) Remove configBundle.tgz file, Manifest.txt file and state.tgz file using rm command.
Part 2
(1) Copy host config file of Server A to /tmp folder under Server B.
(2) Change directory to /tmp.
(3) Extract configBundle.tgz file: tar zxvf configBundle.tgz
(4) Open Manifest.txt file using vi and update the UUID with the one you wrote down for Server B. Save the file.
(5) Remove or rename configBundle.tgz file under /tmp.
(6) tar manifest.txt and state.tgz files: tar zcvf configBundle.tgz Manifest.txt state.tgz
(7) run the vim-cmd restore command to restore the config.
William Lam says
I would recommend filing an SR, someone from GSS should be able to confirm for you.
Anonymous says
Since VMware doesn't mention this important fact anywhere (at least not to my knowledge) you may want to consider adding a strong notice that the backup file generated in /downloads (and anything else there, for that matter) is downloadable via a web browser with no authentication required what-so-ever. So people making backups this way should be aware of security implications and get used to clean up after themselves.
I wouldn't say it's a bug as VMware never stated (to my knowledge) that /downloads part of the web was supposed to be protected, but I would call it frivolous of them at the very least. People are told that the backup is ready there to be downloaded, but they are not warned of the absence of any security protection concerning the backup file (the very file that is the most precious and security important file of the whole server) and thus that anyone can download it. Nevertheless, there is no reason to leave the backup file there so if they do it's their fault.
A wholly different situation is with the vicfg-cfgbackup.pl script, though. This script is supposed to be run remotely and basically does two things: it invokes backup_config and then downloads the file off the web on its own. That's all nice and cool except a little detail - it doesn't delete the file from /downloads, it leaves it there. This fact is again nowhere documented and on top of that the users are actually never told that any file was ever created in /downloads during the vicfg-cfgbackup.pl run. This I would call a serious security bug and VMware's failure.
Anyway, as an alternative and much safer solution to periodically collect backups I would suggest using the ESXi's own backup processes that are already in place. ESXi is doing automatic backups every hour via cron into /(alt)bootbank/state.tgz so if a backup old less than 1 hour is sufficient then there is no need to invoke any backup command at all and instead simply pull the state.tgz file via scp. If the most current backup is needed then all what is necessary to do is to invoke sync_config prior pulling the file. This way all the troubles with /downloads are avoided.
If using scp way I would recommend disabling PermitRootLogin in sshd_config and creating a separate user just for the purpose of pulling backups, with its own authorized_keys, with no permissions in GUI (datastore, VMs etc.) and with IP filter set in access.conf.
William Lam says
Appreciate the feedback and I was not aware that the backup was not being removed in /downloads (which I just confirmed on the latest build of ESXi 5.1u1). I'll bring this up internally and also file a bug, I agree that at a minimum the file should be removed or at least provide some authentication mechanism to access the file, even downloading (the user had already authorized and we should ensure that's always checked).
WellThen says
Appreciate this info very much! But I have some questions, so let me describe the steps to make sure I understand.
To backup ESXI configuration from USB, just one step:
1. scp the file /(alt)bootbank/state.tgz to some safe location
To restore configuration (in the event my USB drive goes bad):
1. Perform install of ESXI from installation media onto new USB drive
2. scp the backup state.tgz onto the new disk
3. Rename \bootbank folder to bootbankorig
4. Create new \bootbank folder
5. Extract state.tgz into the new \bootback folder
6. Reboot from new USB
Is that everything? Do I have to do something special when the new USB boots for the first time to tell ESXI that it's OK to use, etc?
Bengt Magne says
Thanks! Really appreciate your blog.
John c says
Very slick, works on 6.0. One item noted that the configBundle-*.tgz was removed from downloads after I downloaded with Firefox. Directory and all! vSphere appliance happy with host. Thank you!
Nicholas Derasmo says
Hi!! I made a big mistake in my home lab by changing the IP for my VCSA.OVA running in my vm workstation lab environment. Needless to say, I had to create the VCSA.ova and import it into my workstation lab.. Now I am missing all of my DS switches, DRS, HA, Resource pools etc.. The switches do exist when I login to each esxi host via the VC client but sadly not my VCSA SSO... Is there any way to reimport all the hard work I spent creating the cluster, DRS, HA, vSwitches, etc from my ESXi hosts back into my VCSA appliance?
Thanks again
stamster says
Great. Simple, fast, free! All of your blog posts are like that! THANKS A LOT MAN. Keep up the good work!
Euge Oliveri says
Found an error in ESXi 6.0 U3 while backuping up a config from and USB boot disk.
vim-cmd hostsvc/firmware/backup_config --> "internal error"
And the problem was a link to the /scratch/download dir. This points to /usr/lib/vmware/hostd/docroot .
Re create the /scratch/download dir and voila! the
The link to the original note: https://www.elasticsky.de/2013/08/esxi-config-export-error/ which uses a Japanese blog data: http://srvinfo.exblog.jp/16871567/.
Best,
Eugenio
chris says
Hi Wiliam, does the esxi host script backup include backing up custom vibs? Guess my questions is, does this backup everything or do I need to config stuff after restoring a backup on bare metal?
François says
For solve : Do Not rename your backup file. Put it on \tmp of your host with winscp (ssh activated). And finaly, type the command as it :
vim-cmd hostsvc/firmware/restore_config /tmp/configBundle.tgz