ghettoVCB Configuration: ghettoVCB.conf Settings Guide

The ghettoVCB configuration file is where a backup stops being a one-off command and becomes a policy. The file is called ghettoVCB.conf, and it holds the settings the script reads on every run: where backups go, what disk format they use, how many old copies to keep, how snapshots behave, and whether VMs are powered down first. Get the file right, and every backup follows the same rules. Get it wrong, and the script will happily fill the wrong datastore or skip the VMs you meant to protect, so this file deserves a careful read before you change anything.

Open the file with a plain text editor that writes Unix line endings. The project warns in practical terms that Windows line endings cause trouble, and that warning is worth heeding, because a config file edited on Windows and copied to the host can fail in confusing ways. The README is the authority for the settings in your version of the script, and this guide explains what each group of settings means in plain language.

Where Backups Go: VM_BACKUP_VOLUME

The most important setting is VM_BACKUP_VOLUME. It is the directory every backup goes to, for example /vmfs/volumes/datastore1/BACKUP with your real datastore and folder names. Inside that directory, the script creates a folder per VM, and inside each VM folder it creates a dated folder per backup run. The full path matters, and it must point at storage that is not the datastore holding the VMs. Backups on the same datastore as the originals do not survive the datastore failure they exist to protect against, so choose the destination with that rule in mind and check the free space before the first run.

There is one exception to this setting. When non-persistent NFS mode is on, the script ignores VM_BACKUP_VOLUME and uses the NFS settings instead. That exception is covered in the NFS guide on this site. For local, SAN, and persistent NFS destinations, VM_BACKUP_VOLUME is the setting that decides where your backups live, and a typo here is the single most common configuration mistake. Type the path, then verify it exists from the shell before you run a backup.

Disk Format: DISK_BACKUP_FORMAT

DISK_BACKUP_FORMAT decides the format of the VMDK files in the backup. The choices are thin, zeroedthick, eagerzeroedthick, 2gbsparse, and sesparse. Thin is the usual choice for space efficiency, because a thin backup only uses the space the data actually occupies, rather than the full provisioned size of the disk. Thick formats reserve the full space up front. The sparse formats split disks into 2 GB pieces, which is useful on filesystems and transfer methods that handle smaller files better.

One restriction is absolute. On non-VMFS volumes, such as NFS, only 2gbsparse and thick formats can be used. If you set a thin format against an NFS destination, the backup will not behave as you expect, and the failure may not be obvious until you try to restore. Match the format to the destination filesystem, test a backup and a restore with the format you chose, and do not change formats casually between runs, because mixed formats in one backup set make restores harder to reason about.

Rotation and Folder Names

VM_BACKUP_ROTATION_COUNT sets how many backups of each VM are kept before the oldest is deleted. If you set it to 3, the script keeps the three newest backups of a VM and deletes the fourth oldest when a new one arrives. Rotation is your space control. Without it, full copies accumulate until the datastore fills, and a full backup datastore is a failed backup system. Set the count by thinking backwards from your space: how big is a full backup set, how much space does the destination have, and how many days back do you need to reach?

VM_BACKUP_DIR_NAMING_CONVENTION sets how each backup folder is named, usually with a date and time, for example a pattern based on $(date +%F_%H-%M-%S). The convention must not contain spaces, because spaces in paths break shell scripts in subtle ways. A date-based name makes the backup folders sort in order and tells you at a glance when each backup ran. Keep the convention stable once you choose it, because scripts, reports, and your own habits will all learn to read it.

Power, Snapshots, and Quiescing

The power settings decide whether a VM is shut down before its backup. POWER_VM_DOWN_BEFORE_BACKUP powers the guest OS down before the backup and powers it back on afterwards. A powered-down backup is the most consistent kind, because nothing is changing while the files copy. The catch is that the shutdown assumes VMware Tools is installed in the guest, and without Tools the script will wait for a shutdown that never happens. Do not enable power-down backups for a VM unless you have confirmed Tools is installed and a shutdown works. The related settings ENABLE_HARD_POWER_OFF, ITER_TO_WAIT_SHUTDOWN, and POWER_DOWN_TIMEOUT control how long the script waits for a graceful shutdown, in iterations of 60 seconds, before it forces the issue or gives up.

The snapshot settings control how the snapshot itself behaves. VM_SNAPSHOT_MEMORY decides whether guest memory is included in the snapshot, VM_SNAPSHOT_QUIESCE asks the guest to quiesce its filesystem for a cleaner snapshot, and VM_SNAPSHOT_CONSOLIDATE controls consolidation behavior. SNAPSHOT_TIMEOUT sets how long snapshot operations may take. ALLOW_VMS_WITH_SNAPSHOTS_TO_BE_BACKEDUP is off by default, which means VMs with existing snapshots are skipped.

Compression and Email

ENABLE_COMPRESSION controls whether backup files are compressed. A value of 0 turns compression off. A value of 1 compresses with tar and gzip. A value of 2 compresses only the .vmsn and .vmdk files. Compression saves space at the cost of time and CPU, and it changes what a restore looks like, because compressed backups must be decompressed before the VM can be registered. Test a compressed backup and its restore before you rely on compression, and remember that compression does not turn a full backup into an incremental one. Each run still copies the full disks, compressed or not.

The email settings, EMAIL_ALERT, EMAIL_LOG, EMAIL_SERVER, EMAIL_SERVER_PORT, EMAIL_TO, EMAIL_ERRORS_TO, and EMAIL_FROM, let the script send a report after each run. Email needs the ESXi firewall email rule opened for outbound port 25, followed by a firewall refresh with esxcli network firewall refresh. If email is your only notification, test it by running a backup and confirming the message arrives.

Per-VM Policies and Startup Order

One shared configuration fits most hosts, but the script also supports per-VM policies. With a list file and a configuration directory, the -c option lets each VM use its own configuration file, so a critical VM can keep more rotations or use a different format than a lab VM. Per-VM .vmx extra options can also override behavior for one VM, such as power-off behavior, though you should treat those overrides as advanced settings and document any you use.

VM_SHUTDOWN_ORDER and VM_STARTUP_ORDER control the order in which VMs are shut down and started when power-down backups are used, and WORKDIR_DEBUG controls debug output location. Order matters when VMs depend on each other, such as a database VM that should stop after the application VM that uses it.

A Safe Way to Change Settings

Copy the working configuration file before you edit it, so you can roll back in seconds
Change one setting at a time, and write down why you changed it
Edit with Unix line endings, never with an editor that writes Windows line endings
Verify the backup volume path exists and has free space before the first run
Test every change with a dry run, then with one real VM, before you schedule it
Keep the README open while you edit, because it is the authority for your version

That routine feels slow the first time, and it prevents the two classic configuration disasters: a destination typo that writes backups to the wrong place, and a rotation count that deletes the only good backup. Configuration files are read by a script running as root, so they deserve the same care as the script itself.

Conclusion

ghettoVCB.conf turns a script into a backup policy. The destination, disk format, rotation count, and naming convention decide where backups live and how long they last. The power and snapshot settings decide how consistent each backup is. Compression and email decide what each backup costs and who hears about it. Change one setting at a time, test with a dry run, and keep a copy of the working file. When the configuration is proven on one VM, scheduling it is the next step.

ghettoVCB Configuration Explained: ghettoVCB.conf Settings