This chapter describes how to use Oracle Communications Billing and Revenue Management Elastic Charging Engine (ECE) Elastic Charging Controller (ECC) for the operational management of ECE.
You can use Oracle Application Management Pack for Oracle Communications to manage and monitor ECE nodes and clusters. Oracle Application Management Pack for Oracle Communications provides management capabilities for Oracle Communications Billing and Revenue Management (BRM) and other supported Oracle Communications applications. For detailed information about the management capabilities provided by Oracle Application Management Pack for Oracle Communications, see Oracle Application Management Pack for Oracle Communications System Administrator's Guide.
ECC is used for managing ECE software processes which have a role defined in the ECE topology file (ECE_Home/oceceserver/config/eceTopology.conf).
ECC can manage nodes in the Coherence cluster, such as charging server nodes and data-loading utility nodes, as well as ECE utilities such as the pricingLoader utility.
ECC reads the ECE topology file to know where ECE nodes and software are located in your hardware topology.
ECC is an extension of the Groovy Shell (groovysh) for ECE. ECC adds ECE-specific commands to the default Groovy Shell commands. For information about the default Groovy Shell commands and command syntax, see the Groovy Web site at:
http://groovy-lang.org/groovysh.html#GroovyShell-Commands
ECC is installed on the driver machine and can be used to push out configuration changes from the driver machine to all server machines across which the cluster is deployed. ECC uses its sync command for pushing out configuration changes across the cluster. See "About Using ECC on the Driver Machine" for information about the driver machine.
See BRM Elastic Charging Engine Installation Guide for information about setting up the topology file and setting up the driver machine and the server machines.
The following are some of the tasks you can perform by using ECC:
Start all nodes defined in your topology.
For example, start charging server node instances, data-loading utility nodes, data updater nodes, simulator nodes, and so on.
Stop all nodes defined in your topology.
Start the charging server node instances.
Stop the running charging server node instances.
Start the simulator.
Check the status of a running node.
Add a node to your topology.
Remove a node from your topology.
The driver machine, the server that acts as the root of your ECE installation, is where you use ECC. You run ECC from the driver machine and use it to push the ECE installation out to the various server machines on the cluster. The driver machine contains your topology file, ECE properties file, JVM tuning file and so on. The driver machine contains the ECE_Home/oceceserver/management/ configuration settings that apply to all servers currently running on the grid and will apply to those that will be added later.
Before using ECC, perform the following prerequisite tasks:
Install ECE server software on the driver machine and specify the ECE root directory, ECE user name, and the IP address of the driver machine in the ECE_Home/oceceserver/config/ece.properties file.
ECC is included in the ECE server software package and must be run on the server that is the driver machine.
Ensure you have the correct values set in the ece.properties file before you use the sync command.
Verify that all the nodes in your cluster are defined in the ECE_Home/oceceserver/config/eceTopology.conf file.
ECC reads the topology you define in this file to locate all the nodes it can manage.
For example, after you define all charging-server node instances in the eceTopology.conf file, you can use ECC commands to start, stop, and initialize these nodes.
Verify that two-way password-less SSH is configured between the driver machine and all server machines in the cluster.
Verify that the proper permissions are granted in ECC.
Access to ECE files is controlled by creating user accounts and granting specific permissions in ECC. After you have created user groups and set permissions, users can log in through ECC and manage ECE files. For information, see "Setting Up User Accounts and User Groups".
To use ECC:
Log on to the driver machine.
Change directory to the ECE_Home/oceceserver/bin directory.
Enter the following command:
./ecc
From the command prompt, run the command you would like to run.
For information about each command you can use ECC Help. See "Getting Help Using ECC".
ECC command output provides the following information:
The success or failure of the command (status of true or false)
The tasks the command executed
For a failed task, the error message explaining the failure
All ECC commands return a number of events depending on the number of tasks the command performs. ECC command output includes the events and their associated attributes, along with the overall command status.
Depending on individual command results, the following fields are populated and printed on the ECC command output for an event returned by a command:
Request: A string only printed in an error case.
Response: A string returned if the command or task returns a value or includes a confirmation message. For example, the encrypt command returns the encrypted password.
If there is an error performing a task, an error message is stored in the Response field.
Status: A boolean indicating that the task succeeded or failed.
Node: A string of the node name.
Details: A map with further details like the node process ID.
Here is an example of the ECC command output for the start command when starting all charging server nodes for an ECE topology that contains only two charging server nodes (with node names ecs1 and ecs2):
ecc:000> start server -- No JMX Enabled Nodes are available. -- Starting one JMX-Enabled Node. -- Node 'ecs1' started with PID 1331 -- ecs1 (JMX-Enabled) is running and has joined the cluster. -- Node 'ecs2' started with PID 2081 -- ecs2 is running and has joined the cluster. ===> status: true [ Status: true Node: ecs1 details: [pid:1331, state:running] ---------- Status: true Node: ecs2 details: [pid:2081, state:running] ---------- ]
Here is an example of the ECC command output for the encrypt command when encrypting the password aStrongPassword.
ecc:000> encrypt aStrongPassword storepassword Encrypted value for "aStrongPassword" is ===> status: true [ Status: true response: acMTrZo4mXEJa7yWUKClJQ== ]
You run ECC commands to manage nodes (ECE processes) in the cluster. This section provides information about each command. For information about running each command you can also use the ECC help command. See "Getting Help Using ECC".
For a list of all ECC commands, see Appendix B, "ECC Commands".
The following is the syntax and examples for the start command:
Syntax:
start [role] -or- [nodeName]
where:
role is the name of the role specified for that node in the role column of the ECE topology file; this indicates the type of node such as whether it is a charging server node (server) or a simulator node (simulator).
nodeName is the name of the node specified for that node in the node-name column of the ECE topology file.
For example, to start nodes by role, you can do the following:
Start all nodes of type server:
start server
Start all nodes of type simulator:
start simulator
For example, to start nodes by name, you can do the following:
Start a charging server named ecs1:
start ecs1
If you run only the start command without anything passed; for example:
start
this is equivalent to start server.
Caution:
Stopping charging server nodes removes all data from memory. For example, if you run stop server, you will lose all data in Coherence caches. See "Restoring the ECE System" for more information.The following is the syntax and examples for the stop command:
Syntax:
stop [role] -or- [node1 [node2] [...]]
For example, to stop all nodes that have the role server:
stop server
For example, to stop nodes by name:
stop ecs1
To get help on the stop command:
help stop
The following is the syntax for the addNode command:
Syntax:
addNode [node name] [role] [host name] [host ip] [JMX port] [start CohMgt] [JVM Tuning File]
Run the command help addNode for information about the mandatory and optional fields for this command.
When you run the addNode command, you add nodes to the cluster.
The addNode command runs the sync command which installs ECE on the host machine of the node.
addNode adds an entry for the node in the topology file.
addNode does not start the node after it adds the node to the cluster. You must use the start command to start the node.
When you run the removeNode command, you remove nodes from the cluster.
removeNode removes the entry for the node from the topology file.
You cannot use the removeNode command when nodes are running. You are required to stop a node before you remove it by using the removeNode command. The removeNode command reports a warning if you try to run it for a node in a running state.
You use the infoCollector command to collect log files so that you can send them to Oracle technical support when troubleshooting problems with ECE. The command collects ECE configuration files from various directories and puts them in a central location. The command provides options to TAR the files and also enables you to include your custom files (apart from ECE configuration files).
See "Collecting Log Files for Sending to Oracle Support" for more information.
For information about infoCollector command syntax, run the following ECC command:
help infoCollector
You use the rollingUpgrade command to deploy updates onto ECE software while maintaining operation of the ECE syste"Performing a Rolling Upgrade"m (without stopping ECE). For more information, see .
The rollingUpgrade command can be used for the following purposes:
Deploying JVM tuning parameter updates onto a running ECE system. See "Deploying JVM Tuning Parameter Updates onto a Running System" for more information.
Deploying JMS configuration setting updates onto a running ECE system. See the discussion of configuring notifications for charging in BRM Elastic Charging Engine Implementation Guide for more information.
The following is the syntax and examples for the rollingUpgrade command:
Syntax:
rollingUpgrade [role]
For example, to upgrade all running nodes in the topology except the simulator roles, run it with no arguments:
rollingUpgrade
For example, to upgrade all running charging server nodes (nodes that have the role server):
rollingUpgrade server
The order in which the nodes are restarted adheres to the order in which the nodes are listed in the ECE_Home/oceceserver/config/eceTopology.conf file.
You can choose to upgrade nodes (bring them down, upgrade them, and join them back to the cluster) by node role. For example, to first upgrade all the nodes of role ratedEventFormatter, followed by all the nodes of role server, followed by all the nodes of role updater, and then followed lastly by all the nodes of role diametergateway, you would enter the following commands:
rollingUpgrade ratedEventFormatter rollingUpgrade server rollingUpgrade updater rollingUpgrade diametergateway
You require a full cluster restart (when a rolling upgrade cannot be performed) under the following conditions:
Non-backward compatible upgrades
Adding or removing a property
Request specification data once loaded into the cluster are not reversed with a roll back.
The rollingUpgrade command can take as input the user name and password for secured JMX environments:
rollingUpgrade username=username password=Password
Get help using ECC by:
See Appendix B, "ECC Commands" for a list of all ECC commands.
Use the ECC help command for information about using all commands:
help
To get help on a particular command:
help start usage: start [role] start all the nodes of type role.
ECC provides a description about the command.
ECC offers completion support for commands, command options, and command-option parameters. For example:
Type st, then press the space bar and Tab key for command completion:
ecc:000>st
start stop]
ECE lists all command that begin with st.
Type start, then press the space bar and Tab key for command-option completion:
ecc:000>start
gateway loader server simulator]
ECE lists all command options available for the start command. In the preceding example, ECE lists all nodes you can start.
Type start server, and then press the space bar and Tab key for command-option parameter completion:
ecc:000> start server
ebugPort=portNumber extraClassPath=path extraJavaProperties=pros...]
Important:
Rolling upgrades may not be supported for upgrading to specific versions of ECE. Refer to BRM Elastic Charging Engine Release Notes for information about rolling upgrade support in ECE releases.Rolling upgrades can be used for the following:
Deploying JVM tuning parameter updates onto a running ECE system. See "Deploying JVM Tuning Parameter Updates onto a Running System" for more information.
Deploying JMS configuration setting updates onto a running ECE system. See the discussion of configuring notifications for charging in BRM Elastic Charging Engine Implementation Guide for more information.
Upgrading from an old version of ECE to a new version of ECE. See the chapters about upgrading ECE in BRM Elastic Charging Engine Installation Guide for information about performing a rolling upgrade when upgrading to a new version of ECE.
You perform a rolling upgrade to upgrade ECE software while maintaining operation of the ECE system (without stopping ECE). You would perform a rolling upgrade, for example, when you need to install a patch recommended by Oracle.
The rollingUpgrade command performs an upgrade of all nodes of a particular role while ensuring high availability of the system. For example, if a patch fix only applies to the functionality of charging servers, you can apply the command only to nodes with the role server.
One by one, the command will stop the older versions of nodes and start current versions of these nodes.
Prior to moving to the next node to upgrade, the command ensures that the last upgraded node has correctly started and joined the cluster. If the last upgraded node does not correctly start and join, the command interrupts the upgrade process.
For rolling back the upgrade, or downgrade to the older version, run this command from the old installation location.
If no role is provided, all running nodes except simulators are upgraded.
To perform a rolling upgrade:
Note:
Before performing the rolling upgrade, a new installation of ECE must be performed in a different directory. After launching the Elastic Charging Controller using the new installation, the rollingUpgrade is called to upgrade the system to the new version.Perform the new installation of ECE and apply the required patch updates to the installation.
For example, install a patch recommended by Oracle onto the new installation.
Verify that the topology you specify in your new installation (in the ECE topology file) is the same as the topology specified in your old installation.
Go to the new ECE installation's config directory.
cd ECE_Home_new_installation/oceceserver/config
Open the ece.properties file and set the numberOfPauseSecondsForRollingUpgrade parameter
The default is 30.
Set the amount of time in seconds you want ECC to pause between bringing down and upgrading each server node that is running on the old installation.
Setting a time lapse allows for rebalancing of Coherence partitions (for example, for a server node being brought down to be upgraded, it allows time for its backup node to become a primary node). The time lapse also helps ensure that upgraded nodes have come up and joined the cluster individually before the next node is brought down for upgrade.
Go to the bin directory of the new ECE installation.
cd ECE_Home_new_installation/oceceserver/bin
Start ECC.
./ecc
Run the following command to start the rolling upgrade from the new installation while ECE is still operating on the old installation:
rollingUpgrade
One by one, each node on the old location is brought down, upgraded, and joined back to the cluster.
When you run the rollingUpgrade command with no parameters specified, all running nodes are upgraded (charging server nodes, data-loading utility nodes, data updater nodes, and so on) except for simulator nodes (nodes that have the role simulator).
The order in which the nodes are restarted adheres to the order in which the nodes are listed in the ECE_Home/oceceserver/config/eceTopology.conf file.
You can choose to upgrade nodes (bring them down, upgrade them, and join them back to the cluster) by node role. For example, to first upgrade all the nodes of role ratedEventFormatter, followed by all the nodes of role server, followed by all the nodes of role updater, and then followed lastly by all the nodes of role diametergateway, you would enter the following commands:
rollingUpgrade ratedEventFormatter rollingUpgrade server rollingUpgrade updater rollingUpgrade diametergateway
After the upgrade has completed, the new version of ECE is used and you can decide what you would like to do with the old directory installation.