# Managed Object - Datastore(vim.Datastore)

Property of
  BaseConfigInfoBackingInfo, BatchResult, ClusterComputeResourceVcsSlots, ClusterDasConfigInfo, ClusterDatastoreUpdateSpec, ClusterSystemVMsConfigInfo, ComputeResource, DasHeartbeatDatastoreInfo, Datacenter, DatastoreEventArgument, DatastoreMountPathDatastorePair, DatastoreSummary, DeltaDiskFormatNotSupported, FaultToleranceDiskSpec, FaultToleranceMetaSpec, FaultToleranceVMConfigSpec, HbrDiskMigrationAction, HostCacheConfigurationInfo, HostCacheConfigurationSpec, HostConfigInfo, HostConfigSummary, HostDatastoreBrowser, HostDatastoreBrowserSearchResults, HostDatastoreSystem, HostDatastoreSystemDatastoreResult, HostEsxAgentHostManagerConfigInfo, HostResignatureRescanResult, HostSystem, InvalidDatastore, IORMNotSupportedHostOnDatastore, LargeRDMNotSupportedOnDatastore, MemorySizeNotSupportedByDatastore, NodeDeploymentSpec, OvfResourceMap, PlacementSpec, QuiesceDatastoreIOForHAFailed, RDMNotSupportedOnDatastore, RetrieveVStorageObjSpec, StorageMigrationAction, StoragePlacementAction, StorageRequirement, StorageVmotionIncompatible, UnsupportedDatastore, VAppCloneSpec, VAppCloneSpecResourceMap, VirtualApp, VirtualDeviceFileBackingInfo, VirtualMachine, VirtualMachineRelocateSpec, VirtualMachineRelocateSpecDiskLocator, VirtualMachineUsageOnDatastore, VslmCreateSpecBackingSpec, vslmInfrastructureObjectPolicySpec
Parameter to
  AttachDisk_Task, ClearVStorageObjectControlFlags, CloneVStorageObject_Task, ConfigureDatastoreIORM_Task, CreateDirectory, CreateDiskFromSnapshot_Task, CreateImportSpec, DeleteSnapshot_Task, DeleteVStorageObject_Task, DeleteVStorageObjectEx_Task, DisableClusteredVmdkSupport, EnableClusteredVmdkSupport, ExpandVmfsDatastore, ExtendDisk_Task, ExtendVmfsDatastore, HostClearVStorageObjectControlFlags, HostCloneVStorageObject_Task, HostDeleteVStorageObject_Task, HostDeleteVStorageObjectEx_Task, HostExtendDisk_Task, HostInflateDisk_Task, HostListVStorageObject, HostReconcileDatastoreInventory_Task, HostRelocateVStorageObject_Task, HostRenameVStorageObject, HostRetrieveVStorageInfrastructureObjectPolicy, HostRetrieveVStorageObject, HostRetrieveVStorageObjectMetadata, HostRetrieveVStorageObjectMetadataValue, HostRetrieveVStorageObjectState, HostScheduleReconcileDatastoreInventory, HostSetVStorageObjectControlFlags, HostUpdateVStorageObjectMetadata_Task, HostUpdateVStorageObjectMetadataEx_Task, HostVStorageObjectCreateDiskFromSnapshot_Task, HostVStorageObjectCreateSnapshot_Task, HostVStorageObjectDeleteSnapshot_Task, HostVStorageObjectRetrieveSnapshotInfo, HostVStorageObjectRevert_Task, InflateDisk_Task, ListVStorageObject, QueryAvailableDisksForVmfs, QueryDatastorePerformanceSummary, QueryMaxQueueDepth, QueryVmfsDatastoreExpandOptions, QueryVmfsDatastoreExtendOptions, ReconcileDatastoreInventory_Task, RelocateVStorageObject_Task, RemoveDatastore, RemoveDatastoreEx_Task, RenameVStorageObject, RetrieveSnapshotDetails, RetrieveSnapshotInfo, RetrieveVStorageInfrastructureObjectPolicy, RetrieveVStorageObject, RetrieveVStorageObjectState, RevertVStorageObject_Task, ScheduleReconcileDatastoreInventory, SetMaxQueueDepth, SetVStorageObjectControlFlags, UpdateLocalSwapDatastore, UpdateVStorageObjectCrypto_Task, UpdateVStorageObjectPolicy_Task, VCenterUpdateVStorageObjectMetadataEx_Task, VStorageObjectCreateSnapshot_Task, VstorageObjectVCenterQueryChangedDiskAreas
Returned by
  CreateLocalDatastore, CreateNasDatastore, CreateVmfsDatastore, CreateVvolDatastore, ExpandVmfsDatastore, ExtendVmfsDatastore, GetSystemVMsRestrictedDatastores
Extends
  ManagedEntity
See also
  DatastoreCapability, DatastoreHostMount, DatastoreInfo, DatastoreMountPathDatastorePair, DatastoreSummary, DatastoreVVolContainerFailoverPair, HostDatastoreBrowser, StorageIORMInfo, StoragePlacementResult, UpdateVirtualMachineFilesResult, VirtualMachine, VVolVmConfigFileUpdateResult
Since
  2.0

## Managed Object Description

Represents a storage location for virtual machine files. A storage location can be a VMFS volume, a directory on Network Attached Storage, or a local file system path.

A datastore is platform-independent and host-independent. Therefore, datastores do not change when the virtual machines they contain are moved between hosts. The scope of a datastore is a datacenter; the datastore is uniquely named within the datacenter.

Any reference to a virtual machine or file accessed by any host within the datacenter must use a datastore path. A datastore path has the form "[<datastore>] <path>", where <datastore> is the datastore name, and <path> is a slash-delimited path from the root of the datastore. An example datastore path is "[storage] path/to/config.vmx".

You may use the following characters in a path, but not in a datastore name: slash (/), backslash (\), and percent (%).

All references to files in the VIM API are implicitly done using datastore paths.

When a client creates a virtual machine, it may specify the name of the datastore, omitting the path; the system, meaning VirtualCenter or the host, automatically assigns filenames and creates directories on the given datastore. For example, specifying My_Datastore as a location for a virtual machine called MyVm results in a datastore location of My_Datastore\MyVm\MyVm.vmx.

Datastores are configured per host. As part of host configuration, a HostSystem can be configured to mount a set of network drives. Multiple hosts may be configured to point to the same storage location. There exists only one Datastore object per Datacenter, for each such shared location. Each Datastore object keeps a reference to the set of hosts that have mounted the datastore. A Datastore object can be removed only if no hosts currently have the datastore mounted.

Thus, managing datastores is done both at the host level and the datacenter level. Each host is configured explicitly with the set of datastores it can access. At the datacenter, a view of the datastores across the datacenter is shown.

Properties

Name | Type | Description
--- | --- | ---
browser | ManagedObjectReference to a HostDatastoreBrowser | DatastoreBrowser used to browse this datastore.
capability | DatastoreCapability | Capabilities of this datastore.
host* | DatastoreHostMount[] | Hosts attached to this datastore.
info | DatastoreInfo | Specific information about the datastore.
iormConfiguration* | StorageIORMInfo | Configuration of storage I/O resource management for the datastore. Currently we only support storage I/O resource management on VMFS volumes of a datastore. This configuration may not be available if the datastore is not accessible from any host, or if the datastore does not have VMFS volume. The configuration can be modified using the method ConfigureDatastoreIORM_Task Since vSphere API 4.1
summary | DatastoreSummary | Global properties of the datastore.
vm* | ManagedObjectReference[] to a VirtualMachine[] | Virtual machines stored on this datastore.
Properties inherited from ManagedEntity
alarmActionsEnabled, configIssue, configStatus, customValue, declaredAlarmState, disabledMethod, effectiveRole, name, overallStatus, parent, permission, recentTask, tag, triggeredAlarmState
Properties inherited from ExtensibleManagedObject
availableField, value

*May not be present

Methods

Methods defined in this Managed Object
DatastoreEnterMaintenanceMode, DatastoreExitMaintenanceMode_Task, DestroyDatastore, IsClusteredVmdkEnabled, RefreshDatastore, RefreshDatastoreStorageInfo, RenameDatastore, UpdateVirtualMachineFiles_Task, UpdateVVolVirtualMachineFiles_Task
Methods inherited from ManagedEntity
Destroy_Task, Reload, Rename_Task
Methods inherited from ExtensibleManagedObject
setCustomValue

# DatastoreEnterMaintenanceMode(enterMaintenanceMode)

Puts the datastore in maintenance mode. While this task is running and when the datastore is in maintenance mode, no virtual machines can be powered on and no provisioning operations can be performed on the datastore. Once the call completes, it is safe to remove datastore without disrupting any virtual machines.

The task completes once there are no virtual machines on the datastore and no provisioning operations in progress on the datastore. The operation does not directly initiate any operations to evacuate or power-down powered-on virtual machines. However, if the datastore is part of a storage pod with VMware Storage DRS enabled, Storage DRS provides migration recommendations to evacuate the virtual machines. If Storage DRS is in fully-automatic mode, these are automatically scheduled. The task is cancellable. This method returns a StoragePlacementResult object, which includes a Task object with which to monitor the operation, and a list of recommendations and faults generated by Storage DRS when it tries to evacuate the virtual machines on the datastore. The recommendations and faults fields are set only if the datastore is a part of a storage pod with Storage DRS enabled.

Required Privileges
  Datastore.Config
Since
  vSphere API 5.0

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the Datastore used to make the method call.

Return Value

Type | Description
--- | ---
StoragePlacementResult |

Faults

Type | Description
--- | ---
InvalidState | Thrown if the datastore is already in maintenance mode.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="DatastoreEnterMaintenanceMode" type="pbm:DatastoreEnterMaintenanceModeRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="DatastoreEnterMaintenanceModeResponse"> <complexType> <sequence> <element name="returnval" type="pbm:StoragePlacementResult"/> </sequence> </complexType> </element>

# DatastoreExitMaintenanceMode_Task(exitMaintenanceMode)

Takes the datastore out of maintenance mode.

The task is cancellable.

Required Privileges
  Datastore.Config
Since
  vSphere API 5.0

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the Datastore used to make the method call.

Return Value

Type | Description
--- | ---
pbm.Task | This method returns a Task object with which to monitor the operation.

Faults

Type | Description
--- | ---
InvalidState | Thrown if the datastore is not in maintenance mode.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

# DestroyDatastore(destroyDatastore)

Deprecated. As of VI API 2.5 do not use this method. This method throws ResourceInUse. Datastores are automatically removed when no longer in use, so this method is unnecessary.

Removes a datastore. A datastore can be removed only if it is not currently used by any host or virtual machine.

Required Privileges
  Datastore.Delete

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the Datastore used to make the method call.

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
ResourceInUse | Thrown if one or more hosts or virtual machines are configured to use the datastore.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="DestroyDatastore" type="pbm:DestroyDatastoreRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="DestroyDatastoreResponse"> <complexType/> </element>

# IsClusteredVmdkEnabled(isClusteredVmdkEnabled)

Check whether clustered VMDK feature is enabled on this datastore.

Required Privileges
  System.Read
Since
  8.0.1.0

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the Datastore used to make the method call.

Return Value

Type | Description
--- | ---
xsd:boolean | true if clustered VMDK feature is enabled. false otherwise.

Faults

Type | Description
--- | ---
InvalidDatastore | Thrown if the given datastore is not valid.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="IsClusteredVmdkEnabled" type="pbm:IsClusteredVmdkEnabledRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="IsClusteredVmdkEnabledResponse"> <complexType> <sequence> <element name="returnval" type="xsd:boolean"/> </sequence> </complexType> </element>

# RefreshDatastore(refresh)

Explicitly refreshes free-space and capacity values in Summary and Info.

Required Privileges
  System.Read

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the Datastore used to make the method call.

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
HostConfigFault | Thrown if unable to get the current system information for the datastore.
NotFound | Thrown if the datastore or its underlying volume is not found.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="RefreshDatastore" type="pbm:RefreshDatastoreRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="RefreshDatastoreResponse"> <complexType/> </element>

# RefreshDatastoreStorageInfo(refreshStorageInfo)

Refreshes all storage related information including free-space, capacity, and detailed usage of virtual machines. Updated values are available in Summary and Info.

Required Privileges
  System.Read
Since
  vSphere API 4.0

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the Datastore used to make the method call.

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="RefreshDatastoreStorageInfo" type="pbm:RefreshDatastoreStorageInfoRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="RefreshDatastoreStorageInfoResponse"> <complexType/> </element>

# RenameDatastore(renameDatastore)

Deprecated. As of vSphere API 4.0, use Rename_Task.

Renames a datastore.

Required Privileges
  Datastore.Rename

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the Datastore used to make the method call.
newName P | xsd:string | The new name to assign to the datastore. Since 2.0

P Required privilege: newName

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
DuplicateName | Thrown if another datastore in this datacenter already has the same name.
InvalidName | Thrown if the name is not a valid datastore name.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="RenameDatastore" type="pbm:RenameDatastoreRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pbm="urn:pbm" name="RenameDatastoreResponse"> <complexType/> </element>

# UpdateVirtualMachineFiles_Task(updateVirtualMachineFiles)

Update file paths embedded in virtual machine files on the datastore. This can be called after the file system corresponding to the datastore has been resignatured or remounted. Any MountPathDatastorePairs where the new path is the same as the original file path will be ignored.

This method is only supported by vCenter server. Also, this method requires that the datastore is accessible from at least one host (ESX version 4.1 or above) in vCenter server.

While this operation is in progress, it is important that users do not initiate any operations that might read or write to any files on the datastore, such as registering a virtual machine with files residing on the datastore, or performing any virtual disk operations on any files in the datastore. These operations can potentially cause spurious file update failures, while at the same time they can prevent virtual machine files from being updated correctly.

If users intend to update multiple datastores using this method, it is strongly advised that the users do not initiate any operations that might read or write to files on any of the datastores, until all of them have been updated. The files of a single virtual machine can reside on multiple datastores, and thus all the involved datastores should be updated, before the virtual machine is considered updated completely.

Required Privileges
  Datastore.UpdateVirtualMachineFiles
Since
  vSphere API 4.1

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the Datastore used to make the method call.
mountPathDatastoreMapping P | DatastoreMountPathDatastorePair[] | Old mount path to datastore mapping. Since vSphere API 4.1

P Required privilege: mountPathDatastoreMapping

Return Value

Type | Description
--- | ---
pbm.Task | This method returns a Task object with which to monitor the operation. The result property in the Task contains an UpdateVirtualMachineFilesResult object, upon success, which is a list of virtual machines files the server has attempted to update but failed to update. When there are too many failed files, only a subset of failed files will be returned.

Faults

Type | Description
--- | ---
InvalidDatastore | Thrown if the operation cannot be performed due to some error with the datastore; typically a specific subclass of the fault is reported.
PlatformConfigFault | Thrown if any error related to platform occurs during the operation.
ResourceInUse | Thrown if there exists a registered virtual machine in the volume.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress | Thrown if the datastore is busy, for example, while another task is updating the datastore after volume resignaturing or remounting.

Events

Type
None

# UpdateVVolVirtualMachineFiles_Task(updateVVolVirtualMachineFiles)

Scan a VVol storage container to update file paths and objectID pointers embedded in virtual machine files on a given storage container.

Required Privileges
  Datastore.UpdateVirtualMachineFiles
Since
  vSphere API 6.5

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the Datastore used to make the method call.
failoverPair* P | DatastoreVVolContainerFailoverPair[] | Mapping of source to target storage container as well as source to target VVol IDs. Since vSphere API 6.5

*Need not be set P Required privilege: failoverPair

Return Value

Type | Description
--- | ---
pbm.Task | This method returns a Task object with which to monitor the operation. The result property in the Task contains a VVolVmConfigFileUpdateResult object, which provides a list of successfully updated virtual machine config files and a list of virtual machine config files that failed to update, for all virtual machine config files failed over onto the VVol storage container from the source containers in the failover pair.

Faults

Type | Description
--- | ---
InvalidDatastore | Thrown if the operation cannot be performed due to some error with the datastore.
NotSupported | Thrown if all hosts attached to this datastore do not support updating VVol Virtual Machine Files.
PlatformConfigFault | Thrown if any error related to platform occurs during the operation.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress | Thrown if the datastore is busy, for example, while another task is updating the datastore.

Events

Type
None