Raritan Computer CC-WSAPI-0B-v5.1.0-E User's Manual
Contents
1. static void auth exception handler security service webservice bl cc raritan com Authent icationAndAuthorizationException ex String name System out println AuthenticationAndAuthorizationException ex getFaultInfo getMessage System out println t ex getFaultInfo getCode ex printStackTrace Raritan Appendix B Web Services Development in Java public static void set service end point Service service BindingProvider port Pattern pattern Pattern compile CC SG Matcher matcher pattern matcher service getServiceName getLocalPart String service name matcher replaceFirst if ccsg port length lt 1 ccsg port 9443 if ccsg address length gt 0 port getRequestContext put BindingProvider ENDPOINT ADDRESS PROPERTY https ccsg address ccsg port CommandCenterWebServices service name Port wsdl static String get input String message System out println message BufferedReader reader new BufferedReader new InputStreamReader System in String name null try name reader readLine catch IOException ioe Raritan Appendix B Web Services Development in Java System err println Could not read input return null if name equals return null return name public stati2. Introduction 1 J Java keytool 28 L Logging Management 21 LoggingManagementException 22 N Node Management Services 9 NodeData 11 NodeManagementException 12 NodePowerStatus 11 O OpenSSL 28 P PowerlnterfaceStatus 11 R Remotely Authorized Users 4 renameElementinCategory 27 renameNode 16 ReportData 22 ReportRecord 21 runReport 23 47 Index S Sample Application for C 40 Sample Application for Java 32 Saving the CCSG s Server Certificate from a Web Browser EG 28 Services 8 13 19 23 25 setNodePower 17 Setting the CCSG Address 31 signoff 9 signOn 8 System Management 7 SystemInfo 7 SystemManagementException 7 U Unsupported Authentication and Authorization Services 9 URLObject 2 User Management 8 UserManagementException 9 Using a CC SG Web Service in a Project 9 Using Microsoft Management Console to Manage Certificates 29 W Web Services Development in 6 39 Web Services Development in Java 30 WSDL URLs 2 4 48 Raritan Raritan gt U S Canada Latin America Monday Friday 8 a m 6 p m ET Phone 800 724 8090 or 732 764 8886 For CommandCenter NOC Press 6 then Press 1 For CommandCenter Secure Gateway Press 6 then Press 2 Fax 732 764 8887 Email for CommandCenter NOC tech ccnoc raritan com Email for all other products tech raritan com gt China Beijing Mond
3. Note You cannot delete the SuperUser e parameters String sessionID String userName The name of the user to delete e return value boolean true addUserToGroup Assign a user to a group to control their access of the CC SG Note You cannot add users to or delete users from the SuperUser group e parameters String sessionID String userName The name of the user to modify String groupName An array of group names of which the user shall be a member Raritan Chapter 2 API Definitions e return value boolean true deleteUserFromGroup Remove a user from a group to control their access of the CC SG Note If this operation deletes all of a user s groups then the user itself shall be deleted e parameters String sessionID String userName The name of the user to modify String groupName An array of group names in which the user shall no longer be a member e return value boolean true Logging Management Raritan This set of services is for retrieving log records from the CC SG database http s CC IP ADDRESS 8080 CommandCenterWebServices LoggingManagementServicePort wsdl Data Types ReportRecord The components of a CC SG log record This data encompasses multiple types of logs such that not all elements will be populated for a particular record instance e Elements Integer recordNumber The ordinal number of the record re
4. Raritan ka ul Copyright 2011 Raritan Inc CC WSAPI 0B v5 1 0 E February 2011 255 80 0004 00 This document contains proprietary information that is protected by copyright All rights reserved No part of this document may be photocopied reproduced or translated into another language without express prior written consent of Raritan Inc Copyright 2011 Raritan Inc All third party software and hardware mentioned in this document are registered trademarks or trademarks of and are the property of their respective holders FCC Information This equipment has been tested and found to comply with the limits for a Class A digital device pursuant to Part 15 of the FCC Rules These limits are designed to provide reasonable protection against harmful interference in a commercial installation This equipment generates uses and can radiate radio frequency energy and if not installed and used in accordance with the instructions may cause harmful interference to radio communications Operation of this equipment in a residential environment may cause harmful interference VCCI Information Japan CORES 18 5 ERS 0585 VCCI OX ESC 2 2 590518 6340 COREA RE CATS CBR D SERT CL 6 53 0018 5 0 8 5 DS XE ET 4 82 208 Raritan is not responsible for damage to this product resulting from accident disaster misuse abuse non Raritan modification of the product or other events outside
5. String username user name logging into the WS API client String password associated password of the username being used by the WS API client e return value String sessionID Raritan Chapter 2 API Definitions signoff This operations signs off log out a particular user from CC SG The application can have multiple users logged in String username user name that is logging out via the WS API client String session D e return value void Unsupported Authentication and Authorization Services The following Authentication and Authorization services are not supported and should not be used e authenticate e getAllUserGroups e getAllUserGroupsCount Node Management Services Raritan This set of services is for modifying nodes in CC SG http CC IP ADDRESS 8080 CommandCenterWebServices No deManagementServicePort wsdl Data Types AccessMethod Description of a means of accessing a node e Elements String methodName the name of the application used for access Some examples of the application name are SSH Client SSH MPC RemoteDesktop Viewer RemoteDesktop and LO RemoteConsole String methodType inband or outband Inband refers to any interface that uses only the TCP IP network to directly connect to the node Outband is based on reaching a Raritan device product via TCP IP and from the device connecting to the KVM or seria
6. Web Services Development in Java RCSfile Revision Date This source code is owned by Raritan Computer Inc and is confidential and proprietary information distributed solely pursuant to a confidentiality agreement or other confidentiality obligation It is intended for informational purposes only and is distributed as is with no support and no warranty of any kind Copyright c 2009 Raritan Computer Inc All rights reserved Reproduction of any element without the prior written consent of Raritan Computer Inc is expressly forbidden 7 import security service webservice bl cc raritan com Authent icationAndAuthorizationService import security service webservice bl cc raritan com CCSGAut henticationAndAuthorizationService import security service webservice bl cc raritan com types r import node service webservice bl cc raritan com NodeManagem entService 33 Appendix B Web Services Development in Java import node service webservice bl cc raritan com CCSGNodeMan agementService import node service webservice bl cc raritan com types change server address import javax xml ws Service import javax xml ws BindingProvider import java util regex Pattern import java util regex Matcher user input import java io public class SampleClient public static String ccsg address 10 0 0 101 ccsg port 9443
7. B Web Services Development in Java Call the method from your application for each service object This example uses AuthenticationAndAuthorizationService CCSGAuthenticationAndAuthorizationService service new CCSGAuthenticationAndAuthorizationService AuthenticationAndAuthorizationService service port service getAuthenticationAndAuthorizationServicePort set service end point service BindingProvider service port This procedure must be done for each service like NodeManagementService to connect to the intended CC SG Calling a Web Service JAX WS requires an instance of the service class for the desired service generated by wsimport The service object contains a port object that one can use to call the service methods as shown below CCSGAuthenticationAndAuthorizationService service new CCSGAuthenticationAndAuthorizationService AuthenticationAndAuthorizationService service_port service getAuthenticationAndAuthorizationServicePort try String sessionID port signOn user password catch security service webservice bl cc raritan com AuthenticationAndAuthorizationException ex System out printin AuthenticationAndAuthorizationException ex getFaultinfo getMessage System out printin t ex getFaultinfo getCode System out printin signOn for user user failed Sample Application for Java Raritan Raritan Appendix B
8. Vendor Name Maximum 64 characters 5 Generate a self signed certificate Raritan 0 8 k Chapter 1 Introduction Encryption Mode If Require AES Encryption between Client and Server is selected in the Administration gt Security gt Encryption screen AES 128 is the default If AES is not required DES 3 is the default Private Key Length 1024 is the default Validity Period days Maximum 4 numeric characters Country Code CSR tag is Country Name State or Province Maximum 64 characters Type in the whole state or province name Do not abbreviate City Locality CSR tag is Locality Name Maximum 64 characters Registered Company Name CSR tag is Organization Name Maximum 64 characters Division Department Name CSR tag is Organization Unit Name Maximum 64 characters Fully Qualified Domain Name CSR tag is Common Name Administrator Email Address Type in the email address of the administrator who is responsible for the certificate request Challenge Password Maximum 64 characters Note The Challenge Password is used internally by CC SG to generate the certificate You do not need to remember it Password Enter a keystore password Use this password to open the P12 file that you will save in step 7 If you copy the generated certificate and import into your own keystore instead you do not need to remember this keystore password Click Generate Certificate The text appears in th
9. follows Major Minor Point Major increments with big new feature sets or changes to existing services The client should be rebuilt based on the current WSDL Minor increments with small functionality additions A client rebuild may not be necessary Point increments for patches and bug fixes No client rebuilding needed String serial The serial number identifying the unit String platform Hardware identification xsd dateTime date The current date Chapter 2 API Definitions Services getSysteminfo Retrieve information about the CC SG e parameters String sessionID e return value Systemlnfo Authentication and Authorization Services This set of services is for logging into and out of CC SG http CC IP ADDRESS 8080 CommandCenterWebServices Au thenticationAndAuthorizationServicePort wsdl Data Types AuthenticationAndAuthorizationException Exception returned for all errors specific to authentication and authorization signOn This operation is used to login to CC SG and authenticate with the CC SG user database or an external database This is the first method which should be used once a SSL TLS session has been established This operation achieves a SSO Single Sign On effect The WS API can continue to make requests without signing in again The signon is used to authenticate any user credentials that is using the WS API client as a proxy e parameters
10. is the most recent specification for Java Web Services Glassfish contains a JAX WS implementation under Metro which can be found at https jax ws dev java net This document is based on version 2 1 5 but you may use a different version or an entirely different WS system to suit your needs The Glassfish implementation includes a tool called wsimport that one can use to generate WS client code for one s application using WSDL files from the WS server Such tools are invaluable in WS development Please consult the documentation of your chosen JAX WS system for details on wsimport other tools and non CCSG related information Certificates information for Java users Raritan Create a truststore for the trusted server certificate or add the certificate to a truststore you already use gt To tell a Java client about the trusted server certificate You can do this via Djavax net ssl trustStore jssecacerts Save the client certificate from the CC SG s WS client configuration window The file is in PKCS12 format You can pass the client certificate to a Java client using the following parameters Djavax net ssl keyStore new client p12 Djavax net ssl keyStorePassword pass Where pass is the password you entered in the client configuration page Djavax net ssl keyStoreType pkcs12 30 Appendix B Web Services Development in Java Setting the CCSG Address Downloading the WSDL files from port 8080 of the CC SG is
11. of Raritan s reasonable control or not arising under normal operating conditions CE us LISTED Contents Chapter 1 Introduction 1 Connecting to GO SQ iria strate eese C nd a ii aii aaa eee 1 Add Web Services API Client Configuration on CC SG 2 ACCESS Information u een ee 4 a a 4 e i eR 4 Remotely Authorized Users 4 Chapter 2 API Definitions 6 reda 6 Common Data X 6 System Management iii nn tr o ek db tc ne Erde ka P eget Fo Ras ONCE Re va Ra T Tu D p dada 7 Data TYPOS IMG GC 7 SCIT 8 Authentication and Authorization Gervices enne 8 Data TYDES siii dense a en nn in 8 Unsupported Authentication and Authorization Services ooonoocccninoccccconocnnccononnnonnnnnnnccnnnos 9 Node Management Seis iii A sos A lA FA RR Ee HER bi 9 Data EU ms 9 0 13 User Management u M 18 Data TYPOS viii 18 00 2 E E E EEA 19 Eogging ee 21 Data TIPOS EE 21 EIERE 23 Category 0 0 5 Data VCS BE 25 0070 25 Raritan gt Contents Appendix A Certificate Management 28 Java KOVO O anciano aaa 28 OP 28 Saving the CCSG s Server Certificate from a Web Browser EG 28 Installing the Client Certificate into a Key Store Microsoft Windows 6 29 Using Microsoft Management Console to Manage Certflcates 29 Appen
12. parameters String sessionID String category The unique name identifying the category String Jelements Each array entry is a value to be removed from the category e return value returns boolean true on success zie Raritan Appendix A Certificate Management This appendix contains some tips on managing certificates See the respective company s documentation for more details In This Chapter 8 le 28 Saving the CCSG s Server Certificate from a Web Browser IE6 28 Installing the Client Certificate into a Key Store Microsoft Windows XP 29 Using Microsoft Management Console to Manage Certificates 29 Java keytool lt Viewing a certificate keytool printcert file CC SG pem gt Add a certificate to a new key store keytool importcert alias ADDRESS file CC SG cert keystore jssecacerts storepass yourpassword lt View the contents of a key store keytool list keystore jssecacerts OpenSSL lt Viewing a certificate openssl x509 in CC SG pem text lt Changing a certificate s format openssl x509 in CC SG cert out CC SG pem outform PEM inform DER Saving the CCSG s Server Certificate from a Web Browser IE6 1 Using the WS API client machine that is configured in the CC SG open a CC SG service URL via HTTPS and port 9443 28 zie Raritan Appendix A Certificate Management For example https 10 0 0 101 9443 CommandCenterWebSe
13. the default source of the WSDL files however their contents will reflect port 8080 of your CC SG Further you might wish to use your WS client with a different CC SG or you might change the CC SG s address Each WSDL file contains an element like the following lt soap address location https 10 0 0 101 9443 CommandCenterWebSer vices AuthenticationAndAuthorizationServicePort gt Before generating the stubs you can edit this address within each file to reflect the WS port of 9443 the WS protocol of HTTPS and the address of your CC SG After generating and building the source your client will already know the address protocol and port to use to access WS on your CC SG Manually editing the WSDL files requires less coding Or you can tell your WS stubs the URL of your own choice at run time lt Sample method to create a URL to access a CC SGs web services public static void set service end point Service service BindingProvider port Pattern pattern Pattern compile CC SG Matcher matcher pattern matcher service getServiceName getLocalPart String service name matcher replaceFirst String ccsg port 9443 String ccsg address 10 0 0 101 port getRequestContext put BindingProvider ENDPOINT ADDRESS PROPERTY https ccsg address ccsg port CommandCenterWebServices 4 service name Port wsdl Z Raritan 5 Appendix
14. user via the SignOn method Whenever you see a parameter named sessionlD it refers to this definition Note The session ID will be invalidated if no session activity is detected for 5 minutes e String interfacelD CC SG generated unique identifier of an interface e String username The name of a CC SG user account Common Data Types zie Raritan 1 Exceptions Each CC SG WS API service returns an exception upon error If the error is specific to the service the exception will be defined as follows Elements String code Simple definition of the error String message Specific error message 2 xsd dateTime Standard XML type used in Web services and based on ISO 8601 Your WS system will map it to a type appropriate for your target programming language Chapter 2 API Definitions System Management Raritan This set of services is for general CC SG settings and information http s CC_IP_ADDRESS 8080 CommandCenterWebServices System ManagementServicePort wsdl Data Types SystemManagementException Exception returned for all errors specific to system management e Elements String code Simple definition of the error String message Specific error message Systemlnfo General information about the CC SG e Elements String firmwareVersion The version of the software running on the CC SG String WSAPIVersion The version of the WS API on the CC formatted as
15. 3B1EE2CB665564BEB1ACAA8401 The constructed URL should look similar to this one http 10 0 0 101 80 CommandCenterWeb index_frames jsp sessionID 03AC4A3B1EE2CB665564BEB1ACAA8401 Note A single question mark delimits parameters from the document path Parameters themselves are separated from one another using an ampersand amp The path from getinterfaceURL will already contain parameters so you must append the sessionlD using an ampersand delimiter in that case NodeManagementException Exception returned for all errors specific to node management Raritan Chapter 2 API Definitions Services getCCSGAppletURL This operation retrieves the full URL to the CC SG Admin Client applet in order to launch the main CC SG client When this URL is opened in a browser it will display the main CC SG client if the sessionlD is valid or the login screen if the sessionID is invalid e parameters String sessionID e return value URLObject getCCSGHTMLClientURL This operation retrieves the full URL for the CC SG Access Client HTML pages to launch the main access CC SG page When this URL is opened in a browser it will display the main access CC SG page if the Session is valid or the login page if the sessionlD is invalid e parameters String sessionID authentication token granted for use by CCSG in SignOn return value URLObject getinterfaceURL This operation retrieves the URL required to connect
16. Configuration Under Bindings select New Binding Configuration Choose customBinding c Remove httpTransport extension if it is already entered as a Stack Element d Add httpsTransport then edit it to set RequireClientCertificate to True e Select the textMessageEncoding extension and set MessageVersion to Soap 1 f Select the service under Client gt Endpoints g Change the Binding to customBinding h Change BindingConfiguration to the customBinding that you just created i Edit the Address to use HTTPS your CCSG s address and port 9443 rather than 8080 Note You must edit the URL and set the binding for each service that you use The same binding can be used for every CCSG service j Save the configuration 3 Edit the C source back in Visual Studio 2008 39 Appendix C Web Services Development in C 4 Set a call back for ServerCertificate ValidationCallback so that the client will accept the CCSG s server certificate A simple method is to trust the certificate if it matches the CCSG server certificate that you have explicitly saved from the CCSG See Saving the CCSG s Server Certificate Using IE6 ServicePointManager ServerCertificateValidationCall back delegate Object obj X509Certificate certificate X509Chain chain SslPolicyErrors errors X509Certificate server certificate X509Certificate CreateFromCertFile C cc_cert ificate cer return server certificate Equ
17. Status availabilityAndStatus The general interface status String operation The most recent power operation boolean inProgress true if the operation is still running boolean successful true if the operation has finished successfully If both successful and inProgress are false then the operation failed String failureReason If the operation failed then this field will typically contain a description of the failure xsd dateTime timeStamp The time that the CC SG updated the power operation status 11 12 Chapter 2 API Definitions URLObject Components to form a URL to access the CC SG e Elements String protocol the protocol used either http or https String port the TCP port to be used for connecting to the interface port 80 or port 443 String path the path to the actual webservice servlet String tokenKey the name of the property to be used for the token The value is always sessionID String tokenValue the actual property value corresponding to the tokenKey from above Constructing a URL from URLObject Combine the string elements of the returned URLObject italicized in the following order with other data plain protocol CCSG Address port path tokenKey tokenValue Given the following URLObject data protocol http port 80 path CommandCenterWeb index frames jsp tokenKey sessionlD tokenValue OBACAA
18. String name Unique name to identify the category boolean node Applicable to nodes boolean device Applicable to devices String type Data type of elements String or Integer e return value boolean true on success editCategory Facilitates changes to the editable components of a category e parameters String sessionID String currentName the name of the existing category String newName the new name for the category same as currentName if no change boolean forNode boolean forDevice e return value boolean true on success deleteCategory Remove one category e parameters String sessionID String name e return value 26 boolean true on success Raritan Chapter 2 API Definitions addElementToCategory Add one or more values to the specified category e parameters String sessionID String category The unique name identifying the category String Jelements Each entry in this array is a value for the category e return value boolean true on success renameElementinCategory Change the value of a category s element e parameters String sessionID String category The unique name identifying the category String currentElement The current value of the element String newElement The new value intended for the element e return value boolean true on success deleteElementFromCategory Remove one or more values from the specified category e
19. als certificate Create an instance of the service proxy 6 Tell the proxy which client certificate to use through the ClientCredentials member You should save the client certificate into a store See Installing the Client Certificate into the Store Specify the store where you installed the certificate along with a name that the search method can use to find the certificate In this example 10 0 0 150 is the address and FQDN of the client host and the certificate is stored in the Personal section of the Current User store auth_service ClientCredentials ClientCertificate Se tCertificate StoreLocation CurrentUser StoreName My X509FindType FindBySubjectName 10 0 0 150 7 Create an instance of the service s parameters class signOn for instance 8 Setthe parameters Use the proxy and parameters object to access the service 10 You can receive the response through the returned object signOnResponse for example Sample Application for C Raritan Appendix C Web Services Development in C using System using System Collections Generic using System Ling m using System Text using System Security Cryptography X509Certificates using System Net using System Net Security using System ServiceModel namespace CCWSClient WCF class Program static string cc address 10 0 0 101 static string user gregor static string password pass123
20. ased on the unique interface ID e parameters String interfacelD String username This service uses the username to determine whether that user has permission to access the node and thereby the AccessMethod indicated by AccessMethod userAuthorizedForMethod e return value AccessMethod getNodeByName Retrieve nodes by name e parameters String sessionID String name Node name to find accepts wildcards _ and e return value NodeData Z Raritan Chapter 2 API Definitions getNodeBylnterfaceName Retrieves nodes by the name of the interface e parameters String sessionID String interfaceName Interface name to find accepts wildcards and 96 e return value NodeData getNodeByAssociation Find a node based on the category label applied to it e parameters String sessionID String category The unique name identifying the category String element The value from the category that labels this node e return value boolean true on success getNodesForUser This operation retrieves all available nodes for a particular user by username For each node that a user has access to its interfaces are checked and all relevant data recorded for both in band and out of band interfaces All interfaces for one node are then inserted into one object NodeData which besides the interfaces data also contains the name of the particular node for identification An array list o
21. ay Friday 9 a m 6 p m local time Phone 86 10 88091890 Shanghai Monday Friday 9 a m 6 p m local time Phone 86 21 5425 2499 GuangZhou Monday Friday 9 a m 6 p m local time Phone 86 20 8755 5561 gt India Monday Friday 9 a m 6 p m local time Phone 91 124 410 7881 gt Japan Monday Friday 9 30 a m 5 30 p m local time Phone 81 3 3523 5991 Email support japan raritan com gt Europe Europe Monday Friday 8 30 a m 5 p m GMT 1 CET Phone 31 10 2844040 Email tech europe raritan com United Kingdom Monday Friday 8 30 a m to 5 p m GMT Phone 44 0 20 7090 1390 France Monday Friday 8 30 a m 5 p m GMT 1 CET Phone 33 1 47 56 20 39 Germany Monday Friday 8 30 a m 5 30 p m GMT 1 CET Phone 49 20 17 47 98 0 Email rg support raritan com lt Melbourne Australia Monday Friday 9 00 a m 6 p m local time Phone 61 3 9866 6887 gt Taiwan Monday Friday 9 a m 6 p m GMT 5 Standard 4 Daylight Phone 886 2 8919 1333 Email support apac raritan com
22. ble to communicate with the CC SG If you don t want to manually add the certificate to a trust store you can make provisions in the client source to always trust the CC SG or to save the CC SG s certificate into the trust store automatically Remotely Authorized Users Users authorized via remote servers require some special handling in CC SGs Web Services Only AD users can be remotely authorized 1 The signOn service takes the plain user name just as the remote user would enter it on the CC SG s login page 2 Whenever a WS client accesses a service that takes a user name as a parameter including signOff and the targeted user is a remotely authorized user the user name needs to have the remote server s module name appended as follows USER MODULE Raritan Chapter 1 Introduction USER is the plain user name and MODULE is the name that the administrator gave the remote module configuration in CC SG Raritan 3 Chapter 2 Conventions API Definitions In This Chapter CONVENTIONS sentent tien 6 Common Data Types instant nine do Faune FE ERU C23 niet 6 System ann in 7 Authentication and Authorization Services 8 Node Management Services A 9 User Management t 18 Logging Management items cs 21 Category MIA Mic Verona er aa deua aa 25 The following conventions are used within this document e String sessionID The authentication token that was originally assigned to the
23. c void main String args String user gregor String password pass123 String session String current name new name CCSGAuthenticationAndAuthorizationService servic new CCSGAuthenticationAndAuthorizationService AuthenticationAndAuthorizationService port service getAuthenticationAndAuthorizationServic ePort set service end point service BindingProvider port CCSGNodeManagementService node service new CCSGNodeManagementService NodeManagementService node service port node service getNodeManagementServicePort set service end point node service BindingProvider node service port try 2 Raritan Appendix B Web Services Development in Java session port signOn user password catch security service webservice bl cc raritan com Authent icationAndAuthorizationException ex auth exception handler ex signOn System exit 1 current name get input Enter the name of the node to change new name get input Enter the new name if current name null amp amp new name null try if node service port renameNode session current name new name System out println Node name successfully changed to new name else System err println renameNode failed without an exception catch node service webservice bl cc raritan com NodeManagem entEx
24. ce parameters CCAuthentication signOn sign on new CCAuthentication signOn sign on String 1 user sign on String 2 password access the servic Console WriteLine Connecting to cc address try auth service Open CCAuthentication signOnResponse response auth service signOn sign on session id response result Console WriteLine signOn response response result catch Exception exception Console WriteLine exception ToString quit null Raritan S Appendix C Web Services Development in C renameNode servic CCNode NodeManagementServiceClient node service new CCNode NodeManagementServiceClient node service ClientCredentials ClientCertificate SetC ertificate StoreLocation CurrentUser StoreName My X509FindType FindBySubjectName 10 0 01500 CCNode renameNode rename new CCNode renameNode rename String 1 session id Console Write Name of node to change rename String 2 Console ReadLine Console Write New node name Di rename String 3 Console ReadLine try CCNode renameNodeResponse response node service renameNode rename Console WriteLine renameNod response response result catch Exception exception Console WriteLine exception ToString quit auth service quit auth service i Raritan Raritan Appendi
25. ception ex System out println NodeManagementException ex getFaultInfo getMessage System out println Nt ex getFaultInfo getCode ex printStackTrace Raritan Appendix B Web Services Development in Java else System err println Could not change node name without the current and new names try port signOff user session catch security service webservice bl cc raritan com Authent icationAndAuthorizationException ex auth exception handler ex signOff Raritan Appendix C Web Services Development in C The following sections describe how to create a Web Services client for the CCSG written in C This description is based on Microsoft Visual Studio 2008 and IE6 running on Windows XP Other methods of Web Service creation are available in Visual Studio 2008 but this document solely covers services through Windows Communication Foundation WCF and Net Framework Version 3 5 In This Chapter Using 8 CC SG Web Service in a Project 39 Sample Application for GH ists severe iia lt 40 Using a CC SG Web Service in a Project Raritan 1 Choose Project gt Add Service Reference using the CC SG WSDL URL for the intended service such as AuthenticationAndAuthorization 2 Right click app config in Solution Explorer You might have to open WCF Service Configuration Editor under Tools first Choose Edit WCF
26. dix B Web Services Development in Java 30 Choose a WS Library iii 30 Certificates information for Java users sssssssssssseeseeeee eene nennen nnns ener 30 Setting the CCSG Address iris 31 Calling a Web Service sise 32 Sample Application for iii 32 Appendix C Web Services Development in C 39 Using a GC SG Web Service in a 0 iaoea aE A NEA 39 Sample Application for OH au deett diia 40 Index 47 6 Raritan Chapter 1 Introduction Web Services API uses standardized Web Services technologies to allow a client machine to perform node power user and logging management services This client is independent of the CC SG but aims to provide the same capabilities that the CC SG s HTML based Access Client provides through use of the API and a TCP IP network This SDK allows Independent Software Vendors ISVs and Raritan customers to build an application using a development environment compatible with SOAP such as NET and Java In This Chapter Gonnecting to CG SQ diti ta 1 ACCESS Informati rad 4 Connecting to CC SG zie Raritan gt To connect to CC SG 1 Establish client configuration on CC SG Admin Client See Add Web Services API Client Configuration on CC SG on page 2 2 Download client and server CC SG certificates to the client machine for use by the client To connect to the CC SG using SOAP over port 9443 the client must first manually install the x 509 digital client certif
27. e Certificate box Click Save to File to save the certificate to a P12 file Or copy the generated certificate and import it into your own keystore 8 Click Add to save your changes Raritan Chapter 1 Introduction Access Information WSDL URLs http CC IP ADDRESS 8080 CommandCenterWebServices Au thenticationAndAuthorizationServicePort wsdl ttp CC IP ADDRESS 8080 CommandCenterWebServices No ManagementServicePort wsdl ttp s CC IP ADDRESS 8080 CommandCenterWebServices UserManagementServicePort wsdl D m po ttps CC IP ADDRESS 8080 CommandCenterWebServices L oggingManagementServicePort wsdl Certificates The CC SG s Web Services require mutual certificates such that both the CC SG and the WS client present a certificate Once one configures a client on the CC SG the CC SG will know about both certificates The client also needs to know about both certificates The CC SG s server certificate on port 9443 is generated by the CC SG itself The client must accept this certificate however a typical WS client would not be designed to present a certificate acceptance dialog to the user One can simply use a trust store to contain the CC SG s server certificate thereby telling the client certificate library to trust the CC SG Obtain the CC SG s certificate then create a new trust store or add it to an existing one The WS client must be able to access the trust store to be a
28. er this date and time If null the value will be the start of the current day xsd dateTime endDateTime Return records up until this date and time If null or beyond the CC SG s current time the value will be the current time String userName Restrict results to those of this user name Wildcards allowed Optional may be null or empty String userlPAddress Restrict results to those of this IP address Wildcards allowed Optional may be null or empty String messageType Search for messages in the specified category If null or empty include all message types The following are supported zie Raritan Chapter 2 API Definitions Access Audit Access Connection Authentication Error Power Tasks User Maintenance String message Restrict results to those containing this message The only supported wildcard is the asterisk Optional may be null or empty Integer numberOfRecordsToGet The maximum number of records to retrieve If not specified the service retrieves all available records as reported by totalNumberOfRecords When specified can be used to limit the number of records retrieved There is a maximum limit of 10 000 records return value ReportData getReportRecords Retrieve a set of records from a previously generated report starting at the specified record index up to the maximum number of records indicated e parameters String sessionID St
29. f all nodes that the user has access to and their interfaces is returned on success e parameters String username e return value NodeData Custom class NodeData has the following properties String name i e the name of the node InterfaceDatal nterfacesData i e data about interfaces contained in the node zie Raritan h Chapter 2 API Definitions addAssociationToNode Associate the node with one or more category values e parameters String sessionID String nodeName The unique name of the node to modify AssociationData associations e return value boolean true on success deleteAssociationFromNode Disassociate the node from one or more category values e parameters String sessionID String nodeName The unique name of the node to modify AssociationData associations e return value boolean true on success renameNode This operation changes the name of the specified node to the new name e parameters String sessionID String currentNodeName The name of the node that one wants to modify String newNodeName The name to take the place of the current one e return value boolean true Raritan Chapter 2 API Definitions getNodePower Returns the power status of each interface of the node including the status of the latest power operation The user must have permission to access the node In addition to the normal states the availability state of eac
30. g reportiD Identifier used to reference the report Integer totalNumberOfRecords The total number of records available for this report This value is not necessarily the same as the number of ReportRecord entries included ReportRecord records The first set of results for the report LoggingManagementException Exception returned for all errors specific to logging management e Elements String code Simple definition of the error Raritan Chapter 2 API Definitions String message Specific error message Services runReport Returns a log report formed using the request parameters Reports created via the WS API will show up as scheduled reports with the name WS Report Task in the CC SG Admin Client in the Administration gt Tasks section CC SG Admin Client users can see and delete these reports The WS system should handle deleting the tasks created using the WS API The client should call deleteReport for every call to runReport See deleteReport on page 25 If deleteReport is not called the session manager will remove remaining report tasks when the session is closed by any of the following methods 1 The client calls signOff to close the session The session times out and the system closes it An administrator closes the session from the Active Users report using the CC SG Admin Client e parameters String sessionID xsd dateTime startDateTime Return records aft
31. h interface will be set to Processing if the state is pending a change because of a power operation e parameters String sessionID String nodeName Return the status of the interfaces of the node with this name e return value NodePowerStatus setNodePower Initiate a power operation on the interfaces of a node This command requires the user to possess node permissions allowing power control of the node Note Power operations are in progress after setNodePower returns The session must remain valid during the lifetime of the operation otherwise the operation will fail Do not call signOff until the operation is complete see getNodePower e parameters String sessionID String nodeName The name of the node on which to operate String powerlnterfacelD An array of each of the node s interfaces on which to perform the power operation Each interface must be a member of the node String powerOperation The power operation to perform on the interfaces It must be one of the following strings as supported by the specified power interface All operations are not supported by all power interfaces See Raritan s CommandCenter Secure Gateway Administrators Guide zie Raritan H 18 Chapter 2 API Definitions User Management power power off power cycle graceful shutdown suspend Integer sequencelnterval The interval in seconds between successive ope
32. herwise it is the empty string String hostname hostname for the interface for in band interfaces only based on query using the supplied host IP address String portName i e the name for the port for out of band interfaces only otherwise it is the empty string String portiD the Raritan port ID for out of band interfaces This is a unique generated value that occurs as part of configuration of a Raritan devices ports This field is empty for in band interfaces Raritan Z Raritan Chapter 2 API Definitions String deviceName i e the name of the Raritan device This field is filled in only for out of band interfaces otherwise it the empty string String name String id Unique identifier referenced by AccessMethod String description User description of the interface String type Function of the interface NodeData Description of a node s configuration e Elements String name InterfaceData interfacesData The interfaces attached to this node AssociationData associations Category values with which the node is associated NodePowerStatus Describes the power status of a node through its interfaces e Elements PowerlnterfaceStatus powerlnterfaceStatus Contains an entry for each of the node s power interfaces PowerlnterfaceStatus Describes the interface and power operation statuses of a power interface e Elements InterfaceAvailabilityAnd
33. icate that is generated using the CC SG Admin Client CC SG contains a server certificate that will be retrieved using SSL TLS APIs implemented in the client application to establish a trust relationship See Add Web Services API Client Configuration on CC SG on page 2 for instructions on creating the client certificate See Certificates on page 4 Details Open the PKCS 12 file using the password and store the client certificate public and private keys in the keystore that is accessible to the WS API client application Connect on TCP Port 9443 to the CC SG s IP address and exchange certificates using the SSL TLS protocol Note CC SG verifies that the client IP address matches the address set within the client configuration on the CC SG Accept the self signed server certificate from CC SG This may require special handling on Java See Certificates information for Java users on page 30 Chapter 1 Introduction 3 Download WSDL files from the CC SG You can use a web browser or a simple client like wget to access the WSDL URLs See WSDL URLs on page 4 4 Choose a WS client library for your target language Use the tools provided with your chosen WS client library to generate stubs in your target language Each stub should be a complete web service operation such that all that you must do is call the web service as a method function with the appropriate parameters 6 Begin writing the client Call the signOn serv
34. ice found in AuthenticationAndAuthorizationService If successful the signOn returns a session ID that you must provide for some services Access the other services as needed Call signOff to end your session when your application finishes Note The signOn service is only required for services that take the session ID as a parameter signOff is only needed if signOn is called Add Web Services API Client Configuration on CC SG You must accept the End User Agreement before adding a Web Services API client to CC SG You can add up to five WS API clients See the CC SG Web Services API Guide for details on using the API lt To add a Web Services API 1 Select Access gt Add Web Services API This option is available only for users with the CC Setup and Control Privilege 2 Read the End User Agreement You can copy and paste the text to save it or choose Secure Gateway gt Print After you complete configuration this agreement will also be available in the Access menu 3 Click Accept The New Web Services API Configuration window opens 4 Type in the data requested about your web services client Web Services Client Name Maximum 64 characters License Key Your license key from Raritan Each CC SG unit must have a unique license key P Address Hostname Maximum 64 characters HTTPS Web Services Port Read only field CC SG uses port 9443 when trust establishment is generated Licensed
35. l port of the node String InterfacelD CC SG generated string which uniquely identifies the interface within CC SG String InterfaceName CC SG generated string which identifies the interface within CC SG 10 Chapter 2 API Definitions String applicationld CC SG generated string which uniquely identifies the access application type within CC SG for out of band access designated for use within CC SG String is null if not applicable to the interface boolean userAuthorizedForMethod value of the authorization for the user to access this interface with this application If the user has permission the value is TRUE AssociationData Represents a category based label placed on the node e Elements String category The unique name identifying the category String element The value from the category that labels this node InterfaceAvailabilityAndStatus Describes the current state of the interface e Elements String interfacelD String availability Text description of the availability field For example if an operation is still in progress availability will indicate Processing Availability may be Idle Busy or Processing String status Text description of the status field For example Up or Down InterfaceData Description of the node s attachment to the end point e Elements String ip host IP address for the interface This field is filled in for in band interfaces only ot
36. lative to the requested report Numbering begins at one xsd dateTime entryDateTime The date and time of the record String userName The user to which the entry corresponds String userlPAddress The IP address of the corresponding user String messageType The message type of the report entry The following are supported 21 22 Chapter 2 API Definitions Access Audit Access Connection Authentication Error Power Tasks User Maintenance String message The message text describing the user activity String deviceName The managed device the report entry corresponds to provided for message type Access Connection String nodeName The node the report entry corresponds to provided for message type Access Connection String portName The managed device port that the report entry corresponds to provided for message type Access Connection String interfaceName The node interface the report entry corresponds to provided for message type Access Connection String interfaceType The node interface type the report entry corresponds to provided for message type Access Connection String accessMode The access mode used String reasonForAccess The reason for access provided by the user ReportData This data describes a report generated using runReport The information can be used to manage the report and retrieve further results e Elements Strin
37. r is first added with addUser forcePasswordChange will be forced to true The value of forcePasswordChange can be modified with editUser String fullName The user s full name to be used when generating reports and notifications to more easily identify the user optional String emailAddress optional String phoneNumber optional String groups An array of the name s of the group s to which this user is amember These are the groups from which this user s permissions will be assigned UserManagementException Exception returned for all errors specific to user management Services getUser Returns configuration data for the specified user e parameters String sessionID String userName The login name of the desired user e return value CCSGUser The requested user getAllUsers Returns an array containing the CCSGUser data for each user defined on the CC SG e parameters String sessionID e return value CCSGUser 19 20 Chapter 2 API Definitions addUser Add a new user configuration to the CC SG e parameters String sessionID CCSGUser user The new user s settings e return value boolean true editUser Change an existing user s settings excluding groups e parameters String sessionID CCSGUser user The new user s settings e return value boolean true deleteUser Remove the user with the provided name from the CC SG
38. rations of the specified power interfaces Applicable to power on and power off only String reasonForAccess Text used to track access by user required when Node Auditing is enabled for the user s group return value boolean true This set of services is for adding modifying and removing users from the CC SG database as is typically done by system administrators http s CC IP ADDRESS 8080 CommandCenterWebServices UserManagementServicePort wsdl Data Types CCSGUser The settings of a user on the CC SG Elements String name The unique user name used when logging into the CC SG String password The user s password required if remoteAuthentication is false This value will always be null when returned from getUser boolean loginEnabled The user may use the account when true boolean remoteAuthentication true if the user will be remotely authenticated boolean passwordExpirationEnabled When true the user will have to change their password periodically as indicated by passwordExpirationPeriod Raritan Z Raritan Chapter 2 API Definitions Integer passwordExpirationPeriod The user will have to reset their password after this many days required if passwordExpirationEnabled is true This value will always be clear if this feature is disabled boolean forcePasswordChange When true the user will have to change their password on the next login When the use
39. ring report Integer startingAtRecord The index of the first record to retrieve Indexing begins at zero e Integer numberOfRecords The maximum number of records to retrieve If not specified the service retrieves all available records as reported by totalNumberOfRecords When specified can be used to limit the number of records retrieved There is a maximum limit of 10 000 records e return value ReportRecord Raritan Chapter 2 API Definitions deleteReport Delete a previously requested report otherwise reports are deleted after the user session is terminated e parameters String sessionID String report e return value boolean true Category Management Raritan This set of services is for getting and setting categories for CC SG nodes Data Types CategoryData Stores information about a category and its elements e Elements String name boolean node Applicable to nodes boolean device Applicable to devices String type Data type of elements String or Integer String Jelements The values of the elements Services getCategory Retrieve one or more categories including element values e parameters String sessionID String name The name of the category accepts wildcards _ and e return value CategoryDatal 25 Chapter 2 API Definitions addCategory Add a new category to CC SG e parameters String sessionID
40. rvices Authentication AndAuthorizationServicePort wsdl A Security Alert appears Click View Certificate Click Details then Copy to File Use the Certificate Export Wizard to save the certificate to a file Installing the Client Certificate into a Key Store Microsoft Windows XP 1 Save the PKCS12 certificate file on your client computer See Add Web Services API Client Configuration on CC SG see Add Web Services API Client Configuration on CC SG on page 2 2 Double click the client certificate file to open the Certificate Import Wizard 3 Install the certificate in a place where your client will be able to access it such as Personal Using Microsoft Management Console to Manage Certificates zie Raritan You can also use Microsoft Management Console MMC to manage certificates with more control than the methods above For example add the client certificate into a specific store such as Current User or Local Computer 29 Appendix B Web Services Development in Java This section focuses on CC SG specific topics regarding WS client development in Java In This Chapter Choose a WS Library states nm nine 30 Certificates information for Java userg 0 44 6 4 30 Setting the CCSG 000 31 Calling a Web Services eite estonien 32 Sample Application for JaVa cisco ara 32 Choose a WS Library As of this writing Java API for XML Web Services JAX WS 2 1
41. static string session id static void quit CCAuthentication AuthenticationAndAuthorizationS erviceClient auth_service if auth service null try CCAuthentication signOff sign off new CCAuthentication signOff sign off String 1 user sign off String 2 session id CCAuthentication signOffResponse response auth service signOff sign off Raritan 42 Appendix C Web Services Development in C Console WriteLine signOff Response response result catch Exception exception Console WriteLine exception ToString Console WriteLine Press a key to exit Console ReadKey true Environment Exit 0 static void Main string args ServicePointManager ServerCertificateValidationCallba ck delegate Object obj X509Certificate certificate X509Chain chain SslPolicyErrors errors X509Certificate server certificate X509Certificate CreateFromCertFile G C Ncc certificat e cer return server certificate Equals certificate y CCAuthentication AuthenticationAndAuthorizationServic eClient auth service Raritan Appendix C Web Services Development in C new CCAuthentication AuthenticationAndAuthorizationServic eClient auth service ClientCredentials ClientCertificate SetC ertificate StoreLocation CurrentUser StoreName My X509FindType FindBySubjectName 10 0 0 150 servi
42. to an interface using access method application provided by CC SG This URL can be used as the path for a web browser or any HTML aware application to initiate the connection via the chosen application and destination The signOn method must have previously been called for this user e Parameters String sessionID String interfacelD CC SG generated string which uniquely identifies the interface within CC SG String accessApplicationld CC SG generated string which uniquely identifies the application type within CC SG e return value URLObject zie Raritan i Chapter 2 API Definitions getAccessMethodsForNode This operation retrieves all the available access methods applications for a given node in the form of an array Each element in the array has an indicator to denote whether the passed in username has access to particular applications e parameters String nodeName name based on the configured name in CC SG The node name that the user enters in the CC SG is not guaranteed to be unique so the system appends a number in parentheses to make the name unique For example the name MyServer becomes MyServer 1 if another node is already using that name String username CC SG user for which the Access Methods are to be returned return value AccessMethod getAccessMethodsForNodeByInterfacelD This operation retrieves the interface information that defines a particular access method b
43. x C Web Services Development in C 45 Index A Access Information 4 AccessMethod 9 Add Web Services API Client Configuration on CC SG 1 2 29 addAssociationToNode 16 addCategory 26 addElementToCategory 27 addUser 20 addUserToGroup 20 API Definitions 6 AssociationData 10 Authentication and Authorization Services 8 AuthenticationAndAuthorizationException 8 6 Calling a Web Service 2 Category Management 25 CategoryData 25 CCSGUser 18 Certificate Management 28 Certificates 1 4 Certificates information for Java users 30 Choose a WS Library 30 Common Data Types 6 Connecting to CC SG 1 Constructing a URL from URLObject 12 Conventions 6 D Data Types 7 8 9 18 21 25 deleteAssociationFromNode 16 deleteCategory 26 deleteElementFromCategory 27 deleteReport 23 25 deleteUser 20 deleteUserFromGroup 21 E editCategory 26 editUser 20 G getAccessMethodsForNode 14 getAccessMethodsForNodeBylnterfacelD 14 getAllUsers 19 Raritan getCategory 25 getCCSGAppletURL 13 getCCSGHTMLClientURL 13 getinterfaceURL 13 getNodeByAssociation 15 getNodeBylInterfaceName 15 getNodeByName 14 getNodePower 17 getNodesForUser 15 getReportRecords 24 getSystemInfo 8 getUser 19 Installing the Client Certificate into a Key Store Microsoft Windows XP 29 InterfaceAvailabilityAndStatus 10 InterfaceData 10
Download Pdf Manuals
Related Search