z file systems

Part No: E52433-01June 2014

Oracle ZFS Storage Appliance RESTfulApplication Programming Interface

Copyright 2014, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws.Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute,exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law forinteroperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS. Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation,delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplementalregulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed onthe hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerousapplications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to takeall appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by useof this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarksof SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is aregistered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliatesare not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will notbe responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Copyright 2014 Oracle et/ou ses affilis. Tous droits rservs.

Ce logiciel et la documentation qui laccompagne sont protgs par les lois sur la proprit intellectuelle. Ils sont concds sous licence et soumis des restrictions dutilisationet de divulgation. Sauf disposition de votre contrat de licence ou de la loi, vous ne pouvez pas copier, reproduire, traduire, diffuser, modifier, breveter, transmettre, distribuer,exposer, excuter, publier ou afficher le logiciel, mme partiellement, sous quelque forme et par quelque procd que ce soit. Par ailleurs, il est interdit de procder touteingnierie inverse du logiciel, de le dsassembler ou de le dcompiler, except des fins dinteroprabilit avec des logiciels tiers ou tel que prescrit par la loi.

Les informations fournies dans ce document sont susceptibles de modification sans pravis. Par ailleurs, Oracle Corporation ne garantit pas quelles soient exemptes derreurs etvous invite, le cas chant, lui en faire part par crit.

Si ce logiciel, ou la documentation qui laccompagne, est concd sous licence au Gouvernement des Etats-Unis, ou toute entit qui dlivre la licence de ce logiciel ou lutilisepour le compte du Gouvernement des Etats-Unis, la notice suivante sapplique:

U.S. GOVERNMENT END USERS. Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation,delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplementalregulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed onthe hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S.Government.

Ce logiciel ou matriel a t dvelopp pour un usage gnral dans le cadre dapplications de gestion des informations. Ce logiciel ou matriel nest pas conu ni nest destin tre utilis dans des applications risque, notamment dans des applications pouvant causer des dommages corporels. Si vous utilisez ce logiciel ou matriel dans le cadredapplications dangereuses, il est de votre responsabilit de prendre toutes les mesures de secours, de sauvegarde, de redondance et autres mesures ncessaires son utilisationdans des conditions optimales de scurit. Oracle Corporation et ses affilis dclinent toute responsabilit quant aux dommages causs par lutilisation de ce logiciel ou matrielpour ce type dapplications.

Oracle et Java sont des marques dposes dOracle Corporation et/ou de ses affilis. Tout autre nom mentionn peut correspondre des marques appartenant dautrespropritaires quOracle.

Intel et Intel Xeon sont des marques ou des marques dposes dIntel Corporation. Toutes les marques SPARC sont utilises sous licence et sont des marques ou des marquesdposes de SPARC International, Inc. AMD, Opteron, le logo AMD et le logo AMD Opteron sont des marques ou des marques dposes dAdvanced Micro Devices. UNIXest une marque dpose dThe Open Group.

Ce logiciel ou matriel et la documentation qui laccompagne peuvent fournir des informations ou des liens donnant accs des contenus, des produits et des services manantde tiers. Oracle Corporation et ses affilis dclinent toute responsabilit ou garantie expresse quant aux contenus, produits ou services manant de tiers. En aucun cas, OracleCorporation et ses affilis ne sauraient tre tenus pour responsables des pertes subies, des cots occasionns ou des dommages causs par laccs des contenus, produits ouservices tiers, ou leur utilisation.

3

Contents

Using This Documentation ................................................................................ 11

1 Overview ........................................................................................................ 13Authentication ............................................................................................... 13

Basic Authentication ............................................................................... 13User Authentication ................................................................................ 13Session Authentication ............................................................................ 14

API Versions ................................................................................................. 14Service Versions ............................................................................................ 14Common RESTful Operations .......................................................................... 15HTTP Response Body .................................................................................... 15HTTP Response Headers ................................................................................. 16Query Parameters ......................................................................................... 17

props ................................................................................................... 17limit ..................................................................................................... 17start ..................................................................................................... 18

Errors ........................................................................................................... 18

2 Working with the API ..................................................................................... 21Accessing the Service ..................................................................................... 21List Services ................................................................................................. 21Get Service Commands ................................................................................... 22Authentication ............................................................................................... 23

Login Session ........................................................................................ 23Logout Session ...................................................................................... 24

3 Alert Service Commands ............................................................................... 25Alert Service Commands ................................................................................. 25Alert Thresholds ............................................................................................ 26

List Alert Thresholds .............................................................................. 27

Contents

4 Oracle ZFS Storage Appliance RESTful Application Programming Interface June 2014

Get Alert Threshold ............................................................................... 28Create Alert Threshold ............................................................................ 29Modify Alert Threshold .......................................................................... 30Delete Alert Threshold ............................................................................ 30

Alert Actions ................................................................................................. 30List Alert Actions .................................................................................. 38Get Alert Action .................................................................................... 39Create Alert Action ................................................................................ 40Modify Alert Action ............................................................................... 41Delete Alert Action ................................................................................ 41

Alert Action Items ......................................................................................... 42Create Alert Item ................................................................................... 42Modify Alert Action ............................................................................... 42Delete Alert Action Item ......................................................................... 43

4 Analytics Services ......................................................................................... 45Analytics Services Available ............................................................................ 45Settings ........................................................................................................ 46

Get Settings .......................................................................................... 46Modify Settings ..................................................................................... 47

Worksheets ................................................................................................... 47List Worksheets ..................................................................................... 48Get Analytics Worksheet ......................................................................... 48Create Worksheets .................................................................................. 49Destroy Worksheets ................................................................................ 50List Worksheet Datasets .......................................................................... 50Add Worksheet Dataset ........................................................................... 50Modify Worksheet Dataset ....................................................................... 51

Datasets ........................................................................................................ 52List Datasets ......................................................................................... 53Get Dataset ........................................................................................... 54Create Datasets ...................................................................................... 54Modify Dataset ...................................................................................... 55Destroy Datasets .................................................................................... 55Save Dataset ......................................................................................... 56Prune Dataset Data ................................................................................. 56Get Dataset Data .................................................................................... 56

5 Hardware Services ......................................................................................... 59

Contents

5

Cluster ......................................................................................................... 59Get Cluster Properties ............................................................................. 59Get Cluster Resource .............................................................................. 60Modify Cluster Resource ......................................................................... 60Cluster Commands ................................................................................. 61Cluster Links ......................................................................................... 61Setup Cluster ......................................................................................... 62

Chassis ......................................................................................................... 62List Chassis .......................................................................................... 62Get Chassis Components ......................................................................... 64Get Hardware Component ....................................................................... 65Modify Component Property .................................................................... 67

6 Log Commands ............................................................................................. 69Log Commands ............................................................................................. 69List Logs ...................................................................................................... 69Get Log Entries ............................................................................................. 70Download Logs ............................................................................................. 72Download Log .............................................................................................. 72

7 Network Commands ...................................................................................... 73Networking Configuration ............................................................................... 73Network Datalinks ......................................................................................... 74

List Network Datalinks ........................................................................... 76Get Network Datalink ............................................................................. 76Create Network Datalink ......................................................................... 77Modify Network Datalink ........................................................................ 78Delete Network Datalink ......................................................................... 78

Network Devices ........................................................................................... 78List Network Devices ............................................................................. 79Get Network Device ............................................................................... 80

Network Interfaces ......................................................................................... 80List Network Interfaces ........................................................................... 81Get Network Interface ............................................................................ 82Create Network Interface ......................................................................... 83Modify Network Interface ....................................................................... 83Delete Network Interface ......................................................................... 84

Network Routes ............................................................................................. 84List Routes ........................................................................................... 85

Contents


Get Route ............................................................................................. 86Add Route ............................................................................................ 86Delete Route ......................................................................................... 87

8 Problem Service Commands ......................................................................... 89Problem Service Commands ............................................................................ 89

List Problems ........................................................................................ 89List Problem ......................................................................................... 90

Repair Problem .............................................................................................. 91

9 Role Service .................................................................................................. 93Role Service Command Overview .................................................................... 93List Roles ..................................................................................................... 94Get Role ....................................................................................................... 95Create Role ................................................................................................... 95Modify Role ................................................................................................. 96Revoke Role ................................................................................................. 97Delete Role ................................................................................................... 97List Role Authorizations ................................................................................. 97Create Role Authorization ............................................................................... 98Modify Role Authorization .............................................................................. 99Delete Role Authorization ............................................................................... 99

10 SAN Services ............................................................................................. 101Overview .................................................................................................... 101Initiators ..................................................................................................... 101

List Initiators ....................................................................................... 103Get Initiator Details .............................................................................. 103Create an Initiator ................................................................................ 104Modify an Initiator ............................................................................... 104Delete an Initiator ................................................................................ 105

Initiator Groups ............................................................................................ 105List Initiator Groups ............................................................................. 106Get Initiator Group Details .................................................................... 107Create an Initiator Group ....................................................................... 107Delete an Initiator Group ....................................................................... 108

Targets ........................................................................................................ 108List Targets ......................................................................................... 110Get Target Details ................................................................................ 111

Contents

7

Create a Target .................................................................................... 111Modify a Target ................................................................................... 112Delete a Target .................................................................................... 113

Target Groups .............................................................................................. 113List Target Groups ................................................................................ 114Get Target Group ................................................................................. 115Create a Target Group ........................................................................... 115Delete a Target Group ........................................................................... 116

11 Service Commands .................................................................................... 117Service Commands ....................................................................................... 117List Services ................................................................................................ 117Get Service ................................................................................................. 121Change Service State .................................................................................... 121Modify Service Configuration ....................................................................... 122Service Resources ........................................................................................ 123

12 Storage Services ........................................................................................ 125Storage Pool Operations ................................................................................ 125List Pools ................................................................................................... 125Get Pool ..................................................................................................... 126Configure Pool ............................................................................................ 127Add Storage to a Pool ................................................................................... 129Pool Scrub .................................................................................................. 129Unconfigure Pool ......................................................................................... 129Project Operations ........................................................................................ 130

List Projects ........................................................................................ 132Create Project ...................................................................................... 134Modify Project ..................................................................................... 135Delete Project ...................................................................................... 136Project Usage ...................................................................................... 136

Filesystem Operations ................................................................................... 137List Filesystems ................................................................................... 138Get Filesystem ..................................................................................... 139Create Filesystem ................................................................................. 141Modify Filesystem ................................................................................ 142Delete Filesystem ................................................................................. 143Filesystem Quota and Usage .................................................................. 144

LUN Operations ........................................................................................... 144

Contents


List LUNS .......................................................................................... 146Get LUN ............................................................................................ 146Create a New LUN ............................................................................... 148Modify LUN ....................................................................................... 149Delete Lun .......................................................................................... 150

Snapshot and Clone Operations ...................................................................... 150List Snapshots ..................................................................................... 153Get Snapshot ....................................................................................... 154Create Snapshot ................................................................................... 154Rename Snapshot ................................................................................. 155Clone Snapshot .................................................................................... 155Rollback Snapshot ................................................................................ 157Delete a Snapshot ................................................................................. 158List Snapshot Dependents ...................................................................... 159

Schema ....................................................................................................... 160List Properties ..................................................................................... 160Get Property ........................................................................................ 161Create Property .................................................................................... 161Modify Property ................................................................................... 162Delete Property .................................................................................... 162

Replication .................................................................................................. 163Get Replication Service ......................................................................... 163Modify Replication Service State ............................................................ 164

Replication Targets ....................................................................................... 164List Replication Targets ......................................................................... 164Get Replication Target .......................................................................... 165Create Replication Target ....................................................................... 166Delete Replication Target ....................................................................... 166

Replication Actions ...................................................................................... 167List Replication Actions ........................................................................ 170Get Replication Action .......................................................................... 171Create Replication Action ...................................................................... 171Modify Replication Action ..................................................................... 173Cancel Update ..................................................................................... 173Send Update ........................................................................................ 173Delete a Replication Action ................................................................... 174

Replication Packages .................................................................................... 174List Replication Sources ........................................................................ 178List Replication Packages ...................................................................... 179Modify Package ................................................................................... 180

Contents

9

Delete Package .................................................................................... 180Cancel Update ..................................................................................... 180Clone Package ..................................................................................... 181Sever Package ..................................................................................... 182Reverse Package .................................................................................. 182

13 System Commands .................................................................................... 185Appliance System Commands ........................................................................ 185Get Version ................................................................................................. 186Power Off System ........................................................................................ 186Reboot System ............................................................................................. 187Restart System Management .......................................................................... 187Diagnostic Reboot ........................................................................................ 187Factory Reset .............................................................................................. 187System Support Bundles ................................................................................ 188Create Support Bundle .................................................................................. 188List Support Bundles .................................................................................... 189Get Support Bundle ...................................................................................... 189Cancel Support Bundle .................................................................................. 190Retry Support Bundle Upload ......................................................................... 190Upload Support Bundle ................................................................................. 191Delete Support Bundle .................................................................................. 191System Updates ........................................................................................... 191List System Updates .................................................................................... 192Get System Update ....................................................................................... 193Upload System Update .................................................................................. 194Upgrade ...................................................................................................... 194Rollback ..................................................................................................... 195Delete Update Image .................................................................................... 195

14 User Service ............................................................................................... 197User Service Commands ................................................................................ 197List Users ................................................................................................... 198Get User ..................................................................................................... 199Create User ................................................................................................. 200Modify Users .............................................................................................. 202Delete Users ................................................................................................ 202

15 Workflow Commands ................................................................................. 205

Contents


Workflow Service Commands ........................................................................ 205List Workflows ............................................................................................ 206Get Workflow .............................................................................................. 206Modify a Workflow ...................................................................................... 207Execute a Workflow ..................................................................................... 208Delete Workflow .......................................................................................... 208Upload Workflow ......................................................................................... 209

16 RESTful Clients .......................................................................................... 211Curl Rest Client ........................................................................................... 211

Get Resource Data ............................................................................... 211Create a New Resource ......................................................................... 212Modify an Existing Resource ................................................................. 212Delete an Existing Resource ................................................................... 213

Python RESTful Client .................................................................................. 213Get a Resource ................................................................................... 214Create a Resource ............................................................................... 214Modify a Resource .............................................................................. 215Delete an Existing Resource .................................................................. 216

Using This Documentation 11

Using This Documentation

Overview Describes how to work with the Oracle ZFS Storage Appliance RESTFul API Audience Technicians, system administrators, and authorized service providers Required knowledge Advanced experience working with application program interfaces

Product Documentation Library

Product Documentation Library Visit http://www.oracle.com/goto/ZFSStorage/docs for theOracle ZFS Storage Appliance documentation library.

For related documentation, including white papers, visit http://www.oracle.com/technetwork/server-storage/sun-unified-storage/overview/index.html and click on the Documentation tab.For late-breaking information and known issues about this product, visit My Oracle Support athttp://support.oracle.com.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. Forinformation, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Feedback

Provide feedback about this documentation at http://www.oracle.com/goto/docfeedback.

http://www.oracle.com/goto/ZFSStorage/docshttp://www.oracle.com/technetwork/server-storage/sun-unified-storage/overview/index.htmlhttp://www.oracle.com/technetwork/server-storage/sun-unified-storage/overview/index.htmlhttp://support.oracle.comhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infohttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trshttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trshttp://www.oracle.com/goto/docfeedback

Chapter1 Overview 13

1C H A P T E R 1Overview

The Oracle ZFS Storage Appliance (ZFSSA) is a family of enterprise storage products thatprovides efficient file and block data services over the network. This guide describes theZFSSA RESTful Application Programming Interface (API). This API can be used to managethe ZFS Storage Appliance. This documentation is organized using the same hierarchy as theBrowser User Interface (BUI) and Command Line Interface (CLI).

Cloud environments typically use a RESTful architecture, which is based on a layered client-server model. This layered model allows services to be transparently redirected throughstandard hubs, routers, and other network systems without client configuration.

AuthenticationThe service uses the same underlyingauthentication used by the ZFSSA BUI and CLIinterfaces. Authentication can take one of the following forms.

Basic AuthenticationWhen basic authentication is used, each request must contain the user login .

Example HTTP Header:

Authorization: Basic abcefgMWE

User AuthenticationAuthentication can also be accomplished usingthe ZFSSA BUI or CLI login credentials. In thiscase the X-Auth-User header must contain the login name, and the X-Auth-Key header mustcontain the login password.

Example HTTP Headers:

X-Auth-User: root

X-Auth-Key: letmein-xxx

API Versions


Session Authentication

When a session has been authenticated, a session header can be used to continue to runcommands until the session expires. After a session expires, authentication must be done againbefore commands are accepted.

Session Header Example:

X-Auth-Session: guigqpQRE4g89ngb

API Versions

The RESTful API version for a given ZFSSArelease has a global version number matchingthe appliance software version. This version number is returned in the response header of allrequests:

X-Zfssa-Version: nas.2013.1.1

Service Versions

Each service has a version number as part of the Uniform Resource Identifier (URI) to accessthe service.The version has a majorand minor number. Requests must supply the major versionnumber but the minor version number is optional and defaults to a value of "0" if not supplied.The major number must match the major number of the service. The minor number must be lessthan or equal to the minor number of the service.

Example: A client makes some requests for a service that is running version number 2.1.

Request Version Allowed

v1 F alse - Major number does not match

v2 T rue - Major number matches minor is backwardscompatible

v2.1 T rue - Major and minor numbers match

v2.2 F alse - Major matches but minor is a newer revision

No service API version changes are required for the following property changes. The applianceversion number and model must be used to determine which properties are available.Theseproperty changes are also reflected in the CLI and BUI and are an indicationof the capabilitiesof that ZFSSA instance.

Common RESTful Operations


New output properties (without removing old properties). New input properties added to an existing command, that have default values that make the

command behave is it did in an earlier version.

Since a newer version of a backwards-compatible command can return additional properties,clients should be coded to ignore new properties. The minor number is incremented forbackwards-compatible changes to the service API.

Add a new command to an existing service. Add new query parameters to service commands.

The major number is incremented with incompatible changes to the service API.

Removing command query parameters. Removing a command from an existing service.

Major releases of ZFSSA software may include incompatibleversion changes. There may ormay not be older versions of a given service during a major update. Each command responsemust contain an HTTP header with the current version of the ZFSSA API for a given module:

X-Zfssa-Nas-Api: 1.1

Common RESTful OperationsThe following table shows the common RESTful operations for a give resource.

TABLE 1-1 Common RESTful Operations

GET resourcese> List all resources

GET resources/ Get a JSON object describing theselected resource

POST resourcese> Create a new resource

PUT resources/ Modify the selected resource

DELETE resources/ Delete the selected resource

HTTP Response BodyAll response data is encoded in JSON format as defined by RFC 4627 http://tools.ietf.org/html/rfc4627.html. Unless otherwise specified, commands against a single resource return a singleJSON results object with the resource name as a property. Each command section documentswhich property names are returned in this JSON result object.

HTTP Response Headers


Unless otherwise stated, the create (POST) and modify (PUT) commands return the propertiesof the created or modified resource. The contents should match the values returned by the GETrequest.

Example Body:

{

"resource_name": {

"href": "path/to/this/resource",

"property_01": "value_01",

"property_02": "value_01

}

}

Some GET commands return a list of resources.

{

"resource_list_name": [

{

"href": "path/to/resource_01",

"property_01": "value_01"

}, {

"href": "path/to/resource_02",

"property_02", "value_02"

}

]

}

Note - Throughout this document, commands show JSON return results that have beenformatted by adding returns and spaces to make it more readable. The actual output does notcontain this formatting.

HTTP Response Headers

All ZFSSA service commands that send data use the JSON data format and require thefollowing header values:

Accept: application/json

Content-Type: application/json

Response Headers include the following information:

Date: Tue, 23 Jul 2013 13:07:37 GMT X-Zfs-Sa-Appliance-Api: 1.0 Content-Type: application/json

Content-Length: 357

For list results, the content length may not be known before data is sent back. If the contentlength is not supplied, the client must read the response body until EOF to read all the returneddata.

Query Parameters


Query Parameters

Some requests will take optional query parameters that will modify or enhance the datareturned. See the documentation for each resource for details. Not every resource will supportevery query parameter. This section just documents the common query parameters that will beused when a resource does implement the specified query parameter.

Common query parameters:

TABLE 1-2 Common Query Parameters

Parameter Description

props=true List property metadata for a resource (default is false)

limit=n Limit the number of list elements returned.

start=n Index number (or time) used to begin element datareturned

props

The props query parameter can be used on many GET commands that return a single resourceinstance. It will return a 'props' data element that contains a list of property meta data.

Property Metadata Values

TABLE 1-3

Property Description

name Property name

label Description of property

immutable Flag indicating that property cannot be modified

type Property type: String, Integer, Boolean...

choices For enumerated properties, an array of available values

limit

The limit query can be used on many GET commands that can return a large number ofelements in order to limit the maximum number of elements returned.

Errors


start

The start query parameter is supported on the same commands that support the limit parameter.It gives the start index that is used to begin the returned data. For resources that support timevalues, the index may be a time value such as "20130531T01:13:58".

Errors

Errors return an HTTP status code indicatingthe error along with the following fault responsepayload.

JSON Fault Response:

{

fault: {

message: 'ERR_INVALID_ARG',

details: 'Error Details...',

code: 500

}

}

Common Error Codes

TABLE 1-4 Common Error Codes

Name Code Description

ERR_INVALID_ARG 400 Invalid input argument

ERR_UNKNOWN_ARG 400 Extra unhandled input argument

ERR_MISSING_ARG 400 Required input argument missing

ERR_UNAUTHORIZED 401 This user is not authorized to executecommand

ERR_DENIED 403 Operation denied

ERR_STATE_CHANGED Conflict in system state

ERR_NOT_FOUND 404 The requested item was not found

ERR_OBJECT_EXISTS 409 Request creates an object thatalready exists

ERR_OVER_LIMIT 413 Input request too large to handle

ERR_UNSUPPORTED_MEDIA 415 Requested media type is notsupported by request

ERR_NOT_IMPLEMENTED 501 Operation not implemented

Errors


Name Code Description

ERR_BUSY 503 Service not available due to limitedresources

Chapter2 Working with the API 21

2C H A P T E R 2Working with the API

The access service isthe entry point for all RESTful API services on the ZFSSA. The serviceis used to authenticate user credentialsand to list the available RESTful API services includingtheir versions and access points.

Accessing the Service

To access the service, use this URL http://zfssa.example.com:215/api/access/v1

To access other services, log in using the access service to get the location and versions of theavailable services and then use the returned URI to access those services. Service locations canchange based on the current appliance configuration or release level.

TABLE 2-1 Access Service Commands

Request Path Description

GET /api/access/v1 Lists RESTful API service accesspoints

POST /api/access/v1 Creates a login session

DELETE /api/access/v1 Logs out of a session

List Services

Lists the available service access URIs. If a login session is not desired then the list servicescommand can be used with appropriate credentials to list the available service access URIs.This command lists all the RESTful API services and versions available on that appliance.

Example Request:

GET /api/access/v1 HTTP/1.1

Host: zfs-storage.example.com

X-Auth-User: joeadmin

Get Service Commands


X-Auth-Key: letmein

Example Result:

HTTP/1.1 200 OK


Content-Length: 190

X-Zfssa-Access-Api: 1.0

{

"access": {

"services": [{

"version": "1.0",

"name": "appliance",

"uri": "https://zfs-storage.example.com:215/api/appliance/v1"

}, {

"version": "1.0",

"name": "nas",

"uri": "https://zfs-storage.example.com:215/api/nas/v1"

}, {

"version": "1.0",

"name": "replication",

"uri": "https://zfs-storage.example.com:215/api/replication/v1"

}, {

"version": "1.0",

"name": "san",

"uri": "https://zfs-storage.example.com:215/api/san/v1"

} ... ]

}

}

Get Service CommandsThis command returns information about that service, including a list of all the availablecommands.

Example Request:

GET /api/appliance/v1 HTTP/1.1



Example Response:

HTTP/1.1 200 OK


Content-Length: 204


{

"service": {

"name": "appliance",

"methods": [

{

Authentication

Chapter2 Working with the API 23

"description": "Get appliance RESTful services",

"path": "/apis",

"request": "GET"

},

{

"description": "Get appliance RESTful service properties",

"path": "/apis/",

"request": "GET"

},

{

"description": "Create a new alert threshold watch",

"path": "/alerts/thresholds",

"request": "POST"

}, ... ]

}

}

Authentication

An authentication session ID is obtained from the access service by sending a POST request.This authentication session ID can be used by all other services as an identity credential. Theauthentication ID is invalidated after a timeout period set by the users session timeout property.The default is usually 15 minutes. A DELETE request can be used to logout and invalidate thesession ID.

An authentication session is not required as clients can re-send authentication informationwith each request. Since the RESTful API operations are stateless only the authentication ID isstored.

Login Session

An empty POST request requests a new login session. On success, an HTTP status of 201 isreturned along with a JSON object that has a single property access that contains a list ofavailable RESTful API services.

Example Login Request:

POST /api/access/v1 HTTP/1.1


X-Auth-User: root

X-Auth-Key: letmein-xxx

A successful login returns HTTP Status 201 (Created), as well as a session ID through the X-Auth-Session HTTP header. The response body contains a list of services accessible via thislogin.

Response Header:

Authentication


HTTP/1.1 201 Created



Content-Length: 378


{

"access": {

"services":[{

...

}]

}

}

Logout Session

An empty DELETE requests to logout and invalidate the session.

Example Logout Request:

DELETE /api/access/v1 HTTP/1.1


Example Response:

HTTP/1.1 204 No Content


Chapter3 Alert Service Commands 25

3C H A P T E R 3Alert Service Commands

The alert RESTful API service lets you configure alert thresholds and responses to postedalerts.

Alert Service Commands

The following table shows the alert service commands.

TABLE 3-1 Alert Service Commands

Request Path /api/alert/v1 Description

GET List the alert service commands

POST /thresholds Create a new alert threshold watch

GET /thresholds/ Get the specified alert thresholdwatch properties

GET /thresholds List all alert threshold watch objects

PUT /thresholds/ Modify the specified alert thresholdwatch object

DELETE /thresholds/ Destroy the specified thresholdobject

POST /actions Create a new alert actions

GET /actions/ Get the specified alert actionsproperties

GET /actions List all alert actions objects

PUT /actions/ Modify the specified alert actionsobject

DELETE /actions/ Destroy the specified actions object

POST /actions/ Create a new alert actions action

Alert Thresholds


Request Path /api/alert/v1 Description

GET /actions// Get the specified alert actions actionproperties

PUT /actions// Modify the specified alert actionsaction object

DELETE /actions// Destroy the specified action object

GET /events Listen for new alert events

Alert Thresholds

Thresholds can be set to create custom alert watches. The following table lists typical propertiesfor managing an alert threshold. For a complete reference, see the CLI help.

TABLE 3-2 Alert Thresholds

Property Type Description

uuid Default Unique identifier for the watch(immutable)

statname AnalyticsStatistics Statistic to watch [cpu.utilization,arc.accesses, arc.size, arc.l2_bytes, arc.l2_accesses, arc.l2_size, syscap.bytesused, syscap.percentused, repl.bytes, repl.ops, shadow.kilobytes, shadow.ops, shadow.requests, io.bytes,io.ops, datalink.kilobytes, nic.kilobytes, net.kilobytes, ftp.kilobytes, fc.bytes, fc.ops,http.reqs, ndmp.bytes, ndmp.diskkb, ndmp.ops, nfs2.bytes,nfs2.ops, nfs3.bytes, nfs3.ops, nfs4.bytes, nfs4.ops, sftp.kilobytes, smb.ops, srp.bytes,srp.ops, iscsi.bytes, iscsi.ops]

type ChooseOne Whether to post alert when the statexceeds the limit (normal) or fallsbelow the limit (inverted) [normal,inverted]

limit PositiveInteger Limit value for the statistic

minpost Duration Minimum time condition must holdbefore posting alert

days ChooseOne Only post alert on particular days[all, weekdays, weekends]

Alert Thresholds



window_start TimeOfDay Only post alerts between window_start and window_end [none,00:00, 00:30, 01:00, 01:30,02:00, 02:30, 03:00, 03:30,04:00, 04:30, 05:00, 05:30,06:00, 06:30, 07:00, 07:30,08:00, 08:30, 09:00, 09:30,10:00, 10:30, 11:00, 11:30,12:00, 12:30, 13:00, 13:30,14:00, 14:30, 15:00, 15:30,16:00, 16:30, 17:00, 17:30,18:00, 18:30, 19:00, 19:30,20:00, 20:30, 21:00, 21:30,22:00, 22:30, 23:00, 23:30]

window_end TimeOfDay Only post alerts between window_start and window_end [none,00:00, 00:30, 01:00, 01:30,02:00, 02:30, 03:00, 03:30,04:00, 04:30, 05:00, 05:30,06:00, 06:30, 07:00, 07:30,08:00, 08:30, 09:00, 09:30,10:00, 10:30, 11:00, 11:30,12:00, 12:30, 13:00, 13:30,14:00, 14:30, 15:00, 15:30,16:00, 16:30, 17:00, 17:30,18:00, 18:30, 19:00, 19:30,20:00, 20:30, 21:00, 21:30,22:00, 22:30, 23:00, 23:30](immutable)

frequency Duration Minimum time before reposting analert

minclear Duration Minimum time of normality beforereposting all clear alert

List Alert Thresholds

Lists all of the configured alert thresholds.

Example Request:

GET /api/alert/v1/thresholds HTTP/1.1

Authorization: Basic abcd123MWE=

Host: zfssa.example.com:215


Example Response:

HTTP/1.1 200 OK

Date: Tue, 27 Aug 2013 17:38:40 GMT

Alert Thresholds


X-Zfssa-Appliance-Api: 1.0


Content-Length: 689

{

"thresholds": [

{

"days": "all",

"frequency": 300,

"href": "/api/alert/v1/thresholds/

bec758cb-346e-6a7d-c211-b320c09ef6a6",

"limit": 500,

"minclear": 300,

"minpost": 300,

"statname": "cpu.utilization",

"threshold": "threshold-000",

"type": "normal",

"uuid": "bec758cb-346e-6a7d-c211-b320c09ef6a6",

"window_end": 0,

"window_start": -1

},

{

"days": "all",

"frequency": 300,


475799d8-32c8-6ff6-882c-aa3b66e3a5a2",

"limit": 100000,

"minclear": 600,

"minpost": 300,

"statname": "datalink.kilobytes",

"threshold": "threshold-001",

"type": "normal",

"uuid": "475799d8-32c8-6ff6-882c-aa3b66e3a5a2",

"window_end": 300,

"window_start": 1200

}

]

}

Get Alert Threshold

Lists the properties for a single alert threshold.

Example Request:

GET /api/alert/v1/thresholds/1b15d405-75c4-4c0c-e0f6-8a108165b874

HTTP/1.1




Example Result:

HTTP/1.1 200 OK

Alert Thresholds




Content-Length: 363

{

"threshold": {

"days": "weekdays",

"frequency": 300,


1b15d405-75c4-4c0c-e0f6-8a108165b874",

"limit": 100000,

"minclear": 300,

"minpost": 300,

"statname": "datalink.kilobytes",

"type": "normal",

"uuid": "1b15d405-75c4-4c0c-e0f6-8a108165b874",

"window_end": 0,

"window_start": -1

}

}

Create Alert Threshold

Creates an alert threshold.

Example Request:

POST /api/alert/v1/thresholds HTTP/1.1


X-Auth-User: root

X-Auth-Key: letmein


Content-Length: 50

{"statname": "datalink.kilobytes", "limit": 100000}

Example Response:




Content-Length: 321

Location: /api/alert/v1/thresholds

/1b15d405-75c4-4c0c-e0f6-8a108165b874

{

"threshold": {

"href": "/api/alert/v1/alerts/thresholds

/1b15d405-75c4-4c0c-e0f6-8a108165b874",

...

}

}

Alert Actions


Modify Alert ThresholdModifies any of the properties for the specified alert threshold.

Example Request:

PUT /api/alert/v1/thresholds/1b15d405-75c4-4c0c-e0f6-8a108165b874

HTTP/1.1



{"days":"weekdays"}

Example Response:

HTTP/1.1 202 Accepted



Content-Length: 326

{

"threshold": {

"days": "weekdays",

...

}

}

Delete Alert ThresholdDelete the specified alert threshold.

Example Request:

DELETE /api/alert/v1/thresholds/475799d8-32c8-6ff6-882c-aa3b66e3a5a2

HTTP/1.1



Example Response:



Alert ActionsThe category property determines the type of alert action being defined. Each category has itsown property set defined.

Supported categories are:

Alert Actions


ad all appliance_software backup cluster custom hardware hardware_faults ndmp network replication replication_source replication_target restore scrk shadow smf thresholds zfs_pool

TABLE 3-3 Alert Actions


Alert Actions ad

active_directory_degraded Boolean Filter should match active_directory_degraded events [true or false]

smb_kerberos_client_authentication_degraded

Boolean Filter should match mb_kerberos_client_authentication_degradedevents [true or false]

Alert Actions all

all_alerts Boolean Filter should match all_alerts events[true, false]

all_defects Boolean Filter should match all_defectsevents [true, false]

service_alerts Boolean Filter should match service_alertsevents true, false]

all_hardware_faults Boolean Filter should match all_hardware_faults events [true, false]

Alert Actions appliance_software

Alert Actions



obstacles_to_system_software_update

Boolean Filter should match obstacles_to_system_software_update events[true, false]

operating_system_kernel_panic Boolean Filter should match operating_system_kernel_panic events [true orfalse]

Alert Actions backup

backup_finished Boolean Filter should match backup_finishedevents [true or false]

backup_started Boolean Filter should match backup_startedevents [true or false]

Alert Actions cluster

cluster_i /o_link_down Boolean Filter should match cluster_i /o_link_down events [true or false]

cluster_i /o_link_failed Boolean Filter should match cluster_i /o_link_failed events [true or false]

cluster_i /o_link_up Boolean Filter should match cluster_i /o_link_up events [true or false]

unexpected_peer_error_occurred Boolean Filter should match unexpected_peer_error_occurred events [true or false]

communication_t o_peer_lost Boolean Filter should match communication_to_peer_lost events [true or false]

cluster_peer_panicked Boolean Filter should match cluster_peer_panicked events [true or false]

failed_to_set_s p_root_password_on_cluster_peer

Boolean Filter should match failed_to_set_sp_root_password_on_cluster_peerevents [true or false]

cluster_rejoin_failed_on_peer Boolean Filter should match cluster_rejoin_failed_on_peer events [true or false]

cluster_rejoin_mismatch_on_peer Boolean Filter should match cluster_rejoin_mismatch_on_peer events [true orfalse]

cluster_rejoin_completed_on_peer Boolean Filter should match cluster_rejoin_completed_on_peer events [true orfalse]

cluster_peer_lost_communication_token

Boolean Filter should match cluster_peer_lost_communication_token events [trueor false]

cluster_rejoin _failed Boolean Filter should match cluster_rejoin_failed events [true or false]

Alert Actions



cluster_rejoin_mismatch Boolean Filter should match cluster_rejoin_mismatch events [true or false]

cluster_rejoin_completed Boolean Filter should match cluster_rejoin_completed events [true or false]

cluster_takeover_complete Boolean Filter should match cluster_takeover_complete events [true or false]

resource_import_failed_during_cluster_takeover

Boolean Filter should match resource_import_failed_during_cluster_takeoverevents [true or false]

local_cluster_communication_token_lost

Boolean Filter should match local_cluster_communication_token_lost events[true or false]

Alert Actions custom

patterns Default FMA event patterns

Alert Actions hardware

fibre_channel_port_down Boolean Filter should match fibre_channel_port_down events [true or false]

multiple_transi ent_fibre_channel_port_status _changes

Boolean Filter should match multiple_transient_fibre_channel_port _status_changes events [true or false]

transient_fibre_channel_port_status_change

Boolean Filter should match transient_fibre_channel_port_status_change events[true or false]

fibre_channel_port_up Boolean Filter should match fibre_channel_port_up events [true or false]

network_port_down Boolean Filter should match network_port_down events [true or false]

network_port_up Boolean Filter should match network_port_upevents [true or false]

chassis_connected_to_system Boolean Filter should match chassis_connected_to_system events [trueor false]

chassis_removed Boolean Filter should match chassis_removedevents [true or false]

hardware_component_inserted Boolean Filter should match hardware_component_inserted events [true orfalse]

hardware_component_removed Boolean Filter should match hardware_component_removed events [true orfalse]

Alert Actions



disk_inserted Boolean Filter should match disk_insertedevents [true or false]

disk_removed Boolean Filter should match disk_removedevents [true or false]

hba_reset Boolean Filter should match hba_reset events[true or false]

i/o_path_added Boolean Filter should match i/o_path_addedevents [true or false]

i/o_path_removed Boolean Filter should match i/o_path_removed events [true or false]

service_processor_offline_or_unavailable

Boolean Filter should match service_processor_offline_or_unavailableevents [true or false]

service_processor_online_after_outage

Boolean Filter should match service_processor_online_after_outageevents [true or false]

failed_to_set_root_password_on_service_processor

Boolean Filter should match failed_to_set_root_password_on_service_processor events [true or false]

Alert Actions hardware_faults

all_hardware_faults Boolean Filter should match all_hardware_faults events [true or false]

Alert Actions ndmp

invalid_ndmp_restore Boolean Filter should match invalid_ndmp_restore events [true or false]

backup_finished Boolean Filter should match backup_finishedevents [true or false]

backup_started Boolean Filter should match backup_startedevents [true or false]

restore_finished Boolean Filter should match restore_finishedevents [true or false]

restore_started Boolean Filter should match restore_startedevents [true or false]

Alert Actions network

datalink_failed Boolean Filter should match datalink_failedevents [true or false]

datalink_ok Boolean Filter should match datalink_okevents [true or false]

Alert Actions



network_port_down Boolean Filter should match network_port_down events [true or false]

network_port_up Boolean Filter should match network_port_upevents [true or false]

ip_address_conflict Boolean Filter should match ip_address_conflict events [true or false]

ip_address_conflict_resolved Boolean Filter should match ip_address_conflict_resolved events [true orfalse]

ip_interface_degraded Boolean Filter should match ip_interface_degraded events [true or false]

ip_interface_failed Boolean Filter should match ip_interface_failed events [true or false]

ip_interface_ok Boolean Filter should match ip_interface_okevents [true or false]

Alert Actions replication

receive_failed_(unsupported _version)

Boolean Filter should match receive_failed_(unsupported_version) events [trueor false]

receive_failed_(cancelled) Boolean Filter should match receive_failed_(cancelled) events [true or false]

receive_failed_(all_others) Boolean Filter should match receive_failed_(all_others) events [true or false]

receive_failed_(out_of_space) Boolean Filter should match receive_failed_(out_of_space) events [true or false]

receive_failed_(package_not _upgraded)

Boolean Filter should match receive_failed_(package_not_upgraded) events[true or false]

receive_finished Boolean Filter should match receive_finishedevents [true or false]

receive_started Boolean Filter should match receive_startedevents [true or false]

send_failed_(unsupported_version) Boolean Filter should match send_failed_(unsupported_version) events [trueor false]

send_failed_(cancelled) Boolean Filter should match send_failed_(cancelled) events [true or false]

send_failed_(all_others) Boolean Filter should match send_failed_(all_others) events [true or false]

Alert Actions



send_failed_(connectivity) Boolean Filter should match send_failed_(connectivity) events [true or false]

send_failed_(out_of_space) Boolean Filter should match send_failed_(out_of_space) events [true or false]

send_failed_(remote _verification) Boolean Filter should match send_failed_(remote_verification) events [trueor false]

send_finished Boolean Filter should match send_finishedevents [true or false]

send_skipped_(already_running) Boolean Filter should match send_skipped_(already_running) events [true orfalse]

send_started Boolean Filter should match send_startedevents [true or false]

Alert Actions replication_source

send_failed_(unsupported_version) Boolean Filter should match send_failed_(unsupported_version) events [trueor false]

send_failed_(cancelled) Boolean Filter should match send_failed_(cancelled) events [true or false]

send_failed_(all_others) Boolean Filter should match send_failed_(all_others) events [true or false]

send_failed_(connectivity) Boolean Filter should match send_failed_(connectivity) events [true or false]

send_failed_(out_of_space) Boolean Filter should match send_failed_(out_of_space) events [true or false]

send_failed_(remote_verification) Boolean Filter should match send_failed_(remote_verification) events [trueor false]

send_finished Boolean Filter should match send_finishedevents [true or false]

send_skipped_(already_running) Boolean Filter should match send_skipped_(already_running) events [true orfalse]

send_started Boolean Filter should match send_startedevents [true or false]

Alert Actions replication_target

receive_failed_(unsupported_verrsion)

Boolean Filter should match receive_failed_(unsupported_version) events [trueor false]

Alert Actions



receive_failed_(cancelled) Boolean Filter should match receive_failed_(cancelled) events [true or false]

receive_failed _(all_others) Boolean Filter should match receive_failed_(all_others) events [true or false]

receive_failed _(out_of_space) Boolean Filter should match receive_failed_(out_of_space) events [true or false]

receive_failed_(package_not_upgraded)

Boolean Filter should match receive_failed_(package_not_upgraded) events[true or false]

receive_finished Boolean Filter should match receive_finishedevents [true or false]

receive_started Boolean Filter should match receive_startedevents [true or false]

Alert Actions restore

restore_finished Boolean Filter should match restore_finishedevents [true or false]

restore_started Boolean Filter should match restore_startedevents [true or false]

Alert Actions scrk

support_bundle_build_failed Boolean Filter should match support_bundle_build_failed events [true or false]

support_bundle_sent Boolean Filter should match support_bundle_sent events [true or false]

support_bundle _upload_failed Boolean Filter should match support_bundle_upload_failed events [true or false]

an_update_is_available_on_my_oracle_support.

Boolean Filter should match an_update_is_available_on_my_oracle_support.events [true or false]

no_updates_available. Boolean Filter should match no_updates_available. events [true or false]

the_appliance_failed_to_verify _if_an_update_i s_available.

Boolean Filter should match the_appliance_failed_to_verify_if_an_u pdate_is_available. events [true or false]

Alert Actions shadow

shadow_migration_complete Boolean Filter should match shadow_migration_complete events [true orfalse]

Alert Actions smf

Alert Actions



service_failures Boolean Filter should match service_failuresevents [true or false]

Alert Actions thresholds

thresholdid Default UUID of watch whose alerts shouldmatch

Alert Actions zfs_pool

resilver_finished Boolean Filter should match resilver_finishedevents [true or false]

resilver_started Boolean Filter should match resilver_startedevents [true or false]

scrub_finished Boolean Filter should match scrub_finishedevents [true or false]

scrub_started Boolean Filter should match scrub_startedevents [true or false]

hot_spare_activated Boolean Filter should match hot_spare_activated events [true or false]

List Alert Actions

The list alert actions command lists all of the alert actions. To get data for a single resource,send an HTTP GET request to the href property of the given alert actions resource.

Example Request to Get Alert Actions:

GET /api/alert/v1/actions HTTP/1.1


Host: zfs-storage.example.com:215


Example Response:

HTTP/1.1 200 OK



Content-Length: 1395

{

"actions": [

{

"action": "actions-000",

"category": "smf",

"href": "/api/alert/v1/actions/actions-000",

"service_failures": true

},

Alert Actions


{


"category": "scrk",


"action-000": {

"handler": "snmp_trap",

"href": "/api/alert/v1/alerts/actions/actions-001

/action-000"

},

"action-001": {

"address": "[email protected]",

"handler": "email",

"href": "/api/alert/v1/actions/actions-001

/action-001",

"subject": "Phone Home Alert"

},

"support_bundle_build_failed": true,

"support_bundle_sent": true,

"support_bundle_upload_failed": true

},

{


"category": "thresholds",


"action-000": {


"handler": "email",


/action-000",

"subject": "CPU Busy Alert"

},

"thresholdid": "b182ca05-53d3-6604-b874-ec353335704d"

}

]

}

Get Alert Action

This command is similar to List Alert Action but it returns only the specified alert action.

Example Request:

GET /api/alert/v1/actions/actions-002 HTTP/1.1

Example Response:

HTTP/1.1 200 OK



Content-Length: 331

{

"action": {

"category": "thresholds",

Alert Actions



"action-000": {


"handler": "email",

"href": "/api/alert/v1/alerts/actions/actions-002

/action-000",

"subject": "CPU Busy"

},

"thresholdid": "b182ca05-53d3-6604-b874-ec353335704d"

}

}

Create Alert Action

When you create an alert action POST request containing a JSON object the action propertiesmust be sent to /api/alert/v1/alerts/actions. The category property must be set to select the typeof action to create. See the CLI documentation for all of the available category values on agiven system.

Category values typically include:

"ad", "all", "appliance_software", "backup", "cluster", "custom",

"hardware", "hardware_faults", "ndmp", "network", "replication",

"replication_source", "replication_target", "restore", "scrk", "shadow",

"smf", "thresholds" or "zfs_pool"

Example Request:

POST /api/alert/v1/actions HTTP/1.1


X-Auth-Session: uerqghq84vbdv


Content-Length: 30

{"category": "hardware_faults"}

Example Response:




Content-Length: 118

Location: /api/alert/v1/actions/actions-006

{

"action": {


"category": "hardware_faults",

"all_hardware_faults": true

}

}

Alert Actions


Modify Alert Action

Some of the properties returned by the list command can be modified by sending an HTTPPUT request.

Example Request:

PUT /api/alert/v1/actions/actions-001 HTTP/1.1




Content-Length: 30

{"support_bundle_sent": false}

Example Response:




Content-Length: 195

{

"action": {


"category": "scrk",

"support_bundle_build_failed": true,

"support_bundle_sent": false,

"support_bundle_upload_failed": true

}

}

Delete Alert Action

Sending an HTTP DELETE request to any alert actions href or action href deletes the specifiedresource. A successful delete response is HTTP Status 204 (No Content).

Example Request:

DELETE /api/alert/v1/actions/actions-003 HTTP/1.1



Example Response:



Alert Action Items


Alert Action Items

Individual action items are added to each alert actions list.

Create Alert Item

This adds an alert action to an existing alert actions group.

Example Request:

POST /api/alert/v1/actions/actions-001 HTTP/1.1




Content-Length: 68

{"address": "[email protected]", "handler": "email", "subject":"CPU Busy"}

Example Response:




Content-Length: 177

Location: /api/alert/v1/actions/actions-001/action-001

{

"action": {


/action-001",

"handler": "email",



}

}

Modify Alert Action

This modifies an existing alert action.

Example Request:

PUT /api/alert/v1/actions/actions-001/action-000 HTTP/1.1




Content-Length: 28

{"address": "[email protected]"}

Alert Action Items


Example Response:




Content-Length: 176

X-Zfssa-Version: jkremer/[email protected],1-0

{

"action": {


/action-000",

"handler": "email",



}

}

Delete Alert Action Item

For a given alert action, a single action can be deleted. To delete an action, you send a DELETErequest to the action href property.

Example Request to Delete an Action:

DELETE /api/alert/v1/actions/actions-001/action-000 HTTP/1.1




Chapter4 Analytics Services 45

4C H A P T E R 4Analytics Services

Analytics is a facility for graphing a variety of statistics in real-time and recording data for laterretrieval. It provides for long-term monitoring and short-term analysis. Analytics makes useof DTrace to dynamically create custom statistics that allow different layers of the operatingsystem stack be analyzed in detail.

Analytics Services Available

The following Analytics services are available at http://zfssa.example.com/api/analytics/v1.0/

Request Path /analytics/v1 Description

GET List analytics service information

POST /worksheets Create a new analytics dataset

GET /worksheets/ Get the specified analytics datasetproperties

GET /worksheets List all analytics dataset objects

PUT /worksheets/ Modify the specified analyticsdataset object

DELETE /worksheets/ Destroy the specified worksheetobject

PUT /worksheets//suspend Suspend all worksheet datasets

PUT /worksheets//resume Resume all worksheet datasets

POST /worksheets/ /datasets Create a new worksheet dataset

GET /worksheets/ /datasets/

Get the specified worksheet datasetproperties

GET /worksheets/ /datasets List all worksheet dataset objects

PUT /worksheets/ /datasets/

Modify the specified worksheetdataset object

Settings


Request Path /analytics/v1 Description

DELETE /worksheets/ /datasets/

Destroy the specified dataset object

POST /datasets Create a new analytics dataset

GET /datasets/ Get the specified analytics datasetproperties

GET /datasets List all analytics dataset objects

PUT /datasets/ Modify the specified analyticsdataset object

DELETE /datasets/ Destroy the specified dataset object

PUT /datasets Suspend or resume all datasets

PUT /datasets//data Save this dataset (if unsaved)

DELETE /datasets//data Remove data at the given[granularity] from this dataset

GET /settings List analytics settings

PUT /settings Modify analytics settings

SettingsThe following properties let you collect all analytic data or set the number of hours of data toretain.

Name Description

retain_second_data Retention interval in hours for per-second data

retain_minute_data Retention interval in hours for per-minute data

retain_hour_data Retention interval in hours for per-hour data

Get SettingsGets the current values of analytics setting properties.

Example Request:

GET /api/analytics/v1/settings HTTP/1.1

Authorization: Basic ab6rt4psMWE=

Host: example.zfssa.com:215

Worksheets

Chapter4 Analytics Services 47


Example Results:

HTTP/1.1 200 OK


Content-Length: 131

X-Zfssa-Analytics-Api: 1.0

{

"settings": {

"href": "/api/analytics/v1/settings",

"retain_hour_data": 600,

"retain_minute_data": 400,

"retain_second_data": 200

}

}

Modify SettingsThe modify settings command is used to modify analytics settings such as data retention values.

Example Request:

PUT /api/analytics/v1/settings HTTP/1.1




Content-Length: 60

{"retain_hour_data":600, "retain_minute_data":400, "retain_second_data":200}

Example Results:



Content-Length: 101


{

"settings": {

"href": "/api/analytics/v1/settings",

"retain_hour_data": 600,

"retain_minute_data": 400,

"retain_second_data": 200

}

}

WorksheetsA worksheet is the BUI screen on which statistics are graphed. Multiple statistics can be plottedat the same time, and worksheets may be assigned a title and saved for future viewing. The

Worksheets


act of saving a worksheet automatically executes the archive action on all open statistics -meaning whatever statistics were open, continue to be read and archived forever. The worksheetcommands can be used to manage the worksheets available from the BUI.

Name Description

ctime Time and date when this worksheet was created

mtime Time and date when this worksheet was last modified

name Name of this worksheet

owner Owner of this worksheet

uuid Universal unique identifier for this worksheet

List Worksheets

Lists all currently configured analytics worksheets.

Example Request:

GET /api/analytics/v1/worksheets HTTP/1.1




Example Response:

HTTP/1.1 200 OK


Content-Length: 237


{

"worksheets": [{

"href": "/api/analytics/v1/worksheets/ab59bcbc...",

"uuid": "ab59bcbc-080a-cf1a-98c9-9f485bc3a43d"

}, {

"href": "/api/analytics/v1/worksheets/bb3ee729...",

"uuid": "bb3ee729-080a-cf1a-98c9-9f485bc3a43d"

}]

}

Get Analytics Worksheet

Gets a single analytics worksheet.

Example Request:

z file systems

Documents

oracle programs

integrated software

oracle corporation

sparc trademarks

andor documentation

license agreement

general use

safe use