Raritan Computer CC-WSAPI-0B-v5.1.0-E manual

Copyrigh t © 2011 Raritan, In c. CC -WSAPI- 0B -v5.1.0-E February 2011 255 - 80 - 0004 - 00 CommandCenter Sec ure Gateway WS -API Programm ing Guide Release 5.1[...]

This docum ent contains proprietary inform ation that is protected b y copyright. All rights reserv ed. No part of this docum ent ma y be photocopied, re produced, or translated into another language without express prior written co nsent of Raritan, I nc. © Copyright 2011 Rar itan, Inc. All third -party soft ware and hardware m entioned in this d[...]

iii Contents Chapter 1 Introduction 1 Connecting to CC- SG .................................................................................................................... 1 Add Web Services A PI Client Conf iguration on CC - SG ...................................................... 2 Access Inform ation ........................................[...]

Contents iv A ppendix A Certificate Management 28 Java keytool ................................................................................................................................ . 28 OpenSSL ..................................................................................................................................... 28 Saving t[...]

1 W eb Servi ces API uses s tandardized W eb Services technologies to allow a client m achine to perform node, power, user, and logging managem ent services. This client is independent of the CC -SG, but aim s to provide the sam e capabilities that the CC -SG's HT ML-based Access Cl ient provides, through use of the API and a T CP/IP network .[...]

Chapter 1 : Introduction 2 3. Download W SDL files from the CC- SG. You can use a web browser or a simple client lik e wget to access the W SDL URLs. See W SDL URLs (on page 4) 4. Choose a W S client library for y our target lang uage. 5. Use the tools pro vided with your chosen W S client library to generate stubs in your target lang uage. Each st[...]

Chapter 1 : Intro duction 3 a. Encryption Mode: If Require AES Encr yption between Client and Server is selected in the Adm inistration > Security > En cryption screen, AES-128 is the default. If AES is not r equired, DES 3 is the default. b. Private Key Length: 102 4 is the default. c. Validity Period (da ys): Maxim um 4 numeric characters .[...]

Chapter 1 : Introduction 4 A ccess Information WSDL URLs http://CC_IP_ADDRESS:8080/CommandCenterWebServices/Au thenticationAndAuthorizationServicePort?wsdl http://CC_IP_ADDRESS:8080/CommandCenterWebServices/No deManagementServicePort?wsdl http(s)://CC_IP_ADDRESS:8080/CommandCenterWebServices /UserManagementServicePort?wsdl https://CC_IP_ADDRESS:808[...]

Chapter 1 : Intro duction 5 USER is the plain us er nam e and MODULE is the nam e that the administrator gave the remote module conf iguration in CC -SG.[...]

6 In This Chapter Conventions ............................................................................................... 6 Comm on Data Types ................................................................................. 6 System Managem ent ................................................................................. 7 Authentication a[...]

Chapter 2 : AP I Definitions 7 System Management This set of services is f or general CC-SG s ettings and information. http(s)://CC_IP_ADD RESS:8080/Comm andCenterW ebServices/System ManagementSer vicePort?wsdl Data Types SystemManagementException Exception returned f or all errors s pecific to system m anage ment.  Elements  String code – [...]

Chapter 2 : API Definition s 8 Services getSystemInfo Retrieve inform ation about the CC- SG.  parameters  String sessionID  return value  SystemInfo A uthentication a nd Authorization Services This set of services is f or logging into an d out of CC- SG. http://CC_IP_ADDRESS:8080/CommandCenterWebServices/Au thenticationAndAuthorization[...]

Chapter 2 : AP I Definitions 9 signoff() This operations signs off (log out) a particul ar user from CC -SG. The application can have m ultiple users logged in.  String username - user nam e that is logging out via the W S- API client  String sessionID  return value void Unsupported Authentication and A ut horization Ser vices The followin[...]

Chapter 2 : API Definition s 10  String applicationId - CC -SG generated str ing which uniquel y identifies the access ap plication type within CC -SG for out- of - band access designate d for use within CC -SG. Str ing is null if not applicable to t he interface.  boolean userAuthori zedForMethod - value of the auth orization for the user to[...]

Chapter 2 : AP I Definitions 11  String deviceNam e i.e the nam e of the Raritan device. T his field is filled in onl y for out- of -band i nterfaces; other wise, it the empty string.  String nam e -  String id - Unique iden tifier referenc ed by AccessMethod  String description - User desc ription of the interface  String type - Fun[...]

Chapter 2 : API Definition s 12 URLObject Components to form a URL to access the CC -SG.  Elements  String protocol - the protocol used - either http or https  String port - the T CP port to be used for c onnecting to the interface: port 80 or port 443.  String path - the path to the actual webservice servlet  String tokenKey - the n[...]

Chapter 2 : AP I Definitions 13 Services getCCSGAppletURL This operation retr ieves the full URL to the CC-SG Adm in Client applet in order to launch the m ain CC-SG c lient. When this URL is o pened in a browser it will disp lay the main CC- SG client, if the sess ionID is valid, or the login screen, if the sess ionID is invalid.  parameters ?[...]

Chapter 2 : API Definition s 14 getAccessMethodsForNode This operation retr ieves all the available access methods (applicat ions) for a given node in th e form of an arra y. Each element in the arra y has an indicator to denote whether the passed in usernam e has access to particular applications.  parameters  String nodeName - name based on[...]

Chapter 2 : AP I Definitions 15 getNodeByInterfaceName Retrieves nodes b y the nam e of the interface.  parameters  String sessionID  String interfaceNam e - Interf ace name to fi nd (accepts wildcards _ and %)  return value  NodeData[] getNodeByAssociation Find a node based on t he categor y label applied to it.  parameters  S[...]

Chapter 2 : API Definition s 16 addAssociationToNode Associate the node with one or m ore category values  parameters  String sessionID  String nodeNam e - The unique nam e of the node to m odify  AssociationData[]ass ociations  return value  boolean true on success deleteAssociationFromNode Disassociate the no de from one or m or[...]

Chapter 2 : AP I Definitions 17 getNodePower Returns the power stat us of each interface of the node, including t he status of the lates t power operation. The user mus t have permission to access the node. In addition to the norm al states, the availabi lity state of each interface will be set to “Processing” if the state is pending a change b[...]

Chapter 2 : API Definition s 18  power on  power off  power cycle  graceful shutdown  suspend  Integer sequenceInterv al – T he interval, in seconds, be tween successive operations of the specified power in terfaces. Applicable to power on and power of f only.  String reasonForAcces s – T ext used to track ac cess by user, [...]

Chapter 2 : AP I Definitions 19  Integer passwordExpira tionPeriod – T he user will have to reset their password after th is many days (required if passwordExpirationEna bled is true). T his value will always be clear if this feature is disa bled.  boolean forcePasswor dChange - W hen true, the user wil l have to change their pass word on t[...]

Chapter 2 : API Definition s 20 addUser Add a new user conf iguration to the CC -SG.  parameters  String sessionID  CCSGUser user – T he new user's settings.  return value  boolean true editUser Change an existing us er's settings, excluding gro ups.  parameters  String sessionID  CCSGUser user – T he new user&[...]

Chapter 2 : AP I Definitions 21  return value  boolean true deleteUserFromGroup Remove a user fr om a group to control the ir access of the CC -SG. Note: If this operation deletes all of a user's grou ps, then the user itself shall be deleted.  parameters  String sessionID  String userName - The nam e of the user to m odify. [...]

Chapter 2 : API Definition s 22  Access Audit  Access Connection  Authentication  Error  Power  Tasks  User Maintenance  String mess age – The m essage text describing the user acti vity.  String deviceNam e – The m anaged device the report entr y corresponds to, pro vided for mess age type Access Connection.  Stri[...]

Chapter 2 : AP I Definitions 23  String mess age – Specific error m essage. Services runReport Returns a log repor t formed using the request parameters . Reports created via th e W S API will show up as sc heduled reports with the name W S Report Task in the CC-SG Adm in Client in the Administration > T asks section. CC- SG Admin Client u [...]

Chapter 2 : API Definition s 24  Access Audit  Access Connection  Authentication  Error  Power  Tasks  User Maintenance  String mess age – Restrict results to those containing this message. The onl y supported wildcard is th e asterisk . Optional: may be null or em pty.  Integer numberO fRecordsToGet – T he maximum nu[...]

Chapter 2 : AP I Definitions 25 deleteReport Delete a previousl y requested report; other wise, reports are delete d after the user session is term inated.  parameters String sessionID  String reportID  return value  boolean true Category Management This set of services is f or getting and setting cate gories f or CC -SG nodes. Data Typ[...]

Chapter 2 : API Definition s 26 addCategory Add a new categor y to CC-SG.  parameters  String sessionID  String nam e - Unique name to identif y the categor y  boolean node - Applicable to nodes  boolean device - A pplicable to devices  String type - Data t ype of elem ents: "String" or "Integer"  return val[...]

Chapter 2 : AP I Definitions 27 addElementToCategory Add one or m ore values to the spec ified categor y  parameters  String sessionID  String category - The unique nam e identifying the categor y  String[]elements - Each entr y i n this arra y is a value for the category.  return value  boolean true on success renameElementInCate[...]

28 This appendix contai ns some tips on m anaging certificates. See th e respective com pany's documentation for m ore details. In This Chapter Java keytool ............................................................................................. 28 OpenSSL ...................................................................................[...]

Appendix A : Certificate Ma nagemen t 29 For exam ple: https://10.0.0.101:944 3/CommandCenterW ebServices/Authent ication AndAuthorizationService Port?wsdl 2. A Security Alert appears . Click View Certif icate. 3. Click Details then Co py to File. 4. Use the Certificate Exp ort W izard to save the certificate to a f ile. Installing the Client Certi[...]

30 This section focuses on CC-SG s pecific topics regarding W S client development in Java. In This Chapter Choose a W S Library .............................................................................. 30 Certificates inform ation for Java users .................................................... 30 Setting the CCSG Ad dress ................[...]

Appendix B : Web Service s Develo pment in Java 31 Setting the CCSG Address Downloading the W SDL files from port 8080 of the CC- SG is the def ault source of the W SDL files, however, their co ntents will ref lect port 8 080 of your CC-SG. Further, you m ight wish to use your W S client with a different CC-SG or you might change t he CC-SG's [...]

Appendix B : Web Service s Develo pment in Java 32 Call the m ethod from your application f or each service object. T his example uses Authen ticationAndAuthor izationService: CCSGAuthenticationAndAuthorizationService service = new CCSGAuthenticationAndAuthorizationService(); AuthenticationAndAuthorizationService service_port = service.getAuthentic[...]

Appendix B : Web Service s Develo pment in Java 33 /* * 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 [...]

Appendix B : Web Service s Develo pment in Java 34 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 i[...]

Appendix B : Web Service s Develo pment in Java 35 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[...]

Appendix B : Web Service s Develo pment in Java 36 System.err.println("Could not read input."); return null; } if( name.equals("") ) return null; return name; } public static void main (String[] args) { String user = "gregor"; String password = "pass123"; String session = ""; String current_name, ne[...]

Appendix B : Web Service s Develo pment in Java 37 { 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: " ); ne[...]

Appendix B : Web Service s Develo pment in Java 38 } 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()" ); }[...]

39 The following sections d escribe how to create a W eb Services client f or the CCSG written in C#. T his descript ion is based on Microsof t Visual Studio 2008 and IE6 ru nning on W indows XP. Other metho ds of W eb Service creation are available in Visual St udio 2008, but this docum ent solely covers services through W indow s Comm unication F[...]

Appendix C : Web Service s Develop ment in C# 40 4. Set a call back for ServerCertificate ValidationCallback so that the client will accept the CCSG 's server certif icate. A simple m ethod is to trust the certificate if it matches the CCSG ser ver certificate that you have explicitl y saved from the CCSG. See Sa ving the CCSG's Server Ce[...]

Appendix C : Web Service s Developmen t in C# 41 using System; using System.Collections.Generic; using System.Linq; 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&quo[...]

Appendix C : Web Service s Develop ment in C# 42 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.Se[...]

Appendix C : Web Service s Developmen t in C# 43 new CCAuthentication.AuthenticationAndAuthorizationServic eClient(); auth_service.ClientCredentials.ClientCertificate.SetC ertificate( StoreLocation.CurrentUser, StoreName.My, X509FindType.FindBySubjectName, "10.0.0.150"); // service parameters CCAuthentication.signOn sign_on = new CCAuthen[...]

Appendix C : Web Service s Develop ment in C# 44 // renameNode service CCNode.NodeManagementServiceClient node_service = new CCNode.NodeManagementServiceClient(); node_service.ClientCredentials.ClientCertificate.SetC ertificate( StoreLocation.CurrentUser, StoreName.My, X509FindType.FindBySubjectName, "10.0.0.150"); CCNode.renameNode renam[...]

Appendix C : Web Service s Developmen t in C# 45 } } }[...]

[...]

47 A Access Inform ation • 4 AccessM ethod • 9 Add Web Services A PI Client Conf iguration on CC - SG • 1, 2, 29 addAssociationToNod e • 16 addCategory • 26 addElementT oCategory • 27 addUser • 20 addUserToGroup • 20 API Definitions • 6 AssociationData • 10 Authentication and Au thorization Services • 8 AuthenticationAndAut ho[...]

Index 48 S Sample Application for C# • 40 Sample Application for J ava • 32 Saving the CCSG's Ser ver Certificate from a W eb Brow ser (IE6) • 28 Services • 8, 13, 19, 23 , 25 setNodePower • 17 Setting the CCSG Ad dress • 31 signoff() • 9 signOn() • 8 System Managem ent • 7 SystemInfo • 7 SystemManagem entException • 7 U [...]

[...]

U.S./Canada/Latin America Monday - Friday 8 a.m. - 6 p.m. ET Phone: 800- 724 -8090 or 73 2-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 China Beijing Monday - Friday [...]