# System Administrator’s Guide

# Operation and Maintenance: General

The following sections give an overview of the mechanisms available for controlling Oracle Communications Services Gatekeeper.

- Administration Console Overview

- Administration Console

- MBeans pane
- Configuration and Provisioning
- WebLogic Oracle Communications Services Gatekeeper Alarms pane
- Oracle Communications Services Gatekeeper CDRs Pane

- Oracle Communications Converged Application Server Management Console for SIP-based Communication Services

- Java Management Extensions (JMX)
- WebLogic Scripting Tool (WSLT)

- Working in Interactive Mode

- Starting WLST and connecting to Oracle Communications Services Gatekeeper
- Exiting WLST
- Changing an attribute

- Invoking an operation
- Scripting WLST

## Administration Console Overview

Oracle Communications Services Gatekeeper Administration Console provides a graphical user interface for configuring, managing, and provisioning Oracle Communications Services Gatekeeper. The console is an extension to the console available in WebLogic Server.

At least one Network Tier server must be started prior to logging in to WebLogic Server Administration Console. Oracle Communications Services Gatekeeper servers started after logging in to the Administration Console are not displayed in the Administration Console. To see them, you must login again.

### Administration Console

Use a supported web browser to go to `http://<server>:<port>/console` where <server> is the instance you have set up as your Administration Server.

Login using your log-in credentials.

Note: | If it is the first time Oracle Communications Services Gatekeeper is started, use the username `weblogic` and password `weblogic,`which is the recommended value for the installation and initial domain configuration stage. Once you have logged in, create an administrative user using the instructions given in Managing Management Users and Management User Groups, and remove the user `weblogic`. Either remove or change password for the WebLogic Server user, see Oracle WebLogic Server Securing WebLogic Resources Using Roles and Policies at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/secwlres/index.html.

All Oracle Communications Services Gatekeeper configuration and monitoring is provided via the following nodes in the left pane of the console, in the Domain Structure group:

- OCSG — container for all Oracle Communications Services Gatekeeper servers
- <Server Name> — one entry per Oracle Communications Services Gatekeeper server.

- <Server Name> — Clicking on this link displays the MBeans pane which displays all OAM objects available for the selected Oracle Communications Services Gatekeeper server. Some configuration settings are cluster-wide while other settings are per server.
- Alarms — clicking this link displays the WebLogic Oracle Communications Services Gatekeeper Alarms pane.
- CDRs — clicking this link displays the Oracle Communications Services Gatekeeper CDRs Pane.
- EDR Configuration— clicking this link displays the EDR Configuration pane, see Managing EDR, CDR, and alarms configuration files using the EDR Configuration Pane.

- SipServer — clicking this link displays the Oracle Communications Converged Application Server’s administration console, see Oracle Communications Converged Application Server Management Console for SIP-based Communication Services.
Figure 3-1 Domain Structure -links to management console for Oracle Communications Services Gatekeeper and Oracle Communications Converged Application Server

#### MBeans pane

The MBeans pane contains a tree-structure of all management objects applicable for the selected Oracle Communications Services Gatekeeper server.

By clicking on a management object, the corresponding Configuration and Provisioning page for the management object is displayed immediately below the MBean pane: see Configuration and Provisioning.

Figure 3-2 MBeans pane

#### Configuration and Provisioning

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.

Note: | In this document, read-only attributes are indicated by (r) after the name.

Read-write attributes have a check-box next to them.

To change an attribute:

1. Check the check box.
2. Enter the new value in the entry-field.
3. Click Update Attributes.
Figure 3-3 Example Configuration and provisioning pane -Attributes tab

The Operations tab contains a drop-down list with the operations for the managed object.

Operations either display data, set data, or perform an actual task.

To perform an operation:

1. Select the operation from the drop-down-list Select An Operation.

The entry-fields for the operation are displayed.

2. Enter the information in the entry fields.
3. Click Invoke to perform the operation.
Figure 3-4 Example Configuration and provisioning pane -Operations tab

#### WebLogic Oracle Communications Services Gatekeeper Alarms pane

Figure 3-5 Alarms pane

The Oracle Communications Services Gatekeeper Alarms pane displays alarms emitted.

It is possible to filter the output to the page on a set of criteria, see Table 3-1.

The list is returned by clicking Get Alarms.

Table 3-1 Oracle Communications Services Gatekeeper Alarms pane
Filter on... | Input
--- | ---
Severity of alarms | From the drop-down list labeled Severity, choose which severity level to display: The options are: ALL WARNING MINOR MAJOR CRITICAL
The server from which the alarm originates | From the drop-down list labeled Server, choose the server from which to display alarms. The options are: ALL, for all servers <Server name>, for an individual server.
ID of the alarm. | See Oracle Communications Services Gatekeeper Handling Alarms for alarm codes. Use 0 (zero) to wildcard.
Time interval | In the field labeled From, enter the start time for the time interval. The options are: Exact time. No given start time. Leave empty. In the field labeled To, enter the end time for the time interval. The options are: Exact time. No given time. Leave empty. Exact times are formatted as YYYY-MM-DD hh:mm., where: YYYY is the year. Four digits required. MM is the month [1...12] DD is the day [1...[28|29|29|30|31]]. Upper limit depends on month and year. hh is the hour [0...23] mm is the minute [0...59]
Note: | There must be a white space separating YYYY-MM-DD and hh:mm.
Offset | In the field labeled Offset, enter the start offset in the list of alarms entries matching the criteria. Integer. 0 (zero) is the first entry.
Max | In the field labeled Max, enter the maximum number of alarm entries to return. Integer.

#### Oracle Communications Services Gatekeeper CDRs Pane

Figure 3-6 CDRs pane

The Oracle Communications Services Gatekeeper CDRs pane displays CDRs that have been generated.

It is possible to filter the output to the page on a set of criteria, see Table 3-1.

The list is returned by clicking Get CDRs.

Table 3-2 Oracle Communications Services Gatekeeper CDRs pane
Filter on... | Input
--- | ---
Service Name | Enter the service name to get CDRs for. The service name is the service type defined for the network protocol plug-in. Leave empty to wildcard.
Application Id | Enter the application ID to filter on. Leave empty to wildcard.
Service provider Id | Enter the service provider ID to filter on. Leave empty to wildcard.
From | Enter the start time for the time interval. The options are: Exact time. No given start time. Leave empty. Exact time is formatted as YYYY-MM-DD hh:mm:ss., where: YYYY is the year. Four digits required. MM is the month [1...12] DD is the day [1...[28|29|29|30|31]]. Upper limit depends on month and year. hh is the hour [0...23] mm is the minute [0...59] ss is the seconds [0...59]
Note: | There must be a white space separating YYYY-MM-DD and hh:mm:ss.
To | Enter the end time for the time interval. The options are: Exact time. No given 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...12] DD is the day [1...[28|29|29|30|31]]. Upper limit depends on month and year. hh is the hour [0...23] mm is the minute [0...59] ss is the seconds [0...59]
Note: | There must be a white space separating YYYY-MM-DD and hh:mm:ss.
Offset | Enter the start offset in the list of alarms entries matching the criteria. Integer. 0 (zero) is the first entry.
Max | Enter the maximum number of alarm entries to return. Integer.

### Oracle Communications Converged Application Server Management Console for SIP-based Communication Services

There is an administration console for the Oracle Communications Converged Application Server. This handles setting for the Oracle Communications Converged Application Server and the SIP Servlet parts of Oracle Communications Services Gatekeeper communication services.

Click <Domain name>SipServer to open the Oracle Communications Converged Application Server administration console.

## Java Management Extensions (JMX)

Oracle Communications Services Gatekeeper exposes its management interfaces as JMX MBeans.

These MBeans come in two flavours:

- Standard MBeans
- Configuration MBeans

Note: | A link to JavaDoc for OAM can be found in the Reference topic page in the Oracle Communications Services Gatekeeper documentation set. See the reference section for each OAM service for the fully qualified MBean names and how they map to managed objects in Oracle Communications Services Gatekeeper Administration Console

Below is an example of connecting to the MBean server and performing an operation on the JMX interfaces.

The MBean object name is versioned. The MBean name includes the version number for the release. External JMX clients needs to be updated according to the release number.

Listing 3-1 Example of using JMX to manage Oracle Communications 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 setting an attribute or calling an operation fails, a `com.bea.wlcp.wlng.api.management.ManagementException`, or a subclass of this exception is thrown. The following subclasses are defined:

`DuplicateKeyException` - Thrown when the operation results in creating a duplicate key

`InputManagementException` - Thrown for invalid user input

`KeyNotFoundException` - Thrown when the operation cannot find the specified key

A JMX client must have the same version of exception classes available; otherwise the client will throw ClassNotFoundException.

`$BEA_Home/ocsg_pds4.1/lib/wlng/oam.jar` contains custom classes for OAM and return types.

`$BEA_Home/ocsg_pds4.1/doc/javadoc_oam` contains JavDoc for OAM.

## WebLogic Scripting Tool (WSLT)

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

For information about WebLogic Server and WLST, see Oracle WebLogic Server WebLogic Scripting Tool at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/config_scripting/index.html.

The following topics are covered:

- Working in Interactive Mode

- Starting WLST and connecting to Oracle Communications Services Gatekeeper
- Exiting WLST
- Changing an attribute
- Invoking an operation

- WebLogic Scripting Tool (WSLT)

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

### Working in Interactive Mode

#### Starting WLST and connecting to Oracle Communications Services Gatekeeper

1. Make sure the correct Java environment is set:

UNIX: `$Domain_Home/bin/setDomainEnv.sh`

or

Windows: `$Domain_Home\bin\setDomainEnv.cmd`

2. Start WLST: `java weblogic.WLST`
3. Connect to the server to manage:

`connect('<username>','<password>', 't3://<host>:<port>')`

4. Change to the custom tree where Oracle Communications Services Gatekeeper MBeans are located:``

`custom()`

`cd('com.bea.wlcp.wlng')`

5. Display a list of the Mbeans: `ls()`

The MBean names are also displayed in each Configuration and Provisioning page for the management objects in the Oracle Communications Services Gatekeeper Management Console.

6. Select the MBean to change:

`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')`

#### Exiting WLST

1. Disconnect from Oracle Communications Services Gatekeeper: `disconnect()`
2. Exit the WLST shell: `exit()`

#### Changing an attribute

1. Select the MBean to change attribute for.
2. Set the attribute: `set('<name of attribute>', <value of attribute>)`

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

3. The attribute values for an MBean can be displayed using: `ls()`

#### Invoking an operation

1. Select the MBean to invoke an operation on.
2. Define the parameters as an array.
3. Define the data types as an array.
4. Invoke the operation.

For example, to invoke the `displayStatistics` method in the EDRService MBean:

`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))`

This operation has no arguments.

Another example: to add a route using the MBean for the Plug-in Manager:

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)

The method `addRoute` takes two arguments, and the values of the parameters are stated in the same order as the parameters are defined in the signature of the method.

Note: | For a method that has input parameters and a string return value, the `invoke` command can be executed as follows:

    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

When using WLST together with scripts, WLST is invoked as follows:

`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. It may be useful to specify login information and connection information as arguments to the scripts.

Below is a script that connects to Oracle Communications Services Gatekeeper and changes to an MBean defined by argument.

Listing 3-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)

For example: To invoke 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