

========================================================================
README for cat-agentx.pl Perl script

April 2016
========================================================================


Contents
========

- Overview
- Requirements
- Usage
- Legal Disclaimer


Overview
========

cat-agentx.pl is a Net-SNMP AgentX subagent written in Perl to demonstrate
the use of the PQoS library Perl wrapper API. This subagent allows to
read and change CAT configuration via SNMP.

Supported OIDs:
COS configuration OID: SNMPv2-SMI::enterprises.343.3.0.x.y.z
x - socket id
y - cos id
z - field (cdp (RO): 1, ways_mask: 2, data_mask: 3, code_mask: 4)

value:
- z = 1, current CDP setting, Read-Only
- z = 2, ways_mask configuration
- z = 3, data_mask configuration (if CDP == 1)
- z = 4, code_mask configuration (if CDP == 1)

CPU-COS association OID: SNMPv2-SMI::enterprises.343.3.1.x.y
x - socket id
y - cpu id
value - COS ID


Requirements
============

Tested with Net-SNMP v5.7.2 and NetSNMP::agent Perl module.

The cat-agentx.pl is a SNMP subagent to be used with Net-SNMP daemon.
Script requires NetSNMP::agent Perl module and depends on
the pqos.pm Perl module generated by SWIG.

Please refer to the README file in the "../lib/perl" directory
for information on building and installing pqos.pm Perl module.


Usage
=====

AgentX support is included in Net-SNMP by default, but needs
to be explicitly enabled before use. Enable access to OIDs
and activate AgentX support by putting the following lines:

        rwcommunity pqos localhost .1.3.6.1.4.1.343.3
        master agentx

in the snmpd.conf file.

Or run snmpd from command line (e.g. for debugging purposes):

        sudo snmpd -f -Dagentx -Lo -C --rwcommunity=pqos --master=agentx

To run the cat-agentx.pl script:
        "sudo ./cat-agentx.pl"

Note:
"cat-agentx" needs to be restarted when CDP config changes.

Examples:
Example use of snmp-tools to read and set CAT configuration:
1. Get CAT configuration:
$ snmpwalk -v2c -c pqos localhost SNMPv2-SMI::enterprises.343.3

2. Associate COS# 3 to Core# 1 on Socket# 0:
$ snmpset -v2c -c pqos localhost SNMPv2-SMI::enterprises.343.3.1.0.1 u 3

3. Set way_masks to 15 (0xf) for COS# 1 on Socket# 0
$ snmpset -v2c -c pqos localhost SNMPv2-SMI::enterprises.343.3.0.0.1.1 u 15

Troubleshooting:
Error: "Warning: Failed to connect to the agentx master agent ([NIL]):"
- Make sure that Net-SNMP (snmpd) daemon is running and has AgentX support enabled.

Error: "Timeout: No Response from localhost"
- Make sure that snmpd daemon is running;
- Make sure that snmpd.conf consists "rwcommunity pqos ..." line;

Error: "SNMPv2-SMI::enterprises.343.3 = No more variables left in this MIB View (It is past the end of the MIB tree)"
- Make sure that "cat-agentx.pl" is running;

Error: "Error in packet. Reason: notWritable (That object does not support modification) Failed object: SNMPv2-SMI::enterprises.343.3...."
- Make sure that "cat-agentx.pl" is running;


Legal Disclaimer
================

THIS SOFTWARE IS PROVIDED BY INTEL"AS IS". NO LICENSE, EXPRESS OR
IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS
ARE GRANTED THROUGH USE. EXCEPT AS PROVIDED IN INTEL'S TERMS AND
CONDITIONS OF SALE, INTEL ASSUMES NO LIABILITY WHATSOEVER AND INTEL
DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR
USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO
FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT
OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.