Short answer: On the ESXi shell run vim-cmd hostsvc/firmware/sync_config and then vim-cmd hostsvc/firmware/backup_config, and download the configBundle-*.tgz from the URL it prints. With PowerCLI use Get-VMHostFirmware -BackupConfiguration. To restore, the host must run the same ESXi build and, by default, keep the same UUID. Put it in maintenance mode and use restore_config or Set-VMHostFirmware -Restore. The host reboots.
Which ESXi backup do you need?
| You want to protect | Use | Covered here |
|---|---|---|
| The host’s own settings: standard switches, VMkernel ports, storage adapters, users, services, advanced settings | ESXi configuration bundle (backup_config / Get-VMHostFirmware) | Yes, this page |
| Virtual machines and their data | A VM backup product that uses the vSphere data protection APIs | No. The config bundle contains no VMs and no VM inventory. |
| The ESXi image: base image, vendor add-on, drivers and VIBs | The cluster’s vSphere Lifecycle Manager image. Reinstall the same build (bootable ESXi installer USB), then restore the bundle. | Only the “same build” rule |
| One standard configuration for every host in a cluster | Host Profiles, or vSphere Configuration Profiles on vSphere 8 and later | No. It is complementary to the bundle. |
| Distributed switch configuration | vCenter (export the VDS configuration from vCenter) | No. Per KB 313510 the restore brings back standard-switch networking. The VDS comes from vCenter. |
What the ESXi configuration backup contains
The bundle holds the host’s configuration: networking (vSwitches, VMkernel ports), storage settings, users, services, advanced settings and similar. According to Broadcom KB 313510 it does not contain:
- Virtual machine inventory. After a restore you re-register VMs from the datastores.
- Bootbank contents (the ESXi image and VIBs themselves).
The same KB says the procedure is not supported for Distributed Services Engine (DPU) server configurations or for Auto Deploy-provisioned hosts. VM data and datastores need a real backup product; this covers only the host.
ESX 9: KB 313510 lists no 9.x-specific exceptions, so the same vim-cmd hostsvc/firmware and Get-VMHostFirmware procedure applies. On VCF hosts the restore only brings the host back to its own last state. Reconnecting it to vCenter and the distributed switch is still a vCenter task. Test a restore on one lab host before relying on it in production.
Back up ESXi configuration from the command line (vim-cmd)
Enable SSH or the ESXi Shell, log in as root and first record the two values the restore will depend on:
vmware -vl # ESXi version and build number
esxcfg-info -u # host UUID
vim-cmd hostsvc/firmware/sync_config
vim-cmd hostsvc/firmware/backup_config
# Bundle can be downloaded at : http://*/downloads/<id>/configBundle-<host>.tgzReplace * with the host FQDN or IP and download the file with a browser or wget. The file sits under /scratch/downloads only temporarily, so copy it off the host immediately. Store the build number and UUID next to the bundle.
Back up ESXi configuration with PowerCLI (including via vCenter)
Connect-VIServer vcenter.lab.local # or connect directly to the host
Get-VMHostFirmware -VMHost esx01.lab.local -BackupConfiguration -DestinationPath C:\Backup\ESXi
# all hosts managed by vCenter
Get-VMHost | Get-VMHostFirmware -BackupConfiguration -DestinationPath C:\Backup\ESXiPowerCLI downloads the bundle from the host itself, so the machine running it needs network access to each host on TCP 443 and TCP 80, per the KB. A missing port 80 rule is the usual reason this fails when you back up ESXi configuration from vCenter.
Schedule ESXi configuration backups for a whole vCenter
A one-time backup goes stale after the next VMkernel or storage change. This PowerCLI script backs up every connected host through vCenter into a dated folder. It writes the build number and host UUID next to each bundle (the two values a restore depends on) and deletes folders older than the retention period. Run it from Windows Task Scheduler or cron (PowerShell 7) on a management VM that can reach every host on TCP 443 and 80.
# Backup-EsxiConfig.ps1 – requires VMware.PowerCLI (VCF.PowerCLI)
param(
[string]$VCenter = 'vcenter.lab.local',
[string]$Root = 'D:\Backup\ESXi',
[int]$RetentionDays = 30
)
Connect-VIServer -Server $VCenter | Out-Null # use a stored credential, not a password in the script
$target = Join-Path $Root (Get-Date -Format 'yyyy-MM-dd')
New-Item -ItemType Directory -Path $target -Force | Out-Null
foreach ($h in Get-VMHost | Where-Object { $_.ConnectionState -in 'Connected','Maintenance' }) {
try {
Get-VMHostFirmware -VMHost $h -BackupConfiguration -DestinationPath $target -ErrorAction Stop | Out-Null
$esxcli = Get-EsxCli -VMHost $h -V2
[pscustomobject]@{
Host = $h.Name
Version = $h.Version
Build = $h.Build
Uuid = $esxcli.system.uuid.get.Invoke()
} | Export-Csv (Join-Path $target 'hosts.csv') -Append -NoTypeInformation
} catch {
Write-Warning "$($h.Name): $($_.Exception.Message)"
}
}
Get-ChildItem $Root -Directory |
Where-Object { $_.CreationTime -lt (Get-Date).AddDays(-$RetentionDays) } |
Remove-Item -Recurse -Force
Disconnect-VIServer -Confirm:$false- Run it after every change window, not only nightly. A restore needs a bundle from the same build, so take a fresh backup after each ESXi patch.
- Bundles of TPM-protected hosts restore only onto the same TPM. Keep the encryption recovery keys (
esxcli system settings encryption recovery list) in your password vault next to the bundles. - The bundle contains password hashes and host certificates. Store it with the same access controls as other credentials.
Restore rules you cannot skip
| Requirement | Why it matters |
|---|---|
| Same ESXi build as the backup | Install the exact build first (vmware -vl), then restore. |
| Same host UUID | Default restore refuses a mismatch; restore_config 1 forces it. |
| Maintenance mode | Required before the restore. |
| Reboot before restore | The KB lists a reboot as part of the workflow. |
| Automatic reboot after restore | Plan the outage. |
Restore ESXi configuration with vim-cmd
- Rename the file to
configBundle.tgzand copy it to a datastore on the host. - Enter maintenance mode:
vim-cmd hostsvc/maintenance_mode_enter - Reboot the host.
- Move the bundle to
/tmp/configBundle.tgz. - Run
vim-cmd hostsvc/firmware/restore_config 0(or1to override a UUID mismatch). The host reboots when done.
Restore with PowerCLI Set-VMHostFirmware
Set-VMHost -VMHost esx01.lab.local -State Maintenance
Restart-VMHost -VMHost esx01.lab.local -Confirm:$false
# wait for the host to come back
Set-VMHostFirmware -VMHost esx01.lab.local -Restore -SourcePath C:\Backup\ESXi\configBundle-esx01.lab.local.tgz -HostUser root -HostPassword '<password>'The old vSphere CLI command vicfg-cfgbackup is still in the KB, but only for vSphere 6.7 and earlier. On 7.x, 8.x and 9.x use vim-cmd or PowerCLI.
TPM and encrypted configuration caveats
Since vSphere 7.0 U2 the ESXi configuration can be sealed to the host’s TPM. Broadcom’s KB states that in that case the force option does not work if the host has been changed. In other words, restore_config 1 will not move a TPM-protected config to replacement hardware. What protects you is the recovery key. Record it on every TPM-equipped host and store it off-host, as described in Manage a Secure ESXi Configuration:
esxcli system settings encryption recovery listIf a recovered host keeps asking for the recovery key at every boot and backup_config fails with “Internal error”, check the boot options. KB 410638 traces this to a missing or malformed bootUUID or recovery-key entry.
For other host-level commands see esxcli commands for ESXi 8.0. If you run the free hypervisor, see Free VMware ESXi 8.
Further reading
- Broadcom KB 313510: How to back up and restore the ESXi host configuration
- Broadcom KB 410638: ESXi settings are not persisted after restoring an encrypted ESXi with its recovery key
- Broadcom TechDocs: Manage a Secure ESXi Configuration
- Mateusz Romaniuk (vMattroman): Backup and restore ESXi host configuration data using command line (original post)
