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

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


Contents
========

- Overview
- Requirements
- Usage
- Legal Disclaimer


Overview
========

rdt-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 and to monitor LLC occupancy using
CMT 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)

Core properties CAT/Monitoring OID: SNMPv2-SMI::enterprises.343.3.1.x.y.z
x - socket id
y - cpu id
z - field (COS ID: 0, LLC occupancy(RO): 1)

value:
- z = 0, CAT, COS ID assigned
- z = 1, CMT, LLC occupancy, bytes, Read-Only

Monitoring Control OID: SNMPv2-SMI::enterprises.343.3.2.x.y
x - monitoring technology (CMT: 0)
y - field (CMT supported (RO): 0, CMT state: 1)

value:
- y = 0, CMT, supported, true(1)/false(0), Read-Only
- y = 1, CMT, current state, enable(1)/disable(0)


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

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

The rdt-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

And then run the rdt-agentx.pl script followed by the interface argument
    -I [--iface-os] for OS interface 
     No argument needed for MSR interface:
        "sudo ./rdt-agentx.pl -I"
        "sudo ./rdt-agentx.pl --iface-os"
	"sudo ./rdt-agentx.pl"

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

Examples:

Note:
"snmpwalk", "snmpset" and "snmpget" used in examples below are network management
utilities from the NET-SNMP project.

Example use of snmp-tools to read and set CAT configuration:
1. Get CAT and CMT 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.0 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

Example use of snmp-tools to control and read CMT:
1. Check if CMT is supported:
$ snmpget -v2c -c pqos localhost SNMPv2-SMI::enterprises.343.3.2.0.0

2. Enable CMT:
$ snmpset -v2c -c pqos localhost SNMPv2-SMI::enterprises.343.3.2.0.1 u 1

3. Get CMT, LLC occupancy for Core# 1 on Socket# 0:
$ snmpget -v2c -c pqos localhost SNMPv2-SMI::enterprises.343.3.1.0.1.1

4. Disable CMT:
$ snmpset -v2c -c pqos localhost SNMPv2-SMI::enterprises.343.3.2.0.1 u 0


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 "rdt-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 "rdt-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.