APIs in Category: migrate | API version 3.8

migrate-cancel migrate-change-state migrate-cleanup migrate-complete migrate-fix migrate-start migrate-update | A set of APIs to migrate datasets and vFiler units. Migration APIs can be used to start migration, update migration relationships, complete migration, cancel migration and to cleanup stale storage after migration. In a typical migration sequence, migrate-start would be issued to initiate baseline transfers to the destination. Subsequently, after a few migrate-update calls, the user can select a suitable time and cutover to the new destination using migrate-complete API. Once the migrate-complete job finishes, data is served from the new destination. If in between, there is a need to cancel the migration, it can be done using migrate-cancel API. Once the migration is completed, the stale storage can be cleaned up from the source storage system using migrate-cleanup API.

NetApp Manage ONTAP

migrate-cancel | [top]

> Cancel the migration operation for the specified vFiler unit or dataset. Error conditions: EDATABASEERROR - A database error occurred while processing the request. EACCESSDENIED - User does not have required capabilities to initiate the migrate operation. If object-name-or-id refers to a dataset, user should have DFM.Dataset.Write on the datset. If object-name-or-id refers to a vFiler unit, user should have DFM.Resource.Control on the dataset. EOBJECTAMBIGUOUS - When the specified object name is ambiguous. EOBJECTNOTFOUND - When the specified vFiler unit or dataset is not found. EINVALIDMIGRATIONSTATUS - When the migration status of the specified vFiler unit is such that migrate-cancel operation cannot be initiated.

> Input Name | Range | Type | Description
> dry-run |  | boolean validate optional | Indicates whether a dry run needs to be done of all the tasks to be performed as part of migrate-cancel operation. Default value is false.
> object-name-or-id |  | obj-name-or-id | Full name or identifier of the vFiler unit or dataset whose migration operation has to be cancelled. The migration status of the vFiler unit or the vFiler unit attached to the specified dataset should be either "migrating" or "migrate_failed".
> Output Name | Range | Type | Description
> dry-run-results |  | dry-run-result[] optional | Results of a dry run. Each result describes one action the system would take and the predicted effects of that action. Only returned if dry-run is true.
> job-id |  | integer optional | Identifier of the job started to cancel the migration operation. only returned if dry-run is false.

> Errno | Description
> EDATABASEERROR |  |
> EACCESSDENIED |  |
> EOBJECTAMBIGUOUS |  |
> EOBJECTNOTFOUND |  |
> EINVALIDMIGRATIONSTATUS |  |

migrate-change-state | [top]

> Change the state of a migration operation initiated for a vFiler unit or dataset. Only the following state changes are allowed through this API: Change from "migrated" to "not_started": This is used to retain stale storage on the source hosting storage system and migrating a vFiler unit again. Change from "migrated_with_errors" to "migrated": This is used to change the state after going through the errors that occured after cutover and correcting them as necessary. Error conditions: EDATABASEERROR - A database error occurred while processing the request. EACCESSDENIED - User does not have required capabilities to initiate the migrate operation. If object-name-or-id refers to a dataset, user should have DFM.Dataset.Write on the datset. If object-name-or-id refers to a vFiler unit, user should have DFM.Resource.Control on the dataset. EOBJECTAMBIGUOUS - When the specified object name is ambiguous. EOBJECTNOTFOUND - When the specified vFiler unit or dataset is not found. EINVALIDMIGRATIONSTATUS - When the migration status change is not allowed. EINVALIDINPUT - Invalid input specified.

> Input Name | Range | Type | Description
> new-migration-status |  | migration-status | The new migration status for the vFiler unit or dataset.
> object-name-or-id |  | obj-name-or-id | Full name or identifier of the vFiler unit or dataset whose migration status has to be changed.

> Errno | Description
> EDATABASEERROR |  |
> EACCESSDENIED |  |
> EOBJECTAMBIGUOUS |  |
> EOBJECTNOTFOUND |  |
> EINVALIDINPUT |  |
> EINVALIDMIGRATIONSTATUS |  |

migrate-cleanup | [top]

> Delete the stale storage associated with a migration operation from the source storage system. This will destroy all the volumes of the source vFiler unit after successful migration of the vFiler unit. Error conditions: EDATABASEERROR - A database error occurred while processing the request. EACCESSDENIED - User does not have required capabilities to initiate the migrate operation. If object-name-or-id refers to a dataset, user should have DFM.Dataset.Write on the datset. If object-name-or-id refers to a vFiler unit, user should have DFM.Resource.Control on the dataset. EOBJECTAMBIGUOUS - When the specified object name is ambiguous. EOBJECTNOTFOUND - When the specified vFiler unit or dataset is not found. EINVALIDMIGRATIONSTATUS - When the migration status of the specified vFiler unit is such that migrate-cleanup operation cannot be initiated.

> Input Name | Range | Type | Description
> dry-run |  | boolean optional | A dry-run flag that indicates to show a dry-run result of the volumes that will be destroyed as part of this cleanup operation from the source storage system. Default is false.
> object-name-or-id |  | obj-name-or-id | Full name or identifier of the vFiler unit or the dataset whose stale storage has to be cleaned up. The migration status of the vFiler unit or the vFiler unit attached to the dataset should be "migrated".
> Output Name | Range | Type | Description
> dry-run-results |  | dry-run-result[] optional | Results of a dry run. Each result describes one action the system would take and the predicted effects of that action. Only returned if dry-run is true.
> job-id |  | integer optional | Identifier of the job started to cleanup storage after the migration operation. Returned only when dry-run is false.

> Errno | Description
> EDATABASEERROR |  |
> EACCESSDENIED |  |
> EOBJECTAMBIGUOUS |  |
> EOBJECTNOTFOUND |  |
> EINVALIDMIGRATIONSTATUS |  |

migrate-complete | [top]

> Complete the migration operation by doing a cutover from the source vFiler unit to destination vFiler unit. As part of cutover operation the following will be done: A script if specified, will be run in pre mode. The actual cutover will be carried out so that the source vFiler unit is destroyed and data will be served from the destination vFiler unit. The script if specified, will be run in post mode after successful cutover. For all volumes of the vFiler unit, the protection relationships will be migrated to the new destination. All the backup versions will be modified so that they point appropriately to the newly created destination volumes. The migration status is changed to 'migrated' after a successful completion of migration. If migrate-complete fails to cutover to destination storage, then the migration status is changed to 'migrate-failed'. If the cutover to the destination storage succeeds during completion, but some of the subsequent steps like migrating the protection relationships, or copying the history data fails, then the status is changed to 'migrated-with-errors'. Error conditions: EDATABASEERROR - A database error occurred while processing the request. EACCESSDENIED - User does not have required capabilities to initiate the migrate operation. If object-name-or-id refers to a dataset, user should have DFM.Dataset.Write on the datset. If object-name-or-id refers to a vFiler unit, user should have DFM.Resource.Control on the dataset. EOBJECTAMBIGUOUS - When the specified object name is ambiguous. EOBJECTNOTFOUND - When the specified vFiler unit or dataset is not found. EINVALIDMIGRATIONSTATUS - When the specified vFiler unit is not in "migrating" status.

> Input Name | Range | Type | Description
> dry-run |  | boolean optional | A dry-run flag that indicates to show a dry-run result of the migrate-complete operation. Default is false.
> object-name-or-id |  | obj-name-or-id | Full name or identifier of the vFiler unit or the dataset for which the migration operation has to be completed. For a migrate-complete operation, the source vFiler unit should be given as input. The migration status of the vFiler unit or the vFiler unit attached to the dataset should be "migrating".
> script-path |  | string optional | Path to a script that will be run in pre and post mode just before and after cutover operation.
> Output Name | Range | Type | Description
> dry-run-results |  | dry-run-result[] optional | Results of a dry run. Each result describes one action the system would take and the predicted effects of that action. Only returned if dry-run is true.
> job-id |  | integer optional | Identifier of the job started to carry out the complete operation. Returned only when dry-run flag is false.

> Errno | Description
> EDATABASEERROR |  |
> EACCESSDENIED |  |
> EOBJECTAMBIGUOUS |  |
> EOBJECTNOTFOUND |  |
> EINVALIDMIGRATIONSTATUS |  |

migrate-fix | [top]

> Fix the migration status of a dataset. This API should be called if migration job was aborted abnormally, due to server shutdown or machine reboot etc. It fixes the database entries and migration status of the dataset. It can be called only if the last migration job run on the dataset terminated abnormally. Error conditions: EDATABASEERROR - A database error occurred while processing the request. EACCESSDENIED - User does not have required capabilities to initiate the migrate operation. If object-name-or-id refers to a dataset, user should have DFM.Dataset.Write on the datset. If object-name-or-id refers to a vFiler unit, user should have DFM.Resource.Control on the dataset. EOBJECTAMBIGUOUS - When the specified object name is ambiguous. EOBJECTNOTFOUND - When the specified vFiler unit or dataset is not found. EINVALIDINPUT - Invalid input specified.

> Input Name | Range | Type | Description
> dataset-name-or-id |  | obj-name-or-id | Full name or identifier of the dataset for which migration job was terminated abnormally.

> Errno | Description
> EDATABASEERROR |  |
> EACCESSDENIED |  |
> EOBJECTAMBIGUOUS |  |
> EOBJECTNOTFOUND |  |
> EINVALIDMIGRATIONSTATUS |  |

migrate-start | [top]

> Start the migration operation for a dataset or a vFiler unit. This initiates a baseline transfer for all the volumes in the source vFiler unit and changes the migration status to 'migrating'. When a dataset is given as input then the following conditions should hold good: A vFiler unit should be attached to the primary node of the dataset. All the volumes of the vFiler unit with the exception of the root storage should belong to this dataset. If any of these conditions are not met, then EMIGRATENOTSUPPORTED is returned. Error conditions: EDATABASEERROR - A database error occurred while processing the request. EACCESSDENIED - User does not have required capabilities to initiate the migrate operation. If object-name-or-id refers to a dataset, user should have DFM.Dataset.Write on the datset. If object-name-or-id refers to a vFiler unit, user should have DFM.Resource.Control on the dataset. If resource-name-or-id refers to a resource pool, user should have DFM.ResourcePool.Provision on it. If resource-name-or-id refers to a storage system, user should have DFM.Resource.Control on it. If provisioning-policy-name-or-id is specified, user should have DFM.Policy.Read on it. EOBJECTAMBIGUOUS - When the specified object name is ambiguous. EOBJECTNOTFOUND - When the specified vFiler unit, dataset, destination storage system or provisioning policy is not found. EINVALIDINPUT - When invalid inputs are provided for IP Address, Netmask. EINVALIDMIGRATIONSTATUS - When the specified vFiler unit is already in "migrating" status or in a state where migration cannot be started. EMIGRATENOTSUPPORTED - When the dataset or source vFiler unit cannot be migrated due to various reasons like invalid vFiler status, ONTAP version. EMIGRATEDESTINATIONSELECTIONFAILED - When a suitable storage system is not found as a destination for migration.

> Input Name | Range | Type | Description
> description |  | string optional | A short optional description of the migration activity. Default is an empty description. Range: [0..4096] characters.
> dry-run |  | boolean validate optional | Indicates whether a dry run needs to be done of all the tasks to be performed as part of migrate-start operation. Default value is false.
> ip-bindings |  | ip-binding-info[] optional | IP Address to interface binding information for the destination vFiler unit. If this element is not present, then the interface configured as the "defaultVFilerInterface" for the selected destination storage system is used to bind IP Addresses of the source vFiler unit at the destination.
> object-name-or-id |  | obj-name-or-id | Full name or identifier of the vFiler unit or the dataset which has to be migrated. If the input element is a dataset, then a vFiler unit should be attached to the dataset and all the volumes of the vFiler unit should be members of the primary node of the dataset with the exception of the root storage. The vFiler unit will be migrated to a new storage system.
> provisioning-policy-name-or-id |  | obj-name-or-id optional | Name or identifier of the provisioning policy to be used to provision destination volumes during migration. This input is valid only when object-name-or-id refers to a dataset. Default behavior is to use the current provisioning policy associated with the dataset or if not associated, to use the same volume configuration as that of the source vFiler unit.
> resource-name-or-id |  | obj-name-or-id | Name or identifier of the destination storage system or resource pool to which the vFiler unit is to be migrated. If object-name-or-id refers to a dataset, this storage system should be a member of a resource pool on which the user has required capabilities. If object-name-or-id refers to a vFiler unit, this can refer to any destination storage system on which the user has required capabilities. The storage system should be running ONTAP version same or above the source storage system.
> Output Name | Range | Type | Description
> dry-run-results |  | dry-run-result[] optional | Results of a dry run. Each result describes one action the system would take and the predicted effects of that action. Only returned if dry-run is true.
> job-id |  | integer optional | The identifier of the job started to carry out the migrate-start operation. This field is returned only when dry-run is false.

> Errno | Description
> EDATABASEERROR |  |
> EACCESSDENIED |  |
> EOBJECTNOTFOUND |  |
> EOBJECTAMBIGUOUS |  |
> EINVALIDINPUT |  |
> EINVALIDMIGRATIONSTATUS |  |
> EMIGRATENOTSUPPORTED |  |
> EMIGRATEDESTINATIONSELECTIONFAILED |  |

migrate-update | [top]

> Update all the SnapMirror relationships of a vFiler unit for which migration operation has been initiated. Error conditions: EDATABASEERROR - A database error occurred while processing the request. EACCESSDENIED - User does not have required capabilities to initiate the migrate operation. If object-name-or-id refers to a dataset, user should have DFM.Dataset.Write on the datset. If object-name-or-id refers to a vFiler unit, user should have DFM.Resource.Control on the dataset. EOBJECTAMBIGUOUS - When the specified object name is ambiguous. EOBJECTNOTFOUND - When the specified vFiler unit or dataset is not found. EINVALIDMIGRATIONSTATUS - When the migration status of the vFiler unit is such that migrate-update cannot be called.

> Input Name | Range | Type | Description
> object-name-or-id |  | obj-name-or-id | Full name or identifier of the dataset or vFiler unit whose migration status is "migrating" and whose SnapMirror relationships are to be updated.
> Output Name | Range | Type | Description
> job-id |  | integer | Identifier of the job started to update the SnapMirror relationships for a vFiler unit migration.

> Errno | Description
> EDATABASEERROR |  |
> EACCESSDENIED |  |
> EOBJECTAMBIGUOUS |  |
> EOBJECTNOTFOUND |  |
> EINVALIDMIGRATIONSTATUS |  |

Element definition: dry-run-result | [top]

> A description of one action and the predicted effects of taking that action.

> Name | Range | Type | Description
> dry-run-action |  | string | An action the system would take.
> dry-run-effect |  | string | The predicted effect of the action.
> dry-run-reason |  | string optional | Present only if severity is error or warning. Specifies possible reasons for the error, warning. If there are no reasons to specify, this element will not be present.
> dry-run-reason-details |  | result-detail[] optional | These details apply to the associated dry-run-reason within the same dry-run-result. These offer additional information such as the reasons individual reasources may not have been selected for the dry-run-action in this same dry-run-result.
> dry-run-severity |  | obj-status | severity of the dry-run result. Possible values are "information", "error" or "warning".
> dry-run-suggestion |  | string | Present only if severity is error or warning. Specifies any suggestions to rectify the warnings, errors. If there are no suggestions to specify, this element will not be present.

Element definition: ip-binding-info | [top]

> vFiler IP Address to interface binding information.

> Name | Range | Type | Description
> interface |  | obj-name-or-id | Name or identifier of the interface to bind the vFiler IP Address to. This can be either a physical interface, VIF or a VLAN. Example: "e0a", "myvif", "service_vlan"
> ip-address |  | ip-address | IP address of the vFiler which is bound to the interface. If this IP Address is not already added to the vFiler, then the IP Address is first added to the vFiler before binding the IP Address with the given interface.
> netmask |  | string optional | Netmask for the IP address in dotted decimal notation. For IPv4 address, either netmask or prefix-length can be supplied. For IPv6 address, netmask is ignored.
> partner-interface |  | obj-name-or-id optional | Name or identifier of the interface on the partner node. This element is valid when the storage system on which this vFiler unit is present is in a Active/Active configuration. If a new VLAN is getting created on the local node, then a new corresponding VLAN will also be created on the partner node on this interface.
> prefix-length |  | integer optional | Prefix length for the IP address. This is required if IPv6 address is supplied. For IPv4 address, either netmask or prefix-length can be supplied. Range: [1..127]
> vlan-identifier |  | integer optional | Identifier for creating a new VLAN interface. If this element is present, the interface element should refer to a physical VLAN tagged interface. Range: [1..4094]

Element definition: migration-status | [top]

> Migration status for an ongoing vFiler unit migration. Possible values: "in_progress", "migrating", "migrated", "migrated_with_errors", "migrate_failed".

> [none]

Element definition: obj-name-or-id | [top]

> Name or internal ID of a DFM object. This typedef is an alias for the builtin ZAPI type string. An obj-name-or-id must contain between 1 and 64 characters, and must conform to one of the following formats: It must have the format of an obj-name, or It must be the decimal numeric string form of a positive integer whose value is in the range [1..2^31 - 1]. Elements of type obj-name-or-id are used only as inputs to ZAPIs. The value must match either the name or internal ID of an existing DFM object. The ZAPI must specify the object's DFM object type (e.g. dataset, host, DP policy, etc.). Some ZAPIs allow the object to be one of several different types. If the format of an obj-name-or-id input element does not conform, or the value does not match the name or ID of an existing object, then generally the ZAPI documents that it fails with error code EOBJECTNOTFOUND. A ZAPI may return more specific error codes. In such cases, the ZAPI specification must document its behavior. If a ZAPI can accept a null value (e.g. reference to no object at all) for such an element, then the element is declared optional, and the absence of the input element represents a null value.

> [none]

Element definition: ip-address | [top]

> IP address in string format. The length of this string cannot be more than 40 characters.

> [none]

Element definition: obj-status | [top]

> A status value which can be associated with a DFM object. This typedef is an alias for the builtin ZAPI type string. The severity associated with an event has this type. Possible values are: 'unknown', 'normal', 'information', 'unmanaged' 'warning', 'error', 'critical', 'emergency'. unknown: An object has an unknown status when it transitions from one state to another. Ideally, an object will have this status briefly. For example, when an object has been added, but not yet discovered. normal: An object has normal status when it is working within the thresholds specified in DFM. information: The information events are normal occurrences on an object for which you can define alarms. unmanaged: An object is considered to be unmanaged when the login and password are not set for the appliance or agent. warning: An object has the warning status when an event related to the object occurred that an administrator should know about. The event will not cause service disruption. error: An object has error status when it does not cause any service disruption, but it may affect performance. critical: An object has critical status when it is still performing, but service disruption may occur if corrective action is not taken immediately. emergency: An object is in emergency status when it stops performing unexpectedly and could lose data. In some contexts, it is important that severities are ordered (as above). For example, an alarm might be triggered if an event with a given severity "or worse" occurs. In this example, worse means "after" in the list above.

> [none]

Element definition: result-detail | [top]

> Details on a specific action that adds information intended to explain more about a higher level result. For example, the detail may be used to explain a dry-run result by explaining why resources were not selected.

> Name | Range | Type | Description
> action |  | string | An action or check the system had taken.
> effect |  | string | The result of the action or check.
> reason |  | string optional | Specifies possible reasons for the this result. If there are no reasons to specify, this element will not be present.
> severity |  | obj-status | severity of the result result. Possible values are "information", "error" "warning". It is normal for "information" to be used to explain why a resource was not selected.
> suggestion |  | string | Specifies any suggestions to rectify the information, warnings, errors. If there are no suggestions to specify, this element will not be present.

Element definition: obj-status | [top]

> A status value which can be associated with a DFM object. This typedef is an alias for the builtin ZAPI type string. The severity associated with an event has this type. Possible values are: 'unknown', 'normal', 'information', 'unmanaged' 'warning', 'error', 'critical', 'emergency'. unknown: An object has an unknown status when it transitions from one state to another. Ideally, an object will have this status briefly. For example, when an object has been added, but not yet discovered. normal: An object has normal status when it is working within the thresholds specified in DFM. information: The information events are normal occurrences on an object for which you can define alarms. unmanaged: An object is considered to be unmanaged when the login and password are not set for the appliance or agent. warning: An object has the warning status when an event related to the object occurred that an administrator should know about. The event will not cause service disruption. error: An object has error status when it does not cause any service disruption, but it may affect performance. critical: An object has critical status when it is still performing, but service disruption may occur if corrective action is not taken immediately. emergency: An object is in emergency status when it stops performing unexpectedly and could lose data. In some contexts, it is important that severities are ordered (as above). For example, an alarm might be triggered if an event with a given severity "or worse" occurs. In this example, worse means "after" in the list above.

> [none]