IP Detail Record Service
The Cisco Operations Hub hosted IP Detail Record (IPDR) service provides the mechanisms to export IP detailed records to IPDR collectors and the ability to configure the IPDR service.
The Cisco Operations Hub IPDR service operates in a similar way as other Cisco Cable Modem Termination Systems (CMTS) products. You can configure it through the REST interface. See IPDR Streaming Protocol on the Cisco CMTS Routers for reference.
The URL https://{Hostname}/api/ipdr is created for the IPDR service, which is used for the REST configuration and status requests. The collector connects to
the IPDR service on default port 4737 to establish a TCP session. Then, IPDR records are streamed from the IPDR service to
the collector over this TCP session.
For the IPDR service to deliver records, the IP address of the collector that receives the records is required. An ordered list of collectors is contained in a session. Only one collector in a session receives the records, the others are available as backup. The session describes the delivery mechanism and record format. You can define multiple sessions so that more than one collector can receive IPDR records from Operations Hub.
Terminology
This table lists and describes the IPDR terminology.
| Term | Description |
|---|---|
| Collector | The host that receives (collects) the IPDR records. |
| Exporter | The IPDR service includes an exporter service that generates the IPDR records. |
| Session | Describes the set of collectors and templates that are used to send IPDR records. At a time, only one collector in a session gets IPDR data at a time based on a priority order. If a collector is unavailable, the collector with the next highest priority gets the records. |
| Template | Identifies the record format for sending the records. |
Configure IPDR Service
To configure the IPDR service, use a single command to set all configuration parameters in JSON format in one single action. This configuration method overwrites the existing configuration and activates the new configuration.
/v1/config
 Note |
|
To set the configuration, use the PUT HTTP method as shown in the following example.
curl -k -X PUT -H "Content-Type: application/json" -d @- << EOF https://{Hostname}/api/ipdr/v1/config
{json_string}
EOFNote |
Parameter -k allows insecure server connections when using SSL. |
Example: Add or change IPDR configuration.
curl -k -X PUT -H "Content-Type: application/json" -d @- << EOF https://opshub1.cisco.com/api/ipdr/v1/config
{
"sessions": [
{
"id": 1,
"name": "session_1",
"description": "IPDR Session 1",
"type": {
"type": "time-interval",
"interval": 15
},
"templates": [
{
"template-type": "SAMIS-TYPE1"
}
],
"associated-collectors": [
{
"collector-name": "Collector1",
"priority": 1
}
]
},
{
"id": 2,
"name": "session_2",
"description": "IPDR Session 2",
"type": {
"type": "event",
"interval": 0
},
"templates": [
{
"template-type": "DS-UTIL"
}
],
"associated-collectors": [
{
"collector-name": "Collector1",
"priority": 1
}
]
},
{
"id": 3,
"name": "session_3",
"description": "IPDR Session 3",
"type": {
"type": "event",
"interval": 0
},
"templates": [
{
"template-type": "US-UTIL"
}
],
"associated-collectors": [
{
"collector-name": "Collector1",
"priority": 1
}
]
}
],
"collectors": [
{
"name": "Collector1",
"address": "10.0.0.1",
"nat-address": "0.0.0.0",
"port": 0
}
],
"exporter": {
"ack-timeout": 60,
"keep-alive": 300,
"max-unacked": 200,
"started": true
},
"utilization": {
"interval": 300
}
}
EOFAfter setting the configuration, you can use the GET HTTP method as shown in the following example to display the consolidated configuration:
curl -H 'Content-Type: application/json' -X GET https://{Hostname}/api/ipdr/v1/configExample: Display the existing IPDR configuration
curl -k -H 'Content-Type: application/json' -X GET https://opshub1.cisco.com/api/ipdr/v1/config
{
"sessions": [
{
"id": 1,
"name": "session_1",
"description": "IPDR Session 1",
"type": {
"type": "time-interval",
"interval": 2
},
"templates": [
{
"template-type": "SAMIS-TYPE1"
}
],
"associated-collectors": [
{
"collector-name": "Collector1",
"priority": 1
}
]
},
{
"id": 2,
"name": "session_2",
"description": "IPDR Session 2",
"type": {
"type": "event",
"interval": 0
},
"templates": [
{
"template-type": "DS-UTIL"
}
],
"associated-collectors": [
{
"collector-name": "Collector1",
"priority": 1
}
]
},
{
"id": 3,
"name": "session_3",
"description": "IPDR Session 3",
"type": {
"type": "event",
"interval": 0
},
"templates": [
{
"template-type": "US-UTIL"
}
],
"associated-collectors": [
{
"collector-name": "Collector1",
"priority": 1
}
]
}
],
"collectors": [
{
"name": "Collector1",
"address": "10.0.0.1",
"nat-address": "0.0.0.0",
"port": 0
}
],
"exporter": {
"ack-timeout": 60,
"keep-alive": 300,
"max-unacked": 200,
"started": true
},
"utilization": {
"interval": 240
}
}Example: Remove IPDR configuration
curl -X PUT -H "Content-Type: application/json" https://opshub1.cisco.com/api/ipdr/v1/configNote |
The |
Fields In JSON
This table lists the fields used in JSON and their description.
This table lists the fields used in JSON and their description.
| Field Name | Description | Type | Enforcement |
|---|---|---|---|
| ack-timeout | Exporter timeout, after which an acknowledgement is received from the collector before retry. | Number. 5–60 seconds; the default value is 60. | Optional |
| address | The IP address of the collector, which is used to receive the IPDR records. | IP Address | Required |
| collector-name | A specific collector definition for collectors. | String | Required |
| collectors:name | Unique name used to identify a collector. | String | Required |
| description | Long descriptive text. | String | Required |
| id | A unique session number for the purpose of reference. | Number | Required |
| interval | The interval used to send DS-UTIL and US-UTIL data. | Number in seconds, 0 means disabled. | Optional |
| keep-alive | The keepalive time after which the collector is considered unavailable. | Number. 5–300 seconds; the default value is 300. | Optional |
| max-unacked | The maximum number of unacknowledged records. | Number. 5–200; the default value is 200. | Optional |
| name | Descriptive name for reference purposes. | String | Required |
| nat-address | The NAT IP address of the collector. | IP Address | Optional |
| port | The port of the collector. | Number | Optional |
| priority | The order to use the collector. Use the collector with the lowest priority number first. | > 0 | Required |
| started | Start the IPDR service or not. | Boolean | Required |
| type:type | The method used to request data from the service. | String. Possible values: adhoc, event, time-interval | Required |
| type:interval | The frequency of sending the data for a session. | 2–1440 minutes. | Required only if "type:type" field is set to "time-interval". |
| template-type | Identifies the records format. | String. Possible values: SAMIS-TYPE1, US-UTIL, DS-UTIL, TOPOLOGY | Required |
REST Return Codes
You can use the status codes listed in the following table to convey the results of a request.
This table lists the REST Return codes, descriptions, response text, and actions.
| Code | Short Description | Response Text | Actions |
|---|---|---|---|
| 400 | HTTP_BAD_REQUEST |
|
Confirm that the format of the request is valid or restart the IPDR service to apply new sessions. |
| 404 | HTTP_NOT_FOUND |
|
Return this code when adding a session referring to a collector that does not exist. If it is a consolidated configuration request, correct the request to include a valid collector. |
| 500 | HTTP_BAD_REQUEST |
|
Internal error that requires engineering team engagement. |
| 503 | HTTP_SER_UNAVAIL |
|
Use this code only in response to readiness check. If the service is not ready, confirm that the Cassandra database is ready. Otherwise, get the database ready. If the Cassandra database is ready and operational, ask for customer support. |
Monitor
Use the GET HTTP method of the following REST APIs to monitor the status of the IPDR session, collector, and exporter.
Monitor Session Status
-
Get the status of all sessions.
/v1/sessions -
Get the status of a specific session.
/v1/sessions/{id}
Note
/ipdr/session/statusis deprecated but usable.
Example:
curl -k -H 'Content-Type: application/json' -X GET https://opshub1.cisco.com/api/ipdr/v1/sessions Session ID: 1, Name: samis, Descr: samis, Started: True Session Type: Time Interval (15 minutes). Expires in 81 seconds. Exporting not started. 2019-05-29T05:08:14 Statistics: Transmitted 0 Acknowledged 0 Enqueued 0 Lost 0 queuedOutstanding 0 queuedUnacknowledged 0 1 Collectors in the session: Name: collector1, IPAddr: 10.0.0.1, Port: N/A, Priority: 1[DISCONNECTED] Templates in the session: Template ID: 2, Name: http://www.cablelabs.com/namespaces/DOCSIS/3.0/xsd/ipdr/DOCSIS-SAMIS-TYPE-1/DOCSIS-SAMIS-TYPE-1_3.5.1-A.1.xsd, Type: SAMIS-TYPE-1, KeyNumber: 28 Session 1 has a total of 1 templates. Session ID: 2, Name: cmts-ds-util-stats, Descr: cmts-ds-util-stats, Started: True Session Type: Event Based. 2019-05-29T05:08:14 Statistics: Transmitted 0 Acknowledged 0 Enqueued 0 Lost 0 queuedOutstanding 0 queuedUnacknowledged 0 1 Collectors in the session: Name: collector1, IPAddr: 10.0.0.1, Port: N/A, Priority: 0[DISCONNECTED] Templates in the session: Template ID: 13, Name: http://www.cablelabs.com/namespaces/DOCSIS/3.0/xsd/ipdr/DOCSIS-CMTS-DS-UTIL-STATS-TYPE/DOCSIS-CMTS-DS-UTIL-STATS-TYPE_3.5.1-A.3.xsd, Type: http://www.cablelabs.com/namespaces/DOCSIS/3.0/xsd/ipdr/DOCSIS-CMTS-DS-UTIL-STATS-TYPE/DOCSIS-CMTS-DS-UTIL-STATS-TYPE_3.5.1-A.3.xsd, KeyNumber: 11 Session 2 has a total of 1 templates. Session ID: 3, Name: cm-status, Descr: cm-status, Started: True Session Type: Ad-hoc. Exporting not started. 2019-05-29T05:08:14 Statistics: Transmitted 0 Acknowledged 0 Enqueued 0 Lost 0 queuedOutstanding 0 queuedUnacknowledged 0 1 Collectors in the session: Name: collector1, IPAddr: 10.0.0.1, Port: N/A, Priority: 1[DISCONNECTED] Templates in the session: Template ID: 8, Name: http://www.cablelabs.com/namespaces/DOCSIS/3.0/xsd/ipdr/DOCSIS-CMTS-CM-REG-STATUS-TYPE/DOCSIS-CMTS-CM-REG-STATUS-TYPE_3.5.1-A.1.xsd, Type: http://www.cablelabs.com/namespaces/DOCSIS/3.0/xsd/ipdr/DOCSIS-CMTS-CM-REG-STATUS-TYPE/DOCSIS-CMTS-CM-REG-STATUS-TYPE_3.5.1-A.1.xsd, KeyNumber: 18 Session 3 has a total of 1 templates.curl -k -H 'Content-Type: application/json' -X GET https://opshub1.cisco.com/api/ipdr/v1/sessions/1 Session ID: 1, Name: samis, Descr: samis, Started: True Session Type: Time Interval (15 minutes). Expires in 81 seconds. Exporting not started. 2019-05-29T05:08:14 Statistics: Transmitted 0 Acknowledged 0 Enqueued 0 Lost 0 queuedOutstanding 0 queuedUnacknowledged 0 1 Collectors in the session: Name: collector1, IPAddr: 10.0.0.1, Port: N/A, Priority: 1[DISCONNECTED] Templates in the session: Template ID: 2, Name: http://www.cablelabs.com/namespaces/DOCSIS/3.0/xsd/ipdr/DOCSIS-SAMIS-TYPE-1/DOCSIS-SAMIS-TYPE-1_3.5.1-A.1.xsd, Type: SAMIS-TYPE-1, KeyNumber: 28 Session 1 has a total of 1 templates.
Monitor Collector Status
/v1/collectorsNote |
|
Example:
curl -k -H 'Content-Type: application/json' -X GET https://opshub1.cisco.com/api/ipdr/v1/collectors
Collector name collector1, ip addr 10.0.0.1, port 0Monitor Exporter Status
/v1/exporterNote |
|
Example:
curl -k -H 'Content-Type: application/json' -X GET https://opshub1.cisco.com/api/ipdr/v1/exporter
IPDR exporter is started.
Current parameters:
KeepAliveInterval: 300
AckTimeInterval: 60
AckSequenceInterval: 200
Feedback