Administration Guides
Eyeglass API guide
Home


Overview

Customers  requiring  end to end integrated failover of compute layer and dependant storage used by customer or external 3rd party applications like VMware SRM, can use Superna Eyeglass REST API to programmatically interact with Superna Eyeglass.


What's New with Eyeglass API

  1. In 2.5.6 or later the following api updates have been added:
    1. LiveOps DR Test mode enable and disable REST API has been added
    2. IP pool failover has been added
    3. All DR Assistant options in the GUI have been added to the API
    4. Eyeglass appliance health check API has been added
    5. DR Dashboard Access Zone, IP Pool, DFS mode and SyncIQ mode readiness information is now available in the API.  Use the foreadiness = true flag on policy, pool and zone API calls to return full DR validations for each failover target.
    6. Retrieve the failover log using the rest API see API here.
    7. 2.5.6 patch 1
      1. Issues addressed,  target cluster environment variable in script editor for DFS mode scripts now populates with correct values.
      2. REST API will accept a comma separated list of failover target ID's, allowing policy and DFS failovers to group multiple targets into a single failover job, which would be used for bulk fast failover of multiple targets.

API Documentation

This information can be browsed with API Explorer using the url https://<x.x.x.x of eyeglass>/sera/docs/

Architecture

The API is REST based and Eyeglass provides an API explorer to explore the policies, nodes, jobs, needed to build failover scripts.

The API explorer has a CURL builder feature.  This feature allows users to browse the API select policies, or Access Zones and clusters, for  failover automation, and have the CURL command built dynamically for simple cut and paste into a script file to execute failover.

The API uses token generation to identify and authenticate an application using the the failover API.  This information is logged to trace failover requests back to an authorized script or user in the failover logs.

Use Cases

  1. Polling for alarms in Eyeglass using alarm REST interface (new in 2.0 or later).  See Get alarms and alarm history interfaces.
  2. This can be used with CURL or REST to return active alarms Eyeglass only, not PowerScale alarms.
  3. Build dashboards that monitor the readiness  of policies, Access Zones or entire clusters. The API can be used in any development language that supports REST to build monitoring dashboards for end to end applications..
  4. Request failover and monitor the success of the failover.
  5. Build custom failover of one or more policy.
  6. Integrate with post failover scripting solution that executes Eyeglass script engine post failover, and call this logic with the same API for failover.  This enables application specific scripting to be initiated from the API, and all execution runs on the Eyeglass appliance.

How to video Overview of Eyeglass API


How to Configure API Tokens

Tokens are used for authentication of REST commands.  The name parameter is used to identify the application using the token. Example: VMware SRM could have a token called “SRM”.   Revoking a token also disables an application's access to Eyeglass.

Reference this Screenshot


Creating Tokens

  1. Open the Superna Eyeglass REST API icon on the main menu (Requires Enterprise license keys)
  2. Click on Create New Token button and enter a name to reference the token

Deleting Tokens

  1. Open the Superna Eyeglass REST API icon on the main menu (Requires Enterprise license keys)
  2. Click the Revoke Red X to remove the token and block access to Eyeglass

Launch API Explorer

  1. Click API Explorer tab and launch
  2. The interface requires an API key to live view configuration API information to build CURL API


Watch this how to video to build a CURL command builder  to failover Video

Token Authentication

Use the token that was created with CURL or development languages to authentication the application to Eyeglass.  The API Explorer can be used to build curl command and shows syntax or how to contract an API call.

API Token Authentication in header

Include an http header named api_key with an authorized API token to authenticate to the Superna Eyeglass REST API.

Usage

The following curl command with the API token named igls-abc123 demonstrates authentication to the Superna Eyeglass REST API.

  • curl --header "api_key: igls-abc123" --header "accept: application/json" https://eyeglass.example/sera/v1/jobs


Full API routes available

    node : Retrieve information about managed devices, access zones, and SyncIQ policies.

    POST jobs to Create Failovers

    NOTE: 2.5.6 patch 1 build will allow multi select of SyncIQ policy or DFS mode policies with a comma separated list in the source target field.  See example below:



    Implementation Notes

    Launch a new job in Eyeglass.

    Response Class (Status 201)

    create job response

    {   "id": "string" }



       application/json 

    Parameters

    ParameterValueDescriptionParameter TypeData Type

    ID of the source node for this job

    querystring

    ID of the target node for this job

    querystring

    ID of the access zone OR syncIQ policy to fail over.

    querystring

    Pool name in case of pool failover. The name format is groupName:subnetName:poolName

    querystring
                      true  (default)            false       

    Execute a controlled failover by running operations against the source cluster as well as the target

    queryboolean
                      true  (default)            false       

    Run the final incremental data sync before failover

    queryboolean
                      true            false  (default)       

    Run a configuration sync before failover

    queryboolean
                      true  (default)            false       

    Run resync prep on the source cluster to create the mirror policies

    queryboolean
                      true            false  (default)       

    Disable mirror policies created on the failover target

    queryboolean
                      true  (default)            false       

    Run quota jobs to failover quotas to target

    queryboolean
               true  (default)            false       

    Block failover on warnings

    queryboolean
                      true  (default)            false       

    Rollback renamed shares on failure

    queryboolean
                      true            false  (default)       

    SMB data integrity failover

    queryboolean

    Response Messages

    HTTP Status CodeReasonResponse ModelHeaders
    default

    error payload

    {   "code": 0,   "message": "string"

    Create DR LiveOPS Failover Jobs

    Implementation Notes

    Enter/Exit DR test mode for a given policy

    Response Class (Status 201)

    create job response

    {   "id": "string" }



       application/json 

    Parameters

    ParameterValueDescriptionParameter TypeData Type
               true  (default)            false       

    True = Make target writable (Enter DR test mode). False = Make target read-only (Exit DR test mode)

    queryboolean
                      true            false  (default)       

    Run a configuration while DR test job

    queryboolean
                      true  (default)            false       

    Run policy while DR test job

    queryboolean

    DR testing policy id (as retrieved with /nodes/{id}/policies GET)

    querystring

    Response Messages

    HTTP Status CodeReasonResponse ModelHeaders
    default

    error payload

    {   "code": 0,   "message": "string" }

    Create DR Rehearsal Failover Jobs

    Implementation Notes

    Launch a new rehearsal job in Eyeglass.

    Response Class (Status 201)

    create rehearsal job response

    {   "id": "string" }



       application/json 

    Parameters

    ParameterValueDescriptionParameter TypeData Type
               true  (default)            false       

    Enable or disable (=false) the rehearsal mode

    queryboolean

    ID of the source node for this job

    querystring

    ID of the target node for this job

    querystring

    ID of the access zone OR DFS syncIQ policy to fail over.

    querystring

    Pool name in case of pool failover. The name format is groupName:subnetName:poolName

    querystring

    Response Messages

    HTTP Status CodeReasonResponse ModelHeaders
    default

    error payload

    {   "code": 0,   "message": "string" }



    Methods

    GET /healthcheck

    Implementation Notes
    Returns latest health-check timestamp from Superna Eyeglass.

    https://igls/sera/v1/healthcheck

    GET /Alarms

    Use this example and replace API token to retrieve a list of active alarms.

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Returns

    • application/json

     Query parameters for both routes;


    since - epoch time of the earliest alarm to return.

    until - epoch time of the latest alarm to return.

    limit - the maximum number of alarms to fetch.

    for example, we might query:


    /sera/v1/alarms/historical?since=1499189000&until=1499190943&limit=50

    CURL Example

    curl  -X GET --header 'accept:application/json --header 'api_key: igls-11llkok678afe9jo314931r1rdi40ib58r43bih3bsukmbuf0ugj' 'https://x.x.x.x/sera/v1/alarms/active?limit=20' -k


    GET /Alarmhistory


    Use this example and replace API token to retrieve a list of active historical alarms

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Query parameters for both routes;


    since - epoch time of the earliest alarm to return.

    until - epoch time of the latest alarm to return.

    limit - the maximum number of alarms to fetch.

    for example, we might query:

    CURL Example

    curl  -X GET --header 'accept:application/json --header 'api_key: igls-11llkok678afe9jo314931r1rdi40ib58r43bih3bsukmbuf0ugj' 'https://x.x.x.x/sera/v1/alarms/historical?limit=20' -k

    GET /jobs

    Get jobs (jobsGet)

    Returns jobs from Superna Eyeglass.

    Consumes

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Query parameters

    state (optional)

    Query Parameter — filter running or complete jobs [all, running, finished]

    success (optional)

    Query Parameter — filter jobs by result success [true, false]

    Return type

    array[Job]

    Produces

    This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

    • application/json

    Responses

    200

    jobs response

    0

    error payload


    POST /jobs

    Create a new job (jobsPost)

    Launch a new job in Eyeglass.

    Consumes

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Query parameters

    sourceid (required)

    Query Parameter — ID of the source node for this job

    targetid (required)

    Query Parameter — ID of the target node for this job

    failovertarget (required)

    Query Parameter — ID of the access zone OR syncIQ policy to fail over.

    Return type

    inline_response_201

    Produces

    This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

    • application/json

    Responses

    201

    create job response

    0

    error payload


    GET /jobs/{id}

    Retrieve a job by ID (jobsIdGet)

    Retrieve a job by id

    Path parameters

    id (required)

    Path Parameter — ID of the job to retrieve

    Consumes

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Return type

    Job

    Produces

    This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

    • application/json

    Responses

    200

    jobs response

    0

    error payload


    DELETE /jobs/{id}

    cancels a running job (jobsIdDelete)

    Cancels a running job

    Path parameters

    id (required)

    Path Parameter — ID of the running job to cancel

    Consumes

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Return type

    Job

    Produces

    This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

    • application/json

    Responses

    200

    jobs response

    0

    error payload


    GET /nodes

    Get all nodes (nodesGet)

    Returns all Superna Eyeglass Managed Devices.

    Consumes

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Return type

    array[Node]

    Produces

    This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

    • application/json

    Responses

    200

    nodes response

    0

    error payload

    GET /nodes/{id}

    Find nodes by ID (nodesIdGet)

    Returns the Superna Eyeglass Managed Devices based on ID

    Path parameters

    id (required)

    Path Parameter — ID of the node to retrieve

    Consumes

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Return type

    Node

    Produces

    This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

    • application/json

    Responses

    200

    nodes response

    0

    error payload


    How to retrieve health check data and all validations for Access Zones, pools, DFS policies and Synciq policies

    Use the get pool, zone and policies node functions with the foreadiness flag set to true to return all validations provided by Eyeglass to detect failover readiness status.


    See below API's and flag for readiness data 

    GET /nodes/{id}/policies

    Find policies for a node (nodesIdPoliciesGet)

    Returns the syncIQ policies for this node


    forediness = true will return failover readiness validations to check the health of specific policy.

    Parameters

    ParameterValueDescriptionParameter TypeData Type

    ID of the node to retrieve

    pathstring

    Retrieve also failover readiness status details

    queryboolean

    Response Messages

    HTTP Status CodeReasonResponse ModelHeaders
    default

    error payload

    {   "code": 0,   "message": "string" }


    Path parameters

    id (required)

    Path Parameter — ID of the node to retrieve

    Consumes

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Return type

    array[Policy]

    Produces

    This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

    • application/json

    Responses

    200

    policies response

    0

    error payload

    GET /nodes/{id}/pools

    Find pool for a node (nodesIdpoolsGet)

    Returns the pools for this node

    foreadiness = true will return failover readiness validations to check the health of specific pool.

    parameters

    ParameterValueDescriptionParameter TypeData Type

    ID of the node to retrieve

    pathstring

    Retrieve also failover readiness status details

    queryboolean

    Response Messages

    HTTP Status CodeReasonResponse ModelHeaders
    default

    error payload

    {   "code": 0,   "message": "string" }

    GET /nodes/{id}/pools/{name}

    Implementation Notes
    Returns the pool by its name on a given node


    GET /nodes/{id}/zones

    Find zones for a node (nodesIdZonesGet)

    Returns the access zones for this node

    forediness = true will return failover readiness validations to check the health of specific zone.


    Parameters

    ParameterValueDescriptionParameter TypeData Type

    ID of the node to retrieve

    pathstring

    Retrieve also failover readiness status details

    queryboolean

    Response Messages

    HTTP Status CodeReasonResponse ModelHeaders
    default

    error payload

    {   "code": 0,   "message": "string" }

    Path parameters

    id (required)

    Path Parameter — ID of the node to retrieve



    Consumes

    This API call consumes the following media types via the Content-Type request header:

    • application/json

    Return type

    array[Zone]

    Produces

    This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

    • application/json

    Responses

    200

    zones response

    0

    error payload

    ErrorModel

    code

    Integer

    message

    String

    Job

    failoverTarget

    Job_failoverTarget

    finished

    Long The end time of the job

    id

    String

    jobType

    String The type of the job

    Enum:

    zone_failover

    policy_failover

    name

    String Human readable name for this job

    sourceNode

    Node The source node for this job.

    started

    Long The start time of the job

    success

    Boolean True if there were no errors

    targetNode

    Node The target node for this job

    Node

    id

    String

    ip

    String primary IP address of the node

    name

    String Unique name of the node

    Policy

    failoverReadiness

    String Enumeration describing the failover readiness of the policy.

    Enum:

    ok

    warning

    error

    id

    String

    name

    String SyncIQ Policy Name

    target

    Node Node that is the target for this syncIQ policy

    zone

    Zone Access zone for this policy

    Zone

    failoverReadiness String Enumeration describing the failover readiness of the zone.

    Enum:

    ok

    warning

    error

    id

    String

    name

    String Access Zone Name

    Inline_response

    id

    String

    Job_failoverTarget

    zone

    Zone The access zone being failed over.

    policies

    array[Policy] The policies being failed over

    Examples

    Example 1: CMDB Integration API

    CMDB Integration with ServiceNow or other CMDB systems that can use “http get” and “XML input files”.

    CMDB integration requires key data about the cluster and configuration to be maintained in the CMDB to map services, service status or service resources.  This is done for asset management, fault monitoring or common service availability with links between IT components that build a service.  For example home directories requires PowerScale storage and Active directory.

    The Eyeglass solution solves asset management and service status integration for shares and exports.

    Supports CI objects (cluster, nodes, shares, exports, quotas)

    1. CI attributes
    2. cluster health, name, version,  type, revision
    3. node disk usage
    4. share name, path, access zone, DR status (Active, DR, unprotected)
    5. export path, access zone, DR status (Active, DR, unprotected)
    6. quota path, type, usage, (hard, soft, advisory) limits


    To access the file type https://x.x.x.x/servicenow/servicenow.xml  to see the file.

    This file is updated every 5 minutes with the latest information from all managed clusters.  The XML file contains all of the information outlined above with any newly detected configuration added to the file.


    SyncIQ protection of shares and exports in the XML output Description

    The service component of shares and exports works as follows with data protection status indicated in the object

    1. Assumption is anything with a share or export needs to be audited for SyncIQ data protection
    2. Eyeglass discovers all shares and exports and sets attribute of the share in XML to a state.
    1. unprotected - no SyncIQ policy
    2. Active (means writable copy of the data as of now)
    3. backup (means DR copy not writable)

    Quota output in the XML file Description

    Quotas are also output to the XML file with type, path and usage in bytes.  The usage is updated every 5 minutes to the file to keep the CMDB updated with quota usage information.

    Asset Management output in the XML file Description

    The cluster node count serial number output can be used for asset management updates.  This information is dynamically updated, if cluster nodes are added the file will include the new nodes.  If the software is updated on the cluster, the new version of the software will be included in this file.

    This information can be used to maintain CMDB asset records for PowerScale clusters that is current and up to date.

    How to Integrate with a CMDB

    The file path is tested with ServiceNow that has the http get/XML file feature. This is available in most CMDB products and integration and transformation maps are outside the scope of support of Eyeglass.  Professional Services can be purchased for assistance to integrate with a CMDB.  Integration typically requires getting the input file on a schedule and mapping the XML fields to a CI object.

    This screenshot shows how integration can be done with ServiceNow.

    Screen Shot 2017-01-27 at 1.28.36 PM.png

    Sample CMDB XML file for 4 clusters

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

    <elements>

        <element>

            <cluster>

                <name>Cluster-1-7201</name>

                <guid>005056ba34580f410c55fd077989478a3821</guid>

                <local_serial>V5052427352</local_serial>

                <onefs_version>

                    <build>B_7_2_1_014(RELEASE)</build>

                    <release>v7.2.1.0</release>

                    <type>PowerScale OneFS</type>

                    <version>PowerScale OneFS v7.2.1.0 B_7_2_1_014(RELEASE): 0x70201500000000E:Mon Jun 22 20:05:42 GMT 2015    root@sea-build7-03:/b/mnt/obj/b/mnt/src/sys/IQ.amd64.release   clang version 3.3 (tags/RELEASE_33/final)</version>

                    <revision>504967551327928334</revision>

                </onefs_version>

            </cluster>

            <nodes>

                <node>

                    <health>OK</health>

                    <serial_number>V5052427352</serial_number>

                    <HDD_size>35GB</HDD_size>

                    <HDD_used>13GB</HDD_used>

                    <HDD_avail>23GB</HDD_avail>

                    <VHS>n/a</VHS>

                </node>

            </nodes>

            <shares>

                <share>

                    <name>SMB2</name>

                    <path>/ifs/data/policy1</path>

                    <zone>System</zone>

                    <status>ACTIVE</status>

                </share>

                <share>

                    <name>spacetest</name>

                    <path>/ifs/data/policy1/space</path>

                    <zone>System</zone>

                    <status>ACTIVE</status>

                </share>

                <share>

                    <name>igls-dfs-dfs1</name>

                    <path>/ifs/data/userdata/dfs1</path>

                    <zone>data</zone>

                    <status>BACKUP</status>

                </share>

                <share>

                    <name>igls-dfs-roam</name>

                    <path>/ifs/data/userdata/dfs1/roam</path>

                    <zone>data</zone>

                    <status>BACKUP</status>

                </share>

                <share>

                    <name>share1</name>

                    <path>/ifs/data/userdata/share1</path>

                    <zone>data</zone>

                    <status>ACTIVE</status>

                </share>

            </shares>

            <exports>

                <export>

                    <paths>/ifs</paths>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </export>

                <export>

                    <paths>/ifs/data/robot</paths>

                    <zone>EyeglassRunbookRobot-AccessZone</zone>

                    <status>ACTIVE</status>

                </export>

                <export>

                    <paths>/ifs/data/userdata/export1/andrew</paths>

                    <zone>data</zone>

                    <status>ACTIVE</status>

                </export>

                <export>

                    <paths>/ifs/data/userdata/export1</paths>

                    <zone>data</zone>

                    <status>ACTIVE</status>

                </export>

            </exports>

            <aliases/>

            <quotas>

                <quota>

                    <path>/ifs/data/userdata</path>

                    <type>directory</type>

                    <used>5299221577</used>

                    <hardLimit>17008070491</hardLimit>

                </quota>

                <quota>

                    <path>/ifs/data/userdata/export1/andrew</path>

                    <type>directory</type>

                    <used>12</used>

                </quota>

                <quota>

                    <path>/ifs/data/policy1</path>

                    <type>directory</type>

                    <used>1972155571</used>

                    <hardLimit>21474836480</hardLimit>

                </quota>

                <quota>

                    <path>/ifs/data/policy1/space</path>

                    <type>directory</type>

                    <used>851444622</used>

                </quota>

                <quota>

                    <path>/ifs/data/userdata/export1</path>

                    <type>directory</type>

                    <used>124216376</used>

                    <advisoryLimit>1048576000</advisoryLimit>

                </quota>

                <quota>

                    <path>/ifs/data/userdata/share1</path>

                    <type>directory</type>

                    <used>218</used>

                </quota>

                <quota>

                    <path>/ifs/data/policy1/departmentB</path>

                    <type>directory</type>

                    <used>12</used>

                    <hardLimit>26843545600</hardLimit>

                </quota>

                <quota>

                    <path>/ifs/data/robot</path>

                    <type>directory</type>

                    <used>24833</used>

                </quota>

                <quota>

                    <path>/ifs/data/policy1/departmentA</path>

                    <type>directory</type>

                    <used>12</used>

                    <hardLimit>26843545600</hardLimit>

                </quota>

            </quotas>

        </element>

        <element>

            <cluster>

                <name>Cluster2-7201</name>

                <guid>005056ba72edf6450c552312a728d3a22a23</guid>

                <local_serial>V5052443373</local_serial>

                <onefs_version>

                    <build>B_7_2_1_014(RELEASE)</build>

                    <release>v7.2.1.0</release>

                    <type>PowerScale OneFS</type>

                    <version>PowerScale OneFS v7.2.1.0 B_7_2_1_014(RELEASE): 0x70201500000000E:Mon Jun 22 20:05:42 GMT 2015    root@sea-build7-03:/b/mnt/obj/b/mnt/src/sys/IQ.amd64.release   clang version 3.3 (tags/RELEASE_33/final)</version>

                    <revision>504967551327928334</revision>

                </onefs_version>

            </cluster>

            <nodes>

                <node>

                    <health>-A--</health>

                    <serial_number>V5052443373</serial_number>

                    <HDD_size>35GB</HDD_size>

                    <HDD_used>11GB</HDD_used>

                    <HDD_avail>25GB</HDD_avail>

                    <VHS>n/a</VHS>

                </node>

            </nodes>

            <shares>

                <share>

                    <name>igls-dfs-SMB2</name>

                    <path>/ifs/data/policy1</path>

                    <zone>System</zone>

                    <status>BACKUP</status>

                </share>

                <share>

                    <name>igls-dfs-spacetest</name>

                    <path>/ifs/data/policy1/space</path>

                    <zone>System</zone>

                    <status>BACKUP</status>

                </share>

                <share>

                    <name>migrate1</name>

                    <path>/ifs/data/migrate1</path>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </share>

                <share>

                    <name>dfs1</name>

                    <path>/ifs/data/userdata/dfs1</path>

                    <zone>data</zone>

                    <status>ACTIVE</status>

                </share>

                <share>

                    <name>roam</name>

                    <path>/ifs/data/userdata/dfs1/roam</path>

                    <zone>data</zone>

                    <status>ACTIVE</status>

                </share>

                <share>

                    <name>share1</name>

                    <path>/ifs/data/userdata/share1</path>

                    <zone>data</zone>

                    <status>BACKUP</status>

                </share>

                <share>

                    <name>share2</name>

                    <path>/ifs/data/userdata/share2</path>

                    <zone>data</zone>

                    <status>ACTIVE</status>

                </share>

                <share>

                    <name>dfs1</name>

                    <path>/ifs/data/dr-testing/dfs1</path>

                    <zone>DR-Testing-Zone</zone>

                    <status>BACKUP</status>

                </share>

                <share>

                    <name>share1</name>

                    <path>/ifs/data/dr-testing/share1</path>

                    <zone>DR-Testing-Zone</zone>

                    <status>BACKUP</status>

                </share>

                <share>

                    <name>share2</name>

                    <path>/ifs/data/dr-testing/share2</path>

                    <zone>DR-Testing-Zone</zone>

                    <status>BACKUP</status>

                </share>

            </shares>

            <exports>

                <export>

                    <paths>/ifs</paths>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </export>

                <export>

                    <paths>/ifs/data/migrate1</paths>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </export>

                <export>

                    <paths>/ifs/data/robot</paths>

                    <zone>EyeglassRunbookRobot-AccessZone</zone>

                    <status>BACKUP</status>

                </export>

                <export>

                    <paths>/ifs/data/userdata/export1/andrew</paths>

                    <zone>data</zone>

                    <status>BACKUP</status>

                </export>

                <export>

                    <paths>/ifs/data/userdata/export1</paths>

                    <zone>data</zone>

                    <status>BACKUP</status>

                </export>

                <export>

                    <paths>/ifs/data/dr-testing/export1/andrew</paths>

                    <zone>DR-Testing-Zone</zone>

                    <status>BACKUP</status>

                </export>

                <export>

                    <paths>/ifs/data/dr-testing/export1</paths>

                    <zone>DR-Testing-Zone</zone>

                    <status>BACKUP</status>

                </export>

            </exports>

            <aliases/>

            <quotas>

                <quota>

                    <path>/ifs/data/userdata/dfs1</path>

                    <type>directory</type>

                    <used>5175108664</used>

                </quota>

                <quota>

                    <path>/ifs/data/userdata/dfs1/roam</path>

                    <type>directory</type>

                    <used>2251508</used>

                </quota>

                <quota>

                    <path>/ifs/data/migrate1</path>

                    <type>directory</type>

                    <used>769442173</used>

                </quota>

                <quota>

                    <path>/ifs/data/userdata/share2</path>

                    <type>directory</type>

                    <used>12</used>

                </quota>

            </quotas>

        </element>

        <element>

            <cluster>

                <name>prod-8</name>

                <guid>005056ba67371492dd56f106ca5e3ff16028</guid>

                <local_serial>SV200-004EIJ-B96U</local_serial>

                <onefs_version>

                    <build>B_8_0_1_007(RELEASE)</build>

                    <release>v8.0.1.0</release>

                    <type>PowerScale OneFS</type>

                    <version>PowerScale OneFS v8.0.1.0 B_8_0_1_007(RELEASE): 0x800015000000007:Thu Sep  8 06:34:05 PDT 2016    root@sea-build10-02:/b/mnt/obj/b/mnt/src/sys/IQ.amd64.release   FreeBSD clang version 3.3 (tags/RELEASE_33/final 183502) 20130610</version>

                    <revision>576462195412434951</revision>

                </onefs_version>

            </cluster>

            <nodes>

                <node>

                    <health>OK</health>

                    <serial_number>SV200-004EIJ-B96U</serial_number>

                    <HDD_size>18.1GB</HDD_size>

                    <HDD_used>2.6GB</HDD_used>

                    <HDD_avail>15.5GB</HDD_avail>

                    <VHS>n/a</VHS>

                </node>

            </nodes>

            <shares>

                <share>

                    <name>migrate2</name>

                    <path>/ifs/data/migrate2</path>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </share>

                <share>

                    <name>dfs1</name>

                    <path>/ifs/data/marketing/dfs1</path>

                    <zone>marketing</zone>

                    <status>ACTIVE</status>

                </share>

                <share>

                    <name>share1</name>

                    <path>/ifs/data/marketing/shares</path>

                    <zone>marketing</zone>

                    <status>ACTIVE</status>

                </share>

            </shares>

            <exports>

                <export>

                    <paths>/ifs</paths>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </export>

                <export>

                    <paths>/ifs/data/migrate2</paths>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </export>

                <export>

                    <paths>/ifs/data/marketing/nfs/export1</paths>

                    <zone>marketing</zone>

                    <status>ACTIVE</status>

                </export>

            </exports>

            <aliases/>

            <quotas>

                <quota>

                    <path>/ifs/data/marketing/nfs/export1</path>

                    <type>directory</type>

                    <used>0</used>

                </quota>

                <quota>

                    <path>/ifs/data/marketing/shares</path>

                    <type>directory</type>

                    <used>12</used>

                </quota>

                <quota>

                    <path>/ifs/data/marketing/dfs1</path>

                    <type>directory</type>

                    <used>58599</used>

                </quota>

                <quota>

                    <path>/ifs/data/migrate2</path>

                    <type>directory</type>

                    <used>769417411</used>

                </quota>

            </quotas>

        </element>

        <element>

            <cluster>

                <name>dr-8</name>

                <guid>005056ba657091badd564b1487f19066d641</guid>

                <local_serial>SV200-004EIJ-AQR3</local_serial>

                <onefs_version>

                    <build>B_8_0_1_007(RELEASE)</build>

                    <release>v8.0.1.0</release>

                    <type>PowerScale OneFS</type>

                    <version>PowerScale OneFS v8.0.1.0 B_8_0_1_007(RELEASE): 0x800015000000007:Thu Sep  8 06:34:05 PDT 2016    root@sea-build10-02:/b/mnt/obj/b/mnt/src/sys/IQ.amd64.release   FreeBSD clang version 3.3 (tags/RELEASE_33/final 183502) 20130610</version>

                    <revision>576462195412434951</revision>

                </onefs_version>

            </cluster>

            <nodes>

                <node>

                    <health>OK</health>

                    <serial_number>SV200-004EIJ-AQR3</serial_number>

                    <HDD_size>18.1GB</HDD_size>

                    <HDD_used>2.9GB</HDD_used>

                    <HDD_avail>15.2GB</HDD_avail>

                    <VHS>n/a</VHS>

                </node>

            </nodes>

            <shares>

                <share>

                    <name>migrate1</name>

                    <path>/ifs/data/dr/migrate</path>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </share>

                <share>

                    <name>igls-dfs-dfs1</name>

                    <path>/ifs/data/marketing/dfs1</path>

                    <zone>marketing</zone>

                    <status>BACKUP</status>

                </share>

                <share>

                    <name>share1</name>

                    <path>/ifs/data/marketing/shares</path>

                    <zone>marketing</zone>

                    <status>BACKUP</status>

                </share>

            </shares>

            <exports>

                <export>

                    <paths>/ifs</paths>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </export>

                <export>

                    <paths>/ifs/data/dr/migrate</paths>

                    <zone>System</zone>

                    <status>UNPROTECTED</status>

                </export>

                <export>

                    <paths>/ifs/data/marketing/nfs/export1</paths>

                    <zone>marketing</zone>

                    <status>BACKUP</status>

                </export>

            </exports>

            <aliases/>

            <quotas>

                <quota>

                    <path>/ifs/data/dr/migrate</path>

                    <type>directory</type>

                    <used>167747631</used>

                </quota>

            </quotas>

        </element>

    </elements>


    Example 2: VMWare SRM Integrated Failover Example

    vmware SRM API integration.png

    1. VMWare SRM starts site failover of VM’s
    2. External API calls Eyeglass REST API using curl command (created with CURL builder Eyeglass API explorer interface).  VMWare SRM Creating Custom Recovery Steps
    1. Add command to the recovery plan: http://pubs.vmware.com/srm-61/index.jsp#com.vmware.srm.admin.doc/GUID-BABE0457-EB6F-4650-BB8B-01300ACAFF2F.html
    2. Create Message Prompts or Command Steps for Individual Virtual Machines: (http://pubs.vmware.com/srm-61/index.jsp#com.vmware.srm.admin.doc/GUID-45EE6522-3659-437F-B5AF-E9510AAA2CC8.html)
    3. On the Recovery Properties tab, click Pre-Power On Steps.
    1. Command on SRM Server  Runs a command on Site Recovery Manager Server. This option is available for both pre-power on steps and post-power on steps
    2. Complete rest of Step configuration
    1. You must start the Windows command shell using its full path on the local host. For example, to run a script located in c:\alarmscript.bat, use the following command line:

    c:\windows\system32\cmd.exe /c c:\alarmscript.bat

    1. You must install batch files and commands on the Site Recovery Manager Server at the recovery site.
    2. Batch files or commands  producing output that contains characters with ASCII values greater than 127 must use UTF-8 encoding. Site Recovery Manager records only the final 4KB of script output in log files and in the recovery history. Scripts that produce more output should redirect the output to a file rather than sending it to the standard output to be logged.

    Note: Batch files and commands must finish within 600 seconds, otherwise, the recovery plan terminates with an error. (See the following VMWare reference Change Recovery Settings). Therefore, during the configuration of SRM you may receive a timeout after 600 seconds . You can increase or decrease this value by editing the SRM configuration file (vmware-dr.xml). Look for the following section:

    <calloutCommandLineTimeout>600</calloutCommandLineTimeout>

    1. Change value to the appropriate value.
    1. Eyeglass API processes request from CURL command with timeout set and starts any failover mode supported by Eyeglass and requested by the CURL builder setup for the failover.



    Example 3: Initiate an Access Zone failover

    Failover Setting Parameters - Eyeglass REST API

    The following failover setting parameters are available through the Eyeglass REST API curl command:


    Parameter

    Description

    controlled

    Execute a controlled failover by running operations against the source cluster as well as the target

    datasync

    Run the final incremental data sync before failover


    configsync

    Run a configuration sync before failover  Should bd false for Release 2.5.6 and above.

    resyncprep

    Run resync prep on the source cluster to create the mirror policies

    disablemirror

    Disable mirror policies created on the failover target


    quotasync

    Run quota jobs to failover quotas to target


    blockonwarnings Blocks failover from starting if DR failover status is Warning when true.   All Warnings in DR Readiness will block a failover and must be reviewed before disabling this option.  Best Practice: Verify with support.superna.net warning validation prior to setting to false
    rollbackrenamesharesThis applies only to DFS mode failover and should be left enabled to automatically rollback SMB share rename step if required due to error in failover step.
    smbdataintegrity
    This mode disconnects any active SMB sessions prior to failover and ensures that no new sessions can be established on the failover source.  It applies a deny read permission to the Everyone user to each share.  Note any share with run as root bypasses all security and cannot be locked out from from a share.


    Eyeglass REST API - Failover Parameters Rules

    1. Failover Job is only allowed through this Eyeglass REST API when the Readiness shows OK, INFO or WARNING. Status. When the Readiness shows ERROR the failover job will be blocked and curl command will return this code:

    {

    "code": 500,
    "message": "{\"code\":500,\"message\":\"Zone zone01 is not eligible for failover\"}"

    }

    We need to rectify the highlighted issues and then re-verify the Readiness does not show ERROR status before we can execute the Failover job

    1. For uncontrolled Failover (controlled=false), the following parameters also need to be set as false: datasync, configsync, resyncprep, and disablemirror. Otherwise the curl command will return this output to highlight that requirement


    {

    "code": 500,
    "message": "{\"code\":500,\"message\":\"For an uncontrolled failover, datasync, configsync, resyncprep and disablemirror must all be false\"}"

    }


    1. For failover with parameter resyncprep=false, also need to leave the disablemirror parameter as false. If disablemirror is set as true while trying to run the failover job with resyncprep=false, the curl return this output.

    {

    "code": 500,
    "message": "{\"code\":500,\"message\":\"Cannot include the disablemirror flag when reyncprep is false.\"}"

    }




    Step 1: Get all of the PowerScale Clusters provisioned in superna eyeglass:

    Request:

    curl -k -H "api_key: igls-4e81gu94mc3opgf7uuhdtrf6oo0a0arfcuajra65l834l8p53j" https://192.168.10.10/sera/v1/nodes

    Response:

    [

     {

       "id": "Kyle-8-A_00505698937a1b73bb5698242b10b5fe9a97",

       "ip": "172.16.86.238",

       "name": "Kyle-8-A"

     },

     {

       "id": "Kyle-8-B_00505698f0793f8bbb56fc176e2f7b6e204c",

       "ip": "172.16.86.248",

       "name": "Kyle-8-B"

     }

    ]

    Step 2: Using the ID from step 1, get all of the access zones on the cluster:

    Request:

    curl -k -H "api_key: igls-p9cbjc3bjkgbo3ceph9t29jholrtvuc08p17ri7na73eal5g9nv" http://localhost:8089/sera/v1/nodes/Kyle-8-A_00505698937a1b73bb5698242b10b5fe9a97/zones

    Response:

    [

     {

       "failoverReadiness": "warning",

       "id": "zone-Kyle-8-A_kylezone",

       "name": "kylezone"

     }

    ]

    Step 3:  Initiate a failover

    Using the id of the zone and the IDs of the source and target clusters, post a new job to the jobs route to initiate a failover:

    Request

    curl -X POST -k -H "api_key: igls-p9cbjc3bjkgbo3ceph9t29jholrtvuc08p17ri7na73eal5g9nv" -H "Content-type: application/json" "http://localhost:8089/sera/v1/jobs?sourceid=Kyle-8-A_00505698937a1b73bb5698242b10b5fe9a97&targetid=Kyle-8-B_00505698f0793f8bbb56fc176e2f7b6e204c&failovertarget=zone-Kyle-8-A_kylezone"

    Response

    {

     "id": "job-1457385733807-630400755"

    }

    Step 4: Monitor the failover

    Using the ID of the job, monitor the status of the failover.  When the job is complete, there will be a “finished” property in the output and a “success” property indicating whether the job was a success or a failover.


    Request

    curl -k -H "api_key: igls-p9cbjc3bjkgbo3ceph9t29jholrtvuc08p17ri7na73eal5g9nv" http://localhost:8089/sera/v1/jobs/job-1457385733807-630400755

    Response

    {

     "failoverTarget": {

       "zone": {

         "failoverReadiness": "error",

         "id": "zone-Kyle-8-A_kylezone",

         "name": "kylezone"

       }

     },

     "finished": 1457385819964,

     "id": "job-1457385733807-630400755",

     "jobType": "zone_failover",

     "name": "Access_Zone_Failover__Kyle-8-A__2016-03-07_16-22-13",

     "sourceNode": {

       "id": "Kyle-8-A_00505698937a1b73bb5698242b10b5fe9a97",

       "ip": "172.16.86.238",

       "name": "Kyle-8-A"

     },

     "started": 1457385733813,

     "success": true,

     "targetNode": {

       "id": "Kyle-8-B_00505698f0793f8bbb56fc176e2f7b6e204c",

       "ip": "172.16.86.248",

       "name": "Kyle-8-B"

     }

    }

    Example 4: Get all currently running failover jobs

    Step 1: use the ?state=running query to filter by running jobs:

    Output from this route will not have “success” or “finished” parameters in the payload.


    Request:

    curl -k -H "api_key: igls-p9cbjc3bjkgbo3ceph9t29jholrtvuc08p17ri7na73eal5g9nv" http://localhost:8089/sera/v1/jobs\?state\=running

    Response:

    {

     "failoverTarget": {

       "zone": {

         "failoverReadiness": "warning",

         "id": "zone-Kyle-8-A_kylezone",

         "name": "kylezone"

       }

     },

     "id": "job-1457385733807-630400755",

     "jobType": "zone_failover",

     "name": "Access_Zone_Failover__Kyle-8-A__2016-03-07_16-22-13",

     "sourceNode": {

       "id": "Kyle-8-A_00505698937a1b73bb5698242b10b5fe9a97",

       "ip": "172.16.86.238",

       "name": "Kyle-8-A"

     },

     "started": 1457385733813,

     "targetNode": {

       "id": "Kyle-8-B_00505698f0793f8bbb56fc176e2f7b6e204c",

       "ip": "172.16.86.248",

       "name": "Kyle-8-B"

     }

    }

    Example 5: Get a historical record of all previous failover jobs

    Step 1: use the ?state=finished query to filter by completed jobs:

    Output from this route will not have “success” or “finished” parameters in the payload.


    Request:

    curl -k -H "api_key: igls-p9cbjc3bjkgbo3ceph9t29jholrtvuc08p17ri7na73eal5g9nv" http://localhost:8089/sera/v1/jobs?state=finished

    Response:

    {

     "failoverTarget": {

       "zone": {

         "failoverReadiness": "warning",

         "id": "zone-Kyle-8-A_kylezone",

         "name": "kylezone"

       }

     },

     "id": "job-1457385733807-630400755",

     "finished": 1457385819964,

     "jobType": "zone_failover",

     "name": "Access_Zone_Failover__Kyle-8-A__2016-03-07_16-22-13",

     "sourceNode": {

       "id": "Kyle-8-A_00505698937a1b73bb5698242b10b5fe9a97",

       "ip": "172.16.86.238",

       "name": "Kyle-8-A"

     },

     "started": 1457385733813,

     "success": true,

     "targetNode": {

       "id": "Kyle-8-B_00505698f0793f8bbb56fc176e2f7b6e204c",

       "ip": "172.16.86.248",

       "name": "Kyle-8-B"

     }

    }

    Known Issues

    T783 Rest API delete job error

    Description: Deleting a job from the API Explorer requires an empty JSON object to be specified in the body.

    Workaround: Enter ‘{}’ (without quotes) into the body field of the DELETE /jobs section of the API explorer to cancel a job.

    ———————————-

    T15042 Rest API policy readiness is missing output for Target Reachability check

    Description: The SyncIQ policy readiness retrieved using REST API is missing the output for the Target Reachability check.  If the Target Reachability validation fails the overall failover status is correctly shown as ERROR and failover cannot be initiated.

    Workaround: To assess target reachability:

    • Target reachability alarms related to Inventory or Configuration Replication would have been sent.
    • From the Eyeglass web interface, Eyeglass/PowerScale reachability can be viewed from the Continuous Operations dashboard.
    • All failover readiness criteria can be viewed from the Eyeglass web interface DR Dashboard.

    ———————————-

    T10935 Pool failover "failovertarget" field must be "zone id"

    Description: The "failovertarget" field must be "zone id" even though description indicates "ID of the access zone OR syncIQ policy to failover" .

    Workaround: Enter "zone id" for "failovertarget" when initiating pool failover.

    ———————————-

    T15623 Pool failover API does not support multiple pool selection

    Description: From Eyeglass DR Assistant a Pool failover can be initiated for multiple pools but this is not supported from the API.

    Workaround: Run concurrent failover for multiple pools.

    ———————————-

    T15624 Failover API does not block controlled failover when source cluster unreachable

    Failover API does not validate source cluster reachability and will allow a controlled failover to start even if source cluster unreachable.  Controlled failover in this case is expected to fail as it will attempt steps against the source cluster.  When source cluster is not reachable uncontrolled failover should be used.

    Workaround: Use manual process to verify source cluter reachability and initiate the appropriate controlled or uncontrolled failover.




    Copyright Superna LLC