Integrated IBM Systems Director via REST API

IBM Systems Director version 6.1 is a platform management foundation that streamlines the way physical and virtual systems are managed across a multi-system environment. IBM Systems Director version 6.1.2 provides RESTful web services which allows users to utilize System Director's powerful management tasks by simply relying on named resources rather than its web console and command line. This article gives you the experience on how to make customer system management software integrated with IBM Systems Director via the RESTful web services. Besides learning to use the RESTful web service client to implement the basic task of IBM Systems Director, this paper will introduce to you how to receive the asynchronized message from IBM Systems Director.

Share:

Da Shuang He (hedas@cn.ibm.com), Staff Software Engineer, IBM China Development Lab

Photo of Da Shuang HeDa Shuang He is a staff software engineer at the IBM China Development Lab in Shanghai, China. He is currently working on system management software focusing on IBM BladeCenter and System X management and configuration. He is also interested in cloud computing and green technology.



Yao Wen Huang (hyaowen@cn.ibm.com), Software Engineer, IBM China Development Lab

Photo of Yao Wen HuangYao Wen Huang is a software engineer at the IBM China Development Lab in Shanghai. He has worked on system management software for three years and focuses on IBM BladeCenter and System X management and configuration. He is also interested in Java™, OSGi, and web services technology.



Cao Jin (caojin@cn.ibm.com), Software Engineer, IBM China Development Lab

Photo of Cao JinCao Jin is a software engineer at the IBM China Development Lab in Shanghai. He has worked on system management software for three years, and he is also interested in Java and OSGi technology.



Yinjun Xu (xuyinjun@cn.ibm.com), Software Engineer, IBM China Development Lab

Photo of Yinjun XuYinjun Xu is a software engineer at the IBM China Development Lab in Shanghai, China. He is currently working on system management software focusing on IBM BladeCenter and System X management and configuration.



10 August 2010

Introduction

RESTful web services have become more and more popular because they're lightweight, simple, and have the ability to directly transmit data over HTTP. For example, submitting a GET URL and obtaining the desired and readable response in your web browser are easily performed with RESTful web services.

IBM Systems Director version 6.1.2 is a platform management foundation composed of a set of common tasks and core management capabilities, including discovery, inventory, configuration, system health, monitoring, updates, event, and automation across managed systems.

IBM Systems Director allows for different kinds of programming languages and RESTful clients to leverage and integrate those management functionalities into their existing applications, like Java™ code, Perl, Ruby, Python and PHP. In addition, IBM Systems Director can also receive asynchronized messages via JMS.

This article discusses how you can implement one entire process for system discovery via RESTful web services and JMS in IBM Systems Director using the Java language. Moreover, you'll learn how to leverage RESTful web services to integrate your applications with IBM Systems Director for the purpose of achieving system management tasks.

Specifically, you will learn:

  • How to setup the secure connection between client and IBM Systems Director Server.
  • How to discover a system via RESTful web services in IBM Systems Director.
  • How to receive asynchronized message about the discovery completion from IBM Systems Director.
  • How to verify the result on IBM Systems Director.

Setup the secure connection between client and IBM Systems Director Server

To setup the secure connection between client and IBM Systems Director Server, it is necessary to extract the SSL certificate in IBM Systems Director Server and import it into the client application.

By default, IBM Systems Director server generates and owns a certificate named lwiks in the keystore, which is found at %install_root%\lwi\security\keystore\ibmjsse2.jks (the default password for this keystore is ibmpassw0rd). But, if the administrator of the IBM Systems Director server generates a different self-signed certificate or gets a signed certificate from a recognized certificate authority, you need to contact them for information about the certificate available for the used IBM Systems Director server.

First, you will use the ikeyman tool (provided in IBM Systems Director server JRE) to extract the SSL certificate from the server's keystore to a file. The ikeyman tool can be found in %install_root%\jre\bin\ikeyman.exe.

When executing the ikeyman.exe, the following application window will be prompted (see Figure 1). In that window, click the Open icon to locate the key store of IBM Systems Director server for loading this certificate (as seen on Figure 1).

Figure 1. A certificate shown on ikeyman application window
Screen shot of a certificate shown on ikeyman application window

Next, extract and save this certificate. Select the certificate and click the Extract Certificate button on the right bottom. In that dialog box, input the file name (for example, cert.arm) and location of the extracted file into that window (as seen on Figure 2).

Figure 2. Extract the certificate
Window for extracting the certificate to a file

After that, you will need to copy the extracted file onto the system that will run the client application.

The last step is to import that certificate into the key store of JRE environment used to run the client application (which can be a new or existing one). Execute the ikeyman tool on JRE environment running the client application, and the following window will be prompted (see Figure 3). Here, you will create a new key store as an example. In this window, click the New icon. Input the key store name and location (for example, c:\key.jks) for the new key store. After clicking the OK button, you will be asked to provide the password for the new key store. Enter your desired password (assuming to set the key store password as mykeystore). After finishing these steps, the new key store is created, and its related content is shown (as seen on Figure 3).

Figure 3. Create a new key store
Screen shot of creating a new key store

In the window above, click the Add button to open a window named 'Add CA's Certificate from a File'. In that window, select the extracted certificate file and click the OK button (as seen on Figure 4). Now the SSL certificate has been imported into the JRE environment, which will be used to run the client application.

Figure 4. Add a certificate into key store
Window of Add a certificate into key store

Note: besides using the ikeyman tool, you can also use another tool called keytool provided by JDK.

Implement system discovery process via RESTful web services and JMS provided by IBM Systems Director

Step 1: Set the certification and authentication information for the connection

The first step is to obtain the above key store file (which contains the imported certificate) and set the key store file path and password as system properties. Also, configure the authentication information to access the IBM Systems Director Server (including user id and password) so that consequent connections can be successfully made with IBM Systems Director Server.

Listing 1. Set the certification and authentication information for the connection
// the file contain the certification
 File certificateStore = new File(keystoreFile);
 // set Java properties for certificate store and password (for SSL connection).
  System.setProperty("javax.net.ssl.trustStore", certificateStore.getAbsolutePath());
  System.setProperty("javax.net.ssl.trustStorePassword", keystorePassword);
 // set userID/Password to the IBM Systems Director authentication.  
 //Authenticator class is used by the HttpsURLConnection class.
  Authenticator.setDefault(new Authenticator() {
       protected PasswordAuthentication getPasswordAuthentication() {
                return new PasswordAuthentication (user, password);
            }
        }
 );

Step 2: Create the https connection to specific RESTful web services and send corresponding request via this connection

You will be provided a common method to create the https connection to specific RESTful web services and send corresponding request via this connection. In many situations, you can directly use the server host name on the target URL. However, sometimes the host name of the machine running IBM Systems Director Server is not always registered into the DNS server, but the certificate contains the server host name information. So, in this situation, you need to declare to ignore the server host name by implementing one special HostnameVerifier sub-class, and then use the IP address on the targeted URL to connect with it during the connection.

Listing 2. Provide a common method to create the https connection to specific RESTful web services and send corresponding request via this connection
public HttpsURLConnection processRequest
(String resourceUri, String method, String requestBody)throws IOException {
        HttpsURLConnection secureConnection = null;
        URL url = new URL(resourceUri);
        HostnameVerifier hv = new HostnameVerifier() {
            public boolean verify(String hostname, SSLSession session) {
                return true;
            }
        };
        HttpsURLConnection.setDefaultHostnameVerifier(hv);
        secureConnection = (HttpsURLConnection) url.openConnection();
        secureConnection.setRequestMethod(method);        
secureConnection.setRequestProperty("content-type", "application/json");
        if(requestBody != null) {
            secureConnection.setDoOutput(true);
            OutputStreamWriter out = new OutputStreamWriter(
secureConnection.getOutputStream());
            out.write(requestBody);
            out.close();
        }
        return secureConnection;
    }

Step 3: Subscribe to the JMS topic about discovery status so as to be able to register the listener for receiving the message about discovery status change

IBM Systems Director provides a RESTful resource named jmssubscriptions to allow users to subscribe several JMS topics and receive asynchronous messages from IBM Systems Director. Here, you will send such a request to IBM Director Server through POST method so as to register the topic "Director.discovery.status".

Listing 3: Subscribe to the JMS topic about discovery status
// subscribe to the message topic 'Director.discovery.status'
String uri = this.urlString + "/jmssubscriptions";
String requestPayload = 
"{\"Topic\":\"Director.discovery.status\",\"Timeout\":200000, \"Version\":\"1.0.0\"}";
HttpsURLConnection dataConnection = processRequest(uri, "POST",
requestPayload);
int rc = dataConnection.getResponseCode();
// check if the response code is 201 that means new subscription added
if(rc != 201) {
System.out.println("FAIL: Unexpected return code: Expected 201 but got "+ rc);
   return;
}

Step 4: Send out the discovery request

IBM Systems Director provides one RESTful resource named discover to allow users to initiate a discovery to those systems specified by IP addresses. Here, you will send such a request to IBM Director Server through POST method.

Listing 4: Send out the discovery request
requestPayload = "{\"IPAddress\":[\"" + discoverIP + "\"]}";
uri = this.urlString + "/discover";
HttpsURLConnection dataConnection = processRequest(uri, "POST", requestPayload);
int rc = dataConnection.getResponseCode();
// check if the response code is 201 that means new discovery created
if(rc != 201) {
System.out.println("FAIL: Unexpected return code: Expected 201 but got "+ rc);
   return;
}

Step 5: Obtain the discovery identifier

In IBM Systems Director, each discovery job will be assigned to one specific identifier for it. After obtaining this discovery identifier, you can carry out further work, like monitoring or deleting this discovery status change and so on. The response on step 4 will contain the URI in the header with property location so we can get the location from the header and extract the discovery identifier from that location.

Listing 5: Obtain the discovery identifier
String location = dataConnection.getHeaderField("Location");
// extract the DiscoveryID
String identifier = location.substring(location.lastIndexOf("/Discovery**") + 1);
String identifier = identifier.replace("%23", "#");

Step 6: Register the listener for receiving the message about the specific discovery status change

IBM Systems Director uses Apache ActiveMQ as its JMS provider to allow users to receive asynchronous messages from IBM Systems Director. Users can use either standard Java JMS APIs or ActiveMQ APIs for it. Here, you will use ActiveMQ APIs to create the ActiveMQConnectionFactory instance and then create a TopicConnection with the IBM Systems Director server using that factory instance. Based on that TopicConnection, we can create a TopicSession and then a specific topic.

After obtaining the TopicSession and Topic, we will create a message consumer with filter and set our customized listener as the message listener of that consumer. Within this concrete listener, we implement the method onMessage () to process the message we get. Here we will only filter the message related to the discovery job we initialized on the above steps. At last, we start the TopicConnection and only listen to the discovery status messages about 60 seconds.

Listing 6: Register the listener for receiving the message about the specific discovery status change
// url for JMS connection
String url = "failover:tcp://" + this.ipaddress + ":61616"; 
String topicName = "Director.discovery.status"; 
// create connection to the Director JMS provider
ActiveMQConnectionFactory factory = new ActiveMQConnectionFactory(url);
TopicConnection connection = factory.createTopicConnection(systemUserID,systemPassword);
// create a topic session to the topic on the server
TopicSession session = connection.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
Topic  topic = session.createTopic(topicName);
// create a message consumer (with filter) to listen to incoming
messages related only to the DiscoveryID
MessageConsumer consumer = session.
createConsumer(topic, "DiscoveryID='"+ identifier+ "'");
consumer.setMessageListener(this.new MyListener());
// start the connection, listen for 60 seconds, end connection
connection.start();
Thread.sleep(60000);
connection.close();
Listing 7: this concrete implementation for MessageListener
class MyListener implements MessageListener {
    public void onMessage(Message message) {
        try {
            // print out the incoming message in string format
            System.out.println("Incoming message: "
                    + ((ActiveMQTextMessage) message));
            System.out.println("Percent complete: "
                    + ((ActiveMQTextMessage) message)
						.getStringProperty("PercentComplete"));
									 
         }catch(Exception e) {
              System.out.println("FAIL: Exception occurred retrieving message data.");
            }
        }
    }

Now you can receive all the asynchronized messages about that specific discovery status, and you can process these messages as needed. Moreover, you can use also listen to other topics with the specific filter as needed.

Step 7: Verify the result and perform more consequent actions

When executing these above steps, the system specified by the IP address will be discovered on the IBM Systems Director server. We can verify it via the Navigate Resources page after logging into the web console of IBM Systems Director Server.

After that, you can do more consequent operations like deleting completed discovery job, requesting access to that discovered system, etc.

Now, you have successfully demonstrated a RESTful web Service client to finish one entire process for the system discovery with IBM Systems Director.

Conclusion

With the RESTful API provided by IBM Systems Director, users can easily integrate the IBM Systems Director functions into their system management software.

In this paper, we showed you an example about the discover function; you can refer to the IBM Systems Director website to integrate more functions (like request access, inventory, monitor, event and so on) as a full integrated system management solution.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into AIX and Unix on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=AIX and UNIX
ArticleID=504649
ArticleTitle=Integrated IBM Systems Director via REST API
publish-date=08102010