Skip to main content

Retrieve a SnapMirror relationship

Contributors

GET /snapmirror/relationships/{uuid}

Introduced In: 9.6

Retrieves a SnapMirror relationship.

  • snapmirror show

  • snapmirror list-destinations

Expensive properties

  • fabriclink.pull_byte_count

  • fabriclink.push_byte_count

  • fabriclink.pending_work_task_count

  • fabriclink.status

  • source.consistency_group_volumes.name

  • destination.consistency_group_volumes.name

Example

GET "/api/snapmirror/relationships/caf545a2-fc60-11e8-aa13-005056a707ff/"

Parameters

Name Type In Required Description

uuid

string

path

True

SnapMirror relationship UUID

list_destinations_only

boolean

query

False

Set to true to show relationships from the source only.

fields

array[string]

query

False

Specify the fields to return.

Response

Status: 200, Ok
Name Type Description

_links

_links

backoff_level

string

Specifies the SnapMirror backoff level due to Client Ops for FlexVol SnapMirror relationships.

consistency_group_failover

snapmirror_consistency_group_failover

SnapMirror Consistency Group failover information. The SnapMirror Consistency Group failover can be a planned or an unplanned operation. Only active SnapMirror Consistency Group failover operation progress can be monitored using this object. In case of an error during the failover operation, the property "consistency_group_failover.error" holds the reason for the error. ONTAP automatically retries any failed SnapMirror Consistency Group failover operation.

  • Introduced in: 9.8

  • readOnly: 1

create_destination

snapmirror_destination_creation

Use this object to provision the destination endpoint when establishing a SnapMirror relationship for a FlexVol volume, FlexGroup volume, SVM, Consistency Group or ONTAP S3 Bucket. Given a source endpoint, the destination endpoint is provisioned in the SVM specified in the "destination.path" property. While protecting an SVM, 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 , for SVM data protection, the "destination.path" must be specified as <destination-SVM-name:>, and for Consistency Group, the "destination.path" must be specified as <destination-SVM-name:/cg/consistency-group-name> along with the "destination.consistency_group_volumes" property to indicate the list of destination volumes of type "DP" in the Consistency Group. For a FlexVol volume, a FlexGroup volume, Consistency Group or a Bucket destination endpoint, the properties in this object can be specified either from the source or the destination cluster. For an SVM destination endpoint, the properties in this object can be specified from the destination cluster only. This object is not supported for non ONTAP endpoints. While protecting a S3 Bucket, the optional "size" property can be used to create ONTAP S3 Bucket destination endpoint of the specified size.

  • Introduced in: 9.7

  • 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, FlexGroup volume, Consistency Group, ONTAP S3 bucket and NON-ONTAP object-store endpoints can optionally specify the "cluster" property when the source SVM and the destination SVM are peered. A POST request to establish a SnapMirror relationship between the source endpoint and destination endpoint and when the source SVM and the destination SVM are not peered, must specify the "cluster" property for the remote endpoint.

  • Introduced in: 9.6

exported_snapshot

string

Snapshot copy exported to clients on destination.

fabriclink

fabriclink

SnapMirror FabricLink relationship

group_type

string

Specifies the group type of the top level SnapMirror relationship. The volume relationships are shown as none, the SVMDR relationships are shown as svm_dr, the Consistency Group relationships are shown as consistency_group, and the FlexGroup volume relationships are shown as flexgroup.

healthy

boolean

Is the relationship healthy?

identity_preservation

string

Specifies which configuration of the source SVM is replicated to the destination SVM. This property is applicable only for SVM data protection with "async" policy type. This "identity_preservation" overrides the "identity_preservation" set on the SnapMirror relationship's policy.

io_serving_copy

string

Specifies the sites serving I/O for the SnapMirror active sync relationship.

lag_time

string

Time since the exported Snapshot copy was created.

last_transfer_network_compression_ratio

string

Specifies the compression ratio achieved for the data sent over the wire with network compression enabled for the last successful transfer.

last_transfer_type

string

Specifies the operation type of the last transfer that occurred on the relationship. The initialize transfer occurs when the relationship state changes from uninitialized to snapmirrored or in_sync. The update transfer occurs when the snapshots are transferred from the source endpoint to the destination endpoint as part of scheduled or manual update. The resync transfer occurs when the relationship state changes from broken_off to snapmirrored or in_sync. The restore transfer occurs when the snapshot is restored from a destination endpoint to another endpoint.

master_bias_activated_site

string

Specifies the Master Bias Activated Site for the SnapMirror active sync relationship.

policy

policy

Basic policy information of the relationship.

preferred_site

string

Specifies the Primary Site of the SnapMirror active sync 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 FlexVol volume or FlexGroup volume 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 volume endpoints and SVMDR relationships 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 volume relationship. This restores all destination FlexGroup constituent volumes 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 volume 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. SnapMirror relationships with the policy type "async" can be restored. SnapMirror relationships with the policy type "sync" cannot be restored.

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 volume endpoints and when the PATCH state is being changed to "broken_off".

source

snapmirror_source_endpoint

Source 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 establish a SnapMirror relationship between the source endpoint and destination endpoint and when the source SVM and the destination SVM are not peered, must specify the "cluster" property for the remote endpoint.

state

string

State of the relationship. To initialize the relationship, PATCH the state to "snapmirrored" for relationships with a policy of type "async" or to state "in_sync" for relationships with a policy of type "sync". To break the relationship, PATCH the state to "broken_off" for relationships with a policy of type "async" or "sync". SnapMirror relationships with the policy type as "sync" and "sync_type" as "automated_failover" cannot be "broken_off". To resync the relationship, PATCH the state to "snapmirrored" for relationships with a policy of type "async" or to state "in_sync" for relationships with a policy of type "sync". SnapMirror relationships with the policy type as "sync" and "sync_type" as "automated_failover" can be in "broken_off" state due to a failed attempt of SnapMirror failover. To pause the relationship, suspending further transfers, PATCH the state to "paused" for relationships with a policy of type "async" or "sync". SnapMirror relationships with the policy type as "sync" and "sync_type" as "automated_failover" cannot be "paused". To resume transfers for a paused relationship, PATCH the state to "snapmirrored" for relationships with a policy of type "async" or to state "in_sync" for relationships with a policy of type "sync". The entries "in_sync", "out_of_sync", "synchronizing", and "expanding" 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" property, set the state to "snapmirrored" for relationships with a policy of type "async" or to state "in_sync" for relationships with a policy of type "sync".

svmdr_volumes

array[svmdr_volumes]

Specifies the list of constituent FlexVol volumes and FlexGroup volumes for an SVM DR SnapMirror relationship. FlexGroup constituents are not considered.

throttle

integer

Throttle, in KBs per second. This "throttle" overrides the "throttle" set on the SnapMirror relationship's policy. If neither of these are set, defaults to 0, which is interpreted as unlimited.

total_transfer_bytes

integer

Cumulative bytes transferred for the relationship.

total_transfer_duration

string

Indicates the cumulative duration of all transfers since the last aggregate relocation, takeover/giveback, or metrocluster switchover/switchback involving the node that hosts the relationship.

transfer

transfer

Basic information on the current transfer or the last transfer if there is no active transfer at the time of the request.

transfer_schedule

transfer_schedule

Schedule used to update asynchronous relationships. This "transfer_schedule" overrides the "transfer_schedule" set on the SnapMirror relationship's policy. To remove the "transfer_schedule", set its value to null (no-quotes). Only cron schedules are supported for SnapMirror.

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

Unique identifier of the SnapMirror relationship.

Example response
{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "backoff_level": "medium",
  "consistency_group_failover": {
    "error": {
      "arguments": [
        {
          "code": "string",
          "message": "string"
        }
      ],
      "code": "4",
      "message": "entry doesn't exist"
    },
    "state": "string",
    "status": {
      "code": "string",
      "message": "string"
    },
    "type": "string"
  },
  "create_destination": {
    "bucket_retention": {
      "default_period": "P10Y",
      "mode": "governance"
    },
    "snaplock": {
      "retention": {
        "default": "P30Y",
        "maximum": "P30Y",
        "minimum": "P30Y"
      },
      "type": "enterprise"
    },
    "storage_service": {
      "name": "string"
    },
    "tiering": {
      "policy": "string"
    }
  },
  "destination": {
    "cluster": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "cluster1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    },
    "consistency_group_volumes": [
      {
        "name": "volume1",
        "uuid": "028baa66-41bd-11e9-81d5-00a0986138f7"
      }
    ],
    "ipspace": "Default",
    "path": "svm1:volume1",
    "svm": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "svm1",
      "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
    },
    "uuid": "4ea7a442-86d1-11e0-ae1c-123478563412"
  },
  "exported_snapshot": "string",
  "fabriclink": {
    "destination_bucket": "string",
    "destination_role": "string",
    "pending_work_task_count": 0,
    "pull_byte_count": 0,
    "push_byte_count": 0,
    "source_bucket": "string",
    "source_role": "string",
    "status": "string",
    "topology_uuid": "string"
  },
  "group_type": "consistency_group",
  "identity_preservation": "string",
  "io_serving_copy": "C1_sti85-vsim-ucs209a_cluster, C1_sti85-vsim-ucs209c_cluster",
  "lag_time": "PT8H35M42S",
  "last_transfer_network_compression_ratio": 61,
  "last_transfer_type": "initialize",
  "master_bias_activated_site": "C1_sti85-vsim-ucs209a_cluster",
  "policy": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "Asynchronous",
    "transfer_schedule": {
      "name": "hourly"
    },
    "type": "string",
    "uuid": "4ea7a442-86d1-11e0-ae1c-123478563412"
  },
  "preferred_site": "C1_sti85-vsim-ucs209a_cluster",
  "restore_to_snapshot": "string",
  "source": {
    "cluster": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "cluster1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    },
    "consistency_group_volumes": [
      {
        "name": "volume1",
        "uuid": "028baa66-41bd-11e9-81d5-00a0986138f7"
      }
    ],
    "path": "svm1:volume1",
    "svm": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "svm1",
      "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
    },
    "uuid": "4ea7a442-86d1-11e0-ae1c-123478563412"
  },
  "state": "snapmirrored",
  "svmdr_volumes": [
    {
      "name": "volume1"
    }
  ],
  "throttle": 0,
  "total_transfer_bytes": 1098210312,
  "total_transfer_duration": "PT3M21S",
  "transfer": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "end_time": "2020-12-02 21:36:19 -0500",
    "last_updated_time": "2023-09-14 18:39:19 -0400",
    "state": "string",
    "total_duration": "PT28M41S",
    "type": "initialize",
    "uuid": "4ea7a442-86d1-11e0-ae1c-123478563412"
  },
  "transfer_schedule": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "weekly",
    "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
  },
  "unhealthy_reason": [
    {
      "arguments": [],
      "code": "6621444",
      "message": "Failed to complete update operation on one or more item relationships."
    },
    {
      "arguments": [],
      "code": "6621445",
      "message": "Group Update failed"
    }
  ],
  "uuid": "4ea7a442-86d1-11e0-ae1c-123478563412"
}

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

Name Type Description

error

returned_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

Name Type Description

self

href

error_arguments

Name Type Description

code

string

Argument code

message

string

Message argument

error

SnapMirror Consistency Group failover error message.

Name Type Description

arguments

array[error_arguments]

Message arguments

code

string

Error code

message

string

Error message

status

Name Type Description

code

string

Status code

message

string

SnapMirror Consistency Group failover status.

snapmirror_consistency_group_failover

SnapMirror Consistency Group failover information. The SnapMirror Consistency Group failover can be a planned or an unplanned operation. Only active SnapMirror Consistency Group failover operation progress can be monitored using this object. In case of an error during the failover operation, the property "consistency_group_failover.error" holds the reason for the error. ONTAP automatically retries any failed SnapMirror Consistency Group failover operation.

Name Type Description

error

error

SnapMirror Consistency Group failover error message.

state

string

SnapMirror Consistency Group failover state.

status

status

type

string