Solstice Enterprise Manager 4.1 Developing CORBA Applications | ![]() ![]() ![]() ![]() ![]() |
Interacting With SEM CORBA Gateway
The CORBA applications need to interact with SEM CORBA Gateway to perform network management functions. You should know the interfaces and methods exposed by the SEM CORBA Gateway in order to develop these applications which will interact with SEM CORBA Gateway.
This chapter describes the following topics:
- Section 2.1 JIDM Interfaces
- Section 2.2 Interacting With Solstice EM CORBA Request Gateway
- Section 2.3 Non JIDM interfaces
- Section 2.4 Interacting With Solstice EM Event Gateway
- Section 2.5 Interacting With Solstice EM Metadata Gateway
- Section 2.6 Controlling Access and Authorization
- Section 2.7 Enabling Access From Non-Unix Environments
- Section 2.8 Enabling Internet Connections to Solstice EM via CORBA Gateways
- Section 2.9 Providing an Extra Layer of Authentication
The SEM CORBA Gateway is compliant with Joint Inter-Domain Management (JIDM) standards and provides a set of interfaces based on these standards. The SEM CORBA Gateway is designed to work with standard management reference models (such as SNMP/IP and CMIP/OSI). The interfaces defined and implemented by the SEM CORBA Gateway define the interaction between it and applications. Hence, it is critical for developing efficient applications to understand these interfaces.
Note You are assumed to have installed the SEM CORBA ToolKit and setup the development environment. All examples cited henceforth are more appropriate in a scenario in which the ToolKit has been installed and configured.
2.1 JIDM Interfaces
The JIDM Standards specify interfaces that define a basic set of services, of which the SEM CORBA Gateway implements a subset. This section lists the implemented interfaces sorted into different categories.
2.1.1 Interfaces Required for Manager Applications
The following interfaces are required for manager (client) applications:
- ProxyAgent interface
- ProxyAgentController interface
- ProxyAgentFinder interface
- EventPort interface
- EventPortFactory interface
Note Throughout this document, the terms "manager application" and "client" are used interchangeably.
The ProxyAgent interface implements the following CMIS commands required for a client application to interact with the SEM CORBA Gateway:
- cmis_get
- cmis_set
- cmis_create
- cmis_create_sync
- cmis_delete
- cmis_action
2.1.2 Interfaces Required for Agent Applications
The following interface is required for agent applications:
- EventPortFinder interface
2.1.3 OSI Management Interfaces
The Open System Interconnection (OSI) management interface definitions provided by JIDM standards (OSIMgmt.idl) include features that are specific to the OSI management model and support the following functionality:
- Scope and filtering
- Naming of objects according to OSI management principles
- Creation and deletion of objects according to OSI principles
- Creation of DomainPorts and EventPorts associated with OSI AE-titles
The SEM CORBA Gateway implements the following OSI management interfaces which are a subset of the JIDM standards:
- ProxyAgent interface derived from JIDM::ProxyAgent
- LinkedReplyHandler and EndOfRepliesHandler interfaces
The ProxyAgent interface provides all the OSI network management functionality.
The LinkedReplyHandler and EndOfRepliesHandler interfaces facilitate implementation of the asynchronous model of communication.
Note Appendix A provides more information on the IDL files and interfaces implemented by the SEM CORBA Gateway.
FIGURE 2-1 shows the interfaces exposed by the SEM CORBA Gateway components that are the basis on which applications can be developed.
![]()
FIGURE 2-1 Interfaces Exposed by SEM CORBA Gateway Components12.2 Interacting With Solstice EM CORBA Request Gateway
The Request Gateway (RGW) is primarily designed to handle the initial CORBA client connections to the gateway and CMIS requests or responses. Hence, it implements the interfaces that support the following functionality:
- Connecting clients for the first time
- Authenticating clients
- Accessing the managed object domain and creating JIDM::ProxyAgent
- Handling CMIS requests and responses
2.2.1 Connecting Clients for the First Time
A client application (for example a CORBA manager application) must be connected to the SEM CORBA Gateway before you can carry out any manager functions. The steps involved in connecting to the Gateway are:
- Getting the ProxyAgentFinder object
- Creating an AuthenticationClient
- Encrypting the user profile
- Finding/Creating the ProxyAgent
A detailed explanation of each step, and a code example follow.
1. Get the ProxyAgentFinder object
- The first step is to get a reference to the ProxyAgentFinder, an interface implemented by the RGW. This enables client programs to get access to a given managed object domain.
- The client application must initialize the Object Request Broker (ORB), initialize the Object Adapter, and resolve the root naming context before the Proxy Agent Finder can be resolved.
2. Create an AuthenticationClient
- The second step in connecting to the Gateway is to create an AuthenticationClient. The Solstice EM provides UNIX CLEAR encryption and decryption for authenticating users, but you can implement an authentication class and integrate it with Solstice EM (see Section2.9 Providing an Extra Layer of Authentication).
3. Encrypt the user profile
- The third step is to specify the user profile in the JIDM::Criteria structure. The authentication client created in Step2, provides a method for encrypting the user profile. The encrypted user profile is specified in the JIDM:Criteria structure.
4. Find/Create the ProxyAgent
- The user profile provided as part of criteria is validated before finding or creating the ProxyAgent.
- The ProxyAgentFinder has a method called access_domain that locates the ProxyAgent, for the key and the criteria that are passed as parameters. criteria is the attribute that is specified in Step3, with the encrypted user profile.
The following code segment shows how to get connected to the SEM CORBA Gateway.
For detailed working examples, refer to /opt/SUNWconn/em/src/corba_gateway/requests directory of the Solstice EM package.
2.2.2 Authenticating Clients
Authentication of clients is done by ProxyAgentFinder. The ProxyAgentFinder implementation uses internal Solstice EM functionality to check whether the supplied user profile refers to a valid user of Solstice EM and if so, the ProxyAgentFinder returns a reference of the ProxyAgent to the client.
2.2.3 Accessing the Managed Object Domain and Creating JIDM::ProxyAgent
Managed objects are classified into domains. Manager applications that need to interact with a managed object, must first get access to its domain. The SEM CORBA RGW creates a ProxyAgent whenever a client gains access to the domain. The RGW searches through its list of ProxyAgents for any pre-existing ProxyAgent that matches the criteria, and if one is found, it returns a reference for it back to the client application. If a ProxyAgent for the required criteria is not found, the ProxyAgentFinder interface creates a new ProxyAgent and returns its reference to the client application.
2.2.4 Handling CMIS Requests and Responses
The RGW is solely responsible for handling requests sent by manager applications and the responses sent back to them. The RGW accepts the manager requests in IDL, translates them into low-level PMI requests, and sends them to the Solstice EM MIS. The Solstice EM MIS responds to the RGW. The RGW then translates these responses back into IDL format and sends them back to the CORBA application.
The RGW implements the OSI management features specified by the JIDM standards and hence supports those specific to OSI management. The OSI management implementation of the RGW includes a ProxyAgent interface (derived from JIDM::ProxyAgent) and includes methods to support all the OSI management CMIS operations, such as get, set, and create.
2.3 Non JIDM interfaces
The SEM CORBA Gateway provides an extension by means of text based CMIS commands, listed in Section2.1.1 Interfaces Required for Manager Applications.
The following text commands are supported by implementing an interface which is derived from JIDM::ProxyAgent.
- cmis_get_text
- cmis_set_text
- cmis_create_text
- cmis_create_sync_text
- cmis_delete_text
- cmis_action_text
For details on the arguments to be passed to these commands, refer to the examples in the EM_HOME/src/corba_gateway/examples directory. Also refer to the IDL files ASN1TypesExt.idl, CMIExt.idl, and OSIMgmtExt.idl.
2.4 Interacting With Solstice EM Event Gateway
The Solstice EM Event Gateway (EGW) primarily handles the delivery of CMIS events/notifications to CORBA clients or manager applications. To listen to events, the clients or manager applications created by you must handle the following functionality in the given order:
- Creating and registering event ports (using the EventPort interface)
- Creating event discriminating filters (EDFs) using M-create
- Issue of cmis_create() commands on the ProxyAgents implemented by RGW.
The Solstice EM EGW implements the following three interfaces specified by JIDM standards:
- EventPort interface
- EventPortFactory interface
- EventPortFinder interface
Apart from the three JIDM standard interfaces, the Solstice EM EGW provides another interface called EventPortRegistry.
These interfaces and instructions for the interfacing of client/manager applications are described in the following sections.
2.4.1 Gaining Access to a Manager or Client Application
A managed object gains access to a manager or a client application, through the EventPort so that the event notifications can be forwarded to the manager. This port is created according to certain criteria and contains the title that identifies the manager domain. The Solstice EM event dispatcher (part of MIS) sets up a connection with the CosEventChannelAdmin::SupplierAdmin object associated with the JIDM::EventPort (implemented by the EGW) with the appropriate title.
2.4.2 Dynamically Creating JIDM::EventPort Objects
The EventPortFactory interface facilitates dynamic creation of JIDM::EventPort objects by providing the create_event_port() method. This interface is implemented by the EGW and basically does the following every time a new manager/client application registers with the EGW:
- Gets a reference to the CosEventChannelAdmin::SupplierAdmin that is to be used to receive events.
- Creates JIDM::EventPort with the criteria supplied by the manager application.
The following code example gives you the steps to follow for implementing a manager application.
CODE EXAMPLE 2-2 Creating a JIDM::EventPort and Registering for Events
// Example to show how to create JIDM::EventPort and register for events // Assumes ORB is initialized and naming service is resolved. CosNaming::Name name; name.length(1); name[0].id = CORBA::string_dup("EventPortRegistry"); name[0].kind = CORBA::string_dup(""); EventPortRegistry_var epr; try { CORBA::Object_var object = root_nc->resolve(name); epr = EventPortRegistry::_narrow(object); if (CORBA::is_nil(epr)) { cerr << "FAILED: Could not get EventPortRegistry\n"; exit(3); } } catch (const CORBA::Exception& e) { cerr << "FAILED: Could not resolve EventPortRegistry name\n"; exit(4); } cout << "PASSED: Accessing the EventPortRegistry\n" << flush; JIDM::EventPortFactory_var ep_factory; name[0].id = CORBA::string_dup("EventPortFactory"); try { CORBA::Object_var object = root_nc->resolve(name); ep_factory = JIDM::EventPortFactory::_narrow(object); if (CORBA::is_nil(epr)) { cerr << "FAILED: Could not get EventPortFactory\n"; exit(3); } } catch (const CORBA::Exception& e) { cerr << "FAILED: Could not resolve EventPortFactory name\n"; exit(4); } cout << "PASSED: Accessing the EventPortFactory\n" << flush; JIDM::EventPortFinder_var ep_finder; name[0].id = CORBA::string_dup("EventPortFinder"); try { CORBA::Object_var object = root_nc->resolve(name); ep_finder = JIDM::EventPortFinder::_narrow(object); if (CORBA::is_nil(epr)) { cerr << "FAILED: Could not get EventPortFinder\n"; exit(3); } } catch (const CORBA::Exception& e) { cerr << "FAILED: Could not resolve EventPortFinder name\n"; exit(4); } cout << "PASSED: Accessing the EventPortFinder\n" << flush; // Find an EventPort with a right key and criteria JIDM::Key key; key.length(1); key[0].id = CORBA::string_dup("OSI Management"); key[0].kind = CORBA::string_dup("XSM environment"); JIDM::Criteria event_criteria; event_criteria.length(2); event_criteria[0].name = "domain title"; event_criteria[0].value <<= CORBA::string_dup(ae_title); event_criteria[1].name = CORBA::string_dup("ProxyAgent Access Criteria"); event_criteria[1].value <<= criteria; //Find/Create Event Port try { CosEventChannelAdmin::SupplierAdmin_var supplier_admin = epr->find_event_port(key, event_criteria); } catch (const JIDM::NoEventPort& e1) { cout << "PASSED: Finding EventPort with wrong key.\n" << "\tAs expected, NoEventPort exception was raised\n" << endl; } catch (const CORBA::Exception& e) { cerr << "FAILED: Finding EventPort with wrong key" << e._name() << "\nExpected to get NoEventPort exception\n"; exit(5); } // Resolve the EventChannel name[0].id = CORBA::string_dup("event_channel"); CosEventChannelAdmin::EventChannel_var channel = resolve_name<CosEventChannelAdmin::EventChannel>(root_nc,name); CosEventChannelAdmin::SupplierAdmin_var supplier_admin = channel->for_suppliers(); try { JIDM::EventPort_var ep = epr->create_event_port(key, event_criteria, supplier_admin); } catch (const CORBA::Exception& e) { cerr << "FAILED: Could not create event port\n" << e._name()<< endl; exit(8); } // Event port has been successfully created.... cout << "PASSED: Event port creation\n" << flush; //Listen to events by creating the push_consumer object // Set policy for the root POA policies[(CORBA::ULong)0] = root_poa->create_lifespan_policy( PortableServer::TRANSIENT); // The PushConsumerImpl is derived from POA_CosEventComm::PushConsumer // and implements method push to receieve events. PushConsumerImpl push_consumer; PortableServer::POAManager_var rootManager = root_poa->the_POAManager(); root_poa->activate_object(&push_consumer); rootManager->activate(); //--------------------- end of example 2.2 ------------------------------------
Note - This example activates a POA push consumer object.
2.4.3 Obtaining References to JIDM::EventPort
CORBA manager applications can obtain references to JIDM::EventPort objects by using the EventPortFinder interface. This interface provides a find_event_port method which returns a reference to the CosEventChannelAdmin::SupplierAdmin object.
2.4.4 Finding a JIDM::EventPort given the AE-title
The EventPortRegistry interface provides a method for finding a JIDM::EventPort given the AE-title. The current implementation of SEM CORBA Gateway has a one-to-one relationship between titles and event ports.
2.5 Interacting With Solstice EM Metadata Gateway
The Solstice EM Metadata Gateway (MGW) implements the Metadata Repository interface, which provides methods to access ASN1 metadata in Solstice EM. The MGW is independent of the CORBA Gateway of the JIDM, which means that it can be used by any application (even a non-JIDM application) to obtain information about events or attributes, or to traverse the type tree.
See Chapter 5 and Chapter 6 for examples on how to interact with the Solstice EM MGW.
2.6 Controlling Access and Authorization
SEM CORBA Gateway access control involves two aspects:
- Encrypting and decrypting the user profile
- Authenticating user profiles
2.6.1 Encrypting and Decrypting the User Profile
Encryption and decryption are implemented in the following two libraries:
- /opt/SUNWconn/em/lib/libauth_server.so
- /opt/SUNWconn/em/lib/libauth_client.so
These libraries are built based on implementation of classes declared in the following two header files respectively:
- /opt/SUNWconn/em/include/auth_helper/auth_serv er_handle.hh
- /opt/SUNWconn/em/include/auth_helper/auth_clie nt_handle.hh
You can use these class definitions to implement your own encryption and decryption.
Specific steps to be performed are as follows:
1. Implement *.cc files for auth_server_handle.hh2. Implement *.cc files for auth_client_handle.hh3. Create a Makefile to compile the *.cc files and to build the libraries (create two separate libraries, one for the client and one for server object files).4. Make a backup of the client and server libraries provided with Solstice EM.5. Stop SEM CORBA services.6. Replace (overwrite) the default libraries with those created in Step3.7. Restart SEM CORBA services.2.6.2 Authenticating User Profiles
The authentication of user profiles is implemented as part of ProxyAgentFinder. To be able to successfully connect to the Gateway, every application that connects to the SEM CORBA Gateway must provide a correct user profile which is authenticated while accessing the ProxyAgentFinder.
2.7 Enabling Access From Non-Unix Environments
The SEM CORBA Gateway can be accessed from any environment, irrespective of the machine, the operating system, or the programming language. The only requirement is that the ORB used to develop the client applications use Object Management Group's (OMG's) Internet Inter-ORB Protocol (IIOP) to communicate with the SEM CORBA Gateway.
The examples included with the Solstice EM package in the /opt/SUNWconn/em/src/corba_gateway/requests directory implement sample clients in both Java and C++.
2.8 Enabling Internet Connections to Solstice EM via CORBA Gateways
The SEM CORBA Gateway is a set of objects. The applications that wish to connect to the gateways must obtain references of these objects.
The SEM CORBA implementation publishes the references of objects through the naming service and all the gateways are accessed by resolving the naming service.
A CORBA Gateway can be accessed from anywhere on the network, as long as client applications use IIOP. The firewalls and the gateways can be programmed to pass IIOP messages and hence it is possible for a client application to communicate with a CORBA Gateway from anywhere on the network.
2.9 Providing an Extra Layer of Authentication
You can use the SEM CORBA Gateway to add an extra layer of authentication by providing the following exposed classes:
- AuthenticationClientHandle
- AuthenticationClientBody
- AuthenticationClient
- AuthenticationServerHandle
- AuthenticationServerBody
- AuthenticationServer
Client applications that want to connect to the SEM CORBA Gateway use AuthenticationClientHandle to initialize the AuthenticationClient. The following code example shows how to initialize the AuthenticationClient.
CODE EXAMPLE 2-3 Initializing AuthenticationClient
new AuthenticationClientHandle("UNIX_CLEAR"); char user_name[128]; cout << "Enter User Name: " << flush; cin >> user_name; const char* password_prompt = "Enter Password: "; // getpassphrase return a pointer to static data which should not be // deleted char* raw_password = getpassphrase(password_prompt); //Assuming that a_criteria is already declared and //first entry in the criteria is JIDM_MANAGER_TITLE a_criteria[1].name = CGWGlobal::JIDM_USER_PROFILE; a_criteria[1].value = *(ac->encrypt_user_profile( user_name, raw_password, NULL));The AuthenticationClientHandle class implements the following two useful methods:
- get_user_profile(), and
- encrypt_user_profile()
The current Solstice EM-supplied implementation of the AuthenticationServerHandle class is used only for decrypting the user profiles sent by client applications. The method implemented for this purpose by AuthenticationServerHandle is decrypt_user_profile().
Application developers can extend these classes to implement additional layers of security.
Note Implementations of the exposed functions mentioned earlier must retain their signatures and also the names of the shared libraries are to be retained as per the ToolKit requirement.
1 The interfaces shown with dotted lines are created dynamically.
Sun Microsystems, Inc. Copyright information. All rights reserved. |
Doc Set | Contents | Previous | Next | Index |