HPE Serviceguard REST API Reference Guide

Transcription

1 HPE Serviceguard REST API Reference Guide Published: June 2017

2 Table of Contents: 1. Introduction 2. Configuring and using Serviceguard Rest API 3. Accessing the SG REST API Protocol and message format URI format Supported HTTP methods Client HTTP headers 4. Querying information 4.1 Querying information from subnet 4.2 Querying information from non-clustered nodes 4.3 Querying storage information from a cluster 4.4 Querying information from a non-site cluster List all nodes in the cluster List the details of a particular node in the non-site aware cluster Querying all Network interfaces of a specific node in a cluster Querying the details of Network interface of a specific node in a cluster 4.5 Querying information from a site-aware cluster Querying sites in the cluster Querying a specific site in the cluster Query to List all nodes in a particular site Querying to list a particular node on a site in the cluster Querying all network interfaces of site-aware cluster node Querying the details of the network interface of site-aware cluster node 4.6 Querying cluster information (common APIs for both non-site and site-aware clusters) Querying subnets in a cluster Querying all clusters on a subnet Querying a cluster Querying all the software components installed Querying installed Serviceguard software components 4.7 Querying information on a virtual cluster List all the VMFS datastores on a list of nodes List the available Virtual Machine disk (VMDK) details of a particular datastore 4.8 Querying information of package Querying all packages within a cluster

3 4.8.2 Querying a particular package Querying the toolkit associated with the package 5. Working with Clusters 5.1 Creating a cluster 5.2 Modifying a cluster 5.3 Cluster Administration 5.4 Node Administration 5.5 Deleting a cluster 5.6 Working with Sites in a cluster 5.7 Working with virtual clusters Flowchart 6. Working with Packages 6.1 Request payload parameters to create or modify packages Basic parameters Network parameters Service parameters Storage parameters Volume group and Disk group parameters File system parameters VMFS parameters Storage Replication parameters Metrocluster 3PAR Replication parameters XDC HOST Based Replication parameters Generic Resource parameters Script parameters Toolkit Parameters Oracle toolkit NFS Toolkit package Dependency parameters Package weights parameters Access control Policy (ACP) parameters Alert notification parameters Package environment variables parameters Site Controller Parameters 6.2 Creating a Package 6.3 Modifying a Package 6.4 Package administration

4 6.5 Deleting a package Flowchart 7. Working with Application workloads 7.1 Deploy workload To deploy a workload of type Oracle Single Instance DB To deploy a workload of type Oracle Single Instance DB using ASM To deploy a workload of type Oracle Single Instance DB using Data Guard To deploy a workload of type Oracle Single Instance DB using ASM and Data Guard. 7.2 Querying workload information Querying all workloads within a cluster Querying the details of a specific workload Querying the map of the workload Flowchart 8. One-time operations 8.1 Cluster or Package verification Cluster Verification Package Verification 8.2 Working with VMware Migrate (vmotion) of cluster node 8.3 Disaster Recovery Rehearsal (DRR) Starting a Rehearsal Querying all rehearsals Querying a particular rehearsal Deleting a Rehearsal 8.4 Configuration Modifying or Updating configurations Querying the configuration details 9. Miscellaneous 9.1 Alerts 9.2 Logging 9.3 Licensing 10. Error codes HTTP Status and error codes

5 Copyright 2006, 2017 Hewlett Packard Enterprise Development LP. Confidential computer software. Valid license from Hewlett Packard Enterprise required for possession, use, or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor s standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein must be construed as constituting an additional warranty. Hewlett Packard Enterprise shall not be liable for technical or editorial errors or omissions contained herein. Links to third-party websites take you outside the HP website. HP has no control over and is not responsible for information outside HP.com. HP Serviceguard is a registered trademark of Hewlett Packard Enterprise, and is protected by copyright. NIS is a trademark of Sun Microsystems, Inc. Oracle is a registered trademark of Oracle Corporation. UNIX is a registered trademark of The Open Group. Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat Software, Inc. SUSE is a registered trademark of SUSE AG, a Novell Business. VMware, and vcenter Server are registered trademarks or trademarks of VMware, Inc. in the United States and/or other jurisdictions.

6 1 Introduction A REST API is a hierarchical resource structure that you can use on standard HTTP protocol. Use Serviceguard REST API (SGRAPI) as an alternative method to perform cluster operations apart from Serviceguard CLI and Serviceguard Manager. Use SGRAPI to automate cluster tasks on Serviceguard for Linux in your data center. Serviceguard consists of an SGRAPI server that runs on all the nodes in a cluster. When you provide the required API operations and inputs as defined in this guide, the SGRAPI server consumes the request and servises it. The SGRAPI server accepts the request and communicates with the other SGRAPI server running on other nodes in the cluster to successfully service the request. The result of the request is conveyed in the form of output and relevant error codes as required. Use HTTPS protocol to interact with the SGRAPI server. For more information on the supported HTTP methods, see chapter 3 Accessing the SG REST API. 2 Configuring and using Serviceguard Rest API Serviceguard REST APIs provide stateless and a scalable approach to easily integrate with Serviceguard and automate tasks in a Serviceguard cluster. Pre-requisites to use Serviceguard Rest API (SGRAPI): Serviceguard for Linux Base, Advanced, or Enterprise Edition must be installed. Ports 5511, 5522, and 5301 must be free to use SGRAPI. SGRAPI is compatible with Oracle Java (RHEL), Open Java version (RHEL, SUSE), and IBM Java (SUSE). For a complete list of pre-requisites and installation steps see, the latest version of the HPE Serviceguard for Linux Base edition Release Notes at Serviceguard-for-Linux-docs. For more information on supported software versions, refer to Serviceguard for Linux Certification Matrix available at Serviceguard-for-Linux-docs. 3 Accessing the SG REST API Protocol and message format You can use REST clients to communicate with the SG REST API server through HTTPS protocol and data structures represented with JSON. URI format

7 Perform all operations of the SG REST API using an HTTP method such as GET, POST, PUT, or DELETE and a URI. For example, the following URI queries the cluster named testcluster using the GET HTTP method. Supported HTTP methods The SG REST API (SGRAPI) supports the following HTTP methods: GET - Retrieves information identified by the request URI. POST - Requests that an object described by the body of the request, called the request pa yload, be created in the collection identified by the URI, or performs a customized action described in the body of the request. PUT - Requests that an entity identified by the request URI be modified. DELETE - Requests that the server delete the resource identified by the request URI. Client HTTP headers HTTP headers are included in a HTTP request made by a client to the API server. HTTP headers Table lists the required and optional HTTP headers. Optional headers, when present, must be one of the values listed in the values column. For example: Accept: application/json; charset=utf-8 HTTP headers Table The following table describes the supported client HTTP headers for requests Header Values Mandatory Description Content- Type application/json Yes, for requests with a message body Specifies the format being sent in the request body or payload. Note: SGRAPI server accepts only JSON format in the request payload. Accept application/json. Yes Acceptable client response formats. Note: SGRAPI server responds with only JSON format in the response output.

8 Header Values Mandatory Description User- Principal Refer User-Principal Header attributes Table Yes Authenticates the user to access the node One of the following No The response language the client can accept * en en* Acceptlanguage Content- Length Number of bytes No The length of the content in bytes. User-Principal Header attributes Table This table describes the attributes and values involved in User-Principal Header as given in HTTP headers Table. Attribute username password Acceptable value For example: user1 For example: XXXX Description The user name to access the node. This value is root for type local and non-local. But a non-root username must be specified for type replicated. The password to access the node. type local Specifies if the node is local. The operation is being performed on the node from which you are accessing the REST API. nodename non_local replicated For example: NODE2 Specifies if the impacted node is non-local. The operation is being performed on a different node and not from the node which you are accessing the REST API. The operation is being performed using a non-root username. This non-root username must be present (replicated - having same username and password) on the Serviceguard nodes in the cluster or on Serviceguard nodes which are not yet part of a cluster (unused nodes), where the REST API will perform the operation. If the REST API is being accessed from NODE1 in testcluster1, but the operation is to be performed on NODE11 in testcluster11, then testcluster11 is termed as a remote cluster. The replicated type must be specified on most of the HTTP GET calls for viewing information of remote clusters or nodes, unless otherwise specified. This needs to be specified if the type is non_local. This is the node from where the REST operation is being performed. Example:

9 Example 1: The following URI queries the cluster named testcluster fot the node NODE1 using the GET HTTP method. The header specified for the above request contains type as local: Accept: application/json User-Principal : username : user1, password : xxxxx, type : local Example 2: The following URI queries the cluster named testcluster for the node NODE2 using the GET HTTP method. The header specified for the above request contains type as non_local: Accept: application/json User-Principal : username : user1, password : xxxxx, type : non_local, nodename : NODE2 Example 3: A GET HTTP method on the following URI provided different responses based on the type specified in the header. If the header specified for the above request contains type as local: Accept: application/json User-Principal : username : root, password : xxxxx, type : local, nodename : The response contains only the cluster which NODE1 is part of. If the NODE is not part of any cluster then the response has no cluster name listed. If the header specified for the above request contains type as replicated: Accept: application/json User-Principal : username : sgmgr, password : xxxxx, type : replicated, nodename : The response contains all the clusters in the subnet. 4 Querying information This chapter discusses the APIs that query information regarding nodes, network, and storage information within and outside Serviceguard clusters. 4.1 Querying information from subnet This section describes the various queries that you can use to list all the subnets on which a particular node is configured, or to query a subnet to list all the nodes configured on it. These and other queries are described in the following APIs.

10 4.1.1 Query all subnets To query all the subnets, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "subnets": [ "id": " ", "subneturi": "/ha/ " ] Failure Scenario: During the query of all subnets, if an error occurs, the system returns a common or a generic error code listed in error code table Query all the resources of a specific subnet: To query all the resources like clusters, unused nodes within a subnet, use the HTTP GET method with the following URI: An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response:

11 "clusters": [ "name": "testcluster", "uri": "/ha/ /clusters/testcluster", "name": "testcluster1", "uri": "/ha/ /clusters/testcluster1", "name": "testcluster2", "uri": "/ha/ /clusters/testcluster2", "name": "testcluster3", "uri": "/ha/ /clusters/testcluster3", "name": "testcluster4", "uri": "/ha/ /clusters/testcluster4", "name": "testcluster5", "uri": "/ha/ /clusters/testcluster5", "quorum_server_name": "quorum_server", "name": "testcluster6", "uri": "/ha/ /clusters/testcluster6", "name": "testcluster7", "uri": "/ha/ /clusters/testcluster7"

12 "unused_nodes": [ "name": "UnusedNode1", "uri": "/ha/ /unusednodes/unusednode1", "status": null, "name": "UnusedNode2", "uri": "/ha/ /unusednodes/unusednode2", "status": null, "name": "UnusedNode3", "uri": "/ha/ /unusednodes/unusednode3", "status": null, "name": "UnusedNode4", "uri": "/ha/ /unusednodes/unusednode4", "status": null, "name": "UnusedNode5", "uri": "/ha/ /unusednodes/unusednode5", "status": null, "name": "UnusedNode6", "uri": "/ha/ /unusednodes/unusednode6", "status": null ] Failure Scenario:

13 During the query of all the resources of a subnet, if an error occurs, the system returns a common or a generic error code listed in error code table Query the license information of nodes in a subnet To query the node license detail of nodes within a subnet, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: [ "name": "NODE1", "uri": "/ha/ /clusters/testcluster/nodes/node1", "clustername": null, "license": "license_type": "Instant_ON", "license_validity_in_days": "90", "license_invalid_reason": null, "license_count": null, "name": " NODE2", "uri": "/ha/ /clusters/testcluster/nodes/node2", "clustername": null, "license": "license_type": "Instant_ON", "license_validity_in_days": "89", "license_invalid_reason": null, "license_count": null

14 , "sg_version": "A ", "sg_manager_build_version": "B ", "name": "NODE3", "uri": "/ha/ /clusters/testcluster2/nodes/node3", "clustername": null, "name": "NODE4", "uri": "/ha/ /clusters/testcluster2/nodes/node4", "clustername": null, "license": "license_type": "Instant_ON", "license_validity_in_days": "62", "license_invalid_reason": null, "license_count": null, "sg_version": "A ", "sg_manager_build_version": "B ", "name": "NODE5", "uri": "/ha/ /clusters/testcluster2/nodes/node5", "clustername": null, "name": "NODE6", "uri": "/ha/ /clusters/testcluster2/nodes/node6", "clustername": null, "name": "UnusedNode1", "uri": "/ha/ /unusednodes/unusednode1", "clustername": null, "license":

15 "license_type": "Instant_ON", "license_validity_in_days": "28", "license_invalid_reason": null, "license_count": null, "sg_version": "A ", "sg_manager_build_version": "B ", "name": "UnusedNode2", "uri": "/ha/ /unusednodes/unusednode2", "clustername": null, "license": "license_type": "Invalid", "license_validity_in_days": null, "license_invalid_reason": "Expired", "license_count": null, "sg_version": "A ", "sg_manager_build_version": "B ", "name": "UnusedNode3", "uri": "/ha/ /unusednodes/unusednode3", "clustername": null, "license": "license_type": "Base", "license_validity_in_days": "Indefinite", "license_invalid_reason": null, "license_count": "1", "sg_version": "A ", "sg_manager_build_version": "B ", "name": "UnusedNode4", "uri": "/ha/ /unusednodes/unusednode4",

16 "clustername": null, "license": "license_type": "Invalid", "license_validity_in_days": null, "license_invalid_reason": "Expired", "license_count": null, "sg_version": "A ", "sg_manager_build_version": "B ", "name": "UnusedNode5", "uri": "/ha/ /unusednodes/unusednode5", "clustername": null, "license": "license_type": "Invalid", "license_validity_in_days": null, "license_invalid_reason": "Expired", "license_count": null, "sg_version": "A ", "sg_manager_build_version": "B " ] Failure Scenario: During the query of the license information of nodes in a subnet, if an error occurs, the system returns a common or generic error code listed in error code table List the nodes in a subnet To list all nodes in the subnet are listed whether the node is part of a Serviceguard cluster or not, use the HTTP GET method with the following URI:

17 An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "totalcount": null, "nodes": [ "name": "NODE1", "uri": "/ha/ /clusters/testcluster/nodes/node1", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, "name": "NODE2",

18 "uri": "/ha/ /clusters/testcluster/nodes/node2", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, "name": "NODE3", "uri": "/ha/ /clusters/testcluster/nodes/node3", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null,

19 "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, "name": "NODE4", "uri": "/ha/ /clusters/testcluster/nodes/node4", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false,

20 "name": "UnusedNode1", "uri": "/ha/ /unusednodes/unusednode1", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, "name": "UnusedNode2", "uri": "/ha/ /unusednodes/unusednode2", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null,

21 "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false ] Failure Scenario: During the query to list the nodes in a subnet, if an error occurs, the system returns a common or a generic error code listed in error code table Query network information of a list of nodes on the subnet To know if the network interface on a node can be used as a heartbeat in the Serviceguard Cluster, use the HTTP POST method with the following URI: An example URI: Table: Subnet Query payload members table Member JSON Type Mandatory Accepted Value Description action string yes cluster_template Specifies the action to be performed based on the parameters sent. parameters object yes This is a list of parameters that are specified to denote the exact action to be performed. See, Subnet Query parameters submembers table for more information. Table: Subnet Query parameters sub-members table

22 Member JSON Type Mandatory Accepted Value Description nodes Array of Strings yes This is a list of nodes where the query is to be performed. scope Array of string yes network Specifies that the network information is to be queried on the nodes mentioned in the payload. Use this option if all the nodes specified belong to the same subnet. cross_subnet_network It specifies the network information is to be queried on the nodes mentioned in the payload. This option can be used if a subset of the nodes specified belong to a different subnet. A cross-subnet configuration allows nodes from different subnets to be part of the same cluster in which case the cluster heartbeat spans subnets. Example Request Payload "action":"cluster_template", "parameters": "nodes": ["NODE1", "NODE2" "scope":["network"] Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "wwnslist": [ "heartbeat_networks": [ "interfaces": [ "name": "eth5", "ipv6subnet": null, "heartbeat": true, "host": "NODE1", "ip_address": " ",

23 "netmask": " ", "IP_ADDRESS": [], "name": "eth1", "ipv6subnet": null, "heartbeat": true, "host": "NODE2", "ip_address": " ", "netmask": " ", "IP_ADDRESS": [] "subnet_id": " ", "route_id": "1", "ip_monitor": "off", "polling_targets": [] "template": [] Failure Scenario: During the query of network information of a list of nodes on the subnet, if an error occurs, the system returns a common or a generic error code listed in error code table. "message": "Unable to fetch template data for cluster. For more information refer System logs.", "id": "3076", "additional_message": "Warning: Unable to determine local domain name for NODE3\nLooking for other clusters... Gathering storage information\ngathering network information\nbeginning network probing\ncompleted network probing\nunable to open cluster.ascii for writing: Permission denied\nunable to write cluster data to

24 cluster.ascii.\ndone\nname=testcluster\nid= \nstatus=?\nstate=s table\nmember_timeout= \nio_timeout_extension=0\nconfigured_io_ti meout_extension=0\nauto_start_timeout= \nnetwork_polling_interva l= \nhostname_address_family=ipv4\nmax_reformation_duration=15\nma x_configured_packages=300\ncluster_pr_mode=(null)\nnode:node3 name=node3 \nnode:node3 id=1\nnode:node3 node_pr_key= \nnode:node3 virt_tech =VMWare\nnode:NODE3 sg_version=a \nnode:node3 os_release=linux el6.x86_64\nnode:NODE3 os_distribution=redhat\nnode:node3 os_ distribution_release=redhat-release-server-6server elred Hat Enterprise Linux Server release 6.7 (Santiago)\nnode:NODE3 os_distribution_description=red Hat Enterprise Linux Server release 6.7 (Santiago)\nnode:NODE3 cpu_architecture=x86_64\nnode:node3 boot_timestam p= \nnode:node3 interface:eth5 name=eth5\nnode:node3 interface: eth5 id=1\nnode:node3 interface:eth5 mac_address=00:50:56:82:0a:ca\nnode :NODE3 interface:eth5 ppa=0\nnode:node3 interface:eth5 bridged_net=1\nno de:node3 interface:eth5 mac_type=ethernet\nnode:node3 interface:eth5 typ e=primary\nnode:node3 interface:eth5 ip_address: name= \nnode:NODE3 interface:eth5 ip_address: netmask= \nnode:NODE3 interface:eth5 ip_address: subnet= \nnode:node3 interface:eth5 ip_address: route_id=1\nnode:node 3 interface:eth5 ip_address: heartbeat=true\nnode:node3 subne t: name= \nnode:node3 subnet: route_id=1\nn ode:node3 subnet: ip_monitor=off\nnode:node4 name=node4\nnode: NODE4 id=2\nnode:node4 node_pr_key= \nnode:node4 virt_tech=vmware \nnode:node4 sg_version=a \nnode:node4 os_release=linux el6.x86_64\nnode:NODE4 os_distribution=redhat\nnode:node4 os_ distribution_release=redhat-release-server-6server elred Hat Enterprise Linux Server release 6.7 (Santiago)\nnode:NODE4 os_distribution_description=red Hat Enterprise Linux Server release 6.7 (Santiago)\nnode:NODE4 cpu_architecture=x86_64\nnode:node4 boot_timestam p= \nnode:node4 interface:eth4 name=eth4\nnode:node4 interface: eth4 id=1\nnode:node4 interface:eth4 mac_address=00:50:56:82:12:03\nnode :NODE4 interface:eth4 ppa=0\nnode:node4 interface:eth4 bridged_net=2\nno de:node4 interface:eth4 mac_type=ethernet\nnode:node4 interface:eth4 typ e=primary\nnode:node4 interface:eth4 ip_address: name= \nnode:NODE4 interface:eth4 ip_address: netmask= \nnode:NODE4 interface:eth4 ip_address: subnet=

25 \nnode:node4 interface:eth4 ip_address: route_id=1\nnode:node 4 interface:eth4 ip_address: heartbeat=true\nnode:node4 subne t: name= \nnode:node4 subnet: route_id=1\nn ode:node4 subnet: ip_monitor=off\n\nwriting cluster data to cluster.ascii.\n\n" 4.2 Querying information from non-clustered nodes A non-clustered node or an unused node is a node that is not part of any cluster. Use the following APIs to determine information regarding the unused nodes. Querying non-clustered node information The following API quiries the node specific information of unused nodes Query all unused nodes To query all the unused nodes in a particular subnet, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "totalcount": null, "unused_nodes": [ "name": "UnusedNode1", "uri": "/ha/ /unusednodes/unusednode1",

26 "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, "name": "UnusedNode2", "uri": "/ha/ /unusednodes/unusednode2", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [

27 "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, In case, there are no unused nodes, an HTTP code 200 OK with the following response is seen: "totalcount": null, "unused_nodes": [] Failure Scenario: During the query of all unused nodes, if an error occurs, the system returns a common or a generic error code listed in error code table. Filtered query of all Unused Nodes: Use this option to query all unused nodes and view only those that match the filter criteria. The URI will filter out all the information and respond with only those fields specified in the API. The following URI signifies that the query will filter out and respond with the nodes in the cluster along with the information specified in the fields portion of the URI: eq name,uri,operating_system_flavor,node_type,ip_address,license,sg_version,sg_manager_build_version A sample response is as shown below: "totalcount": null,

28 "unused_nodes": [ "name": "UnusedNode1", "uri": "/ha/ /unusednodes/unusednode1", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": " ", "localnode": false, "operating_system_flavor": "SUSE Server 11", "sg_version": null, "configuredpackages": [ "license": "license_type": "Instant_ON", "license_validity_in_days": "27", "license_invalid_reason": null, "license_count": null, "vmotion": false, "NetworkInterface": [ "Subnet": [ "configuredcapacities": [], "name": "UnusedNode2", "uri": "/ha/ /unusednodes/unusednode2", "id": null,

29 "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": " ", "localnode": false, "operating_system_flavor": "SUSE Server 12", "sg_version": null, "configuredpackages": [ "license": "license_type": "Invalid", "license_validity_in_days": null, "license_invalid_reason": "Expired", "license_count": null, "vmotion": false, "NetworkInterface": [ "Subnet": [ "configuredcapacities": [] ] The following fields or a subset of them can be used in the URI query Query field field field options All or a subset of the below fields can be used name

30 Query field field options uri operating_system_flavor node_type ip_address license sg_version sg_manager_build_version Following are the query filter options: Query filter option license_type permissible values One of the following values can be used instant_on base advanced enterprise Example URI: The following URI signifies that the query will filter out and respond with name and URI fields of the unused node: name,uri The following URI signifies that the query will filter out and respond with only name field of the unused node: name The following URI signifies that the query will filter out and respond with only mentioned field of the unused node which has the instant_on evaluation license: fields= name,uri,sg_version,ip_address,license,sg_manager_build_version and query=license_type eq instant_on Querying a specific unused node To query a specific unused node, use the HTTP GET method with the following URI: Request Body: Not Required

31 An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "name": "UnusedNode1", "subnets": [ "storages": "raw_disks": "uri": "/ha/ /unusednodes/unusednode1/storages/rawdisks", "uri": "/ha/ /unusednodes/unusednode1", "localnode": false, "operating_system": "Linux el6.x86_64", "operating_system_flavor": "RHEL Server 6.8", "cpu_architecture": "x86_64", "sg_version": "A ", "interfaces": [ "name": "eth1", "uri": "/ha/ /unusednodes/unusednode1/interfaces/eth1" "node_type": "VMWare", "sg_manager_build_version": "B ", "license": "license_type": "Instant_ON", "license_validity_in_days": "29", "license_invalid_reason": null, "license_count": null

32 Failure Scenario: During the query of a specified unused node, if an error occurs, the system returns one of the common errors 2004, 2005, 2006, 2024 or a generic error code listed in error code table. Example response: "taskstatus": "error", "resource": null, "errorcode": "2024", "errortitle": "Serviceguard REST stack is down on remote node. For more information ref er Serviceguard manager logs.", "numoferror": 1, "numofwarning": 0, "errors": [ "messages": [ "Serviceguard REST stack is down on remote node. For more information refer Servi ceguard manager logs." ] "httpresponsecode": Querying storage information from a cluster The following set of APIs query storage specific information from a Serviceguard cluster Querying all disk groups in a cluster To query the disk groups in the cluster, use the HTTP GET method with the following URI: Request Body: Not Required Only a root user can list all disk groups in a cluster. This means that the header user-principal must specify a root user only. Refer HTTP headers Table for more information.

33 An example URI: Here, testcluster is the name of the cluster. Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "volumegroups": [ "subnets": [ "diskgroups": [ "dg_dd0" "fs_type": [] In case of there are no disk groups in the specified cluster, the HTTP code 200 OK with the following response can be observed: "volumegroups": [ "subnets": [ "diskgroups": [ "fs_type": [] Failure Scenario: During the query of disk groups for a particular cluster, if an error occurs, the system returns the error code number 3091 or a generic error code listed in error code table along with the following response: "message": "Error encountered when trying to fetch disk groups information on the node. For more information refer System logs.", "id": "3091"

34 Filtered querying of diskgroups Example URI: eq node3 A successful operation returns the HTTP code 200 OK with the following response: "volumegroups": [ "subnets": [ "diskgroups": [ "dg_dd0" "fs_type": [] Querying all volume groups in a cluster To query all shared volume groups across a particular cluster specified using <cluster-name>, use the HTTP GET method with the following URI: Request Body: Not Required Only a root user can list all volume groups in a cluster. This means that the header user-principal must specify a root user only. See, HTTP headers Table for more information. An example URI: Here, we are querying all the volume groups in the Serviceguard Cluster named testcluster. Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "volumegroups": [ "vg": "vg_dd2",

35 "logicalvolumes": [], "vg": "vg_dd0", "logicalvolumes": [], "vg": "vg_dd1", "logicalvolumes": [] "subnets": [ "diskgroups": [ "fs_type": [] Failure Scenario: During the query of volume groups for a particular cluster, if an error occurs, the system returns the error code number 3032 or a generic error code listed in error code table along with the following response: "message": "Unable to Fetch package template data. For more information refer Servicegua rd manager logs.", "id": "3032" Filtered querying of shared Volume groups in a cluster The following URI signifies that the query will filter out and respond with only the volume groups belonging to the nodes NODE4 and NODE3 in the cluster: eq NODE4 AND node eq NODE3 Here the URI signifies that the query will filter out and respond with only the volume groups belonging to the node NODE4 in the cluster: eq NODE4

36 4.3.3 Querying a specific volume group in the cluster To query a particular volume group within a cluster specified using <cluster-name>, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Here, vg_dd1 is the name of the volume group. Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "volumegroups": [ "logicalvolumes": [ "/dev/vg_dd1/lvol0", "/dev/vg_dd1/lvol1", "/dev/vg_dd1/lvol2", "/dev/vg_dd1/lvol3", "/dev/vg_dd1/lvol4", "/dev/vg_dd1/lvol5", "/dev/vg_dd1/lvol6", "/dev/vg_dd1/lvol7", "/dev/vg_dd1/lvol8", "/dev/vg_dd1/lvol9" ] "subnets": [ "diskgroups": [ "fs_type": []

37 If the volume group mentioned in the URI does not exist in the cluster, then the following response is displayed: URI: Response: volumegroups : [ subnets : [ diskgroups : [ fs_type : [] Failure Scenario: During the query of volume groups for a particular cluster, if an error occurs, the system returns the error code number 3032 or a generic error code listed in error code table. "message": "Unable to Fetch package template data. For more information refer Servicegua rd manager logs.", "id": "3032" 4.4 Querying information from a non-site cluster You can use the following REST APIs only if this is a non-site cluster. A non-site cluster is a Serviceguard cluster which does not include sites or in other words, is unaware of sites. If the cluster has sites defined see, Querying information from a siteaware cluster. This section describes the following: List all nodes in the cluster List a particular node in the non-site aware cluster Query all Network interfaces of a specific node in a cluster Query the details of Network interface of a specific node in a cluster List all nodes in the cluster

38 To list all the nodes in a particular cluster specified using <cluster-name>, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Here, site-1 is the name of the site in the cluster named testcluster. Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "totalcount": null, "nodes": [ "name": "NODE2", "uri": "/ha/ /clusters/testcluster/nodes/node2", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [

39 "vmotion": false, "name": "NODE1", "uri": "/ha/ /clusters/testcluster/nodes/node1", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false ] Failure Scenario: During the query to list all nodes in the cluster, if an error occurs, the system returns a common or a generic error code listed in error code table. Query filter options for listing nodes in the cluster

40 The following URI signifies that the query will filter out and respond with the nodes in the cluster along with the information specified in the fields portion of the URI: eq 'nam e,uri,operating_system_flavor,status,cluster_name,sitename,configuredcapacities,node_type, ip_address,license,sg_version,sg_manager_build_version,localnode,esx_name' and query=stat us eq 'up' A sample response is as shown below: "totalcount": null, "nodes": [ "name": "NODE2", "uri": "/ha/ /clusters/testcluster/nodes/node2", "cluster_name": "testcluster", "id": null, "status": "up", "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "operating_system_flavor": "SUSE Server 11", "sg_version": "A ", "configuredpackages": [ "node_type": "VMWare",

41 "sg_manager_build_version": "B ", "license": "license_type": "Base", "license_validity_in_days": "83", "license_invalid_reason": null, "license_count": null, "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, "name": "NODE1", "uri": "/ha/ /clusters/testcluster/nodes/node1", "cluster_name": "testcluster", "id": null, "status": "up", "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": true, "operating_system_flavor": "SUSE Server 11", "sg_version": "A ", "configuredpackages": [ "node_type": "VMWare", "sg_manager_build_version": "B ", "license":

42 "license_type": "Base", "license_validity_in_days": "82", "license_invalid_reason": null, "license_count": null, "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false ] The following URI signifies that the query will filter out and respond only with the local node NODE1 information in the cluster if the node has an instant_on evaluation license and if the node is up in the cluster: eq 'nam e,uri,operating_system_flavor,status,cluster_name,sitename,configuredcapacities,node_type, ip_address,license,sg_version,sg_manager_build_version,localnode,esx_name' and query=stat us eq 'up' AND license_type eq 'instant_on' AND localnode eq 'true' The following fields or a subset of them can be used in the URI query Query field field field options All or a subset of the below fields can be used name status uri cluster_name sitename configuredcapacities operating_system_flavor node_type ip_address

43 Query field field options configuredpackages license sg_version sg_manager_build_version localnode esx_name Following are the query filter options: Query filter option status permissible values One of the following values can be used up down unknown license_type One of the following values can be used instant_on base advanced enterprise localnode One of the following values can be used true false List the details of a particular node in the non-site aware cluster To list the details of a node within a cluster specified using <cluster-name>, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario:

44 A successful query returns the HTTP code 200 OK with the following response: "name": "NODE2", "status": "up", "state": "running", "subnets": [ "interfaces": [ "subnet_id": " ", "route_id": "1", "ip_monitor": "off", "polling_targets": [] "ip_address": " ", "clusterlocklun": null, "uri": "/ha/ /clusters/testcluster/nodes/node1", "clustername": "testcluster", "uuid": "421B5C5D-716E-7D4D-4A00-84E18DDE92E9", "localnode": true, "operating_system": "Linux default", "operating_system_flavor": "SUSE Server 11", "cpu_architecture": "x86_64", "sg_version": "A ", "node_pr_key": "9b810001", "configuredpackages": [ "name": "pkg1", "uri": "/ha/ /clusters/testcluster/packages/pkg1", "status": "ok" "interfaces": [ "name": "eth5",

45 "uri": "/ha/ /clusters/testcluster/nodes/node1/interfaces/eth5" "configuredcapacities": [ "node_type": "VMWare", "alerts_uri": "/ha/ /clusters/testcluster/nodes/node1/alerts", "sg_manager_build_version": "B ", "license": "license_type": "Base", "license_validity_in_days": "Indefinite", "license_invalid_reason": null, "license_count": "1", "vmotion": false Failure Scenario: During the query of details of a particular node in the non-site aware cluster, if an error occurs, the system returns one of the generic error codes listed in error code table Querying all Network interfaces of a specific node in a cluster To query all network interfaces, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "interfaces": [ "name": "eth5", "uri": "/ha/ /clusters/testcluster/nodes/node1/interfaces/eth5"

46 ] If no network interfaces are configured for that particular node, the operation returns the HTTP code 200 OK with the following response: "interfaces": [] Failure Scenario: During the query of all network interfaces of a specific node in a cluster, if an error occurs, the system returns one of the common errors 2001, 2002, 2003, 2024 or a generic error code listed in error code table. Example failure response: "taskstatus": "error", "resource": null, "errorcode": "2003", "errortitle": "Remote node connection error. For more information refer Serviceguard man ager logs.", "numoferror": 1, "numofwarning": 0, "errors": [ "messages": [ "Remote node connection error. For more information refer Serviceguard manager log s." ] "httpresponsecode": 0

47 4.4.4 Querying the details of Network interface of a specific node in a cluster To query the details of a particular network interface of a specific node in a cluster, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "name": "interface1", "ipv6subnet": null, "heartbeat": false, "host": null, "IP_ADDRESS": [ "subnet": " ", "heartbeat": true, "ipv6": false, "name": " ", "netmask": " " ] Failure Scenario: During the query of the details of Network interface of a specific node in a cluster, if an error occurs, the system returns one of the common errors 2001, 2002, 2003, 2024 or a generic error code listed in error code table. Example failure response:

48 "taskstatus": "error", "resource": null, "errorcode": "2003", "errortitle": "Remote node connection error. For more information refer Serviceguard man ager logs.", "numoferror": 1, "numofwarning": 0, "errors": [ "messages": [ "Remote node connection error. For more information refer Serviceguard manager log s." ] "httpresponsecode": Querying information from a site-aware cluster You can use the following REST APIs only if the cluster is a site-aware cluster. A site-aware cluster is a Serviceguard cluster which consists of sites which contain the cluster nodes. If the Cluster has no sites defined see, Querying information from a non-site cluster. This section describes the following: Querying sites in the cluster Querying a specific site in the cluster Querying to List all nodes in a particular site Querying to List a particular node on a site in the cluster Querying all network interfaces of site-aware cluster node Querying the details of the network interface of site-aware cluster node Querying sites in the cluster

49 To query sites within a cluster specified using <cluster-name>, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "site": [ "name": "site-2", "uri": "/ha/ /clusters/testcluster/sites/site-2", "id": "2", "nodes": [ "name": "node2", "uri": "/ha/ /clusters/testcluster/sites/site-2/nodes/node2", "status": null ], "name": "site-1", "uri": "/ha/ /clusters/testcluster/sites/site-1", "id": "1", "nodes": [ "name": "node1", "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node1", "status": null ]

50 ] Failure Scenario: If there are no sites in the Cluster, then a response of HTTP code 200 OK with the following response: "site": [] Refer the generic error code listed in error code table for more information on errors Querying a specific site in the cluster To query a particular site within a cluster specified using <cluster-name>, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Here, site-1 is the name of the site in the cluster named testcluster. Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "name": "site-1", "uri": "/ha/ /clusters/testcluster/sites/site-1", "id": "1", "nodes": [ "name": "node1", "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node1", "status": null ]

51 Failure Scenario: During the query of a specific site in the cluster, if an error occurs, the system returns a common or a generic error code listed in error code table Query to list all nodes in a particular site To list all the node in a particular site within a cluster specified using <cluster-name>, use the HTTP GET method with the following URI: Request Body: Not Required Only a root user can list all nodes in a particular site. This means that the header user-principal must specify a root user only. See HTTP headers Table for more information. An example URI: Here, site-1 is the name of the site in the cluster named testcluster. Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "totalcount": null, "nodes": [ "name": "NODE2", "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node2", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null,

52 "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, "name": "NODE1", "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node1", "id": null, "status": null, "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "sg_version": null, "configuredpackages": [ "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false

53 ] If you observe, the fields ID, status, and others are null values. This is as expected. However, you can view the required fields by using query filter options for listing nodes. This is described in Query filter options for listing nodes in a particular site in the cluster section. Failure Scenario: During the query of list of all the nodes in a particular site, if an error occurs, the system returns a common or a generic error code listed in error code table. Query filter options for listing nodes in a particular site in the cluster The following URI signifies that the query will filter out and respond with only the nodes belonging to the site SITE-1 in the cluster: elds eq 'name,uri,operating_system_flavor,status,cluster_name,sitename,configuredcapacitie s,node_type, ip_address,license,sg_version,sg_manager_build_version,localnode,esx_name' an d query=status eq 'up' A sample response is as shown below: "totalcount": null, "nodes": [ "name": "NODE2", "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node2", "cluster_name": "testcluster", "id": null, "status": "up", "state": null, "summary": null, "toolkitsuri": null, "storage": null,

54 "clusterlocklun": null, "siteid": null, "sitename": "SITE-1", "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": false, "operating_system_flavor": "SUSE Server 11", "sg_version": "A ", "configuredpackages": [ "node_type": "VMWare", "sg_manager_build_version": "B ", "license": "license_type": "Instant_ON", "license_validity_in_days": "83", "license_invalid_reason": null, "license_count": null, "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, "name": "NODE1", "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node1", "cluster_name": "testcluster", "id": null, "status": "up", "state": null, "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null,

55 "sitename": "SITE-1", "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": null, "localnode": true, "operating_system_flavor": "SUSE Server 11", "sg_version": "A ", "configuredpackages": [ "node_type": "VMWare", "sg_manager_build_version": "B ", "license": "license_type": "Instant_ON", "license_validity_in_days": "82", "license_invalid_reason": null, "license_count": null, "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false ] The following URI signifies that the query will filter out and respond only with the local node NODE1 information on the site SITE-1 in the cluster if the node has an instant_on license and if the node is up in the cluster: elds eq 'name,uri,operating_system_flavor,status,cluster_name,sitename,configuredcapacitie s,node_type, ip_address,license,sg_version,sg_manager_build_version,localnode,esx_name' an d query=status eq 'up' AND license_type eq 'instant_on' AND localnode eq 'true' The following fields or a subset of them can be used in the URI query

56 Query field fields field options All or a subset of the below fields can be used name status uri cluster_name sitename configuredcapacities operating_system_flavor node_type ip_address configuredpackages license sg_version sg_manager_build_version localnode esx_name Following are the query filter options: Query filter option status permissible values One of the following values can be used up down unknown license_type One of the following values can be used instant_on basic advanced enterprise localnode One of the following values can be used true

57 Query filter option permissible values false Querying to list a particular node on a site in the cluster To list a node in a site within a cluster specified using <cluster-name>, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Here, site-1 is the name of the site in the cluster named testcluster. Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "name": "NODE2", "status": "up", "state": "running", "subnets": [ "interfaces": [ "subnet_id": " ", "route_id": "1", "ip_monitor": "off", "polling_targets": [] "site": "SITE-1", "ip_address": " ", "clusterlocklun": null, "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node2", "clustername": "testcluster", "uuid": "421BE681-BA76-4A6C-8EDC-418CB5E37819", "localnode": false, "operating_system": "Linux default",

58 "operating_system_flavor": "SUSE Server 11", "cpu_architecture": "x86_64", "sg_version": "A ", "node_pr_key": "c ", "configuredpackages": [ "name": "pkg1", "uri": "/ha/ /clusters/testcluster/packages/pkg1", "status": "error" "interfaces": [ "name": "eth1", "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node2/interfaces/eth 1" "configuredcapacities": [ "node_type": "VMWare", "alerts_uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node2/alerts", "sg_manager_build_version": "B ", "license": "license_type": "Instant_ON", "license_validity_in_days": "83", "license_invalid_reason": null, "license_count": null, "vmotion": false Failure Scenario: During the query to list a particular node on a site in the cluster, if an error occurs, the system returns a common or a generic error code listed in error code table Querying all network interfaces of site-aware cluster node

59 To query all the network interfaces of a specific site-aware cluster node, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: Case 1 A successful operation returns the HTTP code 200 OK with the following response: "interfaces": [ "name": "eth1", "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node1/interfaces/eth 1" ] Case 2 If the network interfaces are not configured, then the operation returns the HTTP code 200 OK with the following response: "interfaces": [] Failure Scenario: During the query of all network interfaces of site-aware cluster nodes, if an error occurs, the system returns the generic error code listed in error code table Querying the details of the network interface of site-aware cluster node:

60 To query the details of the network interface of a site-aware cluster node, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "name": "eth1", "ipv6subnet": null, "heartbeat": false, "host": null, "IP_ADDRESS": [ "subnet": " ", "heartbeat": true, "ipv6": false, "name": " ", "netmask": " " ] Failure Scenario: While querying the details of the network interface of site aware cluster node, if an error occurs, the system returns a common or a generic error code listed in error code table. 4.6 Querying Cluster information These are common APIs which can be used for both non-site and site-aware clusters alike. This section describes the following: Querying subnets in a cluster Querying all clusters on a subnet

61 4.6.3 Querying cluster Querying all the software components installed Querying all the installed Serviceguard software components Querying subnets in a cluster To query the subnets in a Serviceguard Cluster, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "subnets": [ "interfaces": [ "subnet_id": " ", "route_id": "1", "ip_monitor": "off", "polling_targets": [] ] Failure Scenario: During the query of subnets, if an error occurs, the system returns one of the common or generic error codes listed in error code table Querying all clusters on a subnet To be able to query all the clusters on a subnet, a non-root user must be available across the cluster nodes. This user must have privileges to monitor and view Serviceguard Clusters on every node in the multiple clusters. This user credentials must be specified in the header using user-principal as follows:

62 "username":"username", "password":"samplepwd", "type":"local", "nodename":"" To query all clusters on a particular subnet specified using <subnet>, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Here, we are querying all the Serviceguard Clusters on the subnet Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "totalcount": null, "clusters": [ "bundleversion":, "sites":, "siteaware": false, "name": "testcluster1", "uri": "/ha/ /clusters/testcluster1", "id": null, "status": null, "state": null, "summary": null, "coordinator": null, "incarnation": null, "clusterformtime": null, "configdataversion": null, "membertimeout": null,

63 "iotimeoutextension": null, "configiotimeoutextension": null, "autostarttimeout": null, "netpollinginterval": null, "hostnameaddrfamily": null, "maxreformduration": null, "maxconfigpackages": null, "clusterprmode": null, "installedsoftwareuri": null, "storageuri": null, "subnetsuri": null, "sgpackagetemplateuri": null, "nodes":, "packages":, "workloads": [ "weights":, "quorumserverip": null, "quorumservername": null, "quorumserverpollinterval": null, "quorumservertimeoutextension": null, "nodesuri": null, "packagesuri": null, "sitesuri": null, "alerts": [ "loadbalancing": null, "smartquorum": null, "smartquorumtimeout": null, "clusternodes": [ "clusternodesmap":, "cluster_type": "CLUSTER", "Nodes": [ "Packages": [ "cluster_weights": [], "bundleversion":, "sites":,

64 "siteaware": false, "name": "testcluster2", "uri": "/ha/ /clusters/testcluster2", "id": null, "status": null, "state": null, "summary": null, "coordinator": null, "incarnation": null, "clusterformtime": null, "configdataversion": null, "membertimeout": null, "iotimeoutextension": null, "configiotimeoutextension": null, "autostarttimeout": null, "netpollinginterval": null, "hostnameaddrfamily": null, "maxreformduration": null, "maxconfigpackages": null, "clusterprmode": null, "installedsoftwareuri": null, "storageuri": null, "subnetsuri": null, "sgpackagetemplateuri": null, "nodes":, "packages":, "workloads": [ "weights":, "quorumserverip": null, "quorumservername": null, "quorumserverpollinterval": null, "quorumservertimeoutextension": null, "nodesuri": null, "packagesuri": null, "sitesuri": null, "alerts": [ "loadbalancing": null,

65 "smartquorum": null, "smartquorumtimeout": null, "clusternodes": [ "clusternodesmap":, "cluster_type": "CLUSTER", "Nodes": [ "Packages": [ "cluster_weights": [] ] Failure Scenario: If the user, specified in the user-principal, fails to query cluster due to privilege issues, the following response can be observed. "totalcount": null, "clusters": [] There may be other common/generic error code in the response. See the error code table for more information. Filtered querying of multiple clusters There is an option available to query multiple clusters and view only select output that match the filter criteria. and query=status eq 'up' Here the URI signifies that query will filter out and respond with only those cluster which are up. The fields name and status will be filled up in the response body. The following fields or a subset of them can be used in the URI query Query field field field options All or a subset of the below fields can be used

66 Query field field options name status uri cluster_type site_aware workloads Following are the query options: Query option cluster_type permissible values One of the following values can be used CLUSTER METRO_CLUSTER EXTENDED_DISTANCE_CLUSTER status One of the following values can be used up down unknown Examples: ype,site_aware,workloads' ype,site_aware,workloads' and query=status eq 'down' ype,site_aware,workloads' and query=status eq 'up' AND cluster_type eq 'CLUSTER' Querying a cluster

67 To query a particular cluster s information, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Successful Scenario: A successful query returns the HTTP code 200 OK with the following response: "name": "testcluster", "status": "up", "uri": "ha/ /clusters/testcluster", "coordinator": "NODE1", "installedsoftwareuri": "ha/ /clusters/testcluster/installedsoftware", "storageuri": "/ha//clusters/testcluster/storage/volumegroups", "subnetsuri": "/ha/ /clusters/testcluster/subnets", "sgpackagetemplateuri": "/ha/ /clusters/testcluster/sgpackagetemplate", "sites": [ "name": "site-2", "uri": "/ha/ /clusters/testcluster/sites/site-2", "id": "2", "nodes": [ "name": "NODE2", "uri": "/ha/ /clusters/testcluster/sites/site-2/nodes/node2", "status": "up", "sg_manager_build_version": "B " ], "name": "site-1", "uri": "/ha/ /clusters/testcluster/sites/site-1", "id": "1",

68 "nodes": [ "name": "NODE1", "uri": "/ha/ /clusters/testcluster/sites/site-1/nodes/node1", "status": "up", "sg_manager_build_version": "B " ] "site_aware": true, "nodes": [ "workloads": [ "quorum_server_name": "qserver1", "member_timeout": " ", "io_timeout_extension": " ", "configured_io_timeout_extension": "0", "auto_start_timeout": " ", "network_polling_interval": " ", "hostname_address_family": "ipv4", "max_reformation_duration": "86", "max_configured_packages": "299", "cluster_pr_mode": "pr_enabled", "quorum_server_polling_interval": " ", "load_balancing": "off", "packages": [ "cluster_weights": [ "name": "package_limit", "value": "1" "serviceguard_user_details": [ "users": [ "user_name": [

69 "ANY_USER" "user_role": "monitor" "user_host": "ANY_SERVICEGUARD_NODE" "configcheckenablednodes": [ "cluster_type": "CLUSTER", "ischeckconfigenable": false Failure Scenario: During querying a cluster, if an error occurs, the system returns one of the error code numbers sucha as 3050, 2001, 2002, 2003, 2029, 3115, or a generic error code listed in error code table. Example failure response A fetch failure returns the HTTP code 500 Server error with the following response: "taskstatus": "error", "resource": null, "errorcode": "3050", "errortitle": "Exception while executing cmviewcl -s config as part of authorization f or view", "numoferror": 1, "numofwarning": 0, "errors": [ "messages": [ "Exception while executing cmviewcl -s config as part of authorization for view" ]

70 "httpresponsecode": Querying all the software components installed To query all the software installed on a specified cluster, use the HTTP GET method with the following URI: Request Body: Not Required Only a root user can query all the software installed. This means that the header user-principal must specify a root user only. Refer HTTP headers Table for more information. An example URI: Successful Scenario: A successful operation returns the HTTP code 200 OK with the following response: "toolkits": [ "name": "dataguard", "uri": "/ha/ /clusters/testcluster/installedsoftware/dataguard", "nodes": [ "node2" "node1" ], "name": "rolemngt", "uri": "/ha/ /clusters/testcluster/installedsoftware/rolemngt", "nodes": [ "node2" "node1" ]

71 , "name": "kvmmnp", "uri": "/ha/ /clusters/testcluster/installedsoftware/kvmmnp", "nodes": [ "node2" "node1" ], "name": "oracle", "type": "failover/multinode", "uri": "/ha/ /clusters/testcluster/installedsoftware/oracle", "nodes": [ "node2" "node1" ], "name": "ppas", "uri": "/ha/ /clusters/testcluster/installedsoftware/ppas", "nodes": [ "node2" ], "name": "kvm", "uri": "/ha/ /clusters/testcluster/installedsoftware/kvm", "nodes": [ "node2" "node1" ] "sitecontroller": "name": "sitecontroller", "uri": "/ha/ /clusters/testcluster/installedsoftware/sitecontroller",

72 "nodes": [ "node2" "node1" ], "replication_modules": [ "name": "srdf", "uri": "/ha/ /clusters/testcluster/installedsoftware/srdf", "nodes": [ "node2" "node1" ], "name": "mcsrdf", "uri": "/ha/ /clusters/testcluster/installedsoftware/mcsrdf", "nodes": [ "node2" "node1" ], "name": "mccaeva", "uri": "/ha/ /clusters/testcluster/installedsoftware/mccaeva", "nodes": [ "node2" "node1" ], "name": "xpca", "uri": "/ha/ /clusters/testcluster/installedsoftware/xpca", "nodes": [ "node2" "node1" ]

73 , "name": "caeva", "uri": "/ha/ /clusters/testcluster/installedsoftware/caeva", "nodes": [ "node2" "node1" ], "name": "mcxpca", "uri": "/ha/ /clusters/testcluster/installedsoftware/mcxpca", "nodes": [ "node2" "node1" ], "name": "3parrc", "uri": "/ha/ /clusters/testcluster/installedsoftware/3parrc", "nodes": [ "node2" "node1" ], "name": "xdc", "uri": "/ha/ /clusters/testcluster/installedsoftware/xdc", "bundleversion": "NODE2": " ", "NODE1": " ", "nodes": [ "node2" "node1" ]

74 ] In case of no softwares installed,it returns the HTTP code 200 OK with the following response: "toolkits": [ "replication_modules": [] Filtered query of Software components installed Following are the query filter options Query filter option node permissible values Name of the nodes in the cluster Example URI: eq node2 Other Example URIs: y=node eq node1 and node eq node2 Failure Scenario: During the query of Software Installed in the cluster, if an error occurs, the system returns the error 3033 or one of the common or generic error codes listed in error code table. "message": "Unable to fetch toolkit template data. For more information refer Servicegua rd manager logs.", "id": "3033" Querying installed Serviceguard software components:

75 To query the serviceguard software components installed on a specified cluster, use the HTTP GET method with the following URI: Request Body: Not Required Only a root user can query the installed Serviceguard software components. This means that the header user-principal must specify a root user only. Refer HTTP headers Table for more information. An example URI: Here software implies to the software installed with respect to serviceguard. You can use dataguard rolemngt kvmmnp oracle ppas kvm sitecontroller srdf mcsrdf mccaeva xpca caeva mcxpca 3parrc xdc Successful Scenario: Example with software in the URI as oracle: A successful operation returns the HTTP code 200 OK with the following response: "template": [ "name": "ASM_VOLUME_GROUP", "iterations": "nonmandatory_with_multiple",

76 "type": "String", "legal_values": [], "name": "LISTENER", "iterations": "mandatory", "type": "String", "legal_values": [ "yes", "no" "default_values": "yes", "name": "ASM_DISKGROUP", "iterations": "nonmandatory_with_multiple", "type": "String", "legal_values": [], "name": "LISTENER_RESTART", "iterations": "nonmandatory_with_multiple", "type": "Integer", "legal_values": [ "value >= 0" ], "name": "ORACLE_HOME", "iterations": "mandatory", "type": "String", "legal_values": [], "name": "CRITICAL_PDB", "iterations": "nonmandatory_with_multiple", "type": "String",

77 "legal_values": [ "default_values": "none", "name": "SID_NAME", "iterations": "mandatory", "type": "String", "legal_values": [], "name": "TIME_OUT", "iterations": "mandatory", "type": "Integer", "legal_values": [ "value > 0" "default_values": "30", "name": "LISTENER_NAME", "iterations": "mandatory_with_multiple", "type": "String", "legal_values": [ "default_values": "LISTENER", "name": " _id", "iterations": "nonmandatory_with_multiple", "type": "String", "legal_values": [ "^[0-9A-Za-z][^\" ']*[0-9A-Za-z]$", "^\"[^\"]*\"$", "^'[^']*'$" ], "name": "ASM_USER",

78 "iterations": "mandatory", "type": "String", "legal_values": [ "default_values": "oracle", "name": "START_MODE", "iterations": "mandatory", "type": "String", "legal_values": [ "mount", "nomount", "open" "default_values": "open", "name": "ORACLE_ADMIN", "iterations": "mandatory", "type": "String", "legal_values": [ "default_values": "oracle", "name": "INSTANCE_TYPE", "iterations": "mandatory", "type": "String", "legal_values": [ "database", "ASM" "default_values": "database", "name": "ASM_PV", "iterations": "nonmandatory_with_multiple", "type": "String",

79 "legal_values": [], "name": "ASM_HOME", "type": "String", "legal_values": [], "name": "ASM", "iterations": "mandatory", "type": "String", "legal_values": [ "yes", "no" "default_values": "no", "name": "DISABLE_BACKUP_MODE", "iterations": "mandatory", "type": "String", "legal_values": [ "yes", "no" "default_values": "no", "name": "MONITOR_PROCESSES", "iterations": "mandatory_with_multiple", "type": "String", "legal_values": [], "name": "LISTENER_PASS", "iterations": "nonmandatory_with_multiple", "type": "String",

80 "legal_values": [], "name": "PFILE", "iterations": "mandatory", "type": "String", "legal_values": [ "default_values": "$ORACLE_ORACLE_HOME/dbs/init$ORACLE_SID_NAME.ora", "name": "MONITOR_INTERVAL", "iterations": "mandatory", "type": "Integer", "legal_values": [ "value >= 1" "default_values": "30", "name": "CLEANUP_BEFORE_STARTUP", "iterations": "mandatory", "type": "String", "legal_values": [ "yes", "no" "default_values": "no", "name": "RETRY_INTERVAL_ORA_ERROR", "iterations": "mandatory", "type": "Integer", "legal_values": [ "value >= 0" "default_values": "0",

81 "name": "ASM_SID", "type": "String", "legal_values": [ "default_values": "+ASM", "name": "DB_SERVICE", "iterations": "nonmandatory_with_multiple", "type": "String", "legal_values": [ "default_values": "all", "name": "PARENT_ENVIRONMENT", "iterations": "mandatory", "type": "String", "legal_values": [ "yes", "no" "default_values": "no", "name": "USER_SHUTDOWN_MODE", "iterations": "mandatory", "type": "String", "legal_values": [ "immediate", "abort" "default_values": "abort", "name": "KILL_ASM_FOREGROUNDS", "iterations": "mandatory", "type": "String",

82 "legal_values": [ "yes", "no" "default_values": "yes" "services": [ "service_name": "oracle_pdb_monitor_service", "service_cmd": "$SGCONF/scripts/tkit/oracle/tkit_module.sh oracle_pdb_monitor 30 fai lure", "service_restart": "none", "service_fail_fast_enabled": "no", "service_halt_timeout": "300", "service_name": "oracle_listener_service", "service_cmd": "$SGCONF/scripts/tkit/oracle/tkit_module.sh oracle_monitor_listener", "service_restart": "none", "service_fail_fast_enabled": "no", "service_halt_timeout": "300", "service_name": "oracle_hang_service", "service_cmd": "$SGCONF/scripts/tkit/oracle/tkit_module.sh oracle_hang_monitor 30 fa ilure", "service_restart": "none", "service_fail_fast_enabled": "no", "service_halt_timeout": "300", "service_name": "oracle_service", "service_cmd": "$SGCONF/scripts/tkit/oracle/tkit_module.sh oracle_monitor", "service_restart": "none", "service_fail_fast_enabled": "no", "service_halt_timeout": "300"

83 "generic_resources": [] In case of an invalid or non-existing installed software, it returns the HTTP code 200 OK with the following response: Example: n_existing software A successful operation returns the HTTP code 200 OK with the following response: "template": [ "services": [ "generic_resources": [] Filtered query of installed Serviceguard Softwares components Following are the query filter options: Query filter option node oracle_home oracle_sid replication permissible values Name of the nodes in the cluster Path of the oracle software installed Value of oracle SID No Yes intent validate Example URI: eq NODE3 and node eq NODE4 and oracle_home eq /home/oracle and oracle_sid eq sid and replication eq no and intent eq validate

84 Failure Scenario: During the query of installed Serviceguard Softwares components, if an error occurs, the system returns a common or a generic error code listed in error code table along with the following response: "message": "Unable to automatically deploy oracle toolkit package. Could not find any pa ckage node with oracle running. Oracle toolkit automatic deployment requires that oracle m ust be running on any one of the package.", "id": "3084" During the query of Serviceguard software components installed in a cluster, if an error occurs, the system returns one of the following errors 3084, 3033, 3079, or one of the common errors or generic error codes listed in error code table. 4.7 Querying information on a virtual cluster VMware ESXi provides Virtual Machine filesystem, a cluster filesystem which allows Virtual machines to access VMFS disks (VMDK) to store data. These disks can be made accessible to the virtual machines by means of a Virtual Machine File System (VMFS) datastore. For more information on storage options see, Vmware documentation. This section describes the following APIs: Listing or querying all the VMFS datastores on a list of nodes Listing or querying the available Virtual Machine disk (VMDK) details of a particular datastore List all the VMFS datastores on a list of nodes The following URI fetches all the datastores of the node list provided in request payload. An example URI: Example Request Payload: "action":"query_vmfsds", "parameters":

85 "nodes": ["NODE1", "NODE2"] Table: VMFS Query payload members table Member JSON Type Mandatory Accepted Value Description action string yes query_vmfsds Specifies the action to be performed based on the parameters sent parameters object yes List of parameters that are specified to denote the exact action to be performed. See the Datastore query sub-members table for more information Table: Datastore query sub-members table Member JSON Type Mandatory Accepted Value Description nodes Array of Strings yes This is a list of nodes from which the information is to be collected. Successful Scenario: A successful query returns the HTTP code 200 OK with the following message body. "taskname": "Get Vmfs Datastore", "taskstatus": "ok", "resource": "name": "testcluster", "type": "Cluster Vmfs", "uri": "/ha/ /clusters/testcluster", "numoferror": 0, "numofwarning": 0, "successresult": [ "datastore1", "test_ds1", "test_ds2",

86 "NODE1_4shared", "test1_ds", "test2_ds", "test3_ds" "httpresponsecode": 0 Failure Scenario: During the VMFS datastore query operation, if an error occurs, the system returns one of the common errors 3150, 3155, or a generic error code listed in error code table. Example response: "taskname": "Get Vmfs Datastore", "taskstatus": "error", "resource": "name": "testcluster", "type": "Cluster Vmfs", "uri": "/ha/ /clusters/testcluster", "errorcode": "3155", "errortitle": "Encountered unexpected Error while auto discovering configured VMDK file s. For more information refer Serviceguard manager logs.", "numoferror": 1, "numofwarning": 0, "errors": [ "messages": [ "Encountered unexpected Error while auto discovering configured VMDK files. For mo re information refer Serviceguard manager logs." ]

87 "httpresponsecode": List the available Virtual Machine disk (VMDK) details of a particular datastore The following URI fetches the available Virtual Machine disk (VMDK) details of the specified datastore common to nodes list provided in request payload. The API lists only those VMDKs that are not used already part of an existing package configured in the cluster. An example URI: Example Request Payload: "action":"query_vmfs", "parameters": "nodes": ["NODE1","NODE2" "vmfsdata_store": "test_ds1" Table: VMFS Query payload members table Member JSON Type Mandatory Accepted Value Description action string yes query_vmfs Specifies the action to be performed based on the parameters sent parameters object yes List of parameters that are specified to denote the exact action to be performed. Refer VMDK parameters sub-members table for more information Table: VMDK parameters sub-members table Member JSON Type Mandatory Accepted Value Description

88 nodes Array of Strings yes List of nodes from which the information is to be collected. vmfsdata_store string yes a string value is accepted Specifies the Datastore for which the available VMDK disk entries are to be queried on the nodes mentioned in the payload. Successful Scenario: A successful query returns the HTTP code 200 OK with the following message body. "taskname": "Get Vmfs", "taskstatus": "ok", "resource": "name": "testcluster", "type": "Cluster Vmfs", "uri": "/ha/ /clusters/testcluster", "numoferror": 0, "numofwarning": 0, "successresult": "vmdatastore": [ "datastore": "test_ds1", "vmdks": [ "vmdiskname": "test4/test4.vmdk", "vmdisktype": "RDM", "vmdiskname": "test1/test1.vmdk", "vmdisktype": "RDM", "vmdiskname": "test3/test3.vmdk", "vmdisktype": "VMFS",

89 "vmdiskname": "test2/test2.vmdk", "vmdisktype": "VMFS" ] "scsislots": [ "scsicontrollernum": "0", "scsislotnum": [ "1", "2", "3", "4", "5", "6", "8", "9", "10", "11", "12", "13", "14", "15" ] "isallscsicontrollerused": false, "httpresponsecode": 0 Failure Scenario: During the VMDK query operation, if an error occurs, the system returns one of the common errors 3150, 3155, or a generic error code listed in error code table.

90 Example response: "taskname": "Get Vmfs", "taskstatus": "error", "resource": "name": "testcluster", "type": "Cluster Vmfs", "uri": "/ha/ /clusters/testcluster", "errorcode": "3155", "errortitle": "Encountered unexpected Error while auto discovering configured VMDK file s. For more information refer Serviceguard manager logs.", "numoferror": 1, "numofwarning": 0, "errors": [ "messages": [ "Encountered unexpected Error while auto discovering configured VMDK files. For mo re information refer Serviceguard manager logs." ] "httpresponsecode": Querying information of package Querying all packages within a cluster To query all the packages within a cluster, use the HTTP GET method with the following URI: Request body: Not required An example URI:

91 Successful scenario: A successful query of all packages within a cluster operation returns the HTTP code 200 OK with the following response: "packages": [ "name": "testpackage1", "uri": "/ha/ /clusters/testcluster/packages/testpackage1", "style": null, "status": null, "state": null, "highlyavailable": null, "summary": null, "id": null, "allclusternodes": null, "initialautorun": null, "multinodepackagedata": null, "packagemodules": null, "drenabled": null, "configureddrstoragearray": "", "post_environmentvariables": null, "alerts": [ "onlinemodificationfailed": false, "task": null, "postexternalscripts": null, "postexternalprescripts": null, "postpackageips": null, "postmonitoredsubnets": null, "postdependency": null, "postpackageweight": null, "postpackagegenericresource": null, "poststoragearrays": null, "posttoolkits": null, "post ": null, "postservices": null, "package_type": "failover",

92 "toolkit_type": "", "name": "testpackage2", "uri": "/ha/ /clusters/testcluster/packages/testpackage2", "style": null, "status": null, "state": null, "highlyavailable": null, "summary": null, "id": null, "allclusternodes": null, "initialautorun": null, "multinodepackagedata": null, "packagemodules": null, "drenabled": null, "configureddrstoragearray": "", "post_environmentvariables": null, "alerts": [ "onlinemodificationfailed": false, "task": null, "postexternalscripts": null, "postexternalprescripts": null, "postpackageips": null, "postmonitoredsubnets": null, "postdependency": null, "postpackageweight": null, "postpackagegenericresource": null, "poststoragearrays": null, "posttoolkits": null, "post ": null, "postservices": null, "package_type": "failover", "toolkit_type": "", "name": "testpackage3",

93 "uri": "/ha/ /clusters/testcluster/packages/testpackage3", "style": null, "status": null, "state": null, "highlyavailable": null, "summary": null, "id": null, "allclusternodes": null, "initialautorun": null, "multinodepackagedata": null, "packagemodules": null, "drenabled": null, "configureddrstoragearray": "", "post_environmentvariables": null, "alerts": [ "onlinemodificationfailed": false, "task": null, "postexternalscripts": null, "postexternalprescripts": null, "postpackageips": null, "postmonitoredsubnets": null, "postdependency": null, "postpackageweight": null, "postpackagegenericresource": null, "poststoragearrays": null, "posttoolkits": null, "post ": null, "postservices": null, "package_type": "failover", "toolkit_type": "" ] Failure scenario:

94 During the query of all packages within a cluster, if an error occurs, the system returns the generic error code listed in error code table. If there are no packages in the cluster then a response of HTTP code 200 OK is returned with the following details: "packages": [] Filtered query options for querying all packages within a cluster: There is an option available to query all packages within a cluster and view only select output that match the filter criteria. The following fields or a subset of them can be used in the URI query. Query field field field options All or a subset of the below fields can be used name status uri style state cluster_name package_type package_description toolkit_type drenabled dependencies volumegroups diskgroups auto_run configurednodes site_controller

95 Query field field options generic_resource configureddrstoragearray storage_array It is possible to filter all packages based on the package type, status, toolkit type, storage replication and other parameters. The following fields or a subset of them can be used in the URI query Query option permissible values package_type failover multi_node status up down unknown toolkit_type oracle apache nfs configureddrstoragearray 3parrc xdc drenabled true false auto_run disabled enabled dependee_pkg site Specify the name of the dependent package Specify the name of the site in the cluster.

96 Query option generic_resource_name permissible values Specify the name of the generic resource For example, e,status,style,state,cluster_name,package_type,package_description,toolkit_type,drenabled, dependencies,volumegroups,diskgroups,auto_run,configurednodes,site_controller,generic_reso urce' and query=package_type eq 'multi_node' AND toolkit_type eq 'oracle' AND status eq 'd own' Here the URI signifies to query the packages of package type multinode, toolkit type oracle and the status down with the package parameter fields name,status,style,state,cluster_name,package_type,package_description,toolkit_type,drenabled,dependencies,volumegroups,di A sample response is as shown below: "packages": [ "name": "testpackage1", "style": "modular", "status": "down", "state": "halted", "highlyavailable": null, "summary": null, "id": null, "allclusternodes": null, "initialautorun": null, "multinodepackagedata": null, "packagemodules": null, "drenabled": false, "configureddrstoragearray": "", "post_environmentvariables": null, "alerts": [ "onlinemodificationfailed": false,

97 "task": null, "workloadinfos": [ "posttoolkits": null, "post ": null, "postpackageips": null, "postmonitoredsubnets": null, "postdependency": null, "postpackageweight": null, "postpackagegenericresource": null, "poststoragearrays": null, "postexternalscripts": null, "postexternalprescripts": null, "postservices": null, "cluster_name": "testcluster", "package_type": "multi_node", "package_description": "\"Serviceguard Package\"", "auto_run": "enabled", "configurednodes": "uri": "/ha/ /clusters/testcluster/packages/testpackage/configurednodes", "post_nodes": null, "nodes": [ "name": "NODE1", "uri": "/ha/ /clusters/testcluster/nodes/node1", "id": null, "status": "up", "state": "halted", "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null,

98 "ip_address": " ", "localnode": false, "switching": "enabled", "available": "yes", "type": null, "order": null, "package_status": "down", "partially_started": null, "sg_version": null, "configuredpackages": [ "node_type": "VMWare", "license": "license_type": "Enterprise", "license_validity_in_days": "Indefinite", "license_invalid_reason": null, "license_count": "1", "last_run_time": "0", "last_halt_time": "0", "last_halt_failed": "no", "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false ], "toolkit_type": "oracle", "ischeckconfigenable": false, "dependencies": [] ] For example,

99 e,status,style,state,cluster_name,package_type,package_description,toolkit_type,drenabled, dependencies,volumegroups,diskgroups,auto_run,site_controller,generic_resource' and query= dependee_pkg eq 'testdependentpackage' Here the URI signifies to query all the packages with the dependent package name testdependentpackage with the specified fields A sample response is shown below: "packages": [ "name": "testpackage2", "style": "modular", "status": "down", "state": "halted", "highlyavailable": null, "summary": null, "id": null, "allclusternodes": null, "initialautorun": null, "multinodepackagedata": null, "packagemodules": null, "storage": "uri": null, "rawdisks": null, "filesystem_details": "concurrent_fsck_operations": 0, "concurrent_mount_and_umount_operations": 0, "fs_mount_retry_count": 0, "fs_umount_retry_count": 0, "flagforhopset": false, "postfilesystems": null, "volumegroup_details": "post_volumegroups": null,

100 "flagforhopset": false, "diskgroup_details": "post_diskgroups": null, "flagforhopset": false, "diskgroups": [], "vmfs_details": "vmfs": null, "flagforhopset": false, "post_vmfs": null, "drenabled": false, "configureddrstoragearray": "", "post_environmentvariables": null, "alerts": [ "onlinemodificationfailed": false, "task": null, "workloadinfos": [ "posttoolkits": null, "post ": null, "postpackageips": null, "postmonitoredsubnets": null, "postdependency": null, "postpackageweight": null, "postpackagegenericresource": [ "poststoragearrays": null, "postexternalscripts": null, "postexternalprescripts": null, "postservices": null, "cluster_name": "testcluster", "package_type": "failover", "package_description": "\"Serviceguard Package\"", "auto_run": "disabled", "configurednodes": "uri": "/ha/ /clusters/testcluster/packages/asmdb/configurednodes", "post_nodes": null,

101 "nodes": [ "name": "NODE1", "uri": "/ha/ /clusters/testcluster/nodes/node1", "id": null, "status": "up", "state": "blocked", "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": " ", "localnode": false, "switching": "enabled", "available": "yes", "type": "Primary", "order": "1", "package_status": "down", "partially_started": null, "sg_version": null, "configuredpackages": [ "node_type": "VMWare", "license": "license_type": "Enterprise", "license_validity_in_days": "Indefinite", "license_invalid_reason": null, "license_count": "1", "last_run_time": "0", "last_halt_time": "0", "last_halt_failed": "no", "NetworkInterface": [

102 "Subnet": [ "configuredcapacities": [ "vmotion": false ], "toolkit_type": "oracle", "ischeckconfigenable": false, "dependencies": [ "dependee_pkg": "testdependentpackage", "postdependencyonnodedetails": null, "dependency_name": "asm inst_pkg", "dependency_condition": "asm inst_pkg=up", "dependency_location": "same_node", "nodes": [ "node": "NODE1", "satisfied": "no" ] ] ] Examples: e,status,style,state,cluster_name,package_type,package_description,toolkit_type,drenabled, dependencies,volumegroups,diskgroups,auto_run,configurednodes,site_controller,generic_reso urce' and query=package_type eq 'multi_node' AND toolkit_type eq 'oracle' AND configureddr StorageArray eq '3parrc' Here the URI signifies to query the packages of package type 'multinode', toolkit type 'o racle' and the storage array configured with '3Parrc' with the package parameter fields 'n ame,status,style,state,cluster_name,package_type,package_description,toolkit_type,drenable

103 d,dependencies,volumegroups,diskgroups,auto_run,configurednodes,site_controller,generic_re source' e,status,style,state,cluster_name,package_type,package_description,toolkit_type,drenabled, dependencies,volumegroups,diskgroups,auto_run,configurednodes,site_controller,generic_reso urce' and query=package_type eq 'multi_node' AND toolkit_type eq 'oracle' AND configureddr StorageArray eq '3parrc' AND status eq 'down' AND auto_run eq 'disabled' Here the URI signifies to query the packages of package type 'multinode', toolkit type 'oracle' and the storage array configured with '3Parrc' and the package status 'down' and auto run 'disabled' with the package parameter fields 'name,status,style,state,cluster_na me,package_type,package_description,toolkit_type,drenabled,dependencies,volumegroups,diskg roups,auto_run,configurednodes,site_controller,generic_resource' e,status,style,state,cluster_name,package_type,package_description,toolkit_type,drenabled, dependencies,volumegroups,diskgroups,auto_run,site_controller,generic_resource' and query= auto_run eq 'enabled' AND status eq 'up' Here the URI signifies to query the packages with the package status 'up' and auto run 'enabled' with the package parameter fields 'name,status,style,state,cluster_name,package_ type,package_description,toolkit_type,drenabled,dependencies,volumegroups,diskgroups,auto_ run,site_controller,generic_resource' e,status,style,state,cluster_name,package_type,package_description,toolkit_type,drenabled, dependencies,volumegroups,diskgroups,auto_run,site_controller,generic_resource' and query= dependee_pkg eq 'testdependentpackage' Here the URI signifies to query the packages with dependency and the dependent package be ing 'testdependentpackage' with the package parameter fields 'name,status,style,state,clus

104 ter_name,package_type,package_description,toolkit_type,drenabled,dependencies,volumegroup s,diskgroups,auto_run,site_controller,generic_resource' e,uri,generic_resource' and query=generic_resource_name eq 'generic_resource1' Here the URI signifies to query the packages having generic resources and the name of th e generic resource being 'generic_resource1' with the package parameter fields 'name,uri,g eneric_resource' e_controller,name,uri' and query=site eq 'site-1' Here the URI signifies to query the packages having sites and the name of the site is 'site-1' with the package parameter fields 'site_controller,name,uri' e,status,style,state,cluster_name,package_type,package_description,toolkit_type,drenabled, auto_run,site_controller,generic_resource' and query=drenabled eq 'false' Here the URI signifies to query the packages with the field 'drenabled' set to 'false' a nd the package parameter fields 'name,status,style,state,cluster_name,package_type,package _description,toolkit_type,drenabled,auto_run,site_controller,generic_resource' Querying a particular package To query a particular package information within a Serviceguard cluster, use the HTTP GET method with the following URI: Request Body: Not Required An example URI: Success scenario:

105 A successful query of querying a particular package returns the HTTP code 200 OK with the following response: "name": "testpackage", "uri": "/ha/ /clusters/testcluster/packages/testpackage", "style": "modular", "status": "up", "state": "running", "highlyavailable": "yes", "summary": "ok", "id": "74764", "allclusternodes": null, "initialautorun": "enabled", "priority": "no_priority", "multinodepackagedata": null, "packagemodules": [ "name": "sg/multi_node", "version": "1", "name": "sg/basic", "version": "1", "name": "sg/priority", "version": "1", "name": "sg/pr_cntl", "version": "2", "script": "$SGCONF/scripts/sg/pr_cntl.sh" "services": [ "drenabled": false,

106 "configureddrstoragearray": "", "post_environmentvariables": null, "alerts": [ "onlinemodificationfailed": false, "task": null, "workloadinfos": [ "toolkits": [ "postexternalscripts": null, "postexternalprescripts": null, "postservices": null, "posttoolkits": null, "post ": [ "postpackageips": null, "postmonitoredsubnets": null, "postdependency": null, "postpackageweight": null, "postpackagegenericresource": null, "storagearrays": [ "poststoragearrays": null, "cluster_name": "testcluster", "package_type": "multi_node", "package_description": "\"Serviceguard Package\"", "log_level": "0", "auto_run": "enabled", "node_fail_fast_enabled": "disabled", "run_script_timeout": "no_timeout", "halt_script_timeout": "no_timeout", "successor_halt_timeout": "no_timeout", "script_log_file": "/usr/local/cmcluster/run/log/mnp.log", "configurednodes": "uri": "/ha/ /clusters/testcluster/packages/testpackage/configurednodes", "post_nodes": null, "nodes": [ "name": "NODE1", "uri": "/ha/ /clusters/testcluster/nodes/node1 "id": null,

107 "status": "up", "state": "running", "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": " ", "localnode": false, "switching": "enabled", "available": "yes", "type": null, "order": null, "package_status": "up", "partially_started": null, "sg_version": null, "configuredpackages": [ "node_type": "VMWare", "license": "license_type": "Enterprise", "license_validity_in_days": "Indefinite", "license_invalid_reason": null, "license_count": "1", "last_run_time": " ", "last_halt_time": "0", "last_halt_failed": "no", "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false,

108 "name": "NODE2", "uri": "/ha/ /clusters/testcluster/nodes/node2", "id": null, "status": "up", "state": "running", "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": " ", "localnode": false, "switching": "enabled", "available": "yes", "type": null, "order": null, "package_status": "up", "partially_started": null, "sg_version": null, "configuredpackages": [ "node_type": "VMWare", "last_run_time": " ", "last_halt_time": "0", "last_halt_failed": "no", "NetworkInterface": [ "Subnet": [ "configuredcapacities": [ "vmotion": false, ]

109 "package_weights": [ " _addresses": [ "environment_variables": [ "alerts_uri": "/ha/ /clusters/testcluster/packages/testpackage/alerts", "configcheckenablednodes": [ "monitor_subnets": [ "toolkit_type": "", "external_scripts": [ "ischeckconfigenable": false, "external_pre_scripts": [ "relocatable_package_ips": [ "dependencies": [ "generic_resources": [] A successful query of querying a particular package which is also a part of workload returns the HTTP code 200 OK with the following response: "name": "asm inst_pkg", "uri": "/ha/ /clusters/testcluster/packages/testpackage1", "style": "modular", "status": "down", "state": "failed", "highlyavailable": "no", "summary": "critical", "id": "42000", "allclusternodes": null, "initialautorun": "enabled", "priority": "no_priority", "multinodepackagedata": null, "packagemodules": [ "name": "sg/ ", "version": "1",

110 "name": "sg/multi_node", "version": "1", "name": "sg/basic", "version": "1", "name": "sg/priority", "version": "1", "name": "tkit/oracle/oracle", "version": "4", "script": "$SGCONF/scripts/tkit/oracle/tkit_module.sh", "name": "sg/pr_cntl", "version": "2", "script": "$SGCONF/scripts/sg/pr_cntl.sh", "name": "sg/service", "version": "1", "script": "$SGCONF/scripts/sg/service.sh" "services": [ "listener_monitored": null, "nodes": [ "name": "NODE1", "status": "down", "restart_limit": "unknown", "restart_count": 0

111 "service_name": "asm inst_pkg_serv", "service_halt_timeout": "300", "service_fail_fast_enabled": "disabled", "service_restart": "none", "service_cmd": "$SGCONF/scripts/tkit/oracle/tkit_module.sh oracle_monitor", "service_halt_on_maintenance": "no", "monitored_generic_resource": "None" "drenabled": false, "configureddrstoragearray": "", "post_environmentvariables": null, "alerts": [ "resource": "name": "asm inst_pkg", "type": "Package", "uri": "/ha/ /clusters/testcluster/packages/testpackage1", "alert_code": "PKG_FAILED", "alert_severity": "degraded", "alert_description": "Package failed ", "alert_resolution": "Please put in an appropriate resolution string for the alert" "onlinemodificationfailed": false, "task": null, "workloadinfos": [ "uri": "/ha/ /clusters/testcluster/workloads/wkld_c6d983668f1edd", "clusters": [ "testcluster" "workloadtype": "oracle_asm_db", "workloadid": "testcluster^~wkld_c6d983668f1edd",

112 "name": "wkld_c6d983668f1edd" "toolkits": [ "toolkitname": "oracle", "deployment": null, "replication": null, "LISTENER_OPTION": "no", "LISTENERS": [ "LISTENER_NAME": "LISTENER" "INSTANCE_TYPE": "ASM", "MONITOR_INTERVAL": "30", "ORACLE_HOME": "/home/oracle", "ORACLE_ADMIN": "ORACLE_ADMIN", "SID_NAME": "sid1g", "START_MODE": "open", "PFILE": "/asm/dbs/init.ora", "RETRY_INTERVAL_ORA_ERROR": "0", "TIME_OUT": "30", "PARENT_ENVIRONMENT": "no", "CLEANUP_BEFORE_STARTUP": "no", "USER_SHUTDOWN_MODE": "abort", "DISABLE_BACKUP_MODE": "no", "MONITOR_PROCESSES": [ "asm_pmon_$oracle_asm_sid", "asm_dbw0_$oracle_asm_sid", "asm_ckpt_$oracle_asm_sid", "asm_smon_$oracle_asm_sid", "asm_lgwr_$oracle_asm_sid", "asm_gmon_$oracle_asm_sid", "asm_rbal_$oracle_asm_sid" "ASM": "no",

113 "ASM_HOME": "/asm", "ASM_SID": "ASM_SID", "ASM_DISKGROUPS": [ "ASM_VGS": [ "ASM_PVS": [ "ASM_USER": "ASM", "KILL_ASM_FOREGROUNDS": "yes", "DB_SERVICES": [ "CRITICAL_PDBS": [] "postexternalscripts": null, "postexternalprescripts": null, "postservices": null, "posttoolkits": null, "post ": [ "postpackageips": null, "postmonitoredsubnets": null, "postdependency": null, "postpackageweight": null, "postpackagegenericresource": null, "storagearrays": [ "poststoragearrays": null, "cluster_name": "testcluster", "package_type": "multi_node", "package_description": "\"Serviceguard Package\"", "auto_run": "enabled", "node_fail_fast_enabled": "disabled", "run_script_timeout": "no_timeout", "halt_script_timeout": "no_timeout", "successor_halt_timeout": "no_timeout", "script_log_file": "/usr/local/cmcluster/run/log/testpackage2.log", "configurednodes": "uri": "/ha/ /clusters/testcluster/packages/testpackage1/configurednodes", "post_nodes": null, "nodes": [

114 "name": "NODE2", "uri": "/ha/ /clusters/testcluster/nodes/node2", "id": null, "status": "up", "state": "blocked", "summary": null, "toolkitsuri": null, "storage": null, "clusterlocklun": null, "siteid": null, "sitename": null, "interfacesuri": null, "configuredpackagesuri": null, "alerts": [ "alertsuri": null, "ip_address": " ", "localnode": false, "switching": "disabled", "available": "no", "type": null, "order": null, "package_status": "down", "partially_started": null, "sg_version": null, "configuredpackages": [ "node_type": "VMWare", "license": "license_type": "Enterprise", "license_validity_in_days": "Indefinite", "license_invalid_reason": null, "license_count": "1", "last_run_time": "0", "last_halt_time": "0", "last_halt_failed": "no", "NetworkInterface": [ "Subnet": [

115 "configuredcapacities": [ "vmotion": false ], "package_weights": [ " _addresses": [ "environment_variables": [ "alerts_uri": "/ha/ /clusters/testcluster/packages/testpackage1/alerts", "configcheckenablednodes": [ "monitor_subnets": [ "toolkit_type": "oracle", "external_scripts": [ "ischeckconfigenable": false, "external_pre_scripts": [ "relocatable_package_ips": [ "dependencies": [ "generic_resources": [] Failure scenario During the query of a particular package, if an error occurs, the system returns the generic error code listed in error code table Querying the toolkit associated with the package To query the toolkit associated with the package within a cluster, use the HTTP GET method with the following URI: Request body: Not required An example URI: Successful scenario: A successful query of the toolkit associated with the package operation returns the HTTP code 200 OK with the following response:

116 The following response depicts the details of Oracle ASM instance package: "toolkit": [ "toolkitname": "oracle", "deployment": null, "replication": null, "LISTENER_OPTION": "no", "LISTENERS": [ "LISTENER_NAME": "LISTENER" "INSTANCE_TYPE": "ASM", "ORACLE_HOME": "/home/oracle", "MONITOR_INTERVAL": "30", "ORACLE_ADMIN": "ORACLE_ADMIN", "SID_NAME": "sid1g", "START_MODE": "open", "PFILE": "/asm/dbs/init.ora", "RETRY_INTERVAL_ORA_ERROR": "0", "TIME_OUT": "30", "PARENT_ENVIRONMENT": "no", "CLEANUP_BEFORE_STARTUP": "no", "USER_SHUTDOWN_MODE": "abort", "DISABLE_BACKUP_MODE": "no", "MONITOR_PROCESSES": [ "asm_pmon_$oracle_asm_sid", "asm_dbw0_$oracle_asm_sid", "asm_ckpt_$oracle_asm_sid", "asm_smon_$oracle_asm_sid", "asm_lgwr_$oracle_asm_sid", "asm_gmon_$oracle_asm_sid", "asm_rbal_$oracle_asm_sid"

117 "ASM": "no", "ASM_HOME": "/asm", "ASM_SID": "ASM_SID", "ASM_DISKGROUPS": [ "ASM_VGS": [ "ASM_PVS": [ "ASM_USER": "ASM", "KILL_ASM_FOREGROUNDS": "yes", "DB_SERVICES": [ "CRITICAL_PDBS": [] ] The following response depicts the details of Oracle database package: "toolkit": [ "toolkitname": "oracle", "deployment": null, "replication": null, "LISTENER_OPTION": "yes", "LISTENERS": [ "LISTENER_NAME": "LISTENER" "INSTANCE_TYPE": "database", "ORACLE_HOME": "/home/oracle", "MONITOR_INTERVAL": "30", "ORACLE_ADMIN": "ORACLE", "SID_NAME": "sid1g", "START_MODE": "open", "PFILE": "$ORACLE_ORACLE_HOME/dbs/init$ORACLE_SID_NAME.ora",

118 "RETRY_INTERVAL_ORA_ERROR": "0", "TIME_OUT": "30", "PARENT_ENVIRONMENT": "no", "CLEANUP_BEFORE_STARTUP": "no", "USER_SHUTDOWN_MODE": "abort", "DISABLE_BACKUP_MODE": "no", "MONITOR_PROCESSES": [ "ora_pmon_$oracle_sid_name", "ora_dbw0_$oracle_sid_name", "ora_ckpt_$oracle_sid_name", "ora_smon_$oracle_sid_name", "ora_lgwr_$oracle_sid_name", "ora_reco_$oracle_sid_name" "ASM": "yes", "ASM_HOME": "/asm", "ASM_SID": "ASM_SID", "ASM_DISKGROUPS": [ "ASM_VGS": [ "ASM_PVS": [ "ASM_USER": "ASM", "KILL_ASM_FOREGROUNDS": "yes", "DB_SERVICES": [ "CRITICAL_PDBS": [] Failure scenario: During the query of toolkit associated with the package, if an error occurs, the system returns the generic error code listed in error code table. If the toolkit is not assosciated with the package, then a response of HTTP code 200 OK with the following response: "toolkit": []

119 5 Working with clusters This chapter describes the following: creating, modifying, and deleting of a cluster administrative operations on a cluster and a cluster node 5.1 Creating a cluster To create a Serviceguard cluster, use the HTTP POST method with the following URI: An example URI: Table-1: Cluster create payload parameters Member JSON Type Submember Mandatory Accepted Value Description name string yes The cluster name must not contain any of the following characters: space, slash (/), backslash (), asterisk (*), at-sign (@), equalsign (=), or-sign, semicolon(;). All other characters are legal. The cluster name can contain up to 39 characters. Name of a Serviceguard Cluster. CAUTION: Ensure that the cluster name is unique within the subnets configured on the cluster nodes; under some circumstances Serviceguard may not be able to detect a duplicate name and unexpected problems may result. In particular ensure that two clusters with the same name do not use the same quorum server; this could result in one of the clusters failing to obtain the quorum server s arbitration services when it needs them, and thus failing to re-form. subnets Array of Objects yes name yes Network address, For example: ip_monitor yes One of the following is acceptable Address of the subnet configured into the cluster. Specifies whether or not the subnet specified in the subnet name entry will be monitored at the IP layer. on

120 Member JSON Type Submember Mandatory Accepted Value Description off off Default value is off. polling_ targets no Network address, For example: The IP address to which polling messages will be sent from all network interfaces on the subnet specified in the name entry, if ip_monitor is set to ON. This is called target polling. users Array of Objects yes authorized_ user_name yes The following special characters are NOT supported space, forward slash (/), backward slash (), asterisk (*). One of the following is acceptable. The user specified in authorized_user_name entry can issue Serviceguard commands. ANY_USER a maximum of 8 login names from the /etc/passwd file on user host authorized_ host_name yes One of the following is acceptable The authorized_host_name is where the user specified in authorized_user_name entry can issue Serviceguard commands. Choose one of these three values: ANY_SERVICEGUARD_NODE, or (any) CLUSTER_MEMBER_NODE, or a specific node. If you specify a specific node it must be the official hostname (the hostname portion, and only the hostname portion, of the fully qualified domain name). ANY_SERVICEGUARD _NODE CLUSTER_MEMBER _NODE

121 Member JSON Type Submember Mandatory Accepted Value Description The name must not contain any of the following characters: space, slash (/), backslash (), asterisk (*), at-sign equalsign (=), or-sign, semicolon(;). All other characters are legal. The name can contain up to 39 characters. Default value is ANY_SERVICEGUARD _NODE. authorized_ user_role> yes One of the following is acceptable authorized_user_role describes the role of the user specified in authorized_user_name entry. MONITOR and FULL_ADMIN can be set only in the cluster configuration file and they apply to the entire cluster. PACKAGE_ADMIN can be set in the cluster configuration file or a package configuration file. If it is set in the cluster configuration file, PACKAGE_ADMIN applies to all configured packages; if it is set in a package configuration file, it applies to that package only. These roles are not exclusive; for example, more than one user can have the PACKAGE_ADMIN role for the same package. MONITOR PACKAGE_ADMIN FULL_ADMIN Default value is MONITOR. cluster_weights Array of Objects no Weight is defined for a package, whereas capacity is defined for a node. For any given weight or capacity pair, cluster weight name, capacity name (and weight_name in the package) must be the same.

122 Member JSON Type Submember Mandatory Accepted Value Description name no The name must not contain any of the following characters: space, slash (/), backslash (), asterisk (*), at-sign equalsign (=), or-sign, semicolon(;). All other characters are legal. The name can contain up to 39 characters. value no Value can range from 0 to default value is 0. load_balancing string no One of the following is acceptable name specifies a name for a weight that corresponds to a capacity specified in this post body. The weight value is a floating point value between 0 and They have meaning only in relation to the corresponding node capacities. When you configure load balancing, Serviceguard places the packages in a load sensitive mode. While starting the packages, Serviceguard places the packages on the nodes to distribute the weights evenly on all the nodes. on off Default value is off. vmfssaltexist string no One of the following is acceptable. false true This parameter specifies whether you want to retain the SCS or Vmuser credentials file that is created as part of Virtual cluster creation when the create operation fails. This is used during virtual cluster creation. If the cluster create operation fails due to unexpected reason, the SCS or Vmuser credential file will be removed and needs to be further created during virtual cluster create operation. If the cluster create operation fails due to unexpected reason, the SCS or Vmuser credential file will remain intact and need not be further created during virtual cluster create operation. Default value is false.

123 Member sites JSON Type Array of Objects Submember Mandatory Accepted Value Description no name Yes, if sites is mentioned The name must not contain any of the following characters: space, slash (/), backslash (), asterisk (*), at-sign equalsign (=), or-sign, semicolon(;). All other characters are legal. The name can contain up to 39 characters. This value represents the name of a site in the cluster nodes Yes, if sites is mentioned nodes is an array of objects. If sites are defined in the cluster then nodes is a sub-member of sites object. Otherwise nodes is a member. See example for more details. nodes Array of Objects nodes is an array of objects. This object provides the details about nodes in the cluster. If sites are defined in the cluster then nodes is a submember of sites object otherwise node is a member. See example for more details. name yes This value represents the name of a node in the site/cluster interfaces yes interfaces is an array of objects. See table-2 interfaces object members, for more information. cluster_ lock_lun no The name must not contain any of the following characters: space, slash (/), backslash (), asterisk (*), at-sign (@), equalsign (=), or-sign, semicolon(;). All other characters are legal. The name can contain up to 39 characters. defines the cluster lock LUN device on a per node basis. The device may only be used for this purpose and by only a single cluster.

124 Member JSON Type Submember Mandatory Accepted Value Description example: /dev/sdc esx_host no A short name notation of host, fully-qualified hostname or IP address for the ESXi hypervisor. ESX_HOST host name, alias or IP address of ESXi hypervisor or host. For every VMware virtual machine that is configured as a Serviceguard node, you can specify the ESX_HOST on which the VM resides. Each NODE_NAME can have only one ESX_HOST. You must not use ESX_HOST parameter if VCENTER_SERVER parameter is specified in the cluster configuration file. Both VCENTER_SERVER and ESX_HOST parameters are mutually exclusive.this is an optional parameter. This is required only when VMWare virtual machines are being used during cluster deployment. example: esxserver1 or vcenter _server string A short name notation of host, fully-qualified hostname or IP address for the ESXi hypervisor. Specifies host name, aliases, or IP address of vcenter server. This parameter is cluster-wide. Only one vcenter server is supported. If you specify VCENTER_SERVER parameter, then you must not specify ESX_HOST parameter for any of the VMWare guest nodes configured in the cluster. This is an optional parameter. This is required only when VMWare virtual machines are being used during cluster deployment. example: vcenter or capacities no capacities is an array of objects. See table-3 Capacities object members, for more information.

125 Member JSON Type Submember Mandatory Accepted Value Description member_ timeout auto_start _timeout network_polling _interval configured_io_ timeout_extension string yes value >= and value <= Default_value: string yes value >= and value <= default_value = string yes value >= and value <= default_value = string no value >= 0 and value <= default_value =0 The amount of time, in microseconds, after which Serviceguard declares that the node has failed and begins re-forming the cluster without this node.minimum supported values: 3 seconds for a cluster with more than one heartbeat subnet and 14 seconds for a cluster that has only one heartbeat LAN. With the lowest supported value of 3 seconds, a failover time of 4 to 5 seconds can be achieved. The amount of time a node waits before it stops trying to join a cluster during automatic cluster startup. All nodeswait this amount of time for other nodes to begin startup before the cluster completes the operation. The time should be selected based on the slowest boot time in the cluster.enter a value equal to the boot time of the slowest booting node minus the boot time of the fastest booting node plus 600 seconds (ten minutes) The network_polling_interval specifies the Interval at which Serviceguard periodically polls all the LAN Interfaces (link-level and the ones configured for IP MONITOR) This specifies the number of microseconds by which to increase the time Serviceguard waits after detecting a node failure, so as to ensure that all pending I/O on the failed node has ceased.

126 Member JSON Type Submember Mandatory Accepted Value Description hostname_address _family max_configured _packages quorum_server _name quorum_server _ip_address quorum_server_ polling_interval string yes One of the following is acceptable IPV4 IPV6 Any Default Value:IPV4 string yes value >= 0 and value <= 300 default_value =300 string no The name must not contain any of the following characters: space, slash (/), backslash (), asterisk (*), at-sign (@), equalsign (=), or-sign, semicolon(;). All other characters are legal. The name can contain up to 39 characters. string no Network address, For example: string no value >= and value <= default_value = This parameter specifies the Internet Protocol address family to which Serviceguard will attempt to resolve cluster node names and quorum server host names. This parameter sets the maximum number of packages that can be configured in the cluster. It is a fully-qualified hostname or IP address of a host system outside the current cluster that is providing quorum server functionality.this parameter is used only when you employ a quorum server for tiebreaking services in the cluster An alternate fully-qualified hostname or IP address for the quorum server. It must be (or resolve to) an IPv4 address on Red Hat 5, Red Hat 6 and RedHat7. On SLES 11 and SLES 12, it can be (or resolve to) either an IPv4 or an IPv6 address if hostname_address_family is set to ANY, but otherwise must match the setting of hostname_address_family. This parameter is used only if you use a quorum server and want to specify an address on an alternate subnet by which it can be reached. The time (in microseconds) between attempts to contact the quorum server to make sure it is running.

127 Member JSON Type Submember Mandatory Accepted Value Description quorum_server_ timeout_extension string no value >= and value <= default_value = You can use thequorum_server_timeout_extension to increase the time interval after which the current connection (or attempt to connect) to the quorum server is deemed to have failed. qs_smart _quorum string no off This parameter can be set to either on or off. By default, qs_smart_quorum parameter is commented. This can be enabled only in a site-aware cluster (that is, where sites are configured). If qs_smart_quorum parameter is enabled (ON), then quorum server decides which site will survive in an event of a split between the sites based on the workload status information. In case of network partition between the sites, smart quorum grants quorum to the site that is running the critical workload. Thus, it avoids unnecessary failover of application. Also, this feature supports the deployment of asymmetric configurations where the two sites can have unequal number of nodes. qs_arbitration _wait on default_value =off string no value >= and value <= default_value = You can use qs_arbitration_wait parameter only if qs_smart_quorum parameter is enabled. This is the time (in microseconds) for which quorum server will wait for both the sites to send their quorum grant request along with workload status. By default,qs_arbitration_wait parameter is disabled. Table-2: Interface object members

128 Member JSON Type Sub-member JSON Type Mandatory Accepted Value Description interfaces Array of Objects yes describes the interfaces of a node in the cluster/site. name string The name must not contain any of the following characters: space, slash (/), backslash (), asterisk (*), at-sign (@), equal-sign (=), or-sign, semicolon(;). All other characters are legal. The name can contain up to 39 characters. Name of the each LAN which will be used as heartbeats or stationary IP heartbeat_address stationary_address Array of strings Array of strings yes Network address, Specifies the IP notation indicating this node s connection to a subnet that will carry the cluster heartbeat. This array may contain list of IP addresses. If hostname_address_family is set to IPV4 or ANY, aheartbeat IP address can be either an IPv4 or an IPv6 address, with the exceptions noted below. If hostname_address_family is set to IPV6, all heartbeat IP addresses must be IPv6 addresses. For example: no Network address, Specifies the node s IP address on each subnet that does not carry the cluster heartbeat, but is monitored for packages. This array may contain list of IPV4 or IPV6 addresses. For example: heartbeat string yes TRUE true indicates that a heartbeat IP is specified in the heartbeat_address entry.

129 Member JSON Type Sub-member JSON Type Mandatory Accepted Value Description FALSE false indicates that there is no heartbeat IP provided in the heartbeat_address entry. The entry heartbeat_address will be ignored. Table-3: Capacities object members Member capacities JSON Type Array of Objects Submember Mandatory Accepted Value Description name no The name must not contain any of the following characters: space, slash (/), backslash (), asterisk (*), at-sign equalsign (=), or-sign, semicolon(;). All other characters are legal. The name can contain up to 39 characters. Specifies a name for the capacity limit yes if capacity name is defined must be a floating-point value between 0 and Specifies a value for the capacity name. Example Request Payload Example JSON Input Body/ Request Payload with sites "name": "testcluster", "subnets": [ "name": " ", "ip_monitor": "off", "polling_targets": [ ] "users": [ "authorized_user_name": "ANY_USER",

130 "authorized_host_name": "ANY_SERVICEGUARD_NODE", "authorized_user_role": "MONITOR" "cluster_weights": [ "load_balancing": "OFF", "sites": [ "name": "site-1", "nodes": [ "name": "NODE1", "interfaces": [ "name": "eth4", "heartbeat_address": [ " " "stationary_address": [ "heartbeat": true "capacities": [ "name": "package_limit", "limit": "10" ] ], "name": "site-2",

131 "nodes": [ "name": "NODE2", "interfaces": [ "name": "eth4", "heartbeat_address": [ " " "stationary_address": [ "heartbeat": true "capacities": [ "name": "package_limit", "limit": "10" ] ] "quorum_server_name": "fep3", "quorum_server_ip_address": "", "quorum_server_polling_interval": , "quorum_server_timeout_extension": 0, "member_timeout": , "auto_start_timeout": , "network_polling_interval": , "configured_io_timeout_extension": 0, "hostname_address_family": "IPV4", "max_configured_packages": "300"

132 Example JSON Input Body/ Request Payload without sites "name": "testcluster", "subnets": [ "name": " ", "ip_monitor": "off", "polling_targets": [ ] "users": [ "authorized_user_name": "ANY_USER", "authorized_host_name": "ANY_SERVICEGUARD_NODE", "authorized_user_role": "MONITOR" "cluster_weights": [ "load_balancing": "OFF", "nodes": [ "name": "NODE1", "interfaces": [ "name": "eth4", "heartbeat_address": [ " " "stationary_address": [

133 "heartbeat": true "cluster_lock_lun": "\/dev\/sda", "capacities": [ "name": "package_limit", "limit": "10" ], "name": "NODE2", "interfaces": [ "name": "eth4", "heartbeat_address": [ " " "stationary_address": [ "heartbeat": true "cluster_lock_lun": "\/dev\/sdc", "capacities": [ "name": "package_limit", "limit": "10" ] "member_timeout": , "auto_start_timeout": , "network_polling_interval": ,

134 "configured_io_timeout_extension": 0, "hostname_address_family": "IPV4", "max_configured_packages": "300" Successful Scenario: A successful creation returns the HTTP code 200 OK with the following message body. "taskname": "Create", "taskstatus": "ok", "resource": "name": "testcluster", "type": "Cluster", "uri": "/ha/ /clusters/testcluster", "numoferror": 0, "numofwarning": 0, "httpresponsecode": 0 Failure Scenario: During the query to create a cluster, if an error occurs, the system returns one of the error code numbers 3003,2001,2002,2003,2017 or a generic error code listed in error code table. Example failure response A creation failure returns the HTTP code 500 Server error with the following response: "taskname": "Create", "taskstatus": "error", "resource": "name": "testcluster", "type": "Cluster", "uri": "",

135 "errorcode": "3003", "errortitle": "Unable to apply cluster configuration. For more information refer Serv iceguard and System logs. ", "numoferror": 1, "numofwarning": 0, "errors": [ "type": "Command", "subtype": "Cmd", "resourcetype": "Generic", "resourcename": "generic", "messages": [ "Error in cluster configuration parameters. " ] "httpresponsecode": Modifying a cluster To modify a Serviceguard Cluster, use the HTTP PUT method with the following URI: An example URI: Refer Table 1: Cluster create payload, Table 2: Interface object members and Table 3: Capacities object members of Create a cluster REST API in section 5.1 for the required payload parameters to modify a cluster. Successful Scenario: A successful modification from the above example returns the HTTP code 200 OK with the following response: Example Success response "taskname": "Update",

136 "taskstatus": "ok", "resource": "name": "testcluster", "type": "Cluster", "uri": "/ha/ /clusters/testcluster", "numoferror": 0, "numofwarning": 0, "warnings": [ "httpresponsecode": 0 Upon successful modification of the cluster, the uri portion of the JSON response header indicates the URI of the updated cluster. Example modifications Example modification 1: Cluster modified to use Quorum Server. /dev/sdb is being used as Cluster Lock LUN for arbitration. We can modify the same to Quorum Server by removing the lock LUN entry in the payload and adding the quorum server parameters. The following flowchart explains the general steps to perform the intended modification.

137 Removed the following entry from both nodes: "cluster_lock_lun": "\/dev\/sdb" Added the following to the payload: "quorum_server_name": "qslinux.example.com", "quorum_server_ip_address": "xx.x.xx.xx", "quorum_server_polling_interval": , "quorum_server_timeout_extension": 0 Response: