Command line tool

vdtrim is the command line edition of Virtual Disk Trim, for scripts, scheduled tasks and servers without a desktop. It uses the same engine and the same licence as the window, and adds a few things the window leaves out: writing the result in another format, choosing the block size, and zeroing free space.

Run without arguments, vdtrim prints this summary with all options. batch, recover, the JSON report and the exit codes are described in Batch mode and scripting.

Analysing an image

analyse reports what is in an image and what a trim would free. It changes nothing and needs no licence.

File:          D:\VMs\openSUSE Tumbleweed.vmdk
File size:     747.6 MB (783941632 bytes)
Container:     VMDK, 64.0 KB blocks, 512-byte sectors
Virtual size:  24.0 GB (25769803776 bytes)
Blocks:        393216 total, 11913 present, 0 zero, 381303 unallocated
Partitioning:  GPT
  1. GPT: BIOS boot at 1.0 MB, 2.0 MB
     Name:        p.legacy
     Not trimmed: no recognised file system (copied verbatim)
  2. GPT: EFI system at 3.0 MB, 512.0 MB
     Name:        p.UEFI
     File system: FAT16 "EFI", 8.0 KB clusters
     Used:        4.1 MB (0%)
     Free:        507.5 MB (99%)
  3. GPT: Unknown {4F68BCE3-E8CD-4DB1-96E7-FBCAF984B709} at 515.0 MB, 23.4 GB
     Name:        p.lxroot
     File system: btrfs crc32c "ROOT", 4.0 KB clusters
     Used:        659.0 MB (2%)
     Free:        22.8 GB (97%)

Reclaimable at 64.0 KB blocks:   59.3 MB (7% of the file)
Reclaimable at 1.0 MB blocks:   19.0 MB (2%)

The first Reclaimable line is what a trim in the image’s own format and block size would free; the second is the same at 1 MB blocks, which is the figure the window shows as Savings. An image that cannot be trimmed prints Declined: with the reason.

Trimming

The copy form refuses to write over an existing file. The replace form keeps the image’s format and layout, always verifies, and declines when the result would be no smaller. A run interrupted with Ctrl+C removes its unfinished output and leaves the image untouched.

Converting between formats

Because the output format follows the name of the output, a trim can also move a disk from one hypervisor to another in one pass:

For a split VMware disk, name the descriptor file, the small .vmdk without a number, never one of its pieces. A disk written in another format gets a new identity, as it would from the hypervisor’s own converter, and has to be attached to the virtual machine in place of the old one. The guide How to convert a virtual disk compares this with the usual converters.

A trim removes whole blocks that hold nothing, but a block that is partly in use is kept as it is, including whatever deleted files left in its free part. Before handing an image to someone else, add --zero-free to clear the free space of the recognised file systems as well. It is not a secure wipe: unrecognised volumes, gaps between partitions and the unused tail of a file’s last cluster are left as they are.

Licence

Analysing, listing with batch and recover work without a licence; trimming needs one. A key entered in the window serves the command line tool of the same user and the other way round.