ESXi Host Configuration Backup and Restore with PowerCLI and ESXCLI: Saving Your Virtualization Cluster During Outages - ITFROMZERO - Share tobe shared! A step-by-step guide to backing up and restoring ESXi host configurations using ESXCLI and PowerCLI. Learn how to recover failed hosts in 10-15 minutes during hardware outages.

Table of Contents

Context & Why You Cannot Afford to Skip ESXi Configuration Backups

Most sysadmins invest heavily in virtual machine (VM) backups using solutions like Veeam, Nakivo, or Synology Active Backup. This is completely justified because data is the core asset. However, many systems engineers overlook the foundational layer: the host configuration of the ESXi server itself.

In production environments, USB boot drives and SD cards running ESXi are prone to failure after 2–3 years of continuous logging. When the boot medium fails, the server crashes entirely. You lose your entire setup: vSwitches, port groups, VLAN tags, VMkernel ports for iSCSI/NFS storage, firewall rules, and local user accounts.

While VM data residing on SAN/NAS storage remains safe, you are still forced to rebuild the host from scratch. Manually reconfiguring dozens of IP ranges, subnets, and VLANs not only consumes half a working day but also carries the risk of typos in network parameters that can prevent VMs from booting properly.

In an 8-node Dell R640 cluster I manage, the SD card on host 03 suddenly died at 8:00 AM on a Monday. Thanks to a configuration backup stored on our Synology NAS, I replaced the card, reinstalled ESXi, and restored the full configuration in just 12 minutes. The host rejoined the cluster seamlessly with zero disruption to production workloads.

An ESXi configuration backup is packaged into a compact configBundle.tgz archive (typically 80KB to 300KB), yet it contains everything you need:

Virtual Switch configuration (standard vSwitches and Distributed Virtual Switch proxy switches).
Storage Fabric configuration (Software iSCSI IQNs, NFS mount paths, Fibre Channel zoning details).
Core network settings: static IPs, default gateway, DNS, NTP servers, and Syslog exporters.
Custom SSL certificates, root/local user accounts, and license keys.

Environment Preparation

Depending on your network topology and access level, there are two primary approaches: using ESXCLI/vim-cmd directly over SSH (ideal for local disaster recovery) or using VMware PowerCLI (ideal for centralized management and automation).

1. Enable SSH on the ESXi Host

ESXi disables SSH by default for security hardening. To enable direct CLI access:

Log in to the ESXi Host Client via your browser: https://<ESXi-IP>/ui.
Navigate to Manage > select the Services tab.
Locate the TSM-SSH service, right-click it, and select Start.

2. Install VMware PowerCLI on the Management Machine

PowerCLI runs smoothly on PowerShell 7 across Windows, Linux, and macOS. This is the optimal route if you want to automate scheduled backups across multiple nodes.

Launch PowerShell as Administrator and run:

# Install the official PowerCLI module from the PowerShell Gallery
Install-Module -Name VMware.PowerCLI -Scope CurrentUser -Confirm:$false

# Ignore SSL warnings for self-signed certificates
Set-PowerCLIConfiguration -InvalidCertificateAction Ignore -Confirm:$false

Detailed Backup & Recovery Workflow

Mandatory Step: Flush RAM Changes to the Boot Partition

ESXi caches runtime configuration changes in memory (RAM). If you have recently changed an IP address or added a port group and export the configuration immediately, the backup bundle will miss that data. Always force an operating system sync to the boot disk first:

vim-cmd hostsvc/firmware/sync_config

Method 1: Executing vim-cmd Commands via SSH

This approach is best suited for quick single-host backups or when vCenter Server is unavailable.

Backup Steps:

# 1. Force the system to sync configuration state from RAM
vim-cmd hostsvc/firmware/sync_config

# 2. Generate the configuration backup bundle
vim-cmd hostsvc/firmware/backup_config

The terminal will return a download URL formatted like this:

Bundle can be downloaded at : http://*/downloads/123456/configBundle-esxi01.local.tgz

Replace the * wildcard with your ESXi host’s IP address (e.g., http://192.168.10.50/downloads/123456/configBundle-esxi01.local.tgz). Paste the link into your browser to download the archive to your workstation.

Restore Procedure:

After performing a fresh installation of ESXi (which must match the original build number):

Rename the downloaded file to the standard naming convention: configBundle.tgz (the restore utility rejects files retaining the long hostname suffix).
Use SCP or WinSCP to transfer the file to the host’s /tmp/ directory:

scp configBundle.tgz [email protected]:/tmp/

Open an SSH session to the host and execute the restore sequence:

# Put the host into Maintenance Mode
esxcli system maintenanceMode set --enable true

# Restore configuration (flag '1' triggers an automatic reboot immediately after application)
vim-cmd hostsvc/firmware/restore_config /tmp/configBundle.tgz 1

The server will unpack the archive, reapply the entire configuration, and initiate a reboot. Once back online, all vSwitches, port groups, and datastores will be restored to their original state.

Method 2: Automating with VMware PowerCLI

If you manage three or more hosts, leveraging PowerCLI allows you to perform cluster-wide backups simultaneously rather than running manual commands on individual nodes.

Backing Up a Single Host:

# Connect to the ESXi host
Connect-VIServer -Server 192.168.10.50 -User root -Password 'ESXiPassword'

# Export the backup bundle to the management drive
Get-VMHostFirmware -VMHost 192.168.10.50 -BackupConfiguration -DestinationPath "D:\VMware_Backups\"

Disconnect-VIServer -Confirm:$false

Cluster-Wide Automated Backup Script:

The following script enumerates all hosts managed by vCenter, organizes backups into dated directories, and downloads the configuration archives automatically:

$vCenter = "vcenter.itfromzero.local"
$DateFolder = Get-Date -Format 'yyyy-MM-dd'
$BackupDir = "D:\ESXi_AutoBackup\$DateFolder"

if (!(Test-Path -Path $BackupDir)) {
    New-Item -ItemType Directory -Path $BackupDir | Out-Null
}

Connect-VIServer -Server $vCenter -User [email protected] -Password 'AdminPassword'

$AllHosts = Get-VMHost
foreach ($HostNode in $AllHosts) {
    Write-Host "[+] Backing up: $($HostNode.Name)" -ForegroundColor Cyan
    Get-VMHostFirmware -VMHost $HostNode -BackupConfiguration -DestinationPath $BackupDir
}

Disconnect-VIServer -Confirm:$false
Write-Host "[✓] Completed backup for all $($AllHosts.Count) hosts!" -ForegroundColor Green

Restoring Configuration Using PowerCLI:

Connect-VIServer -Server 192.168.10.50 -User root -Password 'ESXiPassword'

# Enter Maintenance Mode
Set-VMHost -VMHost 192.168.10.50 -State "Maintenance"

# Restore configuration (ESXi will automatically reboot after this command)
Set-VMHostFirmware -VMHost 192.168.10.50 -Restore -SourcePath "D:\VMware_Backups\configBundle-192.168.10.50.tgz" -HostUser root -HostPassword 'ESXiPassword'

Two Critical Technical Rules to Remember During Restore

Exact Build Number Match: The target ESXi installation must run the exact same patch level as the original host (e.g., both on ESXi 7.0 Update 3k, Build 21313628). Restoring an older configuration bundle onto a newer build or across major versions (e.g., 7.0 to 8.0) will corrupt the VMkernel configuration and cause boot failures.
Hardware UUID Mismatch Handling: If restoring onto a replacement chassis (with differing NIC MAC addresses or motherboard serials), the PowerCLI restore cmdlet will throw a UUID mismatch error. Append the -Force parameter to the Set-VMHostFirmware cmdlet to override this check. After rebooting, make sure to verify the physical network adapter mapping (vmnic0, vmnic1).

Validation and Periodic Monitoring Setup

A backup that has never been tested in a restore scenario leaves your infrastructure exposed.

1. Validate Archive Integrity and File Size

A valid configBundle.tgz file typically ranges between 50KB and 300KB. If the downloaded file is 0KB or only a few bytes, the export pipeline terminated prematurely. Inspect the archive using 7-Zip or the Linux tar command to verify it contains two essential files: state.tgz and Manifest.txt.

# Verify archive structure on Linux/macOS
tar -ztvf configBundle.tgz

2. Automate Schedules with Windows Task Scheduler

Never rely on memory. Integrate the PowerCLI script into Windows Task Scheduler to run automatically every Sunday at 23:00. In addition, enforce a strict operational baseline: whenever you modify VLAN configurations, switch uplink assignments, or replace HBA adapters, run a backup immediately.

3. Offsite and Isolated Storage Tiers

Never store backup archives on the host’s own local datastore. Ship backups automatically to an internal NAS, a management VM hosted on a separate cluster, or a properly permissioned cloud storage bucket. Spending 15 minutes setting up automation today guarantees you can resolve host failures with speed, precision, and zero panic.