Skip to main content
A newer release of this product is available.

Update a SnapMirror relationship

Contributors
PDFs

PATCH /snapmirror/relationships/{uuid}

Updates a SnapMirror relationship. This API is used to initiate SnapMirror operations such as "initialize", "resync", "break", "quiesce", and "resume" by specifying the appropriate value for the "state" field. It is also used to modify the SnapMirror policy associated with the specified relationship.

  • snapmirror modify

  • snapmirror initialize

  • snapmirror resync

  • snapmirror break

  • snapmirror quiesce

  • snapmirror resume

Examples

The following examples show how to perform the SnapMirror "resync", "initialize", "resume", "quiesce", and "break" operations.

Performing a SnapMirror "resync"

 PATCH "/api/snapmirror/relationships/98bb2608-fc60-11e8-aa13-005056a707ff/" '{"state":"snapmirrored"}'

Performing a SnapMirror "initialize"

 PATCH "/api/snapmirror/relationships/98bb2608-fc60-11e8-aa13-005056a707ff/" '{"state":"snapmirrored"}'

Performing a SnapMirror "resume"

 PATCH "/api/snapmirror/relationships/98bb2608-fc60-11e8-aa13-005056a707ff/" '{"state":"snapmirrored"}'

Performing a SnapMirror "quiesce"

 PATCH "/api/snapmirror/relationships/98bb2608-fc60-11e8-aa13-005056a707ff" '{"state":"paused"}'

Performing a SnapMirror "break"

 PATCH "/api/snapmirror/relationships/98bb2608-fc60-11e8-aa13-005056a707ff" '{"state":"broken_off"}'

Updating an associated SnapMirror policy

 PATCH "/api/snapmirror/relationships/9e922e65-1818-11e9-8b22-005056bbee73/" '{"policy": { "name" : "MirrorAndVaultDiscardNetwork"}}'

Learn more

Parameters

Name Type In Required Description

return_timeout

integer

query

False

The number of seconds to allow the call to execute before returning. When doing a POST, PATCH, or DELETE operation on a single record, the default is 0 seconds. This means that if an asynchronous operation is started, the server immediately returns HTTP code 202 (Accepted) along with a link to the job. If a non-zero value is specified for POST, PATCH, or DELETE operations, ONTAP waits that length of time to see if the job completes so it can return something other than 202.

uuid

string

path

True

Relationship UUID

failover

boolean

query

False

If this parameter is set, validation and failover will occur to the Snapmirror relationship destination endpoint. Any other fields specified with this parameter will be ignored.

validate_only

boolean

query

False

Validate the operation and its parameters, without actually performing the operation.

force-failover

boolean

query

False

If this parameter is set, failover will occur to the SVM DR relationship endpoint, overriding the validation errors.

Request Body

Name Type Description

_links

_links

create_destination

snapmirror_destination_creation

Use this object to provision the destination endpoint when establishing a SnapMirror relationship for a FlexVol volume, FlexGroup volume, or SVM. Given a source endpoint, the destination endpoint is provisioned in the SVM specified in the "destination.path" property. The SVM destination endpoint can only be provisioned on the local cluster. To provision the SVM destination endpoint use the optional "source.cluster.name" property to specify the remote cluster name or use the optional "source.cluster.uuid" property to specify the remote cluster UUID. When "create_destination.enabled" option is specified while making a POST for a SnapMirror relationship, the relationship can be automatically initialized by setting the "state" either to "snapmirrored" when the policy is of type "async" or to "in_sync" when the policy is of type "sync". The "destination.path" property must specify the destination endpoint path. For example, for FlexVol volume and FlexGroup volume, the "destination.path" can be specified as , and for SVM data protection, the "destination.path" must be specified as <destination-SVM-name:>. For a FlexVol volume or FlexGroup volume destination endpoint, the properties in this object can be specified either from the source or destination cluster. For an SVM destination endpoint, the properties in this object can be specified from the destination cluster. This object is not supported for non ONTAP endpoints.

  • x-ntap-createOnly: true

destination

snapmirror_endpoint

Endpoint of a SnapMirror relationship. For a GET request, the property "cluster" is populated when the endpoint is on a remote cluster. A POST request to create the destination SVM endpoint or to establish an SVM DR relationship must have the property "cluster" populated with the remote cluster details. A POST request to create the destination FlexVol volume or FlexGroup volume endpoints can optionally specify the "cluster" property. A POST request to establish a SnapMirror relationship when the source SVM and the destination SVM are not peered, must specify the "cluster" property.

exported_snapshot

string

Snapshot copy exported to clients on destination.

healthy

boolean

Is the relationship healthy?

lag_time

string

Time since the exported Snapshot copy was created.

policy

policy

Basic policy information of the relationship.

preserve

boolean

Set to true on resync to preserve Snapshot copies on the destination that are newer than the latest common Snapshot copy. This property is applicable only for relationships with FlexGroup or FlexVol endpoints and when the PATCH state is being changed to "snapmirrored".

quick_resync

boolean

Set to true to reduce resync time by not preserving storage efficiency. This property is applicable only for relationships with FlexVol endpoints and when the PATCH state is being changed to "snapmirrored".

recover_after_break

boolean

Set to true to recover from a failed SnapMirror break operation on a FlexGroup relationship. This restores all destination FlexGroup constituents to the latest Snapshot copy, and any writes to the read-write constituents are lost. This property is applicable only for SnapMirror relationships with FlexGroup endpoints and when the PATCH state is being changed to "broken_off".

restore

boolean

Set to true to create a relationship for restore. To trigger restore-transfer, use transfers POST on the restore relationship.

restore_to_snapshot

string

Specifies the Snapshot copy to restore to on the destination during the break operation. This property is applicable only for SnapMirror relationships with FlexVol endpoints and when the PATCH state is being changed to "broken_off".

source

snapmirror_endpoint

Endpoint of a SnapMirror relationship. For a GET request, the property "cluster" is populated when the endpoint is on a remote cluster. A POST request to create the destination SVM endpoint or to establish an SVM DR relationship must have the property "cluster" populated with the remote cluster details. A POST request to create the destination FlexVol volume or FlexGroup volume endpoints can optionally specify the "cluster" property. A POST request to establish a SnapMirror relationship when the source SVM and the destination SVM are not peered, must specify the "cluster" property.

state

string

State of the relationship. To initialize the relationship, PATCH the state to "snapmirrored" for relationships with a policy of type "async" or "in-sync" for relationships with a policy of type "sync". To break the relationship, PATCH the state to "broken_off". To resync the broken relationship, PATCH the state to "snapmirrored" for relationships with a policy of type "async" or "in_sync" for relationships with a policy of type "sync". To pause the relationship, suspending further transfers, PATCH the state to "paused". To resume transfers for a paused relationship, PATCH the state to "snapmirrored" or "in_sync". The entries "in_sync", "out_of_sync", and "synchronizing" are only applicable to relationships with a policy of type "sync". A PATCH call on the state change only triggers the transition to the specified state. You must poll on the "state", "healthy" and "unhealthy_reason" properties using a GET request to determine if the transition is successful. To automatically initialize the relationship when specifying “create_destination”, set the state to “snapmirrored” for relationships with a policy of type "async" or "in_sync" for relationships with a policy of type "sync".

transfer

transfer

Basic information on the current transfer.

unhealthy_reason

array[snapmirror_error]

Reason the relationship is not healthy. It is a concatenation of up to four levels of error messages.

uuid

string
Example request 
{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "create_destination": {
    "storage_service": {
      "name": "string"
    },
    "tiering": {
      "policy": "string"
    }
  },
  "destination": {
    "cluster": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "cluster1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    },
    "ipspace": "Default",
    "path": "svm1:volume1",
    "svm": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "svm1",
      "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
    }
  },
  "exported_snapshot": "string",
  "lag_time": "PT8H35M42S",
  "policy": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "Asynchronous",
    "type": "string",
    "uuid": "4ea7a442-86d1-11e0-ae1c-123478563412"
  },
  "restore_to_snapshot": "string",
  "source": {
    "cluster": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "cluster1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    },
    "ipspace": "Default",
    "path": "svm1:volume1",
    "svm": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "svm1",
      "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
    }
  },
  "state": "snapmirrored",
  "transfer": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "state": "string",
    "uuid": "4ea7a442-86d1-11e0-ae1c-123478563412"
  },
  "unhealthy_reason": [
    {
      "code": "6621444",
      "message": "Failed to complete update operation on one or more item relationships.",
      "parameters": []
    },
    {
      "code": "6621445",
      "message": "Group Update failed",
      "parameters": []
    }
  ],
  "uuid": "4ea7a442-86d1-11e0-ae1c-123478563412"
}

Response

Status: 202, Accepted
Name Type Description

job

job_link
Example response 
{
  "job": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "uuid": "string"
  }
}

Error

Status: Default

ONTAP Error Response codes

Error code Description

13303825

Could not retrieve information for the SnapMirror policy type

13303817

Unknown value for the SnapMirror state

13303829

Invalid state

13303830

Transient state

13303831

Invalid state for async SnapMirror relationship

13303834

Given input valid only for FlexGroup SnapMirror relationship

13303835

Given flag is valid only when PATCH state is broken_off

13303836

Given flag is valid only when PATCH state is snapmirrored or in_sync

13303818

Invalid state transition requested

13303828

Given state change is not possible for SVM SnapMirror relationship

13303833

Requested state change is not possible

13303832

SnapMirror relationship is already initialized

13303824

Quiescing the SnapMirror relationship has failed

13303826

Required environment variables are not set

13303827

Internal Error

13303823

Quiesce operation timed out

13303821

Invalid SnapMirror policy name/UUID

13303819

Could not retrieve SnapMirror policy information

13303851

Cannot modify attributes of SnapMirror restore relationship

13303816

Could not retrieve state or status values

13303837

Given flags are valid only if SnapMirror state change is requested

6619546

Destination must be a dp volume

13303808

Transition to broken_off state failed

13303809

Transition to paused state failed

13303810

Transition to snapmirrored state failed

13303811

Transition from paused state failed

13303820

SnapMirror policy was successfully updated, state transition failed

13303856

SVM is not configured with any data protocol

13303857

SVM is not configured with any network interface

13303858

Internal error. Failed to check LIF and protocols details for SVM

13303859

Internal error. SVM Failover operation failed. SVM operational state is unavailable.

13303865

Modifying the specified SnapMirror policy is not supported.

13303866

Cannot use the specified policy to modify the policy of the relationship.

13303867

Modifying the policy of an async-mirror or a vault relationship is not supported.

13303884

LIF and protocols details are configured incorrectly for SVM.
Name Type Description

error

error
Example error 
{
  "error": {
    "arguments": [
      {
        "code": "string",
        "message": "string"
      }
    ],
    "code": "4",
    "message": "entry doesn't exist",
    "target": "uuid"
  }
}

Definitions

See Definitions

href

Name Type Description

href

string

_links

Name Type Description

self

href

storage_service

Name Type Description

enabled

boolean

This property indicates whether to create the destination endpoint using storage service.

enforce_performance

boolean

Optional property to enforce storage service performance on the destination endpoint when the destination endpoint is used for read-write operations. This property is applicable to FlexVol volume and FlexGroup volume endpoints.

name

string

Optional property to specify the storage service name for the destination endpoint. This property is considered when the property "create_destination.storage_service.enabled" is set to "true". When the property "create_destination.storage_service.enabled" is set to "true" and the "create_destination.storage_service.name" for the endpoint is not specified, then ONTAP selects the highest storage service available on the cluster to provision the destination endpoint. This property is applicable to FlexVol volume and FlexGroup volume endpoints.

  • enum: ["extreme", "performance", "value"]

tiering

Name Type Description

policy

string

Optional property to specify the destination endpoint's tiering policy when "create_destination.tiering.supported" is set to "true". This property is applicable to FlexVol volume and FlexGroup volume endpoints. This property determines whether the user data blocks of the destination endpoint in a FabricPool will be tiered to the cloud store when they become cold. FabricPool combines flash (performance tier) with a cloud store into a single aggregate. Temperature of the destination endpoint volume blocks increases if they are accessed frequently and decreases when they are not. all ‐ This policy allows tiering of both destination endpoint Snapshot copies and the user transfered data blocks to the cloud store as soon as possible by ignoring the temperature on the volume blocks. This tiering policy is not applicable for synchronous relationships. auto ‐ This policy allows tiering of both destination endpoint Snapshot copies and the active file system user data to the cloud store none ‐ Destination endpoint volume blocks will not be tiered to the cloud store. snapshot_only ‐ This policy allows tiering of only the destination endpoint volume Snapshot copies not associated with the active file system. The default tiering policy is "snapshot_only" for a FlexVol volume and "none" for a FlexGroup volume.

supported

boolean

Optional property to enable provisioning of the destination endpoint volumes on FabricPool aggregates. This property is applicable to FlexVol volume and FlexGroup volume endpoints. Only FabricPool aggregates are used if this property is set to "true" and only non FabricPool aggregates are used if this property is set to "false". Tiering support for a FlexGroup volume can be changed by moving all of the constituents to the required aggregates. Note that in order to tier data, not only do the destination endpoint volumes need to support tiering by using FabricPools, the "create_destination.tiering.policy" must not be "none". A destination endpoint that uses FabricPools but has a tiering "policy" of "none" supports tiering but will not tier any data.

snapmirror_destination_creation

Use this object to provision the destination endpoint when establishing a SnapMirror relationship for a FlexVol volume, FlexGroup volume, or SVM. Given a source endpoint, the destination endpoint is provisioned in the SVM specified in the "destination.path" property. The SVM destination endpoint can only be provisioned on the local cluster. To provision the SVM destination endpoint use the optional "source.cluster.name" property to specify the remote cluster name or use the optional "source.cluster.uuid" property to specify the remote cluster UUID. When "create_destination.enabled" option is specified while making a POST for a SnapMirror relationship, the relationship can be automatically initialized by setting the "state" either to "snapmirrored" when the policy is of type "async" or to "in_sync" when the policy is of type "sync". The "destination.path" property must specify the destination endpoint path. For example, for FlexVol volume and FlexGroup volume, the "destination.path" can be specified as , and for SVM data protection, the "destination.path" must be specified as <destination-svm-name:>. For a FlexVol volume or FlexGroup volume destination endpoint, the properties in this object can be specified either from the source or destination cluster. For an SVM destination endpoint, the properties in this object can be specified from the destination cluster. This object is not supported for non ONTAP endpoints.</destination-svm-name:>

Name Type Description

enabled

boolean

Optional property to create the destination endpoint when establishing a SnapMirror relationship. It is assumed to be "false" if no other property is set and assumed to be "true" if any other property is set.

storage_service

storage_service

tiering

tiering

cluster

Name Type Description

_links

_links

name

string

uuid

string

svm

Name Type Description

_links

_links

name

string

The name of the SVM.

uuid

string

The unique identifier of the SVM.

snapmirror_endpoint

Endpoint of a SnapMirror relationship. For a GET request, the property "cluster" is populated when the endpoint is on a remote cluster. A POST request to create the destination SVM endpoint or to establish an SVM DR relationship must have the property "cluster" populated with the remote cluster details. A POST request to create the destination FlexVol volume or FlexGroup volume endpoints can optionally specify the "cluster" property. A POST request to establish a SnapMirror relationship when the source SVM and the destination SVM are not peered, must specify the "cluster" property.

Name Type Description

cluster

cluster

ipspace

string

Optional property to specify the IPSpace of the SVM.

path

string

ONTAP FlexVol/FlexGroup - svm1:volume1 ONTAP SVM - svm1:

  • example: svm1:volume1

  • readCreate: 1

svm

svm

policy

Basic policy information of the relationship.

Name Type Description

_links

_links

name

string

type

string

uuid

string

transfer

Basic information on the current transfer.

Name Type Description

_links

_links

bytes_transferred

integer

Bytes transferred.

state

string

uuid

string

snapmirror_error

SnapMirror error

Name Type Description

code

integer

Error code

message

string

Error message

parameters

array[string]

Parameters for the error message

snapmirror_relationship

SnapMirror relationship information

Name Type Description

_links

_links

create_destination

snapmirror_destination_creation

Use this object to provision the destination endpoint when establishing a SnapMirror relationship for a FlexVol volume, FlexGroup volume, or SVM. Given a source endpoint, the destination endpoint is provisioned in the SVM specified in the "destination.path" property. The SVM destination endpoint can only be provisioned on the local cluster. To provision the SVM destination endpoint use the optional "source.cluster.name" property to specify the remote cluster name or use the optional "source.cluster.uuid" property to specify the remote cluster UUID. When "create_destination.enabled" option is specified while making a POST for a SnapMirror relationship, the relationship can be automatically initialized by setting the "state" either to "snapmirrored" when the policy is of type "async" or to "in_sync" when the policy is of type "sync". The "destination.path" property must specify the destination endpoint path. For example, for FlexVol volume and FlexGroup volume, the "destination.path" can be specified as , and for SVM data protection, the "destination.path" must be specified as <destination-SVM-name:>. For a FlexVol volume or FlexGroup volume destination endpoint, the properties in this object can be specified either from the source or destination cluster. For an SVM destination endpoint, the properties in this object can be specified from the destination cluster. This object is not supported for non ONTAP endpoints.

  • x-ntap-createOnly: true

destination

snapmirror_endpoint

Endpoint of a SnapMirror relationship. For a GET request, the property "cluster" is populated when the endpoint is on a remote cluster. A POST request to create the destination SVM endpoint or to establish an SVM DR relationship must have the property "cluster" populated with the remote cluster details. A POST request to create the destination FlexVol volume or FlexGroup volume endpoints can optionally specify the "cluster" property. A POST request to establish a SnapMirror relationship when the source SVM and the destination SVM are not peered, must specify the "cluster" property.

exported_snapshot

string

Snapshot copy exported to clients on destination.

healthy

boolean

Is the relationship healthy?

lag_time

string

Time since the exported Snapshot copy was created.

policy

policy

Basic policy information of the relationship.

preserve

boolean

Set to true on resync to preserve Snapshot copies on the destination that are newer than the latest common Snapshot copy. This property is applicable only for relationships with FlexGroup or FlexVol endpoints and when the PATCH state is being changed to "snapmirrored".

quick_resync

boolean

Set to true to reduce resync time by not preserving storage efficiency. This property is applicable only for relationships with FlexVol endpoints and when the PATCH state is being changed to "snapmirrored".

recover_after_break

boolean

Set to true to recover from a failed SnapMirror break operation on a FlexGroup relationship. This restores all destination FlexGroup constituents to the latest Snapshot copy, and any writes to the read-write constituents are lost. This property is applicable only for SnapMirror relationships with FlexGroup endpoints and when the PATCH state is being changed to "broken_off".

restore

boolean

Set to true to create a relationship for restore. To trigger restore-transfer, use transfers POST on the restore relationship.

restore_to_snapshot

string

Specifies the Snapshot copy to restore to on the destination during the break operation. This property is applicable only for SnapMirror relationships with FlexVol endpoints and when the PATCH state is being changed to "broken_off".

source

snapmirror_endpoint

Endpoint of a SnapMirror relationship. For a GET request, the property "cluster" is populated when the endpoint is on a remote cluster. A POST request to create the destination SVM endpoint or to establish an SVM DR relationship must have the property "cluster" populated with the remote cluster details. A POST request to create the destination FlexVol volume or FlexGroup volume endpoints can optionally specify the "cluster" property. A POST request to establish a SnapMirror relationship when the source SVM and the destination SVM are not peered, must specify the "cluster" property.

state

string

State of the relationship. To initialize the relationship, PATCH the state to "snapmirrored" for relationships with a policy of type "async" or "in-sync" for relationships with a policy of type "sync". To break the relationship, PATCH the state to "broken_off". To resync the broken relationship, PATCH the state to "snapmirrored" for relationships with a policy of type "async" or "in_sync" for relationships with a policy of type "sync". To pause the relationship, suspending further transfers, PATCH the state to "paused". To resume transfers for a paused relationship, PATCH the state to "snapmirrored" or "in_sync". The entries "in_sync", "out_of_sync", and "synchronizing" are only applicable to relationships with a policy of type "sync". A PATCH call on the state change only triggers the transition to the specified state. You must poll on the "state", "healthy" and "unhealthy_reason" properties using a GET request to determine if the transition is successful. To automatically initialize the relationship when specifying “create_destination”, set the state to “snapmirrored” for relationships with a policy of type "async" or "in_sync" for relationships with a policy of type "sync".

transfer

transfer

Basic information on the current transfer.

unhealthy_reason

array[snapmirror_error]

Reason the relationship is not healthy. It is a concatenation of up to four levels of error messages.

uuid

string
Name Type Description

_links

_links

uuid

string

The UUID of the asynchronous job that is triggered by a POST, PATCH, or DELETE operation.

error_arguments

Name Type Description

code

string

Argument code

message

string

Message argument

error

Name Type Description

arguments

array[error_arguments]

Message arguments

code

string

Error code

message

string

Error message

target

string

The target parameter that caused the error.