ESA Setup and Configuration
Ericsson SNMP Agent 18.0

Contents

1About This Document
1.1Purpose
1.2Target Group
1.3Prerequisites
1.4Typographic Conventions

2
Configuration Work Process
2.1Introduction
2.2Mandatory Configuration
2.3Recommended Configuration
2.4Optional Configuration
2.5Feature Configurations
2.6Common Configuration

3
Operation
3.1Introduction
3.2Services
3.3Operations
3.4Startup/Shutdown Sequence
3.5SNMP Operation

4
Configuration
4.1Introduction
4.2Configuration Files
4.3Alarm Controllers
4.4Cluster Mode
4.5Community Strings
4.6Directories
4.7FM MIB Preferences
4.8Information Agent
4.9Interfaces
4.10Interface AgentX
4.11Interface Java RMI
4.12Interface SNMP
4.13Java Virtual Machine
4.14PM Agent Preferences
4.15Master Agent Preferences
4.16SNMP Proxy
4.17SNMPv3
4.18Subagent AAL Synchronization
4.19Trap Destination
4.20USM
4.21VACM
4.22Originating source as IP / Hostname

5
Administration
5.1Version
5.2Logging
5.3Backup and Restore
5.4Command Line Interface

6
Appendix A: ESA MIBs

7
Appendix B: SNMP Configuration
7.1Introduction
7.2Overview
7.3Use Case: SNMP Get for SNMPv2
7.4Use Case: SNMP Trap for SNMPv2
7.5Use Case: SNMP Get for SNMPv3
7.6Use Case: SNMP Trap for SNMPv3

Glossary

Reference List

1   About This Document

1.1   Purpose

The purpose of this document is to describe the basic system administration tasks for the Ericsson SNMP Agent (ESA). The basic tasks means the mandatory tasks needed to get the ESA to run at all.

1.2   Target Group

The target group for this document is personnel responsible for administration of the ESA.

1.3   Prerequisites

It is assumed that the user of this document fulfils the following prerequisites.

1.4   Typographic Conventions

The typographic conventions used in this document are described in Reference [1].

2   Configuration Work Process

2.1   Introduction

The ESA is built to be very flexible and to suit basically any environment. Flexibility come with a small cost though; The cost of handling configuration parameters.

It is important to know that ESA is operational immediately after installation and does not require changing any configuration parameter.

The following chapters describe the recommended and optional configuration procedures that are commonly performed at a newly installed ESA. Most of them are optional though.

See also Section 4, which describes all the configuration parameters in more detail.

2.2   Mandatory Configuration

There are no mandatory configuration operations. The ESA is operational with default parameter settings immediately after installation.

2.3   Recommended Configuration

2.4   Optional Configuration

The optional configuration procedures are useful to know about when there are interfaces that must be changed, security is to be setup or other options and capabilities are to be defined according to specific system and/or customer needs.

The following configuration settings are optional:

2.5   Feature Configurations

The configurations in the previous chapters are related to the execution of the ESA itself. To get the most out of the ESA a number of configuration files should be setup for the FM and PM features provided by the ESA.

For FM the following configurations could be setup. Also, see Reference [2].

For PM the following configurations could be setup. Also, see Reference [3].

2.6   Common Configuration

This configuration is common across ESA MA, FMA, and PMA.

IP or Hostname : This part defines the value user is interested to display in MIB table, alarms, and log.

3   Operation

3.1   Introduction

The following chapters describes the ESA services and how to operate them.

3.2   Services

There are three ESA services running.

The name of the services are the same on all platforms.

3.3   Operations

3.3.1   Overview

All ESA services support the following operations.

3.3.2   Linux

The ESA Linux services are operated by using the following instructions.

Command format:

service <service name> <operation>

Attribute <operation> allows the following values:

start

Start the specified service.

stop

Stop the specified service.

restart

Restart the specified service.

status

View the status of the specified service.

Command example:

# service esama start
# service esafma stop
# service esapma restart
# service esama status

Note:  
The output from the command service is different for different Linux variants.

3.4   Startup/Shutdown Sequence

From ESA point of view there is no required startup or shutdown sequence of the ESA services. The services run independently of each other meaning if one or several services are not up and running, the services will handle the missing relation and, most important, they will connect when the services are back in operation.

However, to optimize the startup and shutdown sequences and to also avoid warning and error indications in the logs, the following sequences are recommended.

Recommended Startup Sequence:

  1. esama
  2. esafma

    Depends on the esama for AgentX connection and for alarm synchronization from the OSS.

  3. esapma

    Depends on the esama for AgentX connection and on esafma for counter threshold processing (triggering alarms).

  4. ssmagent

    Depends on the esama for handling OSS requests to the SSM and also esafma for sending traps to the OSS.

Recommended Shutdown Sequence:

  1. ssmagent
  2. esapma
  3. esafma
  4. esama

All the ESA dependent services should be stopped first and all the ESA processes should be stopped only after stopping all the dependent services.

3.5   SNMP Operation

During the initialization of the ESA services, there is a coldstart trap sent to all configured trap destinations. The coldstart trap is a standard trap with trap OID .1.3.6.1.6.3.1.1.5.1 and is described in detail in RFC 1907.

The coldstart trap from the ESA is commonly used in the OSS. It is used as a detection mechanism for node restart and/or agent restart. The coldstart trap indicates an agent restart, but can in fact be an agent restart due to a node restart. From the coldstart trap it is not possible to detect if only the agent or the node restarted. Nevertheless, at any restart type the OSS should use the coldstart trap as a trigger to initiate an alarm synchronization procedure to synchronize the alarms between the manager (OSS) and the agent (ESA) when the node and agent are back in operation.

4   Configuration

4.1   Introduction

The ESA comes with quite many configuration parameters. The many configuration parameters of course makes the use of ESA very flexible, but high flexibility also come with higher complexity.

The following sub sections describe how the ESA may be configured when it comes to options, behavior and security. The chapters are in alphabetical order and may be performed independently of each other. If there is a relation between configuration operations it is clearly indicated in the instructions.

4.2   Configuration Files

The following configuration files come with the ESA. Each configuration file (except cluster.conf) come with an associated XML Schema, which should be used for configuration format verification. Both configuration files and XML Schemas are found in {esa basedir}/conf.

4.3   Alarm Controllers

4.3.1   Introduction

The alarm controllers are available in the ESA to control the alarm flow to the OSS receiving the alarms to the ESA.

The following alarm controllers are available:

4.3.2   Function Description

4.3.2.1   Alarm Clear Control

The Alarm Clear Control (ACC) option makes it possible to stop alarm clear SNMP messages if no corresponding alarm raise SNMP message have been sent before.

The option is useful to stop faulty alarm sequences being sent to the receiving OSS. The OSS does not really need clearing of an alarm that is not active.

It is possible to configure whether the option is active or inactive. The option is by default active.

Figure 1   The Alarm Clear Control (ACC) function suppresses any alarm clear that does not have a corresponding alarm raise.

The figure above shows how the alarm clear without a corresponding alarm raise is suppressed by the ACC function in the ESA when the option is active. When inactive the alarm clear is not suppressed. When active, the FM Agent uses the Active Alarm List (AAL) to check if there is a matching alarm raise in the AAL. If there is not, the alarm clear is suppressed.

The alarm clear is matched with an alarm raise with regards to Module Identity, Error Code, Resource Identity and Originating Source IP.

4.3.2.2   Alarm Flooding Control

The Alarm Flooding Control (AFC) option makes it possible to avoid raising an identical and already active alarm being reported over and over again.

The option is useful to stop repeated alarms flooding the receiving OSS.

It is possible to configure whether the option is active or inactive. The option is by default active.

Figure 2   The Alarm Flooding Control (AFC) function suppresses repeated alarms.

The figure above shows how repeated alarms are suppressed by the AFC function in the ESA when the option is active. When inactive the repeated alarms are not stopped. When active, the FM Agent uses the Active Alarm List (AAL) to check if the alarm to be sent matches any alarm already in the AAL. If a matching alarm is found, the alarm that were supposed to be sent is suppressed.

The alarms are compared with regards to Module Identity, Error Code, Resource Identity and Originating Source IP.

4.3.3   Configuration File

The alarm controller parameters are defined in configuration file mainCfg.xml in directory {esa basedir}/conf.

4.3.4   Configuration Format

The alarm controller configurations are defined using the following format.

Configuration format:

<fm>
  <controllers>
    <acc>data</acc>
    <afc>data</afc>
  </controllers>
</fm>

The parameters contain the following data:

Examples are found in Section 4.3.6.

4.3.5   Configuration Activation

The alarm controller configurations are only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

4.3.6   Examples

The following is a configuration example for the ESA alarm controllers.

<fm>
  <controllers>
    <acc>on</acc>
    <afc>on</afc>
  </controllers>
</fm>

4.4   Cluster Mode

4.4.1   Introduction

The Cluster Mode is a capability in the ESA that allows multiple ESAs to work together as one single unit. From an OSS view the cluster running multiple nodes will be seen as a single node.

With the cluster mode there are additional capabilities introduced, such as High Availability, Alarm Redundancy and Alarm Persistency.

4.4.2   Function Description

The Cluster Mode in the ESA means that the ESA agents in a cluster (two or more nodes) will work together as one single unit representing the cluster as one system. This is also known as "One System View".

One or several nodes will be defined as masters. The rest are simply non-masters of the cluster. The Alarm data will be synchronized over all ESA masters in the cluster.

All members in a cluster can trigger new alarms, but only the masters will process the alarms. What is also given with the Cluster Mode capability is support for High Availability, Alarm Redundancy and Alarm Persistency.

Figure 3   Overview of the ESA layers when operating in Cluster Mode.

The layers in the figure above have the following responsibilities.

The following is a simple example of an alarm being triggered in a non-master, but processed by one of the masters. All data is at all times synchronized over the masters in the cluster, both the alarms being triggered and the processed and active alarm data.

Figure 4   An example alarm flow in cluster mode

  1. An error event is detected in a non-master.
  2. The error is reported to the local ESA.
  3. The error is placed in the alarm queue.
  4. The master A is active and initiates the processing of the alarm queue.
  5. The alarm is processed and stored in the Active Alarm List (AAL), which is replicated over the masters in the cluster.
  6. The alarm is finally sent to the NMS.
Note:  
If there is no master at all running in the cluster, all alarms being triggered are queued in the alarm queue in the local ESA. When a master is back in operation, the master will work on the alarm queue by processing the alarms one by one.

4.4.2.1   Active alarms in the cluster

The FM MIB data and the Active Alarm List (AAL) are only kept on the master nodes. This means that SNMP requests for alarms must be directed to one of the master nodes. The command fmactivealarms must be executed on a master node in the cluster. Executing the command fmactivealarms on a non master node in the cluster will return an error text as result, which is the expected behavior.

4.4.2.2   Master Agent / FM Agent cluster

The ESA Cluster Mode is actually running in two different clusters. The FM Agent cluster is handling the FM Agent functionality such as alarm data. The Master Agent Cluster only handles SNMP functionality such as SNMP engine ID. In order to use a VIP together with SNMPv3, the Master Agent Cluster needs to be active. For cluster solutions that operates a VIP together with SNMPv1 or SNMPv2c, or not running a VIP at all, Master Agent cluster should not be active.

4.4.3   Dynamic or static cluster

ESA are as default handling cluster nodes in a dynamic way, i.e. adding/removing/changing order of seed-nodes in cluster configuration. The advantage of this solution is that it is very easy to increase/decrease cluster size. The drawback with the dynamic solution is that if all cluster members are started at the same time they might form cluster islands. When cluster island are created during startup, they will never connect to each other. To avoid this the first node started up must be started before all the others are trying to connect to the cluster. The solution to get rid of the possible cluster islands is to use a static handling, i.e. the seed-nodes are a static list of all nodes. The user has to manually add/remove seed-nodes in configuration file.

For a description of how to configure seed-nodes see Section 4.4.6.2.

4.4.3.1   Dynamic cluster

Expansion and reduction of the cluster size can be done during runtime without any manual configurations on the already present nodes. The seed-node list(s) is a list of all nodes in the ESA cluster, and will be updated in runtime by ESA. When starting a new cluster, it is important that each node has its own address as the first seed node in the seed-nodes list(s). Recommended to be used for cluster that change its size frequently. When cluster is started one node must be started before all the other nodes.

4.4.3.1.1   Cluster expansion

The cluster can be expanded by adding one or more nodes. When adding a new node the ESA will automatically update the seed-nodes list(s) on all nodes in the cluster. This means that no manual steps are required on the already present cluster members in order for them the recognize the new node as part of the cluster.

The following configurations need to be consider while preparing the new node(s):

4.4.3.1.2   Cluster reduction

Removing a cluster member is done by stopping ESA on the corresponding node. Akka will automatically detect that the member has gone down and left the cluster. The removed node will automatically be removed from the seed-nodes list(s) on all the nodes in the cluster.

If the node is started again, it will rejoin the cluster as long as the seed-nodes list(s) includes at least one running cluster member, and Akka will automatically update the seed-nodes list(s) on the added node to the current state.

Note:  
ESA will always keep at least 10 nodes in the seed-nodes list(s). If the cluster consists of less than 10 nodes and the cluster size is reduced, the removed node will not be removed from the seed-nodes list(s). This will not have any performance impact and it is the expected behavior.

4.4.3.1.3   SSL Dynamic Clustering

The Cluster.cfg file is monitored dynamically for any configurational changes related to SSL settings.

When a node is started with SSL settings in the cluster mode, the following activities take place:

ssl {
enable-ssl = true
# The interface used in cluster. A hostname or IP address.
# Host default IP address is used if left empty.
hostname = "192.168.0.1"
# The port used in cluster.
port = 2551
                                                
security {
# For more available algorithms please visit http://docs.oracle.com.
enabled-algorithms = ["TLS_RSA_WITH_AES_128_CBC_SHA"]
                                                                                                
key-password = "changethis"
                                                                                
# This is the path to the Java Key Store.
key-store = "/opt/esa/conf/keystore"
key-store-password = "changethis"                  
                                                                                                
# Protocol to use for SSL encryption.
protocol = "TLSv1"
                                                                                                
# SecureRandom is default.
random-number-generator = ""
                                                                  
# This is the path to the Java Trust Store.
trust-store = "/opt/esa/conf/truststore"
trust-store-password = "changethis"
}

4.4.3.2   Static cluster

Expansion and reduction of the cluster size can be done during runtime. The seed-node list(s) need to be manually updated on all nodes. All nodes shall have the same list of seed-nodes and they shall be in the same order. The seed-node list(s) shall contain all nodes. Master nodes shall be first in seed-nodes list(s).

The first element in the seed-node list must be started before the other seed nodes in order to avoid forming islands. All other seed nodes in the list can be started in any order and it is not necessary to have all seed nodes running.

Note:  
Having the same seed-node list(s) on all nodes is important when restarting all nodes in cluster.

4.4.3.2.1   Cluster expansion

The cluster can be expanded by adding one or more nodes.

The following configurations need to be consider while preparing the node(s):

The following configurations need to be done on all present nodes:

4.4.3.2.2   Cluster reduction

Removing a cluster member is done by stopping ESA on the corresponding node. Akka will automatically detect that the member has gone down and left the cluster.

The following configurations need to be done on all nodes:

4.4.4   Run script on Acting Master Change

When ESA switches acting master, external script runs on the new acting master node.

The path to the script is configurable. ESA users have possibility to act upon switching acting master.

4.4.5   Configuration Files

The cluster parameters are defined in the configuration files mainCfg.xml and cluster.conf in directory {esa basedir}/conf.

4.4.6   Configuration Format

4.4.6.1   Feature Configuration, mainCfg.xml

The main configurations are defined using the following format.

Configuration format:

    <cluster active="data" master="data" seedNodes="data">
        <ma active="data"/>
        <fm active="data">
            <alarmPersistency>data</alarmPersistency>
            <script>
                <newActiveMaster timeout="data"></newActiveMaster>
                <previousActiveMaster timeout="data"></previousActiveMaster>
            </script>
        </fm>
    </cluster>

The parameters contain the following options:

Configuration example:

<cluster active="yes" master="no" seedNodes="dynamic">
    <ma active="no"/>
    <fm active="yes">
      <alarmPersistency>off</alarmPersistency>
      <script>
       <newActiveMaster timeout="30">/tmp/newactingmaster.sh</newActiveMaster>
       <previousActiveMaster timeout="30">/tmp/lostactingmaster.sh</previousActiveMaster>
      </script>
    </fm>
</cluster>

Note: The script should be available at the specified location.

4.4.6.2   Feature Configuration, cluster.conf

Since the Master Agent and the FM Agent operates in different clusters, the cluster.conf configuration file contains parameters for both the Master Agent cluster and the FM Agent cluster. The configuration between the two are very similar, with the two exceptions: the port parameter and the cluster name. It is important that the two clusters are using different ports and cluster names. This chapter concerns configuration formats for both the FM Agent cluster and the Master Agent Cluster.

4.4.6.2.1   Feature Configuration, cluster.conf, TCP

The most important Akka configurations are defined using the following format. For more information about configuration of Akka, see Reference [5].

Configuration format:

Agent{
  cluster {
     seed-nodes = [
       "akka.tcp://cluster_name@seed_ip_address:seed_port",
        ...]
  }
  ...
  remote {
    enabled-transports = ["akka.remote.netty.tcp"]
    netty {
      tcp {
        hostname = "ip_address"
        port = port
      }
    }
  }
}

The parameters contain the following data:

The following settings of tcp indicates that TCP is used as transport protocol:

enabled-transports = ["akka.remote.netty.tcp"]

netty { tcp {..}

akka.tcp://cluster_name@seed_ip_address:seed_port

Configuration example:

FmAgent{
  ...
  cluster {
    seed-nodes = [
      "akka.tcp://FMCluster@10.1.1.1:2551",
      "akka.tcp://FMCluster@10.1.1.2:2551",
      "akka.tcp://FMCluster@10.1.1.3:2551"]
	 }
  remote {
    enabled-transports = ["akka.remote.netty.tcp"]
    netty {
      tcp {
        hostname = "10.1.1.1"
        port = 2551
      }  
    }
  }
...
}

MasterAgent{
  ...
  cluster {
    seed-nodes = [
      "akka.tcp://MACluster@10.1.1.1:2552",
      "akka.tcp://MACluster@10.1.1.2:2552",
      "akka.tcp://MACluster@10.1.1.3:2552"]
	 }
  remote {
    enabled-transports = ["akka.remote.netty.tcp"]
    netty {
      tcp {
        hostname = "10.1.1.1"
        port = 2552
      }  
    }
  }
...
}

Note:  
Above example shows, the Master Agent and FM Agent configuration will normally be very similar. The only things that separates the two are, the ports and the cluster names.

4.4.6.2.2   Feature Configuration, cluster.conf, SSL

The most important Akka configurations are defined using the following format. For more information about configuration of Akka, see Reference [5]. The following configuration is applicable to both FM Agent and Master Agent cluster configuration.

Configuration format:

Agent{
  ...
  cluster {
      seed-nodes = [
        "akka.ssl.tcp://cluster_name@
             seed_ip_address:seed_port"
      ]
      ...
  }
  remote {
    enabled-transports = ["akka.remote.netty.ssl"]

    netty {
       ssl {
         enable-ssl = true
         hostname = "ip_address"
         port = port

         security {
           enabled-algorithms = ["enabled-algorithms"]
           key-password = "key_password"
           key-store = "keystore"
	          key-store-password = "keystore_password"
           protocol = "protocol"
	          random-number-generator = "random-number-gen"
           trust-store = "truststore"
	          trust-store-password = "truststore_password"
	        }
      }
    ...
    }
  }
}

The parameters contain the following data:

The following settings of ssl indicates that SSL is used:

enabled-transports = ["akka.remote.netty.ssl"]

netty {ssl {}

enable.ssl = true

akka.ssl.tcp://cluster_name@seed_ip_address:seed_port

Configuration example FmAgent:

FmAgent{
 ...
 cluster {
  	  seed-nodes = [
       "akka.ssl.tcp://FMCluster@10.1.1.1:2551",
       "akka.ssl.tcp://FMCluster@10.1.1.2:2551"]
 ...	
 remote {
    enabled-transports = [
       "akka.remote.netty.ssl"]

    netty {
       ssl {
          enable-ssl = true
          hostname = "10.1.1.1"
          port = 2551

          security {
             enabled-algorithms = 
                ["TLS_RSA_WITH_AES_128_CBC_SHA"]
             key-password = "changethis"
             key-store = "/opt/esa/conf/keystore"
	            key-store-password = "changethis"
             protocol = "TLSv1"
             random-number-generator = ""
             trust-store = "/opt/esa/conf/truststore"
	            trust-store-password = "changethis"
	         }
       }
    }
 }
...
}


Configuration example MasterAgent:

MasterAgent{
 ...
 cluster {
  	  seed-nodes = [
       "akka.ssl.tcp://MACluster@10.1.1.1:2552",
       "akka.ssl.tcp://MACluster@10.1.1.2:2552"]
 ...	
 remote {
    enabled-transports = [
       "akka.remote.netty.ssl"]

    netty {
       ssl {
          enable-ssl = true
          hostname = "10.1.1.1"
          port = 2552

          security {
             enabled-algorithms = 
                ["TLS_RSA_WITH_AES_128_CBC_SHA"]
             key-password = "changethis"
             key-store = "/opt/esa/conf/keystore"
	            key-store-password = "changethis"
             protocol = "TLSv1"
             random-number-generator = ""
             trust-store = "/opt/esa/conf/truststore"
	            trust-store-password = "changethis"
	         }
       }
    }
 }
...
}

4.4.7   Configuration Activation

The cluster mode configurations are only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

After configuration and ESA start it could be useful to run the status check command to verify that the nodes in the cluster are up and running. The command will show which nodes are successfully communicating in the ESA cluster. See Section 4.4.9.

4.4.8   Examples

The Akka configuration is in detail described in Reference [5]. Examples of cluster configuration can be found in the configuration files example_cluster.conf, example_cluster_IPv6.conf and example_cluster_SSL.conf in directory {esa basedir}/conf/examples.

4.4.9   Command: Cluster Status

4.4.9.1   Description

This command is used for viewing the current cluster status. It will present all the members and the member identities. Also, the output shows which members are masters and which master is the active one.

4.4.9.2   Command Format

The command format:

$esaclusterstatus <input>

<input> This input is optional. Leaving the "$esaclusterstatus" command without any parameters will show the default clusterstatus output which will show the nodes configured with active ESA FM Agent cluster.

-v

Enables a more detailed clusterstatus. Status for both ESA Master Agent and ESA FM Agent will be shown for each member/node.

4.4.9.3   Command Output

The command output presents a list of all active members in the cluster. The inactive members are not visible even though they are configured to be part of the cluster. Inactive members are the members that have an ESA not running or if the entire node is down.

The following is the output format:

Column1  Column2   Column3 Column4  Column5    Column6
<master> <command> <esama> <esafma> <hostname> <ipaddr>

The following data is found in the output.

<master> This column indicates if the member is defined to act as master or not.

M

The cluster member is master and active.

(M)

The cluster member is master, but standby.

empty

The cluster member is not defined to act as master.

<command> This column indicates on which node/member the cluster status command is executed.

*

This indicator shows on which node in the cluster the status command is executed.

<esama> This column indicates if cluster mode is active for the ESA Master Agent.

esama

Cluster mode is active for the ESA Master Agent.

Inactive

Cluster mode is inactive for the ESA Master Agent.

Unknown

Status for the ESA Master Agent is unknown. Either the unknown node is down/disconnected while configured to be active, or the node running the command has inactive ESA Master Agent cluster.

<esafma> This column indicates if cluster mode is active for the ESA FM Agent.

esafma

Cluster mode is active for the ESA FM Agent.

Inactive

Cluster mode is inactive for the ESA FM Agent.

Unknown

Status for the ESA FM Agent is unknown. Either the unknown node is down/disconnected while configured to be active, or the node running the command has inactive ESA FM Agent cluster.

<hostname> This is the hostname of the cluster member.
<ipaddr> This is the IP address of the cluster member.

The following is an example output for "$esaclusterstatus":

Cluster status:
 M       HostA      10.1.1.1
(M)      HostB      10.1.1.2
         HostC      10.1.1.3
     *   HostD      10.1.1.4
         HostE      10.1.1.5
         HostG      10.1.1.7
         HostH      10.1.1.8

This example shows:
- HostA is the Active Master.
- HostB is also Master, but standby.
- The status command is executed on HostD.
- As HostF is not shown, we can assume that either the
  node is down or only the ESA is down.

The following is an example output for "$esaclusterstatus -v":

Cluster status:
 M       esama      esafma      HostA      10.1.1.1
(M)      esama      esafma      HostB      10.1.1.2
         Inactive   esafma      HostC      10.1.1.3
     *   esama      esafma      HostD      10.1.1.4
         esama      Unknown     HostE      10.1.1.5
         esama      esafma      HostG      10.1.1.7
         esama      esafma      HostH      10.1.1.8

This example shows:
- HostA is the Active Master.
- HostB is also Master, but standby.
- Cluster is inactive for Master Agent on HostC
- The status command is executed on HostD.
- Cluster is configured as active for ESA Fm Agent on HostE 
  but it is not connected to the cluster
- As HostF is not shown, we can assume that either the
  node is down or only the ESA is down.

In case the ESA cluster mode is inactive, the output will simply indicate that the cluster mode is inactive.

Cluster mode inactive.

4.4.10   Cluster troubleshooting

4.4.10.1   Split/merge of cluster

A cluster is split when the connection to one or more cluster member(s) is lost and the lost cluster members creates clusters of their own.

If this happens the cluster with the oldest master is the cluster to keep. The other clusters tries to connect periodically. When the connection is back the other nodes will merge to the cluster. The Active Alarm List (AAL) from the active master will replace the AAL in the merging nodes.

Attention!

This means that during a cluster split/merge, alarms from the merging nodes can be lost!

4.5   Community Strings

4.5.1   Introduction

The SNMP v2c community string is like a user identification or password that allows access to the information of a device, published on the SNMP interface. An OSS sends the community string along with all its SNMP requests. If the community strings match, the device responds with the requested information. If the community strings do not match, an authentication failure trap is sent to the trap destination and the device simply discards the request and does not respond.

The ESA is installed with the default community strings ESA-PC and ESA-PE. These may be changed in the ESA. However, be aware of that modifying a community string in a SNMP agent requires that the community string(s) in the interfacing component(s) or system(s) must also be modified, in order to retain the access rights.

See the figure below, which shows the community strings used and their location in the ESA. The ESA-PC is configured for read only access, which means that only SNMP get operations are possible, while the ESA-PE is configured for read/write access, which means that both SNMP get and SNMP set operations may be performed.

Figure 5   The SNMP v2c community strings used by default in the ESA.

For detailed information about the community string function and configuration, see MIBs SNMP-COMMUNITY-MIB and SNMP-VIEW-BASED-ACM-MIB in directory {esa basedir}/mibs.

4.5.2   Configuration File

The community strings are defined in configuration file communityCfg.xml in directory {esa basedir}/conf.

4.5.3   Configuration Format

The community string configurations are defined using the following format.

Configuration format:

<communityCfg>
  <community active="data">
    <communityString>data</communityString>
    <securityName>data</securityName>
    <contextName>data</contextName>
  </community>
</communityCfg>

The parameters contain the following data:

Examples are found in Section 4.5.5.

4.5.4   Configuration Activation

The community string configurations are read by ESA during runtime, which means that the ESA does not need to be restarted to make the changes take effect.

4.5.5   Examples

The following is a configuration example for the ESA community strings.

<communityCfg>
  <community active="yes">
    <communityString>ESA-PC</communityString>
    <securityName>v1v2ReadOnlySecName</securityName>
  </community>
</communityCfg>

4.6   Directories

4.6.1   Overview

The ESA provides the capability to configure the directories used for both input data as well as output data.

The input directories are the ESA configuration directories. By default the configuration directories are placed within the deployment directory structure of the ESA, but they can be changed if needed.

The output directories are the directories that will be used for files created by the ESA, such as the PM Agent 3GPP XML files. By default the output directories are placed in the /var file system on Unix based systems.

4.6.2   Function Description

For FM and PM there are configuration directories that hold a number of configuration files. The number of files depends on how the ESA is setup for FM and PM. The files are in XML format, except for one file which is an XML Schema.

For further detail about the different configuration files for the different directories, see Reference [2] and Reference [3].

For FM, the following configuration directories are specified.

For PM, the following configuration directories are specified.

There is also an output directory used by the PM feature. The 3GPP XML files that are created is stored in the output directory.

Note:  
To modify the boot counter files path, follow the below steps:
  1. Verify if the ESA services are stopped.
  2. Move the boot counter files to the user preferred path.
  3. Update the {esa_basedir}/conf/mainCfg.xml configuration file with the latest path of the boot counter files.
  4. Start the ESA services.

4.6.3   Configuration File

All the ESA directories are defined in configuration file mainCfg.xml in directory {esa basedir}/conf.

4.6.4   Configuration Format

The directory configurations are defined using the following format.

Configuration format:

<directories>
  <configuration>
    <fmAlarmDefinitions>data</fmAlarmDefinitions>
    <fmAlarmTranslations>data</fmAlarmTranslations>
    <pmCounters>data</pmCounters>
    <pmJobs>data</pmJobs>
    <pmThresholds>data</pmThresholds>
  </configuration>
  <output>
    <pm3gppXml>data</pm3gppXml>
  </output>
  <bootCounter>data</bootCounter>
</directories>

The parameters contain the following data:

Examples are found in Section 4.6.6.

4.6.5   Configuration Activation

The directory configurations are only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

4.6.6   Examples

The following is a configuration example for the ESA directories.

<directories>
  <configuration>
    <fmAlarmDefinitions>/usr/local/esa/conf/
     fmAlarmDefinitions</fmAlarmDefinitions>
    <fmAlarmTranslations>/usr/local/esa/conf/
     fmAlarmTranslations</fmAlarmTranslations>
    <pmCounters>/usr/local/esa/conf/pmCounters</pmCounters>
    <pmJobs>/usr/local/esa/conf/pmJobs</pmJobs>
    <pmThresholds>/usr/local/esa/conf/pmThresholds
    </pmThresholds>
  </configuration>
  <output>
    <pm3gppXml>/var/log/esa/pm3gppXml</pm3gppXml>
  </output>
  <bootCounter>/tmp</bootCounter>
</directories>

4.7   FM MIB Preferences

4.7.1   Overview

The Fault Management MIBs ERICSSON-SNF-ALARM-MIB and ERICSSON-SNF-EVENT-MIB provides a couple of configurable parameters related to table sizes.

4.7.2   Function Description

4.7.2.1   Alarm Cleared List

When an active alarm has been cleared the cleared alarm is put into the Alarm Cleared List. This list is a SNMP table that contains a number of entries of cleared alarms. By default the 100 last cleared alarms are visible in the Alarm Cleared List. The number of entries is configurable.

4.7.2.2   Event History List

When an event has been sent the event is put into the Event History List. This list is a SNMP table that contains a number of entries of sent events. By default the 100 last sent events are visible in the Event History List. The number of entries is configurable.

4.7.3   Configuration File

The FM MIB parameters are defined in configuration file mainCfg.xml in directory {esa basedir}/conf.

4.7.4   Configuration Format

The FM MIB parameters are defined using the following format.

Configuration format:

<fm>
  <mib>
    <clearHistory>data</clearHistory>
    <eventHistory>data</eventHistory>
  </mib>
</fm>

The parameters contain the following data:

Examples are found in Section 4.7.6.

4.7.5   Configuration Activation

The FM MIB preferences are only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

4.7.6   Examples

The following is a configuration example for the ESA FM MIB preferences.

<fm>
  <mib>
    <clearHistory>100</clearHistory>
    <eventHistory>100</eventHistory>
  </mib>
</fm>

4.8   Information Agent

4.8.1   Overview

The ESA Information Agent gives the OSS the possibility to read ESA and System information using SNMP get operations for use in decision making situations in relation to possible operations on the ESA as well as using the information in OSS output, such as in reports. The information is related to identification, version numbering and dates. Also, the configuration file simply contains information related to the System useful for maintenance personnel.

The system information is defined in a configuration file. The ESA information is hard coded in the ESA delivery, but the system information can be modified. The configuration file holding System information is created during the installation of the ESA, but contains by default empty parameters. This file can be edited whenever needed.

When the ESA starts the parameters are loaded and published on SNMP. The data is published according to the MIB named ERICSSON-ESA-INFORMATION-MIB. It is found in directory {esa basedir}/mibs.

4.8.2   Configuration File

All the System information parameters are defined in configuration file infoSystem.xml in directory {esa basedir}/conf.

4.8.3   Configuration Format

The following parameters are available as System information:

Configuration format:

<infoSystem>
  <vendor>data</vendor>
  <name>data</name>
  <nameAbb>data</nameAbb>
  <version>data</version>
</infoSystem>

The parameters contain the following data:

Examples are found in Section 4.8.5.

4.8.4   Configuration Activation

The system information configurations are read by ESA during runtime, which means that the ESA does not need to be restarted to make the changes take effect.

4.8.5   Examples

The following is an example configuration for the ESA Information Agent.

<infoSystem>
  <vendor>Ericsson</vendor>
  <name>Ericsson Charging System</name>
  <nameAbb>CS</nameAbb>
  <version>5.0.3</version>
</infoSystem>

4.9   Interfaces

The ESA comes with several interfaces for FM and PM communication. The interfaces can be configured with IP address and Port number, where the IP address is optional.

The following figure shows all interfaces used in the ESA and their default values.

Figure 6   The ESA interfaces/ports and their default values.

The following ports are used for SNMP communication. See Section 4.12 for details.

The following port are used for AgentX communication. See Section 4.10 for details.

The following ports are used for Java RMI communication. See Section 4.11 for details.

The following port is used for the SSM component.

4.10   Interface AgentX

4.10.1   Introduction

See the overview description of the ESA interfaces in Section 4.9.

AgentX is a communication protocol used between the ESA Master Agent and subagents with AgentX capabilities.

Figure 7   Based on the OID in the SNMP get/set request, the Master Agent uses AgentX to route the request to the correct subagent.

In the ESA the AgentX is by default active and used between the ESA Master Agent and the subagents FM Agent and PM Agent.

Any agent with AgentX capabilities can connect to the ESA Master Agent. The AgentX capability in the ESA Master Agent is always active and can not be turned off.

For detailed information about the AgentX function and configuration, see MIB AGENTX-MIB in directory {esa basedir}/mibs.

There is one AgentX interface to configure:

The purpose of configuring IP addresses and ports for the AgentX interfaces is to bind the ESA to use a limited number of interfaces in a system with multiple interfaces.

If an IP address is specified, the ESA will only run AgentX on the port specified on the IP address specified.

If no IP address is specified, the ESA will run AgentX on the port specified on all IP addresses available in the system.

If a loopback IP address is used, the ESA only accepts AgentX connections from subagents running locally on the same node.

4.10.2   Configuration File

The AgentX parameters are defined in configuration file mainCfg.xml in directory {esa basedir}/conf.

4.10.3   Configuration Format

The AgentX interface configuration is defined using the following format.

Configuration format:

<agentx>
  <ip>data</ip>
  <port>data</port>
</agentx>

The parameters contain the following data:

Examples are found in Section 4.10.5.

4.10.4   Configuration Activation

The AgentX configurations are only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

4.10.5   Examples

The following is an example AgentX interface configuration.

<agentx>
  <ip>19.72.9.21</ip>
  <port>705</port>
</agentx>

4.11   Interface Java RMI

4.11.1   Introduction

See the overview description of the ESA interfaces in Section 4.9.

There are three RMI interfaces to configure:

The purpose of configuring IP addresses and ports for the RMI interfaces is to bind the ESA to use a limited number of interfaces in a system with multiple interfaces.

If an IP address is specified, the ESA will only run RMI on the port specified on the IP address specified.

If no IP address is specified, the ESA will run RMI on the port specified on all IP addresses available in the system.

If a loopback IP address is used, the ESA only accepts RMI connections from API users running locally on the same node.

4.11.2   Configuration File

The Java RMI parameters are defined in configuration file mainCfg.xml in directory {esa basedir}/conf.

4.11.3   Configuration Format

The RMI interface configurations are defined using the following format.

Configuration format:

<rmi>
  <ma>
    <ip>data</ip>
    <port>data</port>
  </ma>
  <fm>
    <ip>data</ip>
    <port>data</port>
  </fm>
  <pm>
    <ip>data</ip>
    <port>data</port>
  </pm>
</rmi>

The parameters contain the following data:

Examples are found in Section 4.11.5.

4.11.4   Configuration Activation

The interfaces configurations are only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

4.11.5   Examples

The following is an example RMI interface configuration.

<rmi>
  <ma>
    <ip/>
    <port>7666</port>
  </ma>
  <fm>
    <ip>2001:0db8:85a3:0042:1000:8a2e:0370:7334</ip>
    <port>8666</port>
  </fm>
  <pm>
    <ip>127.0.0.1</ip>
    <port>9666</port>
  </pm>
</rmi>

4.12   Interface SNMP

4.12.1   Introduction

See the overview description of the ESA interfaces in Section 4.9.

There are two SNMP interfaces to configure:

The purpose of configuring IP addresses and ports for the SNMP interfaces is to bind the ESA to use a limited number of interfaces in a system with multiple interfaces. Also, specifying an IP address also provides the ESA with the sender IP address to use when sending SNMP notifications.

If one or several IP addresses are specified, the ESA will only listen to the port specified on the IP addresses specified. The first specified IP address in the list of IP addresses will be used as the sender IP address in SNMP notifications sent from the ESA.

If no IP address is specified, the ESA will listen to the port specified on all IP addresses available in the system. The system default IP address will be used as the sender IP address.

If a loopback IP address is used, the ESA only accepts SNMP traffic from locally running SNMP components.

4.12.2   Configuration File

The SNMP interface parameters are defined in configuration file mainCfg.xml in directory {esa basedir}/conf.

4.12.3   Configuration Format

The SNMP interface configurations are defined using the following format.

Configuration format:

<snmp>
  <masterAgent>
    <ip>data</ip>
    <port>data</port>
    <engineId>data</engineId>
  </masterAgent>
  <fmAgent>
    <ip>data</ip>
    <port>data</port>
  </fmAgent>
</snmp>

The parameters contain the following data:

Note:  
In a cluster setup, it is mandatory to provide the same engine ID in all the nodes in the cluster.

Examples are found in Section 4.12.5.

4.12.4   Configuration Activation

The interface configurations are only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

4.12.5   Examples

The following is an example SNMP interface configuration.

Example 1: Bind Master Agent to one IPv4 address and
one IPv6 address.

<snmp>
  <masterAgent>
    <ip>19.72.9.21</ip>
    <ip>2001:0db8:85a3:0042:1000:8a2e:0370:7334</ip>
    <port>161</port>
    <engineId></engineId>
  </masterAgent>
  <fmAgent>
    <ip>127.0.0.1</ip>
    <port>8162</port>
  </fmAgent>
</snmp>

The Example 1 above will bind to only two IP addresses in the system. This means that communication towards the ESA is done using any of the two IP addresses. Other IP addresses in the system will not be used by the ESA. The IP address 19.72.9.21, which is specified first in the list of IP addresses, will be used as the sender IP address.

Example 2: Do not bind Master Agent to any IP address, but
select one IPv4 address to be the sender IP address.

<snmp>
  <masterAgent>
    <ip>19.72.9.21</ip>
    <ip></ip>
    <port>161</port>
    <engineId>80:ae:00:01:12:23</engineId>
  </masterAgent>
  <fmAgent>
    <ip>127.0.0.1</ip>
    <port>8162</port>
  </fmAgent>
</snmp>

The Example 2 above will not bind to any IP address in the system as the empty <ip> element indicates "binding to all". This means that communication towards the ESA is done using any IP address in the system. However, the IP address 19.72.9.21, which is specified first in the list of IP addresses, is specifically chosen to act as the sender IP address.

4.13   Java Virtual Machine

4.13.1   Memory Settings

4.13.1.1   ESA Services

The Java heap size can be tuned, if needed. The heap size is configured by using the following parameters.

-Xms Initial heap size.

Default value: 128 MB

-Xmx Maximum heap size.

Default value for FM Agent: 512 MB

Default value for Master Agent and PM Agent: 128 MB

To modify the Java heap size for the ESA services perform the following steps:

  1. Open the java configuration file *.vmoptions in a text editor for the ESA service to modify. The file is located in {esa basedir}/bin.
  2. Edit the following lines:

    For FM Agent:

    -Xms128m
-Xmx512m

    For Master Agent and PM Agent:

    -Xms128m
-Xmx128m

    and set the wanted memory size values.

  3. Save the changes, exit the text editor and restart the ESA.

4.13.1.2   ESA CLI Commands

The ESA CLI commands are executed as small java processes. They are executed for a short time period, but in some cases on some platforms it has been observed that a huge amount of memory has been reserved while executing the commands. This will most likely happen on servers with lot of RAM installed (> 64 GB). In case a limitation of RAM usage is needed for a CLI command, the same method as described in Section 4.13.1.1 can be used, but new .vmoptions files must be created as there are no such files by default.

  1. Create a file .vmoptions for the CLI command that you want to control the RAM.

    Example) If a RAM usage limit is needed for command pmwritecounter, then create file pmwritecounter.vmoptions.

  2. Add the following parameters -Xms and -Xmx to the file. See Section 4.13.1.1 for parameter descriptions.

    Example)

    -Xms64m
-Xmx64m

  3. Save the changes and exit the text editor.

4.13.2   CPU Usage Control

The ESA CLI commands are executed as small java processes. They are executed for a short time period, but in some cases on some platforms it has been observed that they are executed with high CPU load during the execution of the commands.

Note:  
It is not possible to control the CPU usage of a java process by using a vmoptions, similar to controlling RAM. Instead OS commands should be used.

The use of CLI command taskset has been successfully used in a Linux environment.

Example)

To bind the ESA command 'pmwritecounter' to processor #0:

# taskset 01 pmwritecounter <module> <counter> <value> <time>

where 'module', 'counter', 'value' and 'time' are arguments
to the command 'pmwritecounter'.

Please see the OS documentation for the platform being used in order to limit the CPU usage in your environment.

4.13.3   IP Address Cache Time

If the ESA resides on a system where the communication to a subagent is setup using a hostname that changes over time, there is a need to refresh the IP address of the hostname now and then. When the ESA is started, the IP address of the hostname is by the ESA read from a DNS and the IP address is cached. The default setting for cache time is "forever". This means that once the ESA reads the IP address for a hostname, that IP address is used until the ESA is restarted.

To configure the ESA to refresh the IP address on interval perform the following steps:

  1. Open the java configuration file *.vmoptions in a text editor for the ESA service to modify. The file is located in {esa basedir}/bin.
  2. Append the following line to the file:

    -Dsun.net.inetaddr.ttl=<time>

    where <time> is equal to the refresh time in seconds.

  3. Save the changes, exit the text editor and restart the ESA.

4.13.4   Dual Stack IP

On dual stack machines with both IPv4 and IPv6 addresses, there might be issues with the ESA startup time. In order to shorten the startup time the solution could be to mark IPv4 is preferred. This is done by setting the java property java.net.preferIPv4Stack.

To configure the ESA to prefer IPv4 addresses perform the following steps:

  1. Open the java configuration file *.vmoptions in a text editor for the ESA service to modify. The file is located in {esa basedir}/bin.
  2. Append the following line to the file:

    -Djava.net.preferIPv4Stack=true

  3. Save the changes, exit the text editor and restart the ESA.

4.14   PM Agent Preferences

4.14.1   Overview

The PM Agent has a few configuration parameters regarding the creation of 3GPP XML files.

The parameter Unique Identity is about naming the output files. Each 3GPP XML file will be "tagged" with the string used in the uniqueId field.

The parameters File Retention Period and File Retention Scan are about managing the growing number of 3GPP XML output files.

The parameter deltaCustomize is about customizing the calculation of delta value and setting it to zero during the first granularity period.

4.14.2   Function Description

The 3GPP XML files are created according to the job definitions in each interval specified. The number of files will constantly grow, which over time might fill up the disk space. Using file retention control the number of files are limited by controlling the age of the files.

It is recommended to have an OSS reading the PM output files and then delete them when successfully read. But, if there are no such process reading/deleting files, the disk usage can be controlled using ESA internal disk usage control processes.

4.14.3   Configuration File

The PM Agent parameters are defined in configuration file mainCfg.xml in directory {esa basedir}/conf.

4.14.4   Configuration Format

The PM Agent preferences parameters are defined using the following format.

Configuration format:

<pm>
<uniqueId>data</uniqueId>
<fileRetentionPeriod>data</fileRetentionPeriod>
<fileRetentionScan>data</fileRetentionScan>
<deltaCustomize>data</deltaCustomize>
</pm>

The following parameters are defined:

Examples are found in Section 4.14.6.

4.14.5   Configuration Activation

The PM Agent configurations are only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

4.14.6   Examples

The following is a configuration example for the PM Agent settings.

<pm>
<uniqueId>ESA</uniqueId>
<fileRetentionPeriod>14</fileRetentionPeriod>
<fileRetentionScan>60</fileRetentionScan>
<deltaCustomize>off</deltaCustomize>
</pm>

4.15   Master Agent Preferences

4.15.1   Overview

The Master Agent has a configuration parameter regarding the OID validation.

The parameter First Sub-Identifier check is to enable or disable OID validation to start with a sub-identifier of 0, 1, or 2.

Example:

4.15.2   Configuration File

The Master Agent parameters are defined in configuration file mainCfg.xml in directory {esa basedir}/conf

4.15.3   Configuration Format

Caution!

firstSubIDCheck configuration is added only for customers who are using non-standard OID in their architecture and requested to bypass validation when sending information through ESA. It is recommended to keep the validation enabled to align with RFC standard.

The Master Agent preferences parameter is defined using the following format.

Configuration format:

<ma>
  <firstSubIDCheck>data</firstSubIDCheck> 
</ma>

The following parameter is defined:

4.15.4   Configuration Activation

The Master Agent configurations are only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

4.15.5   Examples

The following is a configuration example for the Master Agent settings.

<ma>
   <firstSubIDCheck>yes</firstSubIDCheck>
</ma>

4.16   SNMP Proxy

4.16.1   Introduction

The SNMP proxy capability in the ESA Master Agent is used for routing SNMP operations, such as SNMP-GET and SNMP-SET, to SNMP subagents.

Figure 8   Based on the OID in the SNMP get/set request, the Master Agent uses the proxy configuration to route the request to the correct subagent.

The figure above shows the OIDs defined for a default ESA installation; the SSM OIDs. Note that the SSM proxy settings by default are inactive. If SSM is in operation, the predefined SSM proxy settings can be activated by changing configuration parameter active from no to yes.

Any SNMP agent which allows SNMP get/set requests may be connected to the Master Agent by providing SNMP route information to the Master Agent proxy configuration file. The red dotted line in the figure above shows an example of a SNMP get request, sent to the OID .1.3.6.1.4.1.1977. The proxy configuration settings tells the Master Agent to route the SNMP message to subagent SSM.

For detailed information about the SNMP Proxy function and configuration, see MIBs SNMP4J-PROXY-MIB and SNMP-TARGET-MIB in directory {esa basedir}/mibs.

4.16.2   Configuration File

The SNMP Proxy parameters are defined in configuration file proxyCfg.xml in directory {esa basedir}/conf.

4.16.3   Configuration Format

The SNMP Proxy configurations are defined using the following format.

Configuration format:

<proxyCfg>
  <proxyDefinition active="data">
    <proxy proxyType="data">
      <subtree>data</subtree>
      <contextName>data</contextName>
    <proxy>
    <target snmpVersion="data">
      <ip>data</ip>
      <port>data</port>
      <securityName>data</securityName>
      <securityLevel>data</securityLevel>
      <timeout>data</timeout>
      <retries>data</retries>
    </target>
  </proxyDefinition>
</proxyCfg>

The parameters contains the following data:

Examples are found in Section 4.16.5.

4.16.4   Configuration Activation

The SNMP proxy configurations are read by ESA during runtime, which means that the ESA does not need to be restarted to make the changes take effect.

4.16.5   Examples

The following example shows a proxy configuration for a SNMP subagent using SNMPv2c.

<proxyCfg>
  <proxyDefinition active="yes">
    <proxy proxyType="readAndWrite">
      <subtree>1.3.6.1.4.1.1977</subtree>
    <proxy>
    <target snmpVersion="v2c">
      <ip>127.0.0.1</ip>
      <port>7161</port>
      <securityName>private</securityName>
      <securityLevel>noAuthNoPriv</securityLevel>
      <timeout>5</timeout>
      <retries>3</retries>
    </target>
  </proxyDefinition>
</proxyCfg>

4.17   SNMPv3

4.17.1   Overview

This chapter explains how to enable SNMPv3 in the Ericsson SNMP Agent on a very high level. It is assumed that the reader/user of this chapter is familiar with SNMPv3 and knows the configurations and concepts needed.

The overall procedure is to set up the USM configuration, VACM configuration, Trap Destination configuration and maybe also Proxy configuration according to the following process.

  1. One or several USM users are setup, which are setup with a number of security settings.

    See Section 4.20.

  2. One or several VACM views and access rights are created, which are linked to the USM user(s).

    See Section 4.21.

  3. One or several Trap Destinations can be created, which in turn also are linked to the USM user(s).

    See Section 4.19.

  4. If there are subagents connected to the ESA also Proxies can be setup, which are linked to USM and VACM settings.

    See Section 4.16.

4.17.2   Boot Counter File

This section is for information only. The files described in this section shall not be altered or removed.

The ESA maintains two boot counter files, which are used by the SNMPv3 function according to RFC 3414. The following two files are found on the file system where the ESA is deployed.

4.17.3   SHA2 Support

ESA18 is enabled to support SHA256 authentication along with the existing authentication protocols MD5 and SHA-1. ESA configuration file - UsmCfg.xml should be updated for the SNMP V3 user with SHA2 configuration to consider the user with SHA2 authentication.

Configuration Example:

<usmUser active="yes">
        <securityName>v3AuthSHAPrivDESSecName</securityName>
        <authProtocol>AuthSHA2</authProtocol>
        <authPassword>v3AuthSHAPrivDESAuthPassword</authPassword>
        <privProtocol>PrivDES</privProtocol>
        <privPassword>v3AuthSHAPrivDESPrivPassword</privPassword>
</usmUser>

Note:  
ESA18 supports only AuthHMAC192SHA256 authentication.

4.18   Subagent AAL Synchronization

4.18.1   Introduction

The Subagent AAL Synchronization (SAS) feature is an API that provides an integrator with the possibility to synchronize alarms in subagents with the ESA during ESA startup.

Please see Reference [2] for further information about this function.

4.18.2   Configuration File

The SAS parameters are defined in configuration file mainCfg.xml in directory {esa basedir}/conf.

4.18.3   Configuration Format

The SAS configuration is defined using the following format.

Configuration format:

<sas active="data">
  <agentHost>data</agentHost>
  <agentPort>data</agentPort>
  <agentName>data</agentName>
  <timeout>data</timeout>
</sas>

The attribute contains the following data:

The elements contain the following data:

Examples are found in Section 4.18.5.

4.18.4   Configuration Activation

The SAS configuration is only read at ESA startup, which means that the ESA must be started or restarted to make the changes take effect.

4.18.5   Examples

The following is a configuration example for the SAS feature.

<sas active="yes">
  <agentHost>127.0.0.1</agentHost>
  <agentPort>12345</agentPort>
  <agentName>mySasServer</agentName>
  <timeout>15</timeout>
</sas>

4.19   Trap Destination

4.19.1   Overview

The trap destination tells the ESA to which OSS to send the SNMP notifications.

The Master Agent in the ESA is responsible for handling the trap destination(s). The figure below shows how the trap destinations are defined in the ESA.

Figure 9   An overview of the ESA trap destination configurations.

4.19.2   Function Description

The FM Agent is the module triggering the SNMP notifications from the ESA on incoming order from the RMI and/or SNMP interfaces. The Master Agent is the module being responsible for managing the interface to the OSS.

The ESA supports handling of single or multiple OSSes. At least one trap destination must be defined to get the ESA to send SNMP notifications. The ESA can run with no trap destinations defined at all, which simply means that no SNMP notifications are sent from the ESA, but all other ESA features will work as normal.

The status of each specified trap destination can easily be controlled by a parameter. Each trap destination can, independently of another, be made inactive without removing the trap destination configuration. This is useful if there is a need to temporarily stop the sending of alarms to a manager.

If a trap destination is to be setup using SNMPv3 format, please see the Section 4.17 for additional configurations needed.

For detailed information about the Trap Destination function and configuration, see MIBs SNMP-NOTIFICATION-MIB och SNMP-TARGET-MIB in directory {esa basedir}/mibs. The MIBs VACM-MIB (setting up view and access) and SNMP-NOTIFICATION-LOG-MIB (notification history) could be of interest.

If the ESA is running in cluster mode, it is recommended to not define trap destinations for the ESAs that are not setup as masters. Any ESA will at start/restart send a coldstart trap. In a cluster the ESAs that are not running as master should not send any traps at all.

4.19.3   Configuration File

The trap destination parameters are defined in configuration file trapDestCfg.xml in directory {esa basedir}/conf.

4.19.4   Configuration Format

The following parameters are available for a trap destination.

Configuration format:

<trapDestCfg>
  <managerDefinition snmpVersion="data" active="data">
    <ip>data</ip>
    <port>data</port>
    <securityName>data</securityName>
    <securityLevel>data</securityLevel>
  </managerDefinition>
</trapDestCfg>

The configuration attributes contain the following data:

The configuration elements contain the following data:

Examples are found in Section 4.19.6.

4.19.5   Configuration Activation

The trap destination configurations are read by ESA during runtime, which means that the ESA does not need to be restarted to make the changes take effect.

4.19.6   Examples

4.19.6.1   Example 1: SNMPv2c

The following example shows how the trap destination can be setup using Trap Destination configuration for SNMPv2c traps including VACM configuration. USM configuration is not applicable for SNMPv2c.

File: trapDestCfg.xml:

<trapDestCfg>
  <managerDefinition snmpVersion="v2c" active="yes">
    <ip>100.12.34.56</ip>
    <port>162</port>
    <securityName>v1v2ReadWriteSecName</securityName>
    <securityLevel>noAuthNoPriv</securityLevel>
  </managerDefinition>
</trapDestCfg>

File: vacmCfg.xml:

<securityToGroup active="yes">
  <securityModel>SNMPv2</securityModel>
  <securityName>v1v2ReadWriteSecName</securityName>
  <groupName>v1v2ReadWriteGroup</groupName>
</securityToGroup>

<access active="yes">
  <groupName>v1v2ReadWriteGroup</groupName>
  <securityModel>SNMPv2</securityModel>
  <securityLevel>noAuthNoPriv</securityLevel>
  <contextPrefix/>
  <contextMatch>exact</contextMatch>
  <readViewName>fullReadView</readViewName>
  <writeViewName>fullWriteView</writeViewName>
  <notifyViewName>fullNotifyView</notifyViewName>
</access>

<view active="yes">
  <name>fullNotifyView</name>
  <subtree>1.3</subtree>
  <mask/>
  <type>included</type>
</view>

File: usmCfg.xml

No configuration for SNMPv2c traps!

The example above shows a SNMPv2c trap destination with security name v1v2ReadWriteSecName being defined. The security name v1v2ReadWriteSecName points at access group v1v2ReadWriteGroup, which in turn points at notify view fullNotifyView. The notify view fullNotifyView is set to allow all traps that comply to OID "1.3" to be sent.

For further information about VACM configuration, see Section 4.21.

4.19.6.2   Example 2: SNMPv3

The following example shows how the trap destination can be setup using Trap Destination configuration for SNMPv3 traps including VACM and USM configurations.

File: trapDestCfg.xml:

<trapDestCfg>
  <managerDefinition snmpVersion="v3" active="yes">
    <ip>100.12.34.56</ip>
    <port>162</port>
    <securityName>v3AuthSHAPrivDESSecName</securityName>
    <securityLevel>authPriv</securityLevel>
  </managerDefinition>
</trapDestCfg>

File: vacmCfg.xml

<securityToGroup active="yes">
  <securityModel>USM</securityModel>
  <securityName>v3AuthSHAPrivDESSecName</securityName>
  <groupName>v3AuthPrivGroup</groupName>
</securityToGroup>
	
<access active="yes">
  <groupName>v3AuthPrivGroup</groupName>
  <securityModel>USM</securityModel>
  <securityLevel>authPriv</securityLevel>
  <contextPrefix/>
  <contextMatch>exact</contextMatch>
  <readViewName>fullReadView</readViewName>
  <writeViewName>fullWriteView</writeViewName>
  <notifyViewName>fullNotifyView</notifyViewName>
</access>

<view active="yes">
  <name>fullNotifyView</name>
  <subtree>1.3</subtree>
  <mask/>
  <type>included</type>
</view>


File: usmCfg.xml

<usmUser active="yes">
  <securityName>v3AuthSHAPrivDESSecName</securityName>
  <authProtocol>AuthSHA</authProtocol>
  <authPassword>myAuthPassword</authPassword>
  <privProtocol>PrivDES</privProtocol>
  <privPassword>myPrivPassword</privPassword>
</usmUser>

The example above shows a SNMPv3 trap destination with security name v3AuthSHAPrivDESSecName being defined. The security name v3AuthSHAPrivDESSecName points at access group v3AuthPrivGroup, which in turn points at notify view fullNotifyView. The notify view fullNotifyView is set to allow all traps that comply to OID "1.3" to be sent. In order to allow sending of traps with both authentication and privacy control, USM is defined for the security name v3AuthSHAPrivDESSecName with both authentication and privacy settings.

For further information about VACM configuration, see Section 4.21, and for USM configuration, see Section 4.20.

4.20   USM

4.20.1   Introduction

The ESA fully supports RFC 3415, which describes USM.

See the MIB SNMP-USER-BASED-SM-MIB for further information.

4.20.2   Configuration File

The USM in the ESA is configured in configuration files usmCfg.xml.

Note that there are default configurations created for USM. They are however by default inactive.

4.20.3   Configuration Format

The USM user is setup following the MIB SNMP-USER-BASED-SM-MIB. The user is setup with authentication and privacy settings.

The following parameters are to be defined:

Configuration format:

<usmCfg>
  <usmUser active="data">
    <securityName>data</securityName>
    <authProtocol>data</authProtocol>
    <authPassword>data</authPassword>
    <privProtocol>data</privProtocol>
    <privPassword>data</privPassword>
  </usmUser>
</usmCfg>

The parameters contain the following data:

Examples are found in Section 4.20.5.

4.20.4   Configuration Activation

The USM configurations are read by ESA during runtime, which means that the ESA does not need to be restarted to make the changes take effect.

4.20.5   Examples

The following example shows the authentication and privacy settings for the security name v1v2ReadOnlySecName.

<usmCfg>
  <usmUser active="yes">
    <securityName>v1v2ReadOnlySecName</securityName>
    <authProtocol>AuthMD5</authProtocol>
    <authPassword>myAuthPassword</authPassword>
    <privProtocol>PrivAES128</privProtocol>
    <privPassword>myPrivPassword</privPassword>
  </usmUser>
</usmCfg>

4.20.6   Encrypt USM Configuration

4.20.6.1   Description

Note:  
The encrypted usmCfg.xml is specific to particular installation and cannot be reused across installations.

4.20.6.2   ESA USM Command Format

esausm <action> <usmUserEntry> [<configFile>] <[<authPwd>] || [<privPwd>]>

Table 1    Command-line parameters:

Parameters

Description

action

The type of action to perform

-e

--encrypt

Encrypt a USM user entry.

-d

--decrypt

Decrypt a USM user entry.

-u

--updatePwd

Update authentication password or privilege password for already encrypted entry.

usmUser

USM entry to be encrypted / decrypted

-s

--securityName

The securityName of the USM user entry from configuration file.

-a

--all

Encrypt/Decrypt all USM user entry from configuration file.

configFile

USM configurations file to be encrypted / decrypted

-f

--file

USM configuration file path.

   

Default Path

{ESA_HOME}/conf/usmCfg.xml

authPwd

Mandatory to use it with updatePwd action [ -u ]. To be used for updating encrypted authentication password of the given security name

 

--authPwd

Authentication Password of the encrypted USM entry.

privPwd

Mandatory to use it with updatePwd action [ -u ].


It is used for updating encrypted privilege password of the given security name.

 

--privPwd

Privilege Password of the USM entry

4.20.6.3   Examples

Encryption:

esausm  --encrypt --securityName  v3AuthSHAPrivDESSecName
            Using long option to encrypt a particular USM entry.
esausm  -e -s v3AuthSHAPrivDESSecName
            Using short option to encrypt a particular USM entry.
esausm  --encrypt –-all
            Using long option to encrypt all USM entries.
esausm  -e --all
            Using short option to encrypt all USM entries.

Decryption:

esausm  --decrypt --securityName v3AuthSHAPrivDESSecName
            Using long option to decrypt a particular USM entry.
 
esausm  -d -s v3AuthSHAPrivDESSecName
            Using short option to decrypt a particular USM entry.
 
esausm  --decrypt –-all
            Using long option to decrypt all USM entries.
 
esausm  -d --all
            Using short option to encrypt all USM entries.

Update:

esausm  --updatePwd -s v3AuthSHAPrivDESSecName --authPwd 
Enter Authentication password
*****
      Update already encrypted authentication password field for the given security name.
 
esausm  --updatePwd -s v3AuthSHAPrivDESSecName --privPwd 
Enter Privacy Password
*****
      Update already encrypted privilege password field for the given security name.

4.21   VACM

4.21.1   Introduction

The ESA fully supports RFC 3416, which describes VACM.

See the MIB SNMP-VIEW-BASED-ACM-MIB for further information.

4.21.2   Configuration File

The VACM in the ESA is configured in configuration file vacmCfg.xml.

Please note that there are default configurations created for VACM for v1, v2c and v3. The configurations for SNMP v1 and SNMP v2c are active, but for SNMPv3 inactive

4.21.3   Configuration Format

4.21.3.1   Main Structure

The VACM is setup following the MIB SNMP-VIEW-BASED-ACM-MIB. The VACM is about creating views and setting access rights to the views.

The VACM configuration is built up in three main sections.

Configuration format:

<vacmCfg>
  <securityToGroup>
     ...
  </securityToGroup>
  <accesses>
     ...
  </accesses>
  <views>
     ...
  </views>
</vacmCfg>

The sections are defined as following:

4.21.3.2   Element: SecurityToGroup

The element securityToGroup contains the following parameters:

Configuration format:

<securityToGroup active="data">
  <securityModel>data</securityModel>
  <securityName>data</securityName>
  <groupName>data</groupName>
</securityToGroup>

The parameters contain the following data:

Examples are found in Section 4.21.5.

4.21.3.3   Element: Accesses

The element accesses contains the following parameters:

Configuration format:

<accesses>
  <access active="data">
    <groupName>data</groupName>
    <securityModel>data</securityModel>
    <securityLevel>data</securityLevel>
    <contextPrefix>data</contextPrefix>
    <contextMatch>data</contextMatch>
    <readViewName>data</readViewName>
    <writeViewName>data</writeViewName>
    <notifyViewName>data</notifyViewName>
  </access>
</accesses>

The parameters contain the following data:

Examples are found in Section 4.21.5.

4.21.3.4   Element: Views

The element views contains the following parameters:

Configuration format:

<views>
  <view active="data">
    <name>data</name>
    <subtree>data</subtree>
    <mask>data</mask>
    <type>data</type>
  </view>
</views>

The parameters contain the following data:

Examples are found in Section 4.21.5.

4.21.4   Configuration Activation

The VACM configurations are read by ESA during runtime, which means that the ESA does not need to be restarted to make the changes take effect.

4.21.5   Examples

4.21.5.1   Example securityToGroup

The following example shows a group being specified for the security name v1v2ReadOnlySecName.

<securityToGroup active="yes">
  <securityModel>SNMPv2</securityModel>
  <securityName>v1v2ReadOnlySecName</securityName>
  <groupName>v1v2ReadOnlyGroup</groupName>
</securityToGroup>

4.21.5.2   Example: access

The following example shows an access being defined for security name v1v2ReadOnlyGroup.

<accesses>
  <access active="yes">
    <groupName>v1v2ReadOnlyGroup</groupName>
    <securityModel>SNMPv2</securityModel>
    <securityLevel>noAuthNoPriv</securityLevel>
    <contextPrefix/>
    <contextMatch>exact</contextMatch>
    <readViewName>fullReadView</readViewName>
    <writeViewName>noWriteView</writeViewName>
    <notifyViewName>fullNotifyView</notifyViewName>
  </access>
</accesses>

4.21.5.3   Example: view

The following example shows a view named fullReadView being defined.

<views>
  <view active="yes">
    <name>fullReadView</name>
    <subtree>1.3</subtree>
    <mask/>
    <type>included</type>
  </view>
</views>

4.22   Originating source as IP / Hostname

4.22.1   Introduction

This configuration is used to represent originating source as IP or Hostname in MIB, alarm, and log.

4.22.2   Configuration File

It is defined in mainCfg.xml under {esa basedir}/conf directory.

4.22.3   Configuration Format

Configuration format:
<common>
<orginatingSourceType>data</orginatingSourceType>
</common>

The parameter contains the following data:

IP - It is the default value for the configuration. This value will ensure ESA represent originating source as IP.

HOSTNAME - This value will ensure ESA represent originating source as HOSTNAME

4.22.4   Examples

The following are the example for IP or HOSTNAME configuration for originating source.

To represent originating source as IP address

<common>
<orginatingSourceType>IP</orginatingSourceType>
</common>

To represent originating source as HOSTNAME

<common>
<orginatingSourceType>HOSTNAME</orginatingSourceType>
</common>

5   Administration

5.1   Version

5.1.1   Introduction

This section describes how to find the software versions of ESA and SSM version that is installed on a system.

The software versions are also accessible using SNMP. See section Section 4.8.

5.1.2   ESA Version

The ESA version is found by executing the following commands.

# cd <esa basedir>/lib

# java -jar esa.jar

The following is the output format:

Name=Ericsson SNMP Agent

NameAbbrev=ESA

Version=X.X

Build=X.X.<version>.<build>

BuildDate=<date> <time>

5.1.3   SSM Version

The SSM version is found by executing the following commands.

# cd <ssm basedir>/bin

# ssmagent -v

The following is an output example:

4.0.1-155 (Nov 19 2014)

5.2   Logging

5.2.1   Introduction

This section describes the log files produced by the ESA, how to configure the log content, where to find the logs and some words about the data found within them. The logging component log4j is used for all logs.

The following log files are used in the ESA:

The log file directories are defined in log file configuration files.

5.2.2   Configuration Files

The following configuration files are used for log file administration.

All configuration files are found in directory {esa basedir}/conf.

5.2.3   Configuration Format

5.2.3.1   Overview

The log files are configured using the configuration format of log4j. See the log4j DTD, which is found as DTD file log4j.dtd in directory {esa basedir}/conf, and the log4j documentation at Reference [4].

Normally the log4j configurations are not changed, but there are three parameter that, from time to time, might need modification.

5.2.3.2   Log Activation/Deactivation

The activation and deactivation of the log file creation is managed using values all and off for the value attribute to the logger element.

The following values are supported.

All logging is by default active, except the translated log which by default is inactive.

The following is an example configuration.

Configuration example:

...
	<logger name="alarmRaiseLog" additivity="false">
		<level value="all" />
		<appender-ref ref="alarmLogFileAppender" />
	</logger>
...
	<logger name="translatedLog" additivity="false">
		<level value="OFF" />
		<appender-ref ref="translatedLogFileAppender" />
	</logger>
...

5.2.3.3   Log Level

The log level can be changed to higher or lower level of log details. The log level configuration is done in the log files described in Section 5.2.2.

The following log levels are supported.

Default value is INFO, but in case the ESA is not working well, the level DEBUG could be useful. If the ESA is working well and the log entries are found too detailed the level WARN or ERROR can be used. It is however recommended to keep level INFO for normal operation.

The following is an example of a log level configuration.

Configuration example:

...
<category name="com.ericsson.esa">
  <priority value="INFO" />
</category>
...

5.2.3.4   Log Directory

The target directories where the log files are stored can be modified. The directory configuration is done in the log files described in Section 5.2.2.

The following list presents the default log directories. The directories are by default the same for all log files, but they can be changed individually.

The default target directory for the PM Agent 3GPP XML output files is the following.

The following is an example of a log directory configuration.

Configuration example:

...
<appender name="fileAppender"
    class="org.apache.log4j.RollingFileAppender">
  <param name="File"
      value="/var/log/esa/FmAgent.log"/>
...

5.2.4   Configuration Activation

The logging configurations are read by ESA during runtime, which means that the ESA does not need to be restarted to make the changes take effect.

5.2.5   Default Warning Messages

The following warning messages are by default found in the Master Agent log file MasterAgent.log as well as in the FM Agent log file FmAgent.log. There is no need to take any action on these warning messages. They are completely normal.

First Master Agent start

At the very first start of the Master Agent, it does not find the file esama.bc in directory {esa basedir}/bin. The following is logged in the Master Agent log.

Example:

WARN <timestamp> [main] org.snmp4j.agent.cfg.EngineBootsCounterFile - Could not find boot counter file: <path>/esama.bc

First FM Agent start

At the very first start of the FM Agent, it does not find the file esafma.bc in directory {esa basedir}/bin. The following is logged in the FM Agent log.

Example:

WARN <timestamp> [main] org.snmp4j.agent.cfg.EngineBootsCounterFile - Could not find boot counter file: <path>/esafma.bc

AgentX registration

At the registration of any AgentX subagent, the Master Agent issues a "AgentX connection warning". This is found specifically for the FM Agent and PM Agent, which are part of the ESA. The following is logged in the Master Agent log.

Example:

WARN <timestamp> [DefaultTCPTransportMapping_0.0.0.0/705] org.snmp4j.agent.agentx.master.AgentXCommandProcessor - SysOREntry managed object for context not found, instead found: null

5.2.6   Logging Alarms

The log file alarms.log contains every alarm and event that has been sent from the FM Agent to the Master Agent. Please note that the log shows what was sent from the FM Agent and not what is received in the OSS. The Master Agent might stop the message from being sent due to mismatched SNMPv3 settings between ESA and the OSS or lack of or erroneous trap destination configuration.

Format for message types Alarm Raise and Alarm Clear.

!----- <Message Type> ---------------------------------
Module             : <Module>
Error Code         : <Error Code>
Resource Id        : <Resource Id>
Timestamp First    : <Timestamp First>
Repeated Counter   : <Repeated Counter>
Timestamp Last     : <Timestamp Last>
Model Description  : <Model Description>
Active Description : <Active Description>
Event Type         : <Event Type>
Probable Cause     : <Probable Cause>
Severity           : <Severity>
Orig Source IP     : <Originating Source IP>
Sequence Number    : <Sequence Number>
-------------------------------------------------------!
...

Format for message type Event.

!----- <Message Type> ---------------------------------
Module             : <Module>
Error Code         : <Error Code>
Resource Id        : <Resource Id>
Timestamp          : <Timestamp>
Model Description  : <Model Description>
Active Description : <Active Description>
Event Type         : <Event Type>
Probable Cause     : <Probable Cause>
Severity           : <Severity>
Orig Source IP     : <Originating Source IP>
Sequence Number    : <Sequence Number>
-------------------------------------------------------!
...

The rows are interpreted as follows. The detailed descriptions of each parameter is found in Reference [2].

Example

The following is an example log file output showing one alarm raise, one alarm clear and one event.

!----- Alarm Raise ---------------------------------------
Module             : MYALARM
Error Code         : 10
Resource Id        : 1.1.1.2.3
Timestamp First    : Mon May 05 15:01:00 CEST 2014
Repeated Counter   : 1
Timestamp Last     : Mon May 05 15:01:00 CEST 2014
Model Description  : My test alarm.
Active Description : My test alarm.
Event Type         : 2
Probable Cause     : 119
Severity           : warning
Orig Source IP     : 19.72.9.21
Sequence Number    : 5
---------------------------------------------------------!

!----- Event ---------------------------------------------
Module             : MYEVENT
Error Code         : 20
Resource Id        : 1.1.1.2.8
Timestamp          : Mon May 05 15:02:00 CEST 2014
Model Description  : My test event.
Active Description : My test event.
Event Type         : 2
Probable Cause     : 119
Severity           : cleared
Orig Source IP     : 19.72.9.21
Sequence Number    : 12
---------------------------------------------------------!

!----- Alarm Clear ---------------------------------------
Module             : MYALARM
Error Code         : 10
Resource Id        : 1.1.1.2.3
Timestamp First    : Mon May 05 15:01:00 CEST 2014
Repeated Counter   : 6
Timestamp Last     : Mon May 05 15:31:00 CEST 2014
Model Description  : My test alarm.
Active Description : My test alarm.
Event Type         : 2
Probable Cause     : 119
Severity           : cleared
Orig Source IP     : 19.72.9.21
Sequence Number    : 5
---------------------------------------------------------!

5.2.7   Logging Not Translated Alarms

This log file contains every trap and notification that has gone through the alarm translation process in the FM Agent without being successfully matched to a condition. In other words the log contains traps that are not translated.

Format

A single log entry for one SNMP trap/notification being not translated looks like the following.

!----- <timestamp> ---------------------------------------
Trap OID: <trap oid>
1: <oid varbind 1>, <snmp datatype>, <value>
2: <oid varbind 2>, <snmp datatype>, <value>
...
n: <oid varbind n>, <snmp datatype>, <value>
---------------------------------------------------------!

Example

This log file is an example derived from the FM Agent showing a few SNMP traps that are not translated.

!----- 2015-02-23 18:33:16 -------------------------------
Trap OID: 1.3.6.1.6.3.1.1.5.1
---------------------------------------------------------!

!----- 2015-02-23 19:41:06 -------------------------------
Trap OID: 1.3.6.1.4.1.1977.0.38
1: 1.3.6.1.4.1.1977.1.1.2.1.0, OctetString, d7:9b:f9:1d:83:d7:9c:41:9a:78:4d:e4:43:b1:c8:5f
2: 1.3.6.1.4.1.1977.1.1.2.2.0, IpAddress, 136.225.39.17
3: 1.3.6.1.4.1.1977.1.1.2.3.0, OctetString, SE00003345
4: 1.3.6.1.2.1.2.2.1.6.14, OctetString, 00:1f:b5:23:d7:85
---------------------------------------------------------!

!----- 2015-02-23 20:12:08 -------------------------------
Trap OID: 1.3.6.1.4.1.1977.0.46
1: 1.3.6.1.4.1.1977.30.1.1.3.1, OctetString, c:\temp\testlog.txt
2: 1.3.6.1.4.1.1977.30.3.1.3.1.1.1, OctetString, A test error
3: 1.3.6.1.4.1.1977.30.3.1.4.1.1.1, Integer, 3
4: 1.3.6.1.4.1.1977.30.1.1.14.1, OctetString, Mount connection
---------------------------------------------------------!

5.2.8   Logging Translated Alarms

This log file contains every trap and notification that has gone through the alarm translation process in the FM Agent and being successfully matched to a condition. In other words the log contains traps that are translated.

This logging is by default inactive. Translated alarms will end up as ESA SNMP alarms being sent to the OSS. If logging of translated alarms is needed it is activated in the log configuration, see Section 5.2.3.2.

Format

A single log entry for one SNMP trap/notification being translated looks like the following.

!----- <timestamp> ---------------------------------------
Trap OID: <trap oid>
Sender IP: <sender IP address>
1: <oid varbind 1>, <snmp datatype>, <value>
2: <oid varbind 2>, <snmp datatype>, <value>
...
n: <oid varbind n>, <snmp datatype>, <value>
*** <operation>
Type               : <messageType>
Module             : <moduleId
Error Code         : <errorCode
Resource Id        : <resourceId>
Orig Source IP     : <origSrcIp>
Active Description : <activeDescr>

---------------------------------------------------------!

The format above shows the SNMP alarm and content being received and also what operation is taken; Translation, Suppress or Transparent. One alarm could also trigger multiple operations.

Example

This log file is an example derived from the FM Agent showing a SNMP trap that is translated.

!----- 2015-02-23 18:33:16 -------------------------------
Trap OID: 1.3.6.1.4.1.193.3
Sender IP: 127.0.0.1
1: 1.3.6.1.4.1.193.1.1.1, OctetString, Test string
2: 1.3.6.1.4.1.193.1.1.2, OID, 1.1.1.2.3
3: 1.3.6.1.4.1.193.1.1.3, UnsignedInteger32, 1000
4: 1.3.6.1.4.1.193.1.1.4, Gauge32, 2000
5: 1.3.6.1.4.1.193.1.1.5, Counter32, 4294967295
6: 1.3.6.1.4.1.193.1.1.6, Counter64, 1844674407370955
7: 1.3.6.1.4.1.193.1.1.7, TimeTicks, 0:20:34.56
8: 1.3.6.1.4.1.193.1.1.8, IpAddress, 10.0.0.3
9: 1.3.6.1.4.1.193.1.1.9, IpAddress, 0:0:0:0:0:0:0:1
10: 1.3.6.1.4.1.193.1.1.10, OctetString, String with newline
Text on new row.
11: 1.3.6.1.4.1.193.1.1.11, Integer32, 1234

*** Translation
Type               : Alarm raise
Module             : HARDWARE
Error Code         : 8001
Resource Id        : 1.1.1.2.3
Orig Source IP     : 10.0.0.3
Active Description : Test hw alarm. Fan speed: 1000.
---------------------------------------------------------!

5.2.9   Logging SSM

The log files for the SSM component are found in separate directories from the ESA itself.

{ssm basedir}/log/

This directory contains the log file ssmagent.log.

See the Netcool SSM documentation for more information about the SSM log files.

5.3   Backup and Restore

5.3.1   Overview

The ESA comes with a backup command that simplifies ESA backup of all configuration files by using a single command. The command is copying all the ESA configuration files from the specified configuration directories to a target directory given as an argument to the command. The same command can be used to restore a previous backup.

The command also comes with the option to include all the log files together with the configuration files in the backup operation. This option is useful when executing a backup in order to send all configuration files and log files to ESA support for support and trouble shooting purposes. The option is not valid in the restore operation.

Please note that the SSM, if installed, requires a separate backup procedure, since the SSM configuration is not backed up with the ESA backup command.

All backup and restore procedures for both the ESA and the SSM are described in the following chapters.

5.3.2   ESA Backup and Restore

5.3.2.1   Format

The command esabackup is used for both backup and restore of all the ESA configuration files into and from a backup repository.

Command format:

esabackup <action> [<options>] <target dir>|<source dir>

The command attributes are the following:

5.3.2.2   Operation

Execute the following steps to perform a backup.

  1. The backup is executed no matter if the ESA is running or not. There is therefore no need to stop the ESA prior to backup.
  2. Perform the backup operation.

    # esabackup -b <target dir>

    Note:  
    Add option -l to also include the log files in the backup.

Caution!

Keep in mind that using the restore operation will overwrite the existing ESA configuration files!

Execute the following steps to perform a restore.

  1. Stop the ESA.
  2. Perform the restore operation.

    # esabackup -r <source dir>

  3. Start the ESA.

5.3.2.3   Example

The following is a backup example.

Example

Backup of the ESA configuration that was done September 21st 2014 at time stamp 12:34:56 is done by executing the following command line:

# esabackup -b /var/esa/backup

The files are stored in a directory looking like the following:

/var/esa/backup/20140921_123456/

Restore of the ESA configuration that was done September 21st 2014 at time stamp 12:34:56 is done by executing the following command line:

# esabackup -r /var/esa/backup/20140921_123456/

5.3.3   SSM Backup and Restore

Perform the following steps to perform a backup of SSM configuration:

  1. Make sure that the SSM is started.
  2. Save the SSM configuration and state by using the SSM Console.

    # {ssm basedir}/bin/ssmcons -p 7161

    Agent> config save

    Agent> quit

    Note:  
    The SSM configuration is not found in this document. The port number is by default defined to 7161 during the SSM installation. This port number can be changed to a number of own choice.

  3. Backup the following directory.

    {ssm basedir}/config

Perform the following steps to perform a restore of SSM configuration:

  1. Start the SSM.
  2. Copy the SSM configuration files from the backup directory to directory {ssm basedir}/config.
  3. Load the SSM configuration and state by using the SSM Console.

    # {ssm basedir}/bin/ssmcons -p 7161

    Agent> config execute agent.state

    Agent> warmboot

    Agent> quit

5.4   Command Line Interface

The CLI commands provided by the ESA are described in the documents and chapters that are related to the feature and function of the commands, such as backup command is described in this document, FM commands in Reference [2] and PM commands in Reference [3].

Please note that the very first time a CLI command is executed after installed it will show the following printout:

testing JVM in /usr ...

The printout simply indicates that the command is searching for and testing the java version prior to executing the CLI command. This can take some time on slower machines, which is the reason for having the printout. A user waiting for the command to execute simply needs to know what is happening. This will however only happen the very first time any of the ESA commands are executed by a user. After the first execution the path to the JVM is stored and reused in future command executions.

6   Appendix A: ESA MIBs

The MIBs included in the ESA can be found in the following directories.

The following MIBs are used/published by the ESA:

7   Appendix B: SNMP Configuration

7.1   Introduction

This appendix gives an overview of how SNMPv2 and SNMPv3 can be setup using the ESA. The concepts in this section are generic for SNMP, but the example configurations are in ESA format.

Please note that configuration descriptions for each configuration file presented in this appendix is in more detail described in the sub sections of Section 4.

7.2   Overview

The appendix shows how to setup the following use cases:

7.3   Use Case: SNMP Get for SNMPv2

This use case is about sending an "SNMP get" request from an OSS to the ESA in SNMPv2 mode.

The following picture shows an overview of how the operation is executed by the ESA using the SNMP configuration settings. Please note that the execution is the same for a "SNMP set" operation.

Figure 10   Execution of SNMP get operation for SNMPv2 configuration.

The following steps are taken:

  1. The SNMPv2 get message is sent from the OSS. It contains the following data:

    Community String: ESA-PC
Target Oid: .1.3.6.1.2.1.1.1 (= mib-2.system.sysDescr)

  2. The community string in the SNMP get message is matched with the community strings configured in the ESA.

    The following example is setup in the ESA.

    <communityCfg>
  <community active="yes">
    <communityString>ESA-PC</communityString>
    <securityName>v1v2ReadOnlySecName</securityName>
  </community>
  <community active="yes">
    <communityString>ESA-PE</communityString>
    <securityName>v1v2ReadWriteSecName</securityName>
  </community>
</communityCfg>

    The community string configuration shows that the community string in the SNMP get message is valid and access is granted.

    Also, it can be seen that the community string ESA-PC is mapped to the Security Name "v1v2ReadOnlySecName".

  3. The SNMP get requires access to the OID being targeted. This is controlled by the VACM configuration.

    The following example is setup in the ESA.

    <vacmCfg>
  <securityToGroups>
    ...
    <securityToGroup active="yes">
      <securityModel>SNMPv2</securityModel>
      <securityName>v1v2ReadOnlySecName</securityName>
      <groupName>v1v2ReadOnlyGroup</groupName>
    </securityToGroup>
    ...
  </securityToGroups>
  <accesses>
    ...
    <access active="yes">
      <groupName>v1v2ReadOnlyGroup</groupName>
      <securityModel>SNMPv2</securityModel>
      <securityLevel>noAuthNoPriv</securityLevel>
      <contextPrefix/>
      <contextMatch>exact</contextMatch>
      <readViewName>fullReadView</readViewName>
      <writeViewName>noWriteView</writeViewName>
      <notifyViewName>fullNotifyView</notifyViewName>
    </access>
    ...
  </accesses>
  <views>
    ...
    <view active="yes">
      <name>fullReadView</name>
      <subtree>1.3</subtree>
      <mask/>
      <type>included</type>
    </view>
    ...
  </views>

    The VACM configuration above shows the following:

    • In securityToGroups; The Security Name "v1v2ReadOnlySecName" is an "SNMPv2" security model.
    • In securityToGroups; The Security Name "v1v2ReadOnlySecName" belongs to groups "v1v2ReadOnlyGroup".
    • In accesses; The group "v1v2ReadOnlyGroup" with security model "SNMPv2" has the Security Level "noAuthNoPriv", which indicates use of SNMPv2 (no use of USM and thus not SNMPv3).
    • In accesses; The readViewName, which corresponds to the SNMP get operation, points at the view named "fullReadView".
    • In views; The view "fullReadView" shows reading of OIDs in OID branch "1.3" is allowed, which means the OID in the SNMP message being ".1.3.6.1.2.1.1.1" is allowed to be read.

    At this point access is granted to the requested OID.

    If the OID points at an AgentX subagent the ESA MA will route the request to the registered agent and thus bypass the SNMP proxy configuration.

    If the OID points at a SNMP subagent, please go to the next step.

  4. The ESA MA will now route the request to the correct SNMP subagent holding the requested OID.

    The following example is setup in the ESA.

    <proxyCfg>
  ...
  <proxyDefinition active="yes">
    <proxy proxyType="readAndWrite">
      <subtree>1.3.6.1.2.1.1</subtree>
    </proxy>
    <target snmpVersion="v2c">
      <ip>127.0.0.1</ip>
      <port>7161</port>
      <securityName>private</securityName>
      <securityLevel>noAuthNoPriv</securityLevel>
    </target>   
  </proxyDefinition>
  ...
</proxyCfg>

    The Proxy configuration above shows the following:

    • The configuration is valid for all OIDs within branch "1.3.6.1.2.1.1", which matches the OID ".1.3.6.1.2.1.1.1" found in the SNMP get message.
    • The target is a SNMP agent using SNMPv2c and is reached at localhost and port 7161.
    • The target using SNMPv2 requires community string only, which is represented by Security Name "private".
    • The target is not using SNMPv3 and thus indicated with Security Level "noAuthNoPriv".
    • Please note that a SNMPv2 targets do not have any entries in the USM configuration.

7.4   Use Case: SNMP Trap for SNMPv2

This use case is about sending an "SNMP notification" (a trap) from the ESA to the OSS in SNMPv2 mode.

The following picture shows an overview of how the operation is executed by the ESA using the SNMP configuration settings.

Figure 11   Execution of SNMP trap operation for SNMPv2 configuration.

The following steps are taken:

  1. a SNMPv2 notification with OID "1.3.6.1.4.1.193.110.2.10.2.0.1", which is the ESA alarm "alarm raise", is triggered in the ESA FMA. The trap is created by the FMA and sent to the MA.
  2. The trap destination is defined according to the following:

    <trapDestCfg>
  <managerDefinition snmpVersion="v2c" active="yes">
    <ip>100.12.34.56</ip>
    <port>162</port>
    <securityName>v1v2ReadWriteSecName</securityName>
    <securityLevel>noAuthNoPriv</securityLevel>
  </managerDefinition>
</trapDestCfg>

    The trap destination configuration above shows the following:

    • In securityName; Security name "v1v2ReadWriteSecName" is to be used.
    • In securityLevel; Security level is set to "noAuthNoPriv", which indicates use of SNMPv2 (no use of USM and thus not SNMPv3).
  3. The SNMP notification must be authorized. This is controlled by the VACM configuration.

    The following example is setup in the ESA.

    <vacmCfg>
  <securityToGroups>
    ...
    <securityToGroup active="yes">
      <securityModel>SNMPv2</securityModel>
      <securityName>v1v2ReadWriteSecName</securityName>
      <groupName>v1v2ReadWriteGroup</groupName>
    </securityToGroup>
    ...
  </securityToGroups>
  <accesses>
    ...
    <access active="yes">
      <groupName>v1v2ReadWriteGroup</groupName>
      <securityModel>SNMPv2</securityModel>
      <securityLevel>noAuthNoPriv</securityLevel>
      <contextPrefix/>
      <contextMatch>exact</contextMatch>
      <readViewName>fullReadView</readViewName>
      <writeViewName>fullWriteView</writeViewName>
      <notifyViewName>fullNotifyView</notifyViewName>
    </access>
    ...
  </accesses>
  <views>
    ...
    <view active="yes">
      <name>fullNotifyView</name>
      <subtree>1.3</subtree>
      <mask/>
      <type>included</type>
    </view>
    ...
  </views>

    The VACM configuration above shows the following:

    • In securityToGroups; The Security Name "v1v2ReadWriteSecName" is an "SNMPv2" security model.
    • In securityToGroups; The Security Name "v1v2ReadWriteSecName" belongs to groups "v1v2ReadWriteGroup".
    • In accesses; The group "v1v2ReadWriteGroup" with security model "SNMPv2" has the Security Level "noAuthNoPriv", which indicates use of SNMPv2 (no use of USM and thus not SNMPv3).
    • In accesses; The notifyViewName, which corresponds to the SNMP notification operation, points at the view named "fullNotifyView".
    • In views; The view "fullNotifyView" shows that sending traps and notifications with OIDs within the OID branch "1.3" are allowed, which means the trap with OID "1.3.6.1.4.1.193.110.2.10.2.0.1" is allowed to be sent.
  4. The ESA MA sends the SNMP notification to the trap destination at IP:PORT = 100.12.34.56:162.

7.5   Use Case: SNMP Get for SNMPv3

This use case is about sending an "SNMP get" request from an OSS to the ESA in SNMPv3 mode.

The following picture shows an overview of how the operation is executed by the ESA using the SNMP configuration settings. Please note that the execution is the same for an "SNMP set" operation.

Figure 12   Execution of SNMP get operation for SNMPv3 configuration.

The procedure is the same as for SNMPv2c, but the second step about USM.

  1. See Section 7.3.
  2. The following USM configuration is defined.

    <usmCfg>
  <usmUser active="yes">
    <securityName>v3ReadWriteSecName</securityName>
    <authProtocol>AuthMD5</authProtocol>
    <authPassword>myAuthPassword</authPassword>
    <privProtocol>PrivAES128</privProtocol>
    <privPassword>myPrivPassword</privPassword>
  </usmUser>
</usmCfg>

    The USM configuration above shows the following:

    • The Security Name "v3ReadWriteSecName" is used and defined.
    • Authentication protocol MD5 is used.
    • Authentication password is set to "myAuthPassword".
    • Privacy encryption AES128 is used.
    • Privacy password is set to "myPrivPassword".

    This means that if the SNMP get request contains the correct settings and passwords, the request is authenticated and the content is decrypted.

  3. The SNMP get requires access to the OID being targeted. This is controlled by the VACM configuration. It is very much the same as for the SNMPv2 case.

    <vacmCfg>
  <securityToGroups>
    ...
    <securityToGroup active="yes">
      <securityModel>USM</securityModel>
      <securityName>v3ReadWriteSecName</securityName>
      <groupName>v3AuthPrivGroup</groupName>
    </securityToGroup>
    ...
  </securityToGroups>
  <accesses>
    ...
    <access active="yes">
      <groupName>v3AuthPrivGroup</groupName>
      <securityModel>USM</securityModel>
      <securityLevel>authPriv</securityLevel>
      <contextPrefix/>
      <contextMatch>exact</contextMatch>
      <readViewName>fullReadView</readViewName>
      <writeViewName>fullWriteView</writeViewName>
      <notifyViewName>fullNotifyView</notifyViewName>
    </access>
    ...
  </accesses>
  <views>
    ...
    <view active="yes">
      <name>fullReadView</name>
      <subtree>1.3</subtree>
      <mask/>
      <type>included</type>
    </view>
    ...
  </views>

    The VACM configuration above shows the following:

    • In securityToGroups; The Security Name "v3ReadWriteSecName" is an "USM" security model.
    • In securityToGroups; The Security Name "v3ReadWriteSecName" belongs to groups "v3AuthPrivGroup".
    • In accesses; The group "v3AuthPrivGroup" with security model "USM" has the Security Level "authPriv", which indicates use of SNMPv3.
    • In accesses; The readViewName, which corresponds to the SNMP get operation, points at the view named "fullReadView".
    • In views; The view "fullReadView" shows reading of OIDs in OID branch "1.3" is allowed, which means the OID in the SNMP message being ".1.3.6.1.2.1.1.1" is allowed to be read.
  4. At this point the SNMP get operation enters the same flow of events handling AgentX as in the SNMPv2 case, see Section 7.3.
  5. At this point the SNMP get operation enters the same flow of events handling SNMP proxies as in the SNMPv2 case, see Section 7.3.

7.6   Use Case: SNMP Trap for SNMPv3

This use case is about sending an "SNMP notification" (a trap) from the ESA to the OSS in SNMPv3 mode.

The following picture shows an overview of how the operation is executed by the ESA using the SNMP configuration settings.

Figure 13   Execution of SNMP trap operation for SNMPv3 configuration.

The procedure is the same as for SNMPv2c, but the fourth step about USM.

  1. See Section 7.4.
  2. The trap destination is defined according to the following:

    <trapDestCfg>
  <managerDefinition snmpVersion="v3" active="yes">
    <ip>100.12.34.56</ip>
    <port>162</port>
    <securityName>v3ReadWriteSecName</securityName>
    <securityLevel>authPriv</securityLevel>
  </managerDefinition>
</trapDestCfg>

    The trap destination configuration above shows the following:

    • In securityName; Security name "v3ReadWriteSecName" is to be used.
    • In securityLevel; Security Level is set to "authPriv", which indicates use of SNMPv3.
  3. The VACM configuration is the same as for SNMP get operation in the SNMPv3 case.
  4. The following USM configuration is defined for security name "v3ReadWriteSecName".

    <usmCfg>
  <usmUser active="yes">
    <securityName>v3ReadWriteSecName</securityName>
    <authProtocol>AuthMD5</authProtocol>
    <authPassword>myAuthPassword</authPassword>
    <privProtocol>PrivAES128</privProtocol>
    <privPassword>myPrivPassword</privPassword>
  </usmUser>
</usmCfg>

The USM configuration above shows the following:

This means that the SNMP notification is sent encrypted and with authentication, which must match the SNMPv3 configuration in the OSS.


Glossary

Glossary
ESA Glossary of Terms and Acronyms, 0033-CSH 109 654

Reference List

ESA Documentation
[1] ESA Library Overview, DIRECTIONS FOR USE, 1/1553-CSH 109 654
[2] ESA Fault Management, SYSTEM ADMINISTRATION GUIDE, 2/1543-CSH 109 654
[3] ESA Performance Management, SYSTEM ADMINISTRATION GUIDE, 3/1543-CSH 109 654
Web references
[4] log4j documentation. http://logging.apache.org/log4j/1.2/
[5] akka documentation. http://akka.io/
[6] oracle documentation. http://docs.oracle.com/
Legal | © Ericsson AB 2018