Search the VMware Knowledge Base (KB)
View by Article ID

Using the esxcli storage vmfs unmap command to reclaim VMFS deleted blocks on thin-provisioned LUNs (2057513)

  • 69 Ratings

Purpose

This article provides steps to reclaim unused storage blocks on a VMFS datastore for a thin-provisioned device using the esxcli storage vmfs unmap command.
 
vSphere 5.5 introduced a new command in the esxcli namespace that allows deleted blocks to be reclaimed on thin provisioned LUNs that support the VAAI UNMAP primitive.

The command can be run without any maintenance window, and the reclaim mechanism has been enhanced as such:
  • Reclaim size can be specified in blocks instead of a percentage value to make it more intuitive to calculate.
  • Dead space is reclaimed in increments instead of all at once to avoid possible performance issues.
With the introduction of 62 TB VMDKs, UNMAP can now handle much larger dead space areas. However, UNMAP operations are still manual. This means Storage vMotion or Snapshot Consolidation tasks on VMFS do not automatically reclaim space on the array LUN.

Note: The vmkfstools -y command is deprecated in ESXi 5.5. For more information on reclaiming space in vSphere 5.0 and 5.1, see Using vmkfstools to reclaim VMFS deleted blocks on thin-provisioned LUNs (2014849).

Resolution

Note: If you are using VMFS6 in ESXi 6.5, this article is not applicable.

To reclaim unused storage blocks on a VMFS datastore for a thin-provisioned device, run this command:

esxcli storage vmfs unmap --volume-label=volume_label|--volume-uuid=volume_uuid --reclaim-unit=number

The command takes these options:
  • -l|--volume-label=volume_label

    The label of the VMFS volume to UNMAP. This is a mandatory argument. If you specify this argument, do not use -u|--volume-uuid=volume_uuid.

  • -u|--volume-uuid=volume_uuid

    The UUID of the VMFS volume to UNMAP. This is a mandatory argument. If you specify this argument, do not use -l|--volume-label=volume_label.

  • -n|--reclaim-unit=number

    The number of VMFS blocks to UNMAP per iteration. This is an optional argument. If it is not specified, the command uses a default value of 200.
For example, for a VMFS volume named MyDatastore with UUID of 509a9f1f-4ffb6678-f1db-001ec9ab780e, run this command:

esxcli storage vmfs unmap -l MyDatastore

or

esxcli storage vmfs unmap -u 509a9f1f-4ffb6678-f1db-001ec9ab780e

 
Notes:
  • The default value of 200 for the -n number or --reclaim-unit=number argument is appropriate in most environments, but some array vendors may suggest a larger or smaller value depending on how the array handles the SCSI UNMAP command.

  • Similar to the previous vmkfstools -y method, the esxcli storage vmfs unmap command creates temporary hidden files at the top level of the datastore, but with names using the .asyncUnmapFile pattern. By default, the space reservation for the temporary files depends on the block size of the underlying VMFS file system (the default is --reclaim-unit=200):

    • 200 MB for 1 MB block VMFS3 / VMFS5
    • 800 MB for 4 MB block VMFS3
    • 1600 MB for 8 MB block VMFS3

  • Depending on the use case, an administrator can select a different --reclaim-unit value, for example if the reserved size is considered to be too large or if there is a danger that the UNMAP primitive may not be completed in a timely manner when offloaded to an array. VMware recommends that vSphere administrators consult with their storage array providers on the best value or best practices when manually defining a --reclaim-unit value.

  • If the UNMAP operation is interrupted, a temporary file may be left on the root of a VMFS datastore. However, when you run the command against the datastore again, the file is deleted when the command completes successfully. The .asyncUnmapFile will never grow beyond the --reclaim-unit size.

  • The UNMAP operation may finish without doing anything or fail if the volume partition table and/or the block alignment is incorrect, due to upgrading a VMFS3 files system or repartitioning the volume with a 3rd party tool. For more information, see Thin Provisioning Block Space Reclamation (VAAI UNMAP) does not work (2048466).

  • If the UNMAP operation fails and you see an error about locked files or resource busy, see:

Additional Information

To be alerted when this article is updated, click Subscribe to Document in the Actions box.

Tags

esxcli storage vmfs unmap,reclaim space from datastore,need assistance with a claim of storage on vm's,vmkfstools to reclaim vmfs delete blocks

See Also

Update History

04/20/2015 - Added file and datastore lock KB links, corrected 4MB block VMFS3 datastore unmap value

Request a Product Feature

To request a new product feature or to provide feedback on a VMware product, please visit the Request a Product Feature page.

Feedback

  • 69 Ratings

Did this article help you?
This article resolved my issue.
This article did not resolve my issue.
This article helped but additional information was required to resolve my issue.

What can we do to improve this information? (4000 or fewer characters)




Please enter the Captcha code before clicking Submit.
  • 69 Ratings
Actions
KB: