Cisco RAN Management System Administration Guide, Release 4.x

Bias-Free Language

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.

Book Contents

Find Matches in This Book

Available Languages

Download Options

Book Title

Cisco RAN Management System Administration Guide, Release 4.x

Chapter Title

Cisco Provisioning Management Gateway (PMG)

PDF - Complete Book (5.08 MB) PDF - This Chapter (1.31 MB)
View with Adobe Reader on a variety of devices

Results

Updated:: July 22, 2014

Chapter: Cisco Provisioning Management Gateway (PMG)

PMG Overview
- PMG Message Flow
- LUS Organized Directory Structure for AP PM Files
PMG Event Subscription
Managing the PMG
- PMG Logging
- Alarm Messages
PMG Profiles
- Parameter Definitions

Cisco Provisioning Management Gateway (PMG)

The Cisco Provisioning Management Gateway (PMG) is a generic provisioning and management application that provides the necessary workflow component between the Service Provider (SP) IT or Operations Support Systems (OSS) applications and the Cisco provisioning Broadband Access Center (BAC). These OSS applications include service management and custom care systems.

This guide describes the PMG operations, components and concepts, and services in detail. While PMG is designed to be a generic product, this document describes the concepts specific to this release.

This chapter describes PMG components and concepts as used in the current release.

PMG Overview
PMG Event Subscription
Managing the PMG
PMG Profiles

PMG Overview

The PMG is a generic application suitable for any TR-069 deployment with the BAC. The application provides an Extensible Markup Language (XML) interface over Hypertext Transfer Protocol (HTTP) based Application Programming Interface (API) to the OSS that hides the complexity of the BAC API. The PMG provides the ability to customize a deployment by using a profile that defines the elements of the API (such as messages, parameters, and so on) that are applicable.

The PMG provides the following functionality:

Interfaces to the OSS system for device provisioning and management.
XML messages for provisioning and management.
Interacts with the BAC and HNB-GW.
Interfaces with the HNB-GW via RADIUS for dynamic whitelist.
Reports events to the subscriber/OSS.
Reports SNMP alarms for PMG service related events.
Interfaces with the HNB-GW via RADIUS for dynamic whitelist.

For requests from the OSS, the PMG accepts TCP connections, receives an HTTP request with XML payload and provides response in HTTP response with XML payload. The connection can remain persistent for subsequent requests unless it is closed by the client or times out.

For notifications, the PMG establishes a TCP connection to an IT / OSS / BSS, sends an HTTP request with XML payload and gets confirmation in HTTP response. The connection can remain persistent for subsequent notifications unless closed by target or times out.

The PMG API is defined by a profile, which is an XML document that describes the inbound messages that the PMG supports. The XML schema provides a means for defining the structure, content, and semantics of the XML document. The XML schema for the profile specifies the inbound requests, the required elements, excluded elements, ignored elements, and the applicable parameters. These parameter elements include name, type, readable, writable, deletable, and source type along with optional validation and source key.

Note

PMG is installed as part of the OVA installation.

This table lists a few standard HTTP status codes used in validating the PMG messages:

Table 1 PMG HTTP Status Codes

HTTP Status Codes

Description

200 OK

Occurs for any response containing a valid PMG message response (which in turn may contain an application layer error).

400 Bad Request

Occurs when the request received does not contain a valid PMG message (for example, wrong encoding).

503 Service Unavailable

Used when the service is unavailable, typically due to high load.

Note

The client must resend the service request.

Following is the send.url for posting XML message for httpclientsh:

http://localhost:8083/pmg

Following is the URL for defining the HTTP POST messages to PMG:

http://<host name/IP address>:8083/pmg/

Where,

<host name>, is the host name of the Central Node, or IP address.
<IP address>, is the eth1 of the Central Node.
8083, is the port number.
/pmg, is the path.

Digest authentication is supported in PMG.

The default username for PMG digest authentication is 'pmguser' and it is defined in pmgServer.properties
pmg.auth.username = pmguser
pmg.auth.password.pmguser=<encrypted password>

The path for pmgserve.properties is /rms/app/pmg/conf.

PMG Message Flow
LUS Organized Directory Structure for AP PM Files

PMG Message Flow

The following is the flow of PMG messages:

OSS establishes an HTTP connection with the PMG service url.
OSS sends a message to PMG with the digest authentication credentials.
PMG receives the message and validates the content-type as application/xml or text/xml.
PMG validates that the message is valid XML.
PMG validates that the message complies with PMG XML Schema Definition (XSD).
PMG determines the message type by examining the root node name.
PMG determines if the message type is part of the configured profile.
PMG makes business orchestration by invoking PMG API.
Construct the response message and sent with HTTP 200 OK response message.

LUS Organized Directory Structure for AP PM Files

Currently all the APs upload PM files to LUS server under the same directory (base path). Therefore, if the number of APs are more, then the directory is unmanageable. This feature is added to categorize the APs based on AP's associated group, and upload all these APs PM files to LUS into a same sub directory under base path. (sub directory name will be the associated group name.) New property "ap.upload.url.suffix.group " is added in PMGServer.properties file to enable this feature. By default value of this is "NO_GROUP", means feature is disabled and the current behavior will continue. Possible values of this property are Area/FemtoGateway/Enterprise/Site (Possible FRM group types).

For example: If ap.upload.url.suffix.group = Area,

A P-1,2,3 are associated to Area-1,

AP-4,5,6 are associated to Area-2,

then the uploaded PM files will be structured as below:

                /opt/CSCOuls/files/uploads/Area-1/
                                AP1-stats_1.xml
                                 AP1-stats_2.xml
                                AP2-stats.xml
                                AP3-stats.xml
                        /opt/CSCOuls/files/uploads/Area-2/ 
                                AP4-stats.xml
                                AP5-stats.xml
                                AP6-stats.xml

When this feature is enabled, PMG will set "FC-LOG-PERIODIC-UPLOAD-URL" custom property at device level for all newly registered APs. The same can be added to existing APs with ReAssign API.

PMG Event Subscription

The subscriber should follow these steps for subscribing to the PMG events:

Send the getAllEventTypes message (subscribe.xml) to PMG for receiving all the supported events.

Note

Each subscriber can subscribe to all the events or selected events, and can have multiple (maximum 3 and minimum 1) notification url for one subscriber. PMG picks up one url and delivers the event. If that URL1 is not reachable, then PMG picks up the next url for event delivery.

PMG event subscription supports these events: AssignedData, FirmwareUpgraded, GroupCreated, GroupUpdated, GroupDeleted, LocationStatus, Online, ServiceError, ServiceOperational,Tampered. PMG accepts three number of subscribers by default.

Following is the sample xml request for event subscriptions:

<Subscribe subscriber-name=”ATT-OSS-1”>
<URL>http:server1/notifyme </URL>
<URL>http:server2/notifyme </URL>
<URL>http:server3/notifyme </URL>
<Event name=”AssignedData”>
    <Parameter name=”eCGI”>
</Event>
<Event name=”Groups” isEnabled=false>
</subscribe>

Following is an example xml:

	 <Subscribe xmlns="http://www.cisco.com/ca/sse/PMGMessages-v3_0_0"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xmlns:xsd="http://www.w3.org/2001/XMLSchema"
		xsi:schemaLocation="http://www.cisco.com/ca/sse/PMGMessages-v3_0_0 pmg-messages-v3_0_0.xsd"
	subscriber-name='ATT-OSS-1'>
	<URL>http://10.105.233.87:8085/pmg</URL>
	<Events>
	<Event name='AssignedData' isEnabled='true'>
	
	</Event>
	<Event name='GroupCreated' isEnabled='true'>
	</Event>
	<Event name='GroupUpdated' isEnabled='true'>
	</Event>
	<Event name='GroupDeleted' isEnabled='true'>
	</Event>
	<Event name='FirmwareUpgraded' isEnabled='true'>
	</Event>
	<Event name='LocationStatus' isEnabled='true'>
	</Event>
	<Event name='Online' isEnabled='true'>
	</Event>
	<Event name='ServiceError' isEnabled='true'>
	</Event>
	<Event name='ServiceOperational' isEnabled='true'>
	</Event>
	<Event name='Tampered' isEnabled='true'>
	</Event>
	</Events>
	</Subscribe>

The subscriber can send this subscribe message from any host by specifying the subscriber name and the list of notification URL. Subscribed events are specified in the <Event> element, and events are enabled by default. Changing the Enabled state of particular event to false, to disable the event. Following is an example:
```
<Event name='LocationStatus' isEnabled='false'>
                </Event>
```
The subscriber can customize the events by specifying the parameter names that the notification server prefers to receive. If the parameters are not specified, then the notification will contain all the parameters of an particular event.

Note
If the events are not specified, it indicates that the subscriber has subscribed to all the events.
The subscriber can update event subscription by sending subscribe message with the updated set of additional events and removing previously subscribed events. For example, the subscriber can subscribe to events from the poster in Mozilla Firefox browser, by posting the subscribe.xml message using the url http://<eth1 address of central node>:8083/pmg to receive the notifications.

What to Do Next

Verify whether the event subscription is successful.

Follow the below steps to verify the event subscription:

Log in to RMS central node as root user.
Navigate to /rms/app/rms/conf/.
Check the file subscriber-conf.xml.

Managing the PMG

The PMG uses a standard HTTP request/response protocol with XML message content that allows provisioning and managing the OSS applications. The PMG API involves a specific protocol to send XML encoded messages as defined by XSD over HTTP.

There is a distinct path for messages, the inbound requests, where the OSS Request Sender sends requests to PMG. Multiple simultaneous OSS Request Senders create their own TCP connections, send inbound requests to PMG, and then receive the appropriate response on the same TCP connection.

The PMG upon receiving a message validates the following prior to performing the work flow of the message:

HTTP content-type is application/xml or text/xml.
XML content is a validated PMG message.
Excludes the elements that are as defined in the PMG profile for the messages.
Ignores the elements that are as defined in the PMG profile for the messages.
Validate the parameter names that include ParameterDefinitions or ParameterNames.
Validate the value of the parameter using ParameterDefinition validation.

PMG Logging
Alarm Messages

PMG Logging

The PMG is capable of logging all requests and responses to and from the OSS, and to and from the BAC. The PMG logging automatically rolls its log files on a daily basis. The maximum number of log files stored is configurable through a configuration file. The path for pmglogs is /rms/log/pmg.

This table lists some of the different types of PMG logs:

Table 2 Different Types of PMG Logs
PMG Logs	Description
Performance Logs	The Performance log determines the performance statistics and consists of two files, one for individual message performance and the other hourly roll-up performance metrics.
Audit Logs	The Audit log logs all interactions with the individual provisioning system components and changes, to the device configuration.
Alarm Logs	The alarm logs are triggered for the following scenarios, a) When the connection with the RDU is lost and once the connection with the RDU is established. b) When Radius connection is lost and reestablished with the ASR 5000. c) When PMG server is started, stopped or restarted.
Message Logs	The OSS HTTP Message logs are used for testing and message tracking purposes. The logs are maintained for 7 days.
Syslog	PMG server status will be logged when PMG is started/stopped/restarted. Syslog contains the Alarm messages of PMG server.

Thus, PMG logging is useful in determining device performance and ensuring proper processing with the BAC. Alarm information logged in pmg-alarms.log is also logged in the syslog. The syslog messages can be found in /var/log/local0.log. In addition to the logs mentioned above, the server start/stop will also be logged in syslog.

Note

The server, pmgServer, must be started with the user specified as ciscorms.

All PMG logs are stored in the directory defined in the $RMS-LOGS environmental variable with a "/pmg" added.

PMG Performance Logs
PMG Alarm Logs
PMG Syslogs
PMG Message Logs

PMG Performance Logs

The Performance logging consists of two files; one for individual message performance and the other hourly roll-up performance metrics.

Individual Performance Log File
Hourly Performance Log File

Individual Performance Log File

The performance log for individual messages is output to the file "pmg-msg-perf.csv" and is stored in the directory /rms/log/pmg. The Performance log file is in the CSV format and begins with a header row followed by the individual message performance data. An example of the individual performance logs is shown here:

2011-12-09T01:01:49.309	Block	          ead1eb47-...-472bb	00223A-0000393086	220	215	319
2011-12-09T01:01:49.319	Unblock	        ead1eb47-...-472bb	00223A-0000393086	220	215	320
2011-12-09T01:01:49.329	Update	         ead1eb47-...-472bb	00223A-0000393086	222	216	321
2011-12-09T01:01:49.339	GetStoredData	  ead1eb47-...-472bb	00223A-0000393086	220	225	319
2011-12-09T01:01:49.349	Block	          ead1eb47-...-472bb	00223A-0000393086	221	215	320
2011-12-09T01:01:49.359	UnBlock	        ead1eb47-...-472bb	00223A-0000393086	220	215	319
2011-12-09T01:01:49.359	Unknown	        Unknown	           Unknown	            2	  0	  3
2011-12-09T01:01:49.359	Unknown Content	Unknown	           Unknown	            2	  1	  3
2011-12-09T01:01:49.359	XML Parse error	Unknown	           Unknown	            2	  0	  3

Following are the headings of the fields in the log file and their descriptions:

timestamp is the date and time of the received message. The timestamp is represented in the ISO 8601 format "YYYY-MM-DDThh:mm:ss.fffZ", where:
- YYYY-represents the four-digit year
- MM-represents the two-digit month
- DD-represents the two-digit day of the month
- T-is the time delimiter
- hh-represents the time in hours
- mm-represents the time in minutes
- ss-represents the time in seconds
- fff-represents the time in milliseconds
- Z-represents the zone designator for the zero (Co-ordinated Universal Time) UTC off set, if the time is in UTC
msg name-the message name as found in the XML root element
trans id-the transaction ID in the message
eidthe device ID for the record. If the message is called with a Secondary ID, the EID must be looked up and used
msg process time ms-the message processing time of the message processor in milliseconds, with the BAC processing time removed
BAC process time ms-the BAC processing time in milliseconds
total msg process time ms-the total message processing time in milliseconds that includes time in un-marshaling the message, message processing time, BAC processing time, and the response time in message marshaling.

To track the performance of unknown messages, messages with XML parser errors and messages that are not of XML content are also logged in the individual performance log file.

Following are some of the logging details for unknown messages:

All unknown messages have the message name, transID, and EID as "Unknown".
All message XMLs that fail to parse, have the message name as "XML Parse error" with transID and EID as "Unknown".
All messages that are not of content type application/xml or text/xml have the message name as "Unknown Content", with transID and EID as "Unknown".

The audit logging is output to the file "pmg-audit.log" and is stored in the directory /rms/log/pmg. The audit logs are used to identify the workflow from the receipt of a PMG message to the response back to the OSS. The audit logs will be rotated at 12 a.m. each day or if larger than 250 MB in size.

Note

The individual logs are maintained on the RDU for 60 days, at which time they are backed up and removed from the RDU.

Hourly Performance Log File

The hourly performance log file is a summary of each message performance from the start of PMG or for the last hour, on the hour. The hourly performance log files are output to the file "pmg-perf-periodic.csv", and are stored in the directory /rms/log/pmg.

The hourly performance log file is in the CSV format and begins with a header row followed by a performance summary for each message.

An example of the messages in the file for the hourly performance logs is shown below:

 2011-12-13T00:00:00.034Z,1400,Block,362,60461,236,19,0
 2011-12-13T00:00:00.034Z,1400,GetStoredData,199,199,199,1,0
 2011-12-13T00:00:00.034Z,1400,Update,60564,60564,60564,1,0
 2011-12-13T00:00:00.034Z,1400,GetLiveData,360941,360941,360941,1,0
 2011-12-13T00:00:00.034Z,1400,Reboot,232,236,228,2,0
 2011-12-13T00:00:00.034Z,1400,Unknown,2,6,8,2,0
 2011-12-13T00:00:00.034Z,1400,Unknown Content,2,6,8,2,0
 2011-12-13T00:00:00.034Z,1400,XML Parse error,2,6,8,2,0
 2011-12-13T01:00:00.034Z,3600,Block,362,60461,236,19,0
 2011-12-13T01:00:00.034Z,3600,GetStoredData,199,199,199,1,0
 2011-12-13T01:00:00.034Z,3600,Update,60564,60564,60564,1,0
 2011-12-13T01:00:00.034Z,3600,GetLiveData,360941,360941,360941,1,0
 2011-12-13T01:00:00.034Z,3600,Reboot,232,236,228,2,0
 2011-12-13T01:00:00.034Z,3600,Unknown,2,6,8,2,0
 2011-12-13T01:00:00.034Z,3600,Unknown Content,2,6,8,2,0
 2011-12-13T01:00:00.034Z,3600,XML Parse error,2,6,8,2,0

The headers for the fields in the hourly performance summary file are described here:

period end-the summary period end timestamp in the ISO 8601 format. The timestamp is in the format "YYYY-MM-DDThh:mm:ss.fffZ", where time is represented in milliseconds
summary period sec-the time interval in milliseconds, for receiving the messages during the summary period
msg name-the message name received during the summary period
avg response time ms-the average response time in milliseconds
max response time ms-the maximum response time in milliseconds
min response time ms-the minimum response time in milliseconds
num msgs-the total number of messages received during the summary period
num errors-the number of errors occurred during the summary period

To track the performance of unknown messages, messages with XML parser errors and messages that are not of XML content are also rolled up in the hourly performance summary file.

Following are some of the logging details for unknown messages:

All unknown messages have the message name as "Unknown".
All message XMLs that fail to parse have the message name as "XML Parse error".
All messages that are not of content type application/xml or text/xml have the message name as "Unknown Content".

Note

The hourly performance log files will be maintained on the RDU for 30 days, at which time the log files are backed up and removed from the RDU. Each hourly performance log file will be rotated at 12 a.m. each day, or if the file size exceeds 250 MB. 2.1.2 Audit Logs

Note

The individual logs are maintained on the RDU for 60 days, at which time they are backed up and removed from the RDU.

PMG Alarm Logs

The PMG triggers alarms for the following conditions and these alarm messages are logged to the file "pmg-alarm.log".

Table 3 PMG Alarm Log Messages
Alarm Condition	Alarm Level	Alarm Text
Connection with the RDU lost	Critical	Alarm raised: Type=RDU Connection
Connection with RDU established	Clear	Alarm resolved: Type=RDU Connection
Radius connection lost	Minor	Alarm raised: Type=Radius Connection
Radius connection restored	Clear	Alarm rersolved: Type=Radius Connection
PMG connection limit exceeded	warning	Alarm raised: Type=PMG Connection
PMG connection limit exceeded	Major	Alarm raised: Type=PMG Connection
PMG Server start	warning	Alarm resplved Type= PMG Status
PMG Server stop	Major	Alarm raised Type= PMG Status

PMG Syslogs

The alarms logged in pmg-alarms.log are logged in the syslog (/var/log/local0.log). In addition to the above mentioned logs, the server start/stop are also logged in the syslog.

For the statements to appear in the syslogs, the udp port has to be uncommented in/etc/rsyslog.conf.

These parameters, (if commented) need to be uncommented in rsyslog.conf.

#$ModLoad imudp.so
#$UDPServerRun 514

The rsyslog needs to be restarted: /etc/init.d/rsyslog restart

PMG Message Logs

The PMG includes inbound message logs for testing and inbound message tracking. This logging is output to the file "pmg-inbound-msg.log", and is stored in the directory /rms/log/pmg. The PMG also includes outbound message logs for testing and outbound message tracking. This logging is output to the file "pmg-outbound-msg.log", and is stored in the directory /rms/log/pmg. Inbound message logs and outbound message logs are rotated at 12 a.m. each day or if the file is larger than 250 MB in size.

Note: The individual logs are maintained on the RDU for seven days, at which time they are removed from the RDU.

Alarm Messages

The PMG triggers SNMPv1 traps to multiple configurable destinations on the following conditions:

Exceeds the maximum concurrent messages of 1500.
Lost connection with BAC. A critical alarm is triggered in this case.
A critical alarm is raised when connection is lost with HNB-GW (ASR 5000) and the clear alarm is raised when connection is restored.
When the PMG is stopped and started.

SNMP TRAP - MIB:

The PMG server sends the following alarm and uses ciscoMhsServerAlarm object to send SNMPV1 alarms.

 1.3.6.1.4.1.9.9.9999.0.5 ( ciscoMhsServerAlarm )

ciscoMhsServerAlarm NOTIFICATION-TYPE
 OBJECTS {
           ciscoMhsServerType,
           ciscoMhsServerName,
           ciscoMhsAlarmDescription,
           ciscoMhsAlarmSeverity,
           ciscoMhsTimeStamp
         }
 ciscoMhsServerType OBJECT-TYPE
SYNTAX INTEGER {
                cmhs(1),
                others(2),
                upload(3),
                watchdog(4),
                bac rdu(5),
                radius(6),
                pmg(7)
            }

where,

ciscoMhsServerType = PMG, ciscoMhsServerName=machine name, ciscoMhsAlarmDescription="Exceeds the maximum concurrent messages of 1500"

Note

ciscoMhsServerType specifies the component which raises the trap.

Note

The internal Watchdog also monitors the process and enables to log to the syslog, the watchdog alarms that are triggered.

PMG Profiles

A PMG profile defines the messages used for the configuration and activation processes. The profile specifies the inbound requests that are used along with the required, ignored, and excluded elements. The PMG profile also contains a number of exclusions, but does not add element requirements. The PMG profile is referred to as pmg-profile.xml in the server.

Using the pmg-profile.xml, the operator can add/remove/exclude/ignore for any message.

For all PMG messages, either an EID or SecondaryID is specified as the device ID. The device search is performed using the SecondaryID which is the device's Fully Qualified Domain Name (FQDN) in BAC or with the EID which is the device's DeviceID property in the BAC.

Profiles are used to specify the subset of messages, elements, and parameters to be used in a given deployment. A Profile is a way to configure the generic PMG to deployment-specific requirements.

The PMG profile contains the Parameter Definition section, which defines the names and types of the supported parameters.

Note

When pmg-profile is customized for the first time, the PMG server must be restarted. Place the customized pmg-profile.xml in the /rms/app/rms/conf/ directory.

The path for the default pmg-profile.xml is /rms/app/rms/doc/pmg/pmg-profile.xml.

Parameter Definitions

Parameter Definitions

Some PMG messages support the parameter structure to add, update, delete, or retrieve parameters. The PMG profile contains the Parameter Definition section, which defines the names and types of the supported parameters.

This table lists some of the parameter elements that are defined in the parameter definition.

Table 4 Parameter Elements and Description
Parameter Elements	Description
Name	The parameter name or the alias used in the message.
Type	The type of the parameter that can be: String Integer (BAC custom property which is an integer) Unsigned integer (BAC custom property which is of the type Long) Decimal Boolean Date/Time
Source Type	The type of the source that includes: DeviceParameters An example of BAC API constant: DeviceDetailsKeys.DEVICE_ID. DeviceProperty (BAC property or custom property)
Writable	Indicates if the parameter is writable (can be added or updated).
Readable	Indicates if the parameter is returned by a get.
Deletable	Indicates if the parameter can be deleted.
Validation	Defines the validation to use on a Writable parameter value and is defined by the following: Type - defines the type of validation that can be: A range, used to validate numbers. The expression element is of the format [low:high], where "low" is the lowest number in the range, or empty if there is none, and "high" is the highest number in the range or empty if there is none. A Regular expression. The expression element contains a regular expression that is used to match the value. Expression - Expression as defined by the type, either a range or regex expression. Following is an example for validation: <ParameterDefinition> <Name>MAX-TRANS-PWR</Name> <Type>int</Type> <SourceType>DeviceProperty</SourceType> <Writable>true</Writable> <Readable>true</Readable> <Deletable>true</Deletable> <Validation> <Type>range</Type> <Expression>[-100:10]</Expression> </Validation> </ParameterDefinition>

Was this Document Helpful?

Feedback

Contact Cisco

Open a Support Case
(Requires a Cisco Service Contract)