1. Oracle ZFS Storage Appliance RESTful API Guide, Release OS8.8.x
  2. RESTful API Storage Service
  3. Replication Targets

Replication Targets

The following table shows the available replication target commands.

Table 13-15 Replication Target Commands

Request Append to Path /api/storage/v{1|2} Description

POST

/replication/targets

Create a new replication target

GET

/replication/targets/target

Get the specified replication target properties

GET

/replication/targets

List all replication target objects

PUT

/replication/targets/target

Modify the specified replication target object

DELETE

/replication/targets/target

Destroy the specified target object

The following table shows the properties of a replication target.

Property Description

label

The target name to display

hostname

The fully qualified domain name or IPv4 address of the target Oracle ZFS Storage Appliance

host_match

Perform or bypass hostname verification; see Verify the Target Certificate

auto_accept_cert

Automatically accept the target's certificate; see Verify the Target Certificate

List Replication Targets

Lists all of the available replication targets on an Oracle ZFS Storage Appliance system.

Example Request:

GET /api/storage/v2/replication/targets HTTP/1.1
Host: zfs-storage.example.com:215
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

{ 
        "targets": [{     
            "address": "ipaddr-1", 
            "label": "zfs-storage-1", 
            "hostname": "ipaddr-2", 
            "asn": "9d7a7543-ca83-68f5-a8fc-f818f65e1cfc", 
            "actions": 0, 
            "target": "target-000", 
            "href": "/api/storage/v2/replication/targets/zfs-storage-1" 
        }, { 
            "address": "ipaddr-3", 
            "label": "zfs-storage-2", 
            "hostname": "ipaddr-4", 
            "asn": "16a4c82c-26c1-4a50-e317-ac53181f2e86", 
            "actions": 0, 
            "target": "target-001", 
            "href": "/api/storage/v2/replication/targets/zfs-storage-2" 
        }] 
}

List a Specified Replication Target

This command lists the details of a single replication target. The target is accessed by its hostname.

Example Request:

GET /api/storage/v2/replication/targets/zfs-storage-1 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

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

{ 
        "target": { 
            "href": "/api/storage/v2/replication/targets/zfs-storage-1", 
            "address": "ipaddr-1", 
            "label": "zfs-storage-1", 
            "hostname": "ipaddr-2", 
            "asn": "9d7a7543-ca83-68f5-a8fc-f818f65e1cfc", 
            "actions": 0 
        } 
}

Create a Replication Target

The targets command creates a new replication target for replication.

If you need to ensure that the replication traffic goes over a particular network interface, set up a static route for the target that specifies that interface as shown in Add Route.

Example Request:

See Verify the Target Certificate for information about the hostname and auto_accept_cert properties. 

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

{
    "label":"zfs-storage-3",
    "hostname":"zfs-storage-3.example.com",
    "root_password":"root-password",
    "auto_accept_cert":true
}

Example Result:

HTTP/1.1 201 Created
Content-Length: 135
Content-Type: application/json
Location: /service/v2/services/replication/targets/target-000
X-Zfssa-Replication-Api: 1.0
{
    "target": {
        "actions": 0,
        "address": "123.45.78.9:216",
        "asn": "fa5bf303-0dcb-e20d-ac92-cd129ccd2c81",
        "auto_accept_cert": true,
        "hostname": "zfs-storage-3.example.com",
        "href": "/service/v2/services/replication/targets/target-000",
        "label": "zfs-storage-3"
    }
}

Verify the Target Certificate

When you create a replication target, certificate verification is performed. Certificate verification consists of the following steps:

  1. Certificate hostname check

  2. Certificate trust check

If either the hostname check or the certificate trust check fails, the target is not created.

Hostname Check

The value of the hostname property can be a fully qualified domain name or an IPv4 address. The recommended value to use is the target's fully qualified domain name.

The hostname check verifies that the hostname specified in the hostname property for the target matches a host specified in the certificate. If you specify an IP address or an unqualified domain name for hostname, and the certificate only has fully qualified domain names, the hostname check fails and the target is not created.

If the target is using an ASN-based certificate, specify the target's fully qualified domain name for the value of the hostname property.

The hostname check is performed by default. If you set the host_match property to false, the hostname check is not performed.

For stronger security, set the value of the hostname property to the target's fully qualified domain name, and make sure the host_match property is set to true.

Certificate Trust Check

The certificate trust check verifies that one of the following certificates has been added to the source's trusted certificate list and is enabled for peer use:

  • The target appliance's certificate

  • The certificate for the certificate authority that issued the target appliance's certificate

If the certificate is not trusted, HTTP status 409 (Conflict) is returned and the target is not created. In the following example, the message line is broken for readability:

{
    "fault": {
        "code": 409,
        "name": "ERR_ILLEGAL_STATE",
        "message": "operation failed due to illegal state (Certificate is not trusted 
                    (encountered while attempting to run command \"commit\"))"
    }
}

The first time you create this target for this source, the target host's certificate is not known to be trusted. Because the RESTful API cannot prompt you to confirm the certificate, set the auto_accept_cert property to true to automatically accept the target's certificate.

After the target is created, its certificate can become untrusted. For example, the source's administrator could remove the certificate from the list of trusted certificates, or the target's administrator could replace the certificate. Modify the target to set the auto_accept_cert property to true to tell the source to accept this certificate as trusted.

The certificate trust check is performed for every peer and replication connection. If the certificate is not trusted, the source rejects the connection.

To check the properties of a certificate such as fingerprint or issuer commonName or SubjectAltName, to upload a certificate, or to delete a certificate, see Managing Certificates.

Modify a Replication Target

This command modifies the properties of a replication target.

Example Request:

PUT /api/replication/v2/targets/target-001 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json
Content-Type: application/json
Content-Length: 78

{ 
    "hostname": "zfs-storage-3.example.com" 
}

Delete a Replication Target

This command deletes an existing replication target.

Example Request:

DELETE /service/v2/services/replication/targets/target-000 HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=

Successful delete returns HTTP status 204 (No Content).