Protected VMs API
Important: This document is being phased out and does not contain up-to-date information. For updated API documentation for Zerto versions 9.5 and later, see ZVM REST API - Swagger.
You can also access Swagger from the ZVM: click the menu button (
) on the top right and select APIs or navigate to https://<ZVM IP>:9669/swagger/index.html in a Windows ZVM or https://<ZVM IP>/management/api/swagger/index.html in ZVM Appliance.
/v1/vms returns information about all virtual machines protected on the site processing the API.
URL
| All VMs | https://zvm_ip:port/v1/vms
|
| Filtered VMs | https://zvm_ip:port/v1/vms?vpgName={VPGNAME}&vmName={VMNAME}&status={STATUS}&substatus={SUBSTATUS}&organizationName={ORGNAME}&priority={PRIORITY}&protectedSiteType={PROTECTEDSITETYPE}&recoverySiteType={RECOVERYSITETYPE}&protectedSiteIdentifier={PROTECTEDSITEIDENTIFIER}&recoverySiteIdentifier={RECOVERYSITEIDENTIFIER}vmIdentifier={vmIdentifier}
|
| Single VM | https://zvm_ip:port/v1/vms/{vmIdentifier}
Note: Running an API for a single virtual machine returns details of the single virtual machine only if it is protected in a single VPG. For information about virtual machines that are protected in several VPGs, use the filter vmIdentifier. |
Where:
| zvm_ip | The IP address of the Zerto Virtual Manager where the API is run. | |
| port | The port to access the Zerto Virtual Manager. The default port is 9669. | |
| vmIdentifier | The identifier of the virtual machine for which information is returned. The identifier comprises the server identifier and the virtual machine moref, with the format, serverid.moref. |
|
| Filters | Filters are optional and any combination of filters is valid. When no filter is specified, all virtual machines are returned. Filters are not case-sensitive. | |
Filter |
Description |
|
| vpgName | The name of the VPG which protects the virtual machine. | |
| vmName | The name of the virtual machine. | |
| status | The status of the VPG. Possible values are: 0 or Initializing– The VPG is being initialized. This includes when a VPG is created, and during the initial sync between sites. 1 or MeetingSLA: The VPG is meeting the SLA specification. 2 or NotMeetingSLA: The VPG is not meeting the SLA specification for both the journal history and RPO SLA settings. 3 or RpoNotMeetingSLA: The VPG is not meeting the SLA specification for the RPO SLA setting. 4 or HistoryNotMeetingSLA: The VPG is not meeting the SLA specification for the journal history. 5 or FailingOver: The VPG is in a Failover operation. 6 or Moving: The VPG is in a Move operation. 7 or Deleting: The VPG is being deleted. 8 or Recovered: The VPG has been recovered. |
|
| substatus | The substatus of the VPG, for example the VPG is in a bitmap sync. For the description of substatuses, refer to the Zerto Virtual Manager Administration Guide. Possible values are: 0 or None 1 or InitialSync 2 or Creating 3 or VolumeInitialSync 4 or Sync 5 or RecoveryPossible 6 or DeltaSync 7 or NeedsConfiguration 8 or Error 9 or EmptyProtectionGroup |
|
| 10 or DisconnectedFromPeerNoRecoveryPoints 11 or FullSync 12 or VolumeDeltaSync 13 or VolumeFullSync 14 or FailingOverCommitting 15 or FailingOverBeforeCommit 16 or FailingOverRollingBack 17 or Promoting 18 or MovingCommitting 19 or MovingBeforeCommit |
||
| 20 or MovingRollingBack 21 or Deleting 22 or PendingRemove 23 or BitmapSync 24 or DisconnectedFromPeer 25 or ReplicationPausedUserInitiated 26 or ReplicationPausedSystemInitiated 27 or RecoveryStoragePolicyError 29 or RollingBack |
||
|
30 or RecoveryStorageError 36 or StoppingFotFailure |
||
| sourceType | Deprecated. See protectedSiteType. | |
| targetType | Deprecated. See recoverySiteType. | |
| sourceSite | Deprecated. See protectedSiteIdentifier. | |
| targetSite | Deprecated. See recoverySiteIdentifier. | |
| protectedSiteType | The protected site environment. Possible values are: 0 or VCVpg: The VPG is protecting virtual machines in a VMware vCenter Server. 1 or VCvApp: Deprecated. See VCDvApp. 2 or VCDvApp: The VPG is protecting a VMware vCloud Director vApp. 3 or PublicCloud– Not applicable. 4 or HyperV: The VPG is protecting virtual machines in Microsoft Hyper-V. |
|
| recoverySiteType | The recovery site environment. Possible values are: 0 or VCVpg: The VPG is recovering virtual machines in a VMware vCenter Server. 1 or VCvApp: Deprecated. See VCDvApp. 2 or VCDvApp: The VPG is recovering a VMware vCloud Director vApp. 3 or PublicCloud: The VPG is recovering virtual machines to a public cloud. 4 or HyperV: The VPG is recovering virtual machines in Microsoft Hyper-V. |
|
| protectedSiteIdentifier | The identifier of the protected site where the VPG virtual machines are protected. | |
| recoverySiteIdentifier | The identifier of the recovery site where the VPG virtual machines are recovered. | |
| organizationName | The ZORG for this VPG. | |
| priority | The priority specified for the VPG. Possible values are: 0 or Low: The VPG has a low priority for transferring data. 1 or Medium: The VPG has a medium priority for transferring data. 2 or High: The VPG has a high priority for transferring data. |
|
HTTP Method
GET
Security
The API is exposed over HTTPS. Client code must use the x-zerto-session HTTP authorization header.
See Also
| • | Starting a session: Session: POST |
| • | Return a list of unprotected virtual machines: Virtualization Sites API: https://zvm_ip:port/v1/virtualizationsites/{siteIdentifier}/vms |
| • | Return a list of unprotected vCD vApps: List Unprotected vCD vApps in a Site: https://zvm_ip:port/v1/virtualizationsites/{siteIdentifier}/vcdvapps |
Format
Json, XML
Request Body Using Json Format
The request body is empty.
Response In Json Format
The following is an example response Json body for https://zvm_ip:port/v1/vms and for https://zvm_ip:port/v1/vms/{vmIdentifier}.
[
{
"ActualRPO": 4,
"EnabledActions": {
"IsFlrEnabled": true
},
"Entities": {
"Protected": 0,
"Recovery": 0,
"Source": 0,
"Target": 0
},
"HardwareVersion": "String content",
"IOPs": 1,
"IsVmExists": true,
"JournalHardLimit": {
"LimitType": 1,
"LimitValue": 153600
},
"JournalUsedStorageMb": 0,
"JournalWarningThreshold": {
"LimitType": 1,
"LimitValue": 115200
},
"LastTest": null,
"Link": {
"href": "String content",
"identifier": "String content",
"rel": null,
"type": "VmApi"
},
"Link_{0}": {
"href": "String content",
"rel": "self",
"type": "VmApi"
},
"OrganizationName": "String content",
"OutgoingBandWidthInMbps": 4.48681640625,
"Priority": 1,
"ProtectedSite": {
"href": "String content",
"identifier": "String content",
"rel": null,
"type": "PeerSiteApi"
},
"ProvisionedStorageInMB": 11938,
"RecoveryHostIdentifier": "String content",
"RecoverySite": {
"href": "String content",
"identifier": "String content",
"rel": null,
"type": "LocalSiteApi"
},
"SourceSite": "String content",
"Status": 1,
"SubStatus": 0,
"TargetSite": "String content",
"ThroughputInMB": 9,
"UsedStorageInMB": 0,
"VmIdentifier": "String content",
"VmName": "String content",
"Volumes": [
{
"VmVolumeIdentifier": "String content"
}
],
"VpgIdentifier": "String content",
"VpgName": "String content"
}
]
XML Response Format
For the XML response format, see VMs API XML Response Format.
Response Values
Response values for https://zvm_ip:port/v1/vms and for https://zvm_ip:port/v1/vms/{vmIdentifier}
| Parameter | Description | |||||||||
| ActualRPO | The time since the last checkpoint was written to the journal in seconds. This should be less than the Target RPO Alert value specified for the VPG. A value of -1 means that the RPO has not been calculated. | |||||||||
| Entities | The source type and target types, vCenter Server of vCloud Director, where the virtual machine is protected and recovered. | |||||||||
| The type of virtual machines being protected. Possible values are (Json/XML): 0/VCVpg: The VPG is protecting virtual machines in a VMware vCenter Server. 1/VCvApp: Deprecated. See VCDvApp. 2/VCDvApp: The VPG is protecting a VMware vCloud Director vApp. 3/AWS: Not applicable. 4/HyperV: The VPG is protecting virtual machines in Microsoft Hyper-V. |
||||||||||
| The type of virtual machines being recovered. Possible values are (Json/XML): 0/VCVpg: The VPG is recovering virtual machines in a VMware vCenter Server. 1/VCvApp: Deprecated. See VCDvApp. 2/VCDvApp: The VPG is recovering a VMware vCloud Director vApp. 3/AWS: The VPG is recovering virtual machines in Amazon Web Services (AWS). 4/HyperV: The VPG is recovering virtual machines in Microsoft Hyper-V. |
||||||||||
|
Source |
Deprecated. See Protected. | |||||||||
|
Target |
Deprecated. See Recovery. | |||||||||
| JournalHardLimit | The maximum size the Journal can grow to. | |||||||||
|
LimitType |
The type of Journal size limit. Possible values are:
|
|||||||||
|
LimitValue |
The limit value according to the limit type. | |||||||||
| JournalUsedStorageMb | The amount of used journal storage for the virtual machine, in Mb. | |||||||||
| JournalWarningThreshold | The journal size that generates a warning that the journal is nearing its hard limit. | |||||||||
|
LimitType |
The type of Journal size limit. Possible values are:
|
|||||||||
|
LimitValue |
The limit value according to the limit type. | |||||||||
| HardwareVersion | The VMware hardware version. | |||||||||
| IOPS | The IO per second between all the applications running on the virtual machine in the VPG and the VRA that sends a copy to the remote site for replication. | |||||||||
| IsVmExists | True: The VM exists. False: The VM does not exist. |
|||||||||
| LastTest | The date the last failover test occurred. The value can be converted to an understandable date using code similar to the following: var date = new Date(jsonDate); or code similar to the Perl code example, jsonDateToString($), in Managing vCD APIs. |
|||||||||
| Link | The link details. | |||||||||
|
href |
The URL used. | |||||||||
|
identifier |
The unique identifier of the virtual machine. | |||||||||
|
rel |
The next path level for the API relative to the current path. | |||||||||
|
type |
The API interface service. | |||||||||
| Link | The link details. | |||||||||
|
href |
The URL used. | |||||||||
|
rel |
The next path level for the API relative to the current path. | |||||||||
|
type |
The API interface service. | |||||||||
| OrganizationName | The name of the organization set up in the Zerto Cloud Manager, the ZORG, that uses a Managed Service Provider for recovery. | |||||||||
| OutgoingBandWidthInMbps | The bandwidth throttling defined for the virtual machines. | |||||||||
| Priority | The priority specified for the VPG. Possible values are (Json/XML): 0/Low: The VPG has a low priority for transferring data. 1/Medium: The VPG has a medium priority for transferring data. 2/High: The VPG has a high priority for transferring data. |
|||||||||
| ProtectedSite | The identifier of the protected site where the VPG virtual machines are protected. | |||||||||
|
href |
The URL used. | |||||||||
| The unique identifier of the virtual machine. | ||||||||||
|
rel |
The next path level for the API relative to the current path. | |||||||||
|
type |
The API interface service. | |||||||||
| ProvisionedStorageInMB | The storage provisioned for the virtual machine in the recovery site. | |||||||||
| RecoveryHostIdentifier | The identifier of the host that handles the replicated data. The identifier comprises the server identifier and the host moref, with the format, serverid.moref. | |||||||||
| RecoverySite | The identifier of the recovery site where the VPG virtual machines are recovered. | |||||||||
|
href |
The URL used. | |||||||||
| The unique identifier of the virtual machine. | ||||||||||
|
rel |
The next path level for the API relative to the current path. | |||||||||
|
type |
The API interface service. | |||||||||
| SourceSite | Deprecated. See ProtectedSite > identifier. | |||||||||
| Status | The status of the VPG that contains the virtual machine. Possible values are (Json/XML): 0/Initializing– The VPG is being initialized. This includes when a VPG is created, and during the initial sync between sites. 1/MeetingSLA: The VPG is meeting the SLA specification. 2/NotMeetingSLA: The VPG is not meeting the SLA specification for both the journal history and RPO SLA settings, for example during a delta sync or when there is an error. 3/RpoNotMeetingSLA: The VPG is not meeting the SLA specification for the RPO SLA setting. 4/HistoryNotMeetingSLA: The VPG is not meeting the SLA specification for the journal history. 5/FailingOver: The VPG is in a Failover operation. 6/Moving: The VPG is in a Move operation. 7/Deleting: The VPG is being deleted. 8/Recovered: The VPG is recovered. |
|||||||||
| SubStatus | The substatus of the VPG that contains the virtual machine, for example the VPG is in a bitmap sync. For the description of substatuses, refer to the Zerto Virtual Manager Administration Guide. Possible values are (Json/XML): 0/None 1/InitialSync 2/Creating 3/VolumeInitialSync 4/Sync 5/RecoveryPossible 6/DeltaSync 7/NeedsConfiguration 8/Error 9/EmptyProtectionGroup |
|||||||||
| 10/DisconnectedFromPeerNoRecoveryPoints
11/FullSync 12/VolumeDeltaSync 13/VolumeFullSync 14/FailingOverCommitting 15/FailingOverBeforeCommit 16/FailingOverRollingBack 17/Promoting 18/MovingCommitting 19/MovingBeforeCommit |
||||||||||
| 20/MovingRollingBack
21/Deleting 22/PendingRemove 23/BitmapSync 24/DisconnectedFromPeer 25/ReplicationPausedUserInitiated 26/ReplicationPausedSystemInitiated 27/RecoveryStoragePolicyError 29/RollingBack |
||||||||||
|
30/RecoveryStorageError
36/StoppingFotFailure
|
||||||||||
| TargetSite | Deprecated. See RecoverySite > identifier. | |||||||||
| ThroughputInMb | The MBs for all the applications running on the virtual machine being protected. | |||||||||
| UsedStorageInMB | The storage used by the virtual machine at the recovery site. | |||||||||
| VmIdentifier | The identifier of the virtual machine for which information is returned. The identifier comprises the server identifier and the virtual machine moref, with the format, serverid.moref. |
|||||||||
| VmName | The virtual machine name. | |||||||||
| Volumes | Information about the volumes of the virtual machine. | |||||||||
|
vmVolumeIdentifier |
The identifier of the volume used by the virtual machine. The volume identifier uses the SCSI standard to describe controllers and units, for example: SCSI:0:0. | |||||||||
| VpgName | The name of the VPG in which the virtual machine is protected. | |||||||||
| EnabledActions | Actions that can be performed on the virtual machine. | |||||||||
|
IsFlrEnabled |
Whether file level restore is enabled. | |||||||||
| VpgIdentifier | The identifier of the VPG. |
PowerShell Scripts
For complete PowerShell Scripts, see Examples.
Instant VM Restore from the Journal
The Instant VM Restore from the Journal API enables you to instantaneously restore a single VM from a checkpoint in the local continuous backup journal, while preserving the journal history. Preserving journal checkpoints allows you to revert to other points in time for the same VM if the selected restore point does not meet requirements. Instantaneous restore allows for a read/write view of the VM to be created to reduce RTO with a background copy of data only upon commit operation.
To following APIs are described in this section:
| 1. | Get Information About a Single Protected VM |
| 2. | Restore a Protected VM |
| 3. | Commit a Restored Journal VM |
| 4. | Roll Back a Restored Journal VM |
| 5. | Get Points In Time for a Protected VM |
| 6. | Get Earliest and Latest Points In Time for a Protected VM |
Note: These APIs are only available for Local Continuous Backup VPGs (Local VPGs).
Get Information About a Single Protected VM
v1/vms/{vmIdentifier} gets information about a single protected VM. VpgId may be required if the VM is protected in more than one VPG.
| METHOD | URL |
|---|---|
| GET |
https://zvm_ip:port/v1/vms/{vmIdentifier} |
Where:
| zvm_ip | The IP address of the Zerto Virtual Manager where the API is run. |
| port | The port to access the Zerto Virtual Manager. The default port is 9989. |
| vmIdentifier | Identifier of the protected VM. |
Restore a Protected VM
v1/vms/{vmIdentifier}/restore starts the Journal VM restore operation. Returns the command task identifier of the operation.
| METHOD | URL |
|---|---|
| GET |
https://zvm_ip:port/v1/vms/{vmIdentifier}/restore |
Where:
| zvm_ip | The IP address of the Zerto Virtual Manager where the API is run. |
| port | The port to access the Zerto Virtual Manager. The default port is 9989. |
| vmIdentifier | Identifier of the protected VM. |
Commit a Restored Journal VM
v1/vms/{vmIdentifier}/RestoreRollBack commits a restored journal VM.
| METHOD | URL |
|---|---|
| GET |
https://zvm_ip:port/v1/vms/{vmIdentifier}/RestoreCommit |
Where:
| zvm_ip | The IP address of the Zerto Virtual Manager where the API is run. |
| port | The port to access the Zerto Virtual Manager. The default port is 9989. |
| vmIdentifier | Identifier of the protected VM. |
Roll Back a Restored Journal VM
v1/vms/{vmIdentifier}/RestoreRollBack rolls back a restored VM.
| METHOD | URL |
|---|---|
| GET |
https://zvm_ip:port/v1/vms/{vmIdentifier}/RestoreRollBack |
Where:
| zvm_ip | The IP address of the Zerto Virtual Manager where the API is run. |
| port | The port to access the Zerto Virtual Manager. The default port is 9989. |
| vmIdentifier | Identifier of the protected VM. |
Get Points In Time for a Protected VM
v1/vms/{vmIdentifier}/pointsInTime gets all the relevant points in time for the VM. VpgId may be required if the VM is protected in more than one VPG.
| METHOD | URL |
|---|---|
| GET |
https://zvm_ip:port/v1/vms/{vmIdentifier}/pointsInTime |
Where:
| zvm_ip | The IP address of the Zerto Virtual Manager where the API is run. |
| port | The port to access the Zerto Virtual Manager. The default port is 9989. |
| vmIdentifier | Identifier of the protected VM. |
Get Earliest and Latest Points In Time for a Protected VM
v1/vms/{vmIdentifier}/pointsInTime/stats gets the earliest and latest points in time for a protected VM.
| METHOD | URL |
|---|---|
| GET |
https://zvm_ip:port/v1/vms/{vmIdentifier}/pointsInTime/stats |
Where:
| zvm_ip | The IP address of the Zerto Virtual Manager where the API is run. |
| port | The port to access the Zerto Virtual Manager. The default port is 9989. |
| vmIdentifier | Identifier of the protected VM. |