2 Understanding Services Gatekeeper System Administration Tools

This chapter introduces Oracle Communications Services Gatekeeper configuration and administration.

About Services Gatekeeper Installation

The single-tier version of Services Gatekeeper is designed to deploy quickly on a single or clustered self-contained system. When you install the single-tier version of Services Gatekeeper, the resulting system already configured and ready to run. The multi-tier version of Services Gatekeeper includes all the features of a single-tier Services Gatekeeper, but is intended for larger and more complex implementation and requires configuration. You can extend it into a more robust and flexible environment.

For an overview of Services Gatekeeper features and the types of implementations, see ”Understanding Services Gatekeeper” in Services Gatekeeper Concepts.

About the Oracle WebLogic Platform

Services Gatekeeper is based on Oracle WebLogic Server. Many system-level configuration tasks are the same for both products. This chapter addresses the system-level configuration tasks that are unique to Services Gatekeeper. These tasks relate to network and security configuration and cluster configuration for the engine.

WebLogic Server configuration and other basic configuration tasks such as logging are addressed in the WebLogic Server documentation. This guide refers you to the WebLogic documentation for information where appropriate.

Services Gatekeeper configurations are built using a version of Oracle WebLogic Server 12c. See the Oracle Fusion Middleware 12c website for more information about WebLogic Server:

http://docs.oracle.com/middleware/1212/wls/index.html

Using the Administration Console to Configure Services Gatekeeper

Services Gatekeeper Administration Console is a graphical user interface (GUI) for configuring, managing, and provisioning Services Gatekeeper. The Administration Console is an extension of the WebLogic Server Administration Console.

About Using the Administration Console

Services Gatekeeper runs a WebLogic administration server for configuration which is accessible through the Administration Console. The Administration Console exposes the underlying JMX MBean attributes and operations in GUI form. These MBeans are also available for your to use programmatically.

Run an instance of the Administration Console on every system with an administration server.

The single-tier version of Services Gatekeeper uses a single administration server for the entire implementation. Run one instance of the Administration Console to configure the server.

Multi-tier Services Gatekeeper implementations however, generally run different administration servers for Services Gatekeeper and for the partner relationship management (PRM) portals. You run an Administration Console on each of those systems to administer them.

Starting and Using the Administration Console

At least one network tier server must be started before you can log in to the WebLogic Server Administration Console. Otherwise, the configuration settings do not display in the Administration Console. To see them, log in to WebLogic Server Administration Console again.

Logging in to the Administration Console

To log in to the Administration Console:

Open a supported web browser and go to the following URL:

http://server_address:port/console

Where:
- server_address is the instance you have set up as your administration server, usually the IP address of the system. Use the entry localhost when the Administration Console is on the same system as the administration server.
- port is the port to connect to. The default is 7001.
Log with the WebLogic user credentials you created during installation.

See the on-screen help text on the Administration Console for information on changing this password, and "Managing Users and User Groups", for information in removing or changing this user.

About the Administration Console

The Administration Console user interface consists of a set of selection panels to the left and to the right, the page or pages used for configuring and monitoring the selected node in the specific domain:

Change Center, the starting point for using the Administration Console to configure the current domain. To prevent other accounts from updating the configuration simultaneously, lock the editable configuration hierarchy for the domain. To do so, click Lock & Edit.
Domain Structure, a tree structure you can use to navigate to pages in the Administration Console. See "Navigating the Domain Structure".
How do I ..., with links to online help tasks that are relevant to the current Console page.
Toolbar, at the top of the Console with important details such as your access name, the connection address, and links.
Bread Crumb Navigation, a series of links that show the path you have taken through the pages of the Administration Console.
System Status, a panel that reports on the number of information, error, and warning messages that have been logged.

For more information, see the discussion ”About the Administration Console” in Fusion Middleware Understanding Oracle WebLogic Server.

Navigating the Domain Structure

Figure 2-1 displays the Domain Structure, located in left pane of the console. To view the page for a node, select the node in the Domain Structure tree. To expand a node or to collapse the node, click a + (plus) icon or a - (minus) icon in the Domain Structure.

Figure 2-1 Domain Structure Setup

Description of ''Figure 2-1 Domain Structure Setup ''

You monitor Services Gatekeeper configuration through the following nodes in the Domain Structure group for services-gatekeeper-domain, the container for all Services Gatekeeper servers:

Environment, to create, configure, and control servers, clusters, server templates, virtual hosts, targets that can be migrated. Some configuration settings are cluster-wide, and other settings are per server.
Deployments, to install, update, and delete installed applications. This link displays the list of Java EE applications and standalone application modules in this domain.
Services, to configure WebLogic Server services.
Security Realms, to configure the mechanisms that are used to protect WebLogic resources such as users, groups, security roles, security policies, and security providers. You can have multiple security realms in a WebLogic Server domain, but only one can be set as the default (active) realm.
Interoperability, to configure interoperability between WebLogic Server applications and Tuxedo services.
Diagnostics, to configure the collection of monitoring and performance data, through the WebLogic Diagnostics Framework (WLDF).
Media Server Control, to provide media server connectivity. Applications can look up a media server control factory on the Java Naming and Directory Interface (JNDI) tree.
SipServer, to access the Oracle Communications Converged Application Server Administration Console. To configure SIP settings, use the WebLogic Server Administration Console.

See "Converged Application Server Administration Console for SIP-based Services" for information.
OCSG:
- Server Name- One entry per Services Gatekeeper server.
- Alarms - displays the Alarms panel. See "Oracle Communications Services Gatekeeper Alarms Pane".
- CDRs - displays the charging data records (CDRs) panel. See "Using the Services Gatekeeper CDRs Pane".
- EDR Configuration - displays the EDR Configuration pane. See "Managing and Configuring EDRs, CDRs, and Alarms" for information.

Using the Configuration and Provisioning Pane

The Configuration and Provisioning pane contains two tabs:

Attributes
Operations

The Attributes tab displays a list of attributes, either read-only or read/write for the managed object. Attributes that have read/write capabilities have a check-box next to them.

Note:

This document identifies read-only attributes with an (r) after the name.

To change an attribute:

Select the check box.
Enter the new value in the entry field.
Click Update Attributes.

Figure 2-2 Example Configuration and Provisioning Pane Attributes Tab

Description of ''Figure 2-2 Example Configuration and Provisioning Pane Attributes Tab''

The Operations tab contains a list with the methods that either display data, set data, or perform an actual task.

To call a method displayed in the Operations tab:

Select the method from the Select An Operation list.

The fields display the information required by the method.
Enter the information in the fields.
To call the method, click Invoke.

Figure 2-3 Example Configuration and Provisioning Pane Operations Tab

Description of ''Figure 2-3 Example Configuration and Provisioning Pane Operations Tab''

Oracle Communications Services Gatekeeper Alarms Pane

Figure 2-4 Alarms Pane

Description of ''Figure 2-4 Alarms Pane''

The Services Gatekeeper Alarms pane displays alarms emitted.

It is possible to filter the output to the page on a set of criteria. See Table 2-1.

To retrieve the current alarms, click Get Alarms.

Table 2-1 Services Gatekeeper Alarms Pane Display Filters

Filter on...	Input
Severity	From the Severity list, select which severity level to display. The options are: ALL WARNING MINOR MAJOR CRITICAL
Source	From the Server list, select the server from which to display alarms. The options are: ALL, for all servers Server_name, for an individual server
Identifier.	See Services Gatekeeper Alarms Handling Guide for alarm identifiers. Use 0 (zero) to wildcard.
From	In the From, field, enter the start time for the time interval. The options are: Exact time. No given start time. Leave empty. Exact times are formatted as YYYY-MM-DD hh:mm:ss, where: YYYY is the year. Four digits required. MM is the month (1 through 12). DD is the day (1 through 31). Upper limit depends on month and year. hh is the hour (0 through 23). mm is the minute (0 through 59). ss is the second (0 through 59). Note: There must be a space separating YYYY-MM-DD and hh:mm:ss.
To	In the To, field, enter the end time for the time interval. The options are: Exact time. No given start time. Leave empty. Exact times are formatted as YYYY-MM-DD hh:mm:ss, where: YYYY is the year. Four digits required. MM is the month (1 through 12). DD is the day (1 through 31). Upper limit depends on month and year. hh is the hour (0 through 23). mm is the minute (0 through 59). ss is the second (0 through 59). Note: There must be a space separating YYYY-MM-DD and hh:mm:ss.
Offset	In the Offset field, enter the start offset in the list of alarms entries matching the criteria. Integer. 0 (zero) is the first entry.
Max	In the field Max field, enter the maximum number of alarm entries to return. Integer.

Using the Services Gatekeeper CDRs Pane

Figure 2-5 CDRs pane

Description of ''Figure 2-5 CDRs pane''

The Services Gatekeeper Charging Data Records (CDRs) pane displays any generated CDRs.

It is possible to filter the output to the page on a set of criteria. See Table 2-2.

To retrieve the list of CDRs, click Get CDRs.

Table 2-2 Services Gatekeeper CDRs Pane Filters

Filter on...	Input
Service Name	In the Service Name field, enter the name of the service name for which CDRs are required. The service name is the service type defined for the network protocol plug-in. A blank entry indicates the wildcard character.
Application Id	In the Application Id field, enter the application ID to filter on. A blank entry indicates the wildcard character.
Service Provider Id	In the Service Provider Id field, enter the service provider ID to filter on. A blank entry indicates the wildcard character.
From	In the From field, enter the start time for the time interval. The options are: Exact time. No given start time. Leave empty. Exact times are formatted as YYYY-MM-DD hh:mm:ss, where: YYYY is the year. Four digits required. MM is the month (1 through 12). DD is the day (1 through 31). Upper limit depends on month and year. hh is the hour (0 through 23). mm is the minute (0 through 59). ss is the second (0 through 59). Note: There must be a space separating YYYY-MM-DD and hh:mm:ss.
To	In the To field, enter the end time for the time interval. The options are: Exact time. No given start time. Leave empty. Exact times are formatted as YYYY-MM-DD hh:mm:ss, where: YYYY is the year. Four digits required. MM is the month (1 through 12). DD is the day (1 through 31). Upper limit depends on month and year. hh is the hour (0 through 23). mm is the minute (0 through 59). ss is the second (0 through 59). Note: There must be a space separating YYYY-MM-DD and hh:mm:ss.
Offset	Enter the start offset in the list of CDR entries matching the criteria. Enter integer values. 0 (zero) is the first entry.
Max	Enter the maximum number of CDR entries to return. Enter integer values.

Converged Application Server Administration Console for SIP-based Services

You use the Oracle Communications Converged Application Server Administration Console to configure settings for that product and the SIP Servlet parts of Services Gatekeeper communication services.

To open the Converged Application Server Administration Console, click Domain Name, and then SipServer.

Localizing the Administration Console

For instructions on setting the Administration Console to a different locale, see ”Rebranding the Administration Console” in Oracle Fusion Middleware Extending Administration Console for Oracle WebLogic Server.

Understanding the Java Management MBeans

Services Gatekeeper exposes its management interfaces as Java Management Extensions (JMX) MBeans based on the Oracle WebLogic server.

WebLogic Server uses two types of MBeans:

Runtime MBeans that contain information about the run-time state of a server and its resources.
Configuration MBeans that contain configurable configuration settings.

See ”Understanding WebLogic Server MBeans” in Fusion Middleware Developing Custom Management Utilities With JMX for Oracle WebLogic Server for more information on how WebLogic uses MBeans.

See the ”All Classes” section of the OAM Java API documentation for details on the Services Gatekeeper operations, administration, and management (configuration) MBeans. This includes their fully qualified names, and information about how they map to managed objects in the Services Gatekeeper Administration Console

The code in Example 2-1 connects to the MBean server and calls a method to complete a task on the JMX interfaces.

The MBean object name is associated with a version number. The MBean name includes the version number for the release. Update external JMX clients according to the release number.

Example 2-1 Example of using JMX to manage Services Gatekeeper

import java.io.IOException;
import java.net.MalformedURLException;
import java.util.Hashtable;
import javax.management.MBeanServerConnection;
import javax.management.MalformedObjectNameException;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
import javax.naming.Context;
public class TestMgmt {
  private static MBeanServerConnection connection;
  private static JMXConnector connector;
/*
  * Initialize connection to the Domain Runtime MBean Server
  */
  public static void initConnection(String hostname, String portString,
                                    String username, String password) throws IOException,
      MalformedURLException {
    String protocol = "t3";
    Integer portInteger = Integer.valueOf(portString);
    int port = portInteger.intValue();
    String jndiroot = "/jndi/";
    String mserver = "weblogic.management.mbeanservers.domainruntime";
    JMXServiceURL serviceURL = new JMXServiceURL(protocol, hostname,
        port, jndiroot + mserver);
    Hashtable h = new Hashtable();
    h.put(Context.SECURITY_PRINCIPAL, username);
    h.put(Context.SECURITY_CREDENTIALS, password);
    h.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES,
        "weblogic.management.remote");
    connector = JMXConnectorFactory.connect(serviceURL, h);

    connection = connector.getMBeanServerConnection();
  }
  public static void main(String[] args) throws Exception {
    String hostname = args[0];   //hostname of the admin server
    String portString = args[1]; //port of the admin server
    String username = args[2];
    String password = args[3];
    String mbserverName = args[4];  //NT server name
    String operationName = "addRoute";
    String id = "Plugin_px21_multimedia_messaging_mm7";
    String addressExpression = ".*";
    String[] params = new String[]{id, addressExpression};
    String[] signature = new String[]{"java.lang.String", "java.lang.String"};
    ObjectName on;
    try {
      on = new ObjectName("com.bea.wlcp.wlng:Name=wlng,InstanceName=PluginManager,Type= com.bea.wlcp.wlng.plugin.PluginManagerMBean,Location=" + mbserverName);
    } catch (MalformedObjectNameException e) {
      throw new AssertionError(e.getMessage());
    }
    initConnection(hostname, portString, username, password);
    //invoke the operation
    Object result = connection.invoke(on, operationName, params, signature);
    System.out.println(result.toString());  //displays the result
    connector.close();
  }
}

If an attempt to set an attribute or call a method fails, an com.bea.wlcp.wlng.api.management.ManagementException exception, or a subclass of this exception is thrown. The following subclasses are defined:

DuplicateKeyException, thrown when the called method creates a duplicate key.
InputManagementException, thrown for invalid user input.
KeyNotFoundException, thrown when the called method cannot find the specified key.

If a JMX client does not have the same version of exception classes available, the client throws ClassNotFoundException.

The Middleware_home/ocsg_pds/lib/wlng/oam.jar file contains custom classes for OAM and return types. The Middleware_home/ocsg_pds/doc/javadoc_oam file contains Javadoc for OAM. The Services Gatekeeper OAM Java API Reference is also available at the top level of this documentation set.

Using the WebLogic Scripting Tool to Administer Services Gatekeeper

The following section gives examples of how to use the WebLogic Scripting Tool (WLST) in both interactive and script mode when configuring and managing Services Gatekeeper.

For information about WebLogic Server and WLST, see ”Introduction and Roadmap” in Oracle WebLogic Server Understanding the WebLogic Scripting Tool.

The following topics are covered in this section:

Using WLST in Interactive Mode
Using the WebLogic Scripting Tool to Administer Services Gatekeeper

Note:
A link to Javadoc for OAM can be found on the Reference topic page in the Services Gatekeeper documentation set.

Using WLST in Interactive Mode

This section gives examples of how to use WLST in interactive mode.

Connecting to Services Gatekeeper with WLST

To connect to Services Gatekeeper with WLST:

To ensure that the Java environment is set, enter the following command:
- On UNIX systems:
  
  Domain_Home/bin/setDomainEnv.sh
- On Windows systems:
  
  Domain_Home\bin\setDomainEnv.cmd
To start WLST, enter the following command:

java weblogic.WLST
To connect to the server to manage, enter the following command:

connect('username','password','t3://host:port')
To change to the custom tree where Services Gatekeeper MBeans are located, enter:

custom()

cd('com.bea.wlcp.wlng')
To display a list of the Mbeans, enter:

ls()

The MBean names are also displayed in each Configuration and Provisioning page for the management objects in the Services Gatekeeper Administration Console.
To select the MBean:

cd('com.bea.wlcp.wlng:Name=wlng_nt,Type=MBean_name')

For example, to select the MBean for the EDRService, use:

cd('com.bea.wlcp.wlng:Name=wlng,InstanceName=EdrService,Type=com.bea.wlcp.wlng.edr.management.EdrServiceMBean')

Disconnecting from WLST

To disconnect from Services Gatekeeper:

Enter:

disconnect()
To exit from the WLST shell, enter the following command:

exit()

Changing an MBean Attribute

To change the attribute of an MBean:

Select the MBean.
Set the attribute:

set('name_of_attribute',value_of_attribute)

For example, to change the attribute BatchSize to 2001 in the managed object EDRService, enter:
```
set('Batchsize', 2001)
```

To display the attribute values for an MBean, enter:

ls()

Calling an MBean Method

To call an MBean method:

Select the MBean.
Define the parameters as an array.
Define the data types as an array.
Call the method.

The displayStatistics method in the EDRService MBean takes no arguments. For example:

cd('com.bea.wlcp.wlng:Name=wlng,InstanceName=EdrService,Type=com.bea.wlcp.wlng.edr.management.EdrServiceMBean')
objs = jarray.array([],java.lang.Object)
strs = jarray.array([],java.lang.String)
print(invoke('displayStatistics',objs,strs))

To add a route using the MBean for the Plug-in Manager, call the addRoute method. The addRoute method takes two arguments. State the values of the parameters in the order in which the parameters are defined in the signature of the method. For example:

cd('com.bea.wlcp.wlng:Name=wlng,InstanceName=PluginManager,Type=com.bea.wlcp.wlng.plugin.PluginManagerMBean ')
objs=jarray.array(['Plugin_px21_multimedia_messaging_mm7','.*'],Object)
strs=jarray.array(['java.lang.String', 'java.lang.String'],String)
invoke('addRoute', objs, strs)

For a method that has input parameters and a string return value, run the invoke command as shown below:

objs = jarray.array([java.lang.String('stringInput1'),java.lang.String('stringInput2'), java.lang.String('StringInput3')],java.lang.Object)
strs = jarray.array(['java.lang.String', 'java.lang.String', 'java.lang.String'],java.lang.String)
invoke('methodName',objs,strs)

Scripting WLST

To run WLST using scripts, use the following command:

java weblogic.WLST script_name.py argument_1 argument_2 ...argument_n

The arguments can be retrieved from within the scripts in the array sys.argv[], where sys.argv[0] is the script name, sys.argv[1] is the second argument and so on. You can also specify the login information and connection information as arguments to the python script.

The script in Example 2-2 connects to Services Gatekeeper and changes an MBean defined by argument.

Example 2-2 Example of script

userName = sys.argv[1]
passWord = sys.argv[2]
url="t3://"+sys.argv[3]+":"+sys.argv[4]
objectName = sys.argv[5]
objectName = "com.bea.wlcp.wlng:Name=nt,Type=" + sys.argv[5] 
print objectName
connect(userName, passWord, url)
custom()
cd('com.bea.wlcp.wlng')
cd(objectName)

The following command uses the script:

java weblogic.WLST script1.py weblogic weblogic localhost 7001 com.bea.wlcp.wlng:Name=wlng,InstanceName=PluginManager,Type=com.bea.wlcp.wlng.plugin.PluginManagerMBean