NAME
COPS::Client - COPS Protocol - Packet Cable Client
VERSION
Version 0.06
SYNOPSIS
This module provides a simple COPS client for managing Packet Cable Multi
Media sessions for CMTS. It should provide all the neccessary functionality to
enable a service provider to deploy, manage and control service flows within
their network. This does not maintain a connection to the CMTS but issue the
configured command, get the response and then close the TCP connection. I am
working on a stateful Client however this is not yet available.
As basic initial use of the module is as follows
my $cops_client = new COPS::Client (
[
ServerIP => '192.168.0.1',
ServerPort => '3918',
Timeout => 2,
DataHandler => \&display_data
]
);
$cops_client->set_command("set");
$cops_client->subscriber_set("ipv4","172.20.1.1");
$cops_client->gate_specification_add(
[
Direction => 'Downstream',
DSCPToSMark => 0,
Priority => 0,
PreEmption => 0,
Gate_Flags => 0,
Gate_TOSField => 0,
Gate_TOSMask => 0,
Gate_Class => 0,
Gate_T1 => 0,
Gate_T2 => 0,
Gate_T3 => 0,
Gate_T4 => 0
]
);
$cops_client->classifier_add(
[
Classifier_Type => 'Classifier',
Classifier_Priority => 64,
Classifier_SourceIP => "172.20.1.1",
]
);
$cops_client->envelope_add (
[
Envelope_Type => "authorize,reserve,commit",
Service_Type => 'DOCSIS Service Class Name',
ServiceClassName => 'S_down'
]
);
$cops_client->connect();
$cops_client->check_data_available();
This will connect to a CMTS on IP 192.168.0.1 and apply a PCMM gate to
the subscriber with IP address 172.20.1.1 and apply the service class S_down.
It should be noted not all CMTS support all the functions available, so
if the COPS request is failing for you remove opaque_set, timebase_set or
volume_set and try again.
You may also get a very cryptic error if an envelope or classifier is
incorrectly configured.EXPORT
There are no exports.
FUNCTIONS
new
set_command
subscriber_set
gate_specification_add
classifier_add
envelope_add
rks_set
decode_radius_attribute
volume_set
timebase_set
opaque_setnew
The new function initialises the module and sets the CMTS IP, Port and
the data handling function which gets called if a RTP message is received.
The parameters are
ServerIP - The IP address of the CMTS to connect to
ServerPort - The port that the Packet Cable service is running
on. There is no default value however most server
implementations use port 3918, so this should be
set to that
Timeout - This is a timeout parameter for the connection to the
CMTS. It has a default of 5 so can be omitted.
DataHandler - This should be set to point to a local function to
handle any data returned by a COPS message sent.
The function will accept 2 variables as input the
first is the module point, the second is a point to
a hash containing any data returned.
An example of use would be.
my $cops_client = new COPS::Client (
[
ServerIP => '192.168.0.1',
ServerPort => '3918',
Timeout => 2,
DataHandler => \&display_data
]
);
sub display_data
{
my ( $self ) = shift;
my ( $data ) = shift;
print "Report Datagram sent.\n\n";
foreach my $name ( sort { $a cmp $b } keys %{$data} )
{
print "Attribute Name is '$name' value is '${$data}{$name}'\n";
}
}set_command
This command sets the type of command to be sent in the connection. It
can be one of 4 types as follows
set - Meaning GateSet
delete - Meaning GateDelete
info - Meaning GateInfo
synch - Meaning Synch Request
An example of use is
$cops_client->set_command ( "set" );
The command specified must match *Exactly* otherwise it will be ignored. It
appears Cisco CMTS do NOT respond to Synch requests. Cisco have been asked
to respond to this query but no information has been forthcoming.subscriber_set
This function sets the subscriber ID to be used. The subcriber ID can be
either an IPV4 or IPV6 address. If you use an IPV6 address it *MUST* be
fully qualified.
The function takes two parameters the first specifies which IPVx to use,
the second is the IPVx value.
An example of use is
$cops_client->subscriber_set("ipv4","172.20.1.1");
The subscriber ID is required for 99% of all COPS messages.gate_specification_add
This function builds a gate with the attributes specified. Possible
attributes are
Direction - This can be 'Upstream' or 'Downstream' only.
If specified this overrides Gate_Flags as
direction is one bit of the Gate_Flags
parameter.
Priority - This is a value of 0 to 7. If specified this
overrides Gate_Class as Priority is 3 bits
of that parameter.
PreEmption - This has a value of 0 or 1. This allows this
gate to take bandwidth from any other gates
already set against this subscriber. If
specified this overrides Gate_Class as this is
1 bit of that parameter.
DSCPToSMark - This has a value of 0 or 1
Priority - This has a value between 0 and 255 and should
determine the priority of the gate.
Gate_Flags - This field is broken down into 2 used bits and
6 unused bits.
Bit 0 - Direction.
0 is Downstream
1 is Upstream
If you use the Direction parameter
this is set for you.
Bit 1 - DSCP/TOS Field
0 is enable
1 is overwrite
GateTOSField - IP TOS and Precedence value.
GateTOSMask - IP TOS Mask settings
GateClass - This field is broken down into 8 bits as follows
Bit 0-2 - Priority of 0-7
Bit 3 - PreEmption bit
Bit 4-7 - Configurable but should default 0
Gate_T1 - Gate T1 timer
Gate_T2 - Gate T2 timer
Gate_T3 - Gate T3 timer
Gate_T4 - Gate T4 timer
An example of use would be
$cops_client->gate_specification_add(
[
Direction => 'Downstream',
DSCPToSMark => 0,
Priority => 0,
PreEmption => 0,
Gate_Flags => 0,
Gate_TOSField => 0,
Gate_TOSMask => 0,
Gate_Class => 0,
Gate_T1 => 0,
Gate_T2 => 0,
Gate_T3 => 0,
Gate_T4 => 0
]
);classifier_add
This function adds a classifier to the COPS request being sent and
supports normal and extended classifiers.
The function requires two types of parameters depending on the type
of classifier specified.
To specify the correct classifier the attribute Classifier_Type
can be used as follows
Classifier_Type - This should be 'Classifier' or 'Extended'
Classifier_Type 'Classifier' attributes are as follows
Classifier_IPProtocolId - This is a standard IP protocol
number. You can set this to 0
or omit this and a default of 0
will be used.
Classifier_TOSField - The TOSField of the IP packets
to match. You can set this to 0
or omit this and a default of 0
will be used.
Classifier_TOSMask - The TOSMask of the IP packets
to match. you can set this to 0
or omit this and a default of 0
will be used.
Classifier_SourceIP - This should be set to the source
IP address of the associated flow.
If you have a device attached to
the cable modem such as a PC, then
you should use the IP of that
device, not that of the cable modem.
Classifier_DestinationIP - This is the destination IP of the
flow. It can be a wildcard of 0.
If you omit this then a default 0
will be used.
Classifier_SourcePort - The source port of the flow. If
you omit this then a default of 0
will be used.
Classifier_DestinationPort - This is the destination port of the
flow. If you omit this then a default
if 0 will be used.
Classifier_Priority - The priority of this Classifier. If
you have multiple Classifiers then
this determines the order they are
checked.
An example of use would be
$cops_client->classifier_add(
[
Classifier_Type => 'Classifier',
Classifier_Priority => 64,
Classifier_SourceIP => "172.20.1.1",
]
);
This sets up a Standard classifier with a priority of 64, Source IP of
172.20.1.1,any port and a wildcard destination address any port.
Classifier_Type 'Extended' attributes are as follows
EClassifier_IPProtocolId - This is a standard IP protocol
number. You can set this to 0
or omit this and a default of 0
will be used.
EClassifier_TOSField - The TOSField of the IP packets
to match. You can set this to 0
or omit this and a default of 0
will be used.
EClassifier_TOSMask - The TOSMask of the IP packets
to match. you can set this to 0
or omit this and a default of 0
will be used.
EClassifier_SourceIP - This should be set to the source
IP address of the associated flow.
If you have a device attached to
the cable modem such as a PC, then
you should use the IP of that
device, not that of the cable modem.
With an extended classifier you can
also specify a network address.
EClassifier_SourceMask - This is the associated netmask for
the SourceIP specified.
EClassifier_DestinationIP - This is the destination IP of the
flow. It can be a wildcard of 0.
If you omit this then a default 0
will be used.
With an extended classifier you can
also specify a network address.
EClassifier_DestinationMask - This is the associated netmask for
the DestinationIP specified.
EClassifier_SourcePortStart - The start source port of the flow.
If you omit this then a default of 0
will be used.
EClassifier_SourcePortEnd - The end source port of the flow. If
both the start and end ports are 0
then all ports are matched.
EClassifier_DestinationPortStart - The start destination port of the
flow. If you omit this then a default
of 0 will be used.
EClassifier_DestinationPortEnd - The end destination port of the flow.
If both the start and end ports are 0
then all ports are matched.
EClassifier_ClassifierID - An extended classifier must have numerical
ID and it should unique per classifier per
gate. It can range from 1 to 65535 (16bit)
EClassifier_Priority - The priority of this Classifier. If
you have multiple Classifiers then
this determines the order they are
checked.
EClassifier_State - This determines if this classifier is
Inactive or Active, values 0 and 1
respectively.
EClassifier_Action - This has 4 possible values
0 - Means Add - This is the default if not
specified.
1 - Replace
2 - Delete
3 - No Change
An example of use would be
$cops_client->classifier_add(
[
Classifier_Type => 'Extended',
EClassifier_Priority => 64,
EClassifier_SourceIP => "172.20.1.1",
EClassifier_ClassifierID => 100,
EClassifier_State => 1
]
);
This sets up an Extended classifier with a priority of 64, Source IP of
172.20.1.1,any port and a wildcard destination address any port. The ID is set
to 100 and it is set to State 1 which is Active.envelope_add
This function adds the correct envelope type to the gate. All the possible parameters
can not be detailed here as it would this man page *VERY* long. I may add them in the
future.
The Attributes that are *ALWAYS* required at
Envelope_Type - This specifies the type of request and is managed
by three bits (LSB first), lowest value 1 highest
value 7
0 - Authorize - Value 1
1 - Reserve - Value 2
2 - Commit - Value 4
This is a string and should be one/more of the following
authorize reserve commit
Service_Type - This determines the type of service that the gate
will apply. By specifying the Service_Type and
Envelope_Type this determines the additional
parameters required.
The following values are valid for Service_Type
Flow Spec
DOCSIS Service Class Name
Best Effort Service
Non-Real-Time Polling Service
Real-Time Polling Service
Unsolicited Grant Service
Unsolicited Grant Service with Activity Detection
Downstream
There is an example of each one in the examples
directory examples/profiles/
An example of use would be
$cops_client->envelope_add (
[
Envelope_Type => "authorize reserve commit",
Service_Type => 'DOCSIS Service Class Name',
ServiceClassName => 'S_down'
]
);
This sets up the Envelope to be authorized, reserved and committed. It contains a Service
Class Name (this should be configured on the CMTS already) and it has been named as
S_down. If the specified ServiceClassName is incorrect or does not correspond to the
direction specified an error will be returned.rks_set
This function add a Reporting server to the COPS request. You can have a primary and
secondary Reporting server and events, such as volume quota reached, time reached should
be report to the Reporting server configured. All Reporting server messages are via
the RADIUS protocol. This rks_set only supports IPV4 addressing.
As part of a RKS request you can also specify unique indentifiers that will be sent in
the Reporting request for each specific gate created. The Gate ID is not sent in the
reporting request so some external management system will need to track these.
The variables you can set in an RKS configuration are as follows
PRKS_IPAddress - This is the PRIMARY (PRKS) reporting server IP address.
It should be specified as an IP, hostnames are not
supported and only IPV4 is available.
PRKS_Port - This is the Port that reporting messages are sent to.
The protocol used is RADIUS so the standard 1813 port
should be used if a default RADIUS server configuration
is to be used.
PRKS_Flags - Ignore, further work is required, however if you
understand this usage it is available to be set.
SRKS_IPAddress - This is the SECONDARY (SRKS) reporting server IP address.
This is ONLY used if the primary is considered down.
It should be specified as an IP, hostnames are not
supported and only IPV4 is available.
SRKS_Port - This is the Port that reporting messages are sent to
for the SECONDARY reporting server.
SRKS_Flags - Ignore, further work is required, however if you
understand this usage it is available to be set.
Billing Correlation Identification
BCID_TimeStamp - This is a 32bit number and EPOCH is a good use here.
BCID_ElementID - This is an eight (8) character entry and should be
alphanumeric only to be supported by all vendors.
BCID_TimeZone - This is an eight(8) character entry and specifies
the timezone of the entry.
BCID_EventCounter - This is a 32bit number and can be anything within that
range. This could be an auto-increment in a table, so
allowing GateID to be linked back later.
An example of use would be
my $timer=time();
$cops_client->rks_set (
[
PRKS_IPAddress => '192.168.50.2',
PRKS_Port => 2000,
PRKS_Flags => 0,
SRKS_IPAddress => 0,
SRKS_Port => 0,
SRKS_Flags => 0,
BCID_TimeStamp => $timer,
BCID_ElementID => '99999999',
BCID_TimeZone => '00000000',
BCID_EventCounter => 12347890
]
);
You can omit fields which are not used and they will default to 0, but for completeness
are included above.decode_radius_attribute
This function takes the output from FreeRadius 2.1.9 and expands it where possible. The
supported attributes are
CableLabs-Event-Message
CableLabs-QoS-Descriptor
When called this function returns the converted attribute into a hash of the attributes
found and decoded.
An example of use would be
my %return_data;
$cops_client->decode_radius_attribute("CableLabs-Event-Message",
"
0x00034c163b873939393939393939303030303030303000bc69f2000700022020203232323200312b3030303030300000002b32303130303631343135313233382e3032330000000080000400",
\%return_data);
Note the 0x is required at the beginning so validity checking will pass.
The %return_data has should then contain the following keys with values.
EventMessageVersionID - 3
TimeZone - 1+000000
Status - 0
AttributeCount - 4
SequenceNumber - 43
BCID_TimeZone - 00000000
EventObject - 0
ElementType - 2
EventMessageType - 7
BCID_Timestamp - 1276525447
BCID_ElementID - 99999999
BCID_EventCounter - 12347890
EventMessageTypeName - QoS_Reserve
Priority - 128
ElementID - ' 2222'
EventTime - 20121019163303.51volume_set
This functions adds a volume limit to the gate being sent. You should be aware the CMTS
may not stop traffic flowing through the gate when the limit is reached, implementation
dependent, however should send a RKS notification.
This function just takes the Volume in the number of bytes, 64 bit number.
An example of use would be
$cops_client->volume_set( 3000000000 );
This would set the volume to 3Gigabytes.timebase_set
This function add a time limit to the gate being sent. You should be aware the CMTS may
not stop traffifc flowing through the gate when the limit is reached, implementation
dependent, however should sent a RKS notification.
This function just takes the time in seconds , 32bit number.
An example of use would be
$cops_client->timebase_set( 60 );
This would set the time limit to 60 seconds.opaque_set
This function allows you to add arbitary data to the COPS message sent which *may* be
recorded against the gate by the remote CMTS.
The only attribute for this function is
OpaqueData - This be any data, although keeping it to something
humanly readable is probably a good idea.
An example of use would be
$cops_client->opaque_set(
[
OpaqueData => 'a test string'
]
);
This would add 'a test string' as Opaque data to the gate.Summary
This is very much a 'work in progress'. AUTHOR
shamrock@cpan.org, <shamrock at cpan.org>
BUGS
- Sync messages to Cisco CMTS do not seem to work. I have tried alternative formats, headers, etc but to no avail. They do work to Motorola and Aris. I have raised this with Cisco but do not expect a response any time soon. If anyone has a packet trace with a working Synch using a Cisco CMTS that would be useful.
- The different traffic profiles need work, see examples/profiles. The following examples produce an 'Unspecified error' and may be down to the values being used. If any one can help with the values that should be used, packet trace, then I can look at improving their use.
Flow Spec
Non-Real-Time Polling Service
Real-Time Polling Service
Unsolicited Grant Service Please report any bugs or feature requests to bug-cops-cmts at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=COPS-Client. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
Please do email me if you have any issues so they can be looked at as soon as possible.
You can find documentation for this module with the perldoc command.
perldoc COPS::ClientYou can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE
Copyright 2012 shamrock@cpan.org, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 3336:
=cut found outside a pod block. Skipping to next block.