Replication Actions

Using the Flat Action Interface

Requests to manage replication actions can be made directly to an Oracle ZFS Storage Appliance system, without specifying a project or share.

The following table lists the base commands for managing replication actions.

Table 13-16 Base Action Interface

Request	Append to Path /api/storage/v{1\|2}	Description
GET	/replication/actions	List all replication action objects
GET	/replication/actions/ra_id	Get the specified replication action properties
PUT	/replication/actions/ra_id	Modify the specified replication action object
DELETE	/replication/actions/ra_id	Delete the specified replication action object
PUT	/replication/actions/ra_id/sendupdate	Start the selected replication action
PUT	/replication/actions/ra_id/cancelupdate	Stop the selected replication action

The following table lists the commands for managing replication action schedules.

Table 13-17 Accessing Action Schedules

Request	Append to Path /api/storage/v{1\|2}	Description
GET	/replication/actions/ra_id/schedules	List all replication action schedule objects
GET	/replication/actions/ra_id/schedules/ra_schedule	Get the specified replication action schedule properties
POST	/replication/actions/ra_id/schedules	Create a new replication action schedule
PUT	/replication/actions/ra_id/schedules/ra_schedule	Modify the specified replication action schedule object
DELETE	/replication/actions/ra_id/schedules/ra_schedule	Delete the specified replication action schedule object

The following table lists the commands for replication automatic snapshot management.

Note:

Share-level auto-snapshot schedules configured within project-level replication actions cannot be accessed with the following commands. Project-level actions can have multiple auto snapshot schedules in multiple shares, and this interface does not provide a definitive way to identify all the combinations.

Table 13-18 Accessing Replication Automatic Snapshot Configuration

Request	Append to Path /api/storage/v{1\|2}	Description
GET	/replication/actions/ra_id/autosnaps	Retrieve auto-snapshot configurations for the selected replication action
GET	/replication/actions/ra_id/autosnaps/autosnaps_id	Get the specified replication action auto-snapshot object
PUT	/replication/actions/ra_id/autosnaps	Modify the specified replication action auto-snapshot properties
PUT	/replication/actions/ra_id/autosnaps/autosnaps_id	Modify the specified replication action auto-snapshot object
DELETE	/replication/actions/ra_id/autosnaps/autosnaps_id	Delete the specified replication action auto-snapshot object

The following table lists the command for Replication Action Statistics.

Table 13-19 Accessing Replication Action Statistics

Request	Append to Path /api/storage/v{1\|2}	Description
GET	/replication/actions/ra_id/stats	Retrieve read-only replication statistics for the selected replication action

Replication Actions in Project, Filesystem, or LUN Context

Requests to manage replication actions can also be made in the context of a specific project, filesystem, or LUN.

The following table lists the base commands for managing replication actions.

Project-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project

Filesystem-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project/filesystems/filesystem

LUN-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project/luns/lun

Append the following base commands to the desired context URI listed above to manage replication actions.

Table 13-20 Project, Filesystem, or LUN Base Replication Action Interfaces

Request	Append to Project, Filesystem, or LUN URI Listed Above	Description
GET	/replication/actions	List all replication action objects
GET	/replication/actions/ra_id	Get the specified replication action properties
POST	/replication/actions	Create a new replication action
PUT	/replication/actions/ra_id	Modify the specified replication action object
DELETE	/replication/actions/ra_id	Delete the specified replication action object
PUT	/replication/actions/ra_id/sendupdate	Start the selected replication action
PUT	/replication/actions/ra_id/cancelupdate	Stop the selected replication action

The following table lists the base commands for managing replication schedules.

Project-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project

Filesystem-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project/filesystems/filesystem

LUN-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project/luns/lun

Append the following base commands to the desired context URI listed above to manage replication schedules.

Table 13-21 Project, Filesystem, or LUN Replication Action Schedules

Request	Append to Project, Filesystem, or LUN URI Listed Above	Description
GET	/replication/actions/ra_id/schedules	List all replication action schedule objects
GET	/replication/actions/ra_id/schedules/ra_schedule	Get the specified replication action schedule properties
POST	/replication/actions/ra_id/schedules	Create a new replication action schedule
PUT	/replication/actions/ra_id/schedules/ra_schedule	Modify the specified replication action schedule object
DELETE	/replication/actions/ra_id/schedules/ra_schedule	Delete the specified replication action schedule object

The following table lists the base commands for managing replication automatic snapshot configuration.

Project-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project

Filesystem-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project/filesystems/filesystem

LUN-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project/luns/lun

Append the following base commands to the desired context URI listed above to manage replication automatic snapshot configuration.

Note:

Share-level auto-snapshot schedules configured within project-level replication actions cannot be accessed with the following project-based operations. Project-level actions can have multiple auto-snapshot schedules in multiple shares, and this interface does not provide a definitive way to identify all combinations.

Table 13-22 Project, Filesystem, or LUN Replication Automatic Snapshot Configuration

Request	Append to Project, Filesystem, or LUN URI Listed Above	Description
GET	/replication/actions/ra_id/autosnaps	Retrieve auto-snapshot configurations for a project/share's selected replication action
GET	/replication/actions/ra_id/autosnaps/autosnaps_id	Get a project/share's specified replication action auto-snapshot configuration
POST	/replication/actions/ra_id/autosnaps	Create a new project/share's level replication action auto-snapshot object
PUT	/replication/actions/ra_id/autosnaps	Modify a project/share's specified replication action's target auto-snapshot retention policy.
PUT	/replication/actions/ra_id/autosnaps/autosnaps_id	Modify the specified replication action auto-snapshot object
DELETE	/replication/actions/ra_id/autosnaps/autosnaps_id	Delete the specified replication action auto-snapshot object

The following table lists the base command for accessing replication action statistics.

Project-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project

Filesystem-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project/filesystems/filesystem

LUN-based operations URIs begin with:

/api/storage/v{1|2}/pools/pool/projects/project/luns/lun

Append the following base commands to the desired context URI listed above to access replication action statistics.

Table 13-23 Accessing Replication Action Statistics

Request	Append to Project, Filesystem, or LUN URI Listed Above	Description
GET	/replication/actions/ra_id/stats	Retrieve read-only replication statistics for the selected replication action

List Replication Actions

Gets a list of all available replication actions.

Example Request:

GET /api/storage/v2/replication/actions HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Replication-Api: 1.0
Content-Type: application/json
Content-Length: 529

{
    "actions": [{
        "href": ""
        ...
    }, {
        "href": "",
        ...
    }]
}

Get Replication Action

The get replication action status command returns the status of a single replication action given by its ID.

Example Request:

GET /api/storage/v2/replication/actions/1438ed7f-aad3-c631-d869-9e85cd7f15b4 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Replication-Api: 1.0
Content-Type: application/json
Content-Length: 529

{
    "action": {
        "average_throughput": 0.0,
        "bytes_sent": 0.0,
        "collection": "local",
        "compression": true,
        "continuous": false,
        "enabled": true,
        "estimated_size": 0.0,
        "estimated_time_left": 0.0,
        "href": "/api/storage/v2/replication/actions",
        "id": "8373d331-de60-e590-90e8-9ad69fcb4aec",
        "include_clone_origin_as_data": false,
        "include_snaps": true,
        "last_sync": "20130916T21:36:50",
        "last_try": "20130916T21:36:50",
        "max_bandwidth": 0,
        "pool": "p1",
        "project": "proj-01",
        "retain_user_snaps_on_target": false,
        "share": "fs1",
        "state": "sending",
        "target": "38094753-6c90-49ed-aa92-995a296d432a",
        "use_ssl": true
    }
}

Example Request:

The following replication action response shows an example recovery point objective (RPO) and related replica lag warning and alerts.

GET /api/storage/v2/replication/actions HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type:application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Replication-Api: 1.0
Content-Type: application/json
Content-Length: 529

{
    "action": {"id": "12d981c3-b098-c65a-e1e9-a6b8263a0f6a",
        "target_id": "4fd305ac-4af5-c34a-87c3-88203207305b",
        ...
        "replica_lag": "42:25:31",
        "recovery_point_objective": 0,
        "replica_lag_warning_alert": 0,
        "replica_lag_error_alert": 0,
        "replica_lag_over_warning_limit": false,
        "replica_lag_over_error_limit": false,
        "project": "default"
    }
}

Create Replication Action

Creates a new replication action.

Create Properties:

Initial values:
                          target = cleo
                         enabled = true
                      continuous = false
                   include_snaps = true
     retain_user_snaps_on_target = false
                           dedup = true
    include_clone_origin_as_data = false
                   max_bandwidth = unlimited
                      bytes_sent = 0
                  estimated_size = 0
             estimated_time_left = 0
              average_throughput = 0
                         use_ssl = true
                     compression = on

Example Request:

POST /api/storage/v2/replication/actions HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json
Content-Length: 121
Accept: application/json

{
    "pool": "p1",
    "project": "proj-01",
    "share": "fs1",
    "target_pool": "pool1",
    "target": "38094753-6c90-49ed-aa92-995a296d432a"
}

Example Result:

HTTP/1.1 201 Created
Content-Length: 506
Content-Type: application/json
Location: /api/storage/v2/replication/action/8373d331-de60-e590-90e8-9ad69fcb4aec
X-Zfssa-Replication-Api: 1.0

{
    "action": {
        "project": "blue1",
        "target": "38094753-6c90-49ed-aa92-995a296d432a",
        "bytes_sent": 0.0,
        "compression": true,
        "continuous": false,
        "enabled": true,
        "dedup": false,
        "max_bandwidth": 0,
        "collection": "local",
        "estimated_size": 0.0,
        "state": "idle",
        "href": "/api/storage/v2/replication/pools/p1/projects/blah1/shares/fs1/
                  actions/8373d331-de60-e590-90e8-9ad69fcb4aec",
        "average_throughput": 0.0,
        "use_ssl": true,
        "estimated_time_left": 0.0,
        "retain_user_snaps_on_target": false,
        "share": "fs1",
        "id": "8373d331-de60-e590-90e8-9ad69fcb4aec",
        "pool": "p1",
        "include_clone_origin_as_data": false,
        "include_snaps": true
    }
}

Creates a schedule for a replication action.

Example Request:

POST /api/storage/v2/replication/actions/b77bd8cd-17ed-69da-9e4b-aebe3cc63755/schedules HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
Content-Type:application/json
Content-Length: 65

{
    "frequency":"month",
    "day":"5th", 
    "hour":"auto", 
    "minute":"auto"
}

Example Result:

HTTP/1.1 201 Created
Date: Thu, 12 Jan 2017 17:35:48 GMT
Server: TwistedWeb/192.0.2
Content-Length: 0
X-Zfssa-Storage-Api: 1.1
Content-Type: application/json; charset=utf-8
X-Zfssa-Api-Version: 1.0
X-Zfssa-Version: user/generic@2016.12.08,1-0

Modify Replication Action

Modifies an existing replication action.

Example Request:

PUT /api/storage/v2/replication/actions/c141d88d-ffd2-6730-d489-b71905f340cc HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json

{
    "use_ssl": false
}

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Replication-Api: 1.0
Content-Type: application/json
Content-Length: 620

{
    "action": {
        "target_id": "407642ae-91b5-681c-de5e-afcd5cbf2974",
        "compression": true,
        "continuous": false,
        "enabled": true,
        "max_bandwidth": 0,
        "dedup": false,
        "retain_user_snaps_on_target": false,
        "use_ssl": false,
        "id": "c141d88d-ffd2-6730-d489-b71905f340cc",
        "include_clone_origin_as_data": false,
        "include_snaps": true
    }
}

Example Request:

PUT /api/storage/v2/replication/actions/action_id -d '{"recovery_point_objective": 60}HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json

Example Result:

X-Zfssa-Replication-Api: 1.0
Content-Type: application/json
Content-Length: 620

{
    "action": {
        "state_description": "Idle (no update in progress)",
        "recovery_point_objective": 60,
        "replica_lag_over_warning_limit": false,
        "bytes_sent": "0",
        "last_try": "Mon Nov 21 2016 23:25:59 GMT+0000 (UTC)",
        "max_bandwidth": 0,
        "estimated_size": "0",
        "href": "/api/storage/v2/replication/actions/12d981c3-b098-c65a-e1e9-a6b8263a0f6a",
        "estimated_time_left": 0,
        "use_ssl": true,
        "id": "12d981c3-b098-c65a-e1e9-a6b8263a0f6a",
        "stats": {"total_logical_bytes": 40656,
        "last_dd_table_build": 9169029,
        "total_after_dedup": 18476,
        "last_try": "Mon Nov 21 2016 23:25:59 GMT+0000 (UTC)",
        "dd_total_updates": 1,
        "href": "/api/storage/v2/replication/actions/12d981c3-b098-c65a-e1e9-a6b8263a0f6a/stats", 
        "dd_total_duration": 47149245470,
        "last_logical_bytes": 40656,
        "dd_total_table_mem": 2097152,
        "last_result": "success",
        "last_after_dedup": 18476,
        "last_duration": 47149245470,
        {"dd_total_logical_bytes": 40656,
        "total_updates": 1,
        "total_duration": 47149245470,
        "replica_data_timestamp": "Mon Nov 21 2016 23:25:12 GMT+0000 (UTC)",
        "total_to_network": 9623,
        "dd_total_table_build": 9169029,
        "dd_total_phys_bytes": 16800,
        "last_to_network": 9623,
        "total_phys_bytes": 16800,
        "last_phys_bytes": 16800,
        "last_sync": "Mon Nov 21 2016 23:25:59 GMT+0000 (UTC)",
        "last_dd_table_mem": 2097152,
        "dd_total_after_dedup": 18476,
        "dd_total_to_network": 9623},
        "compression": "on",
        "dedup": true,
        "replica_lag_warning_alert": 0,
        "last_result": "success",
        "include_clone_origin_as_data": false,
        "state": "idle",
        "offline": false,
        "export_path": "",
        "export_pending": false,
        "autosnaps": {"autosnaps_retention_policies":
        "synchronized",
        "href": "/api/storage/v2/replication/actions/12d981c3-b098-c65a-e1e9-a6b8263a0f6a/autosnaps"},
        "replica_data_timestamp": "Mon Nov 21 2016 23:25:12 GMT+0000 (UTC)",
        "continuous": false,
        "target_id": "4fd305ac-4af5-c34a-87c3-88203207305b",
        {"average_throughput": "0B/s",
        "next_update": "Sync now",
        "pool": "p1",
        "replica_lag_over_error_limit": false,
        "target": "pool1",
        "replica_lag": "42:28:24",
        "retain_user_snaps_on_target": false,
        ...
    }
}

Monitor Replication Action Progress

The get replication action status command returns the status of a single replication action given by its ID. Examine state and state_description to determine replication progress.

state property values:

sending
idle

state_description property values:

Connecting to replication target
Receiving checkpoint from target
Estimating size of update
Building deduplication tables

This property value is only for deduplicated replication streams.

Example Request:

GET /api/storage/v2/replication/actions/1438ed7f-aad3-c631-d869-9e85cd7f15b4 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Replication-Api: 1.0
Content-Type: application/json
Content-Length: 529

{
    "action": {
       "id": "1438ed7f-aad3-c631-d869-9e85cd7f15b4",
       "target_id": "4fd3483e-b1f5-4bdc-9be3-b3a4becd0c42",
       "target": "cleo",
       "pool": "p0",
       "replication_of": "testproj",
       "enabled": true,
       "continuous": false,
       "include_snaps": true,
       "retain_user_snaps_on_target": false,
       "dedup": true,
       "include_clone_origin_as_data": false,
       "max_bandwidth": -1,
       "bytes_sent": 0,
       "estimated_size": 0,
       "estimated_time_left": 0,
       "average_throughput": 0,
       "use_ssl": true,
       "compression": "on",
       "export_path": "",
       "state": "sending",
       "state_description": "Receiving checkpoint from target",
       "export_pending": false,
       "offline": false,
       "next_update": "Sync now",
       "replica_data_timestamp": "Thu Apr 28 2016 22:38:03 GMT+0000 (UTC)",
       "last_sync": "<unknown>",
       "last_try": "<unknown>",
       "last_result": "<unknown>",
       "replica_lag": "00:00:18",
       "recovery_point_objective": 0,
       "replica_lag_warning_alert": 0,
       "replica_lag_error_alert": 0,
       "replica_lag_over_warning_limit": false,
       "replica_lag_over_error_limit": false,
       "project": "testproj"
    }
}

Cancel Update

Cancels an in-progress replication update.

Example Request:

PUT /api/storage/v2/replication/actions/c141d88d-ffd2-6730-d489-b71905f340cc/cancelupdate HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Replication-Api: 1.0

Send Update

Schedules a replication update to start as soon as possible.

Example Request:

PUT /api/storage/v2/replication/actions/c141d88d-ffd2-6730-d489-b71905f340cc/sendupdate HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=

Example Result:

HTTP/1.1 202 Accepted
X-Zfssa-Replication-Api: 1.0

Delete a Replication Action

Deletes an existing replication action.

Example Request:

DELETE /api/storage/v2/replication/actions/e7e688b1-ff07-474f-d5cd-cac08293506e HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=

Successful delete returns HTTP status 204 (No Content).

Example Result:

HTTP/1.1 204 No-Content
X-Zfssa-Replication-Api: 1.0