Compaq TCP/IP Services for
OpenVMS
SNMP Programming and
Reference
Order Number: AA–R04BC–TE
January 2001
Revision/Update Information: This manual supersedes the DIGITAL
TCP/ IP Services for OpenVMS eSNMP
Programming and Reference, Version
5.0.
Software Version:
Compaq TCP/IP Services for OpenVMS
Version 5.1
Operating Systems:
OpenVMS Alpha Versions 7.1, 7.2-1
OpenVMS VAX Versions 7.1, 7.2
Com p a q Com p u ter Cor p or a tion
Hou ston , Texa s
Download from Www.Somanuals.com. All Manuals Search And Download.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vii
1 Overview
1.1
1.2
1.3
1.4
1.5
1.5.1
1.6
1.7
1.7.1
1.8
SNMP Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1–1
1–2
1–4
1–5
1–6
1–7
1–7
1–8
1–8
1–9
Request Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCP/IP Services Components for SNMP . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing an eSNMP Subagent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The eSNMP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The SNMP Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The MIB Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SNMP Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Existing (SNMP Version 1) MIB Modules . . . . . . . . . . . . . . . . .
For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 MIBs Provided with TCP/IP Services
2.1
Overview of the Host Resources MIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2–1
2–1
2–3
2–5
2–6
2–6
2.1.1
2.1.2
2.2
2.2.1
2.2.2
Defining Host Resources MIB Implemented Objects . . . . . . . . . . . . . .
Restrictions to Host Resources MIB . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview of MIB II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MIB II Implemented Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Restrictions to MIB II Implementation . . . . . . . . . . . . . . . . . . . . . . . .
3 Creating a Subagent Using the eSNMP API
3.1
3.2
Creating a MIB Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Structure of Management Information . . . . . . . . . . . . . . . . . . . . . . . .
Assigning Object Identification Codes . . . . . . . . . . . . . . . . . . . . . . . . .
MIB Subtrees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a MIB Source File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing the ASN.1 Input File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Processing the Input File with the MIB Compiler . . . . . . . . . . . . . . . .
UNIX Utilities Supplied with TCP/IP Services . . . . . . . . . . . . . . .
Object Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The subtree_TBL.H Output File . . . . . . . . . . . . . . . . . . . . . . . . . . .
The subtree_TBL.C Output Files . . . . . . . . . . . . . . . . . . . . . . . . . .
Including the Routines and Building the Subagent . . . . . . . . . . . . . . . . . .
Including Extension Subagents in the Startup and Shutdown
3–1
3–1
3–2
3–2
3–5
3–5
3–5
3–7
3–7
3–7
3–9
3–11
3.2.1
3.2.2
3.3
3.3.1
3.3.2
3.3.2.1
3.3.2.2
3.3.2.3
3.3.2.4
3.4
3.5
Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3–12
iii
Download from Www.Somanuals.com. All Manuals Search And Download.
4 Using the SNMP Utilities
4.1
4.1.1
4.1.2
4.1.3
4.1.4
4.2
4.2.1
4.2.1.1
4.2.1.2
4.2.1.3
4.2.2
4.2.2.1
4.2.2.2
4.2.2.3
Using the MIB Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4–1
4–1
4–2
4–5
4–6
4–8
4–9
4–9
4–10
4–11
4–12
4–12
4–12
4–13
MIB Browser Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MIB Browser Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MIB Browser Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Command Examples for snmp_request . . . . . . . . . . . . . . . . . . . . . . . .
Using the Trap Sender and Trap Receiver Programs . . . . . . . . . . . . . . . . .
Entering Commands for the Trap Sender Program . . . . . . . . . . . . . . .
Trap Sender Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Trap Sender Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Trap Sender Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Entering Commands for the Trap Receiver Program . . . . . . . . . . . . . .
Trap Receiver Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Up an SNMP Trap Service . . . . . . . . . . . . . . . . . . . . . . . . .
Trap Receiver Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5 eSNMP API Routines
5.1
Interface Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5–1
5–2
esnmp_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_unregister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_register2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_unregister2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_uncapabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_poll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_are_you_there . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_trap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5–3
5–6
5–7
5–11
5–12
5–13
5–14
5–15
5–16
5–17
esnmp_sysuptime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Method Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5–18
5–19
5.2
*_get Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5–20
*_set Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Processing *_set Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Method Routine Applications Programming . . . . . . . . . . . . . . . . . . . . .
Value Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Support Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5–22
5–24
5–26
5–27
5–30
5.2.1
5.2.2
5.2.3
5.3
o_integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
o_octet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
o_oid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
o_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
o_counter64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
str2oid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sprintoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
instance2oid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
oid2instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
inst2ip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cmp_oid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5–31
5–33
5–34
5–35
5–37
5–38
5–39
5–40
5–42
5–44
5–47
iv
Download from Www.Somanuals.com. All Manuals Search And Download.
cmp_oid_prefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clone_oid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
free_oid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clone_buf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
mem2oct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cmp_oct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clone_oct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
free_oct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
free_varbind_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
set_debug_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
is_debug_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ESNMP_LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
_ _print_varbind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
set_select_limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
_ _set_progname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
_ _restore_progname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
_ _parse_progname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
esnmp_cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5–48
5–49
5–50
5–51
5–52
5–53
5–54
5–55
5–56
5–57
5–58
5–59
5–60
5–61
5–62
5–63
5–64
5–65
6 Troubleshooting eSNMP Problems
6.1
6.2
6.3
Modifying the Subagent Error Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying the Subagent Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6–1
6–1
6–2
Index
Figures
1–1
1–2
3–1
SNMP Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eSNMP Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MIB II in SMI Tree Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1–2
1–3
3–3
Tables
1
TCP/IP Services Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SNMP Component Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Files for Building a Subagent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Host Resources MIB Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
snmp_request Command Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .
Flags for the snmp_request Command . . . . . . . . . . . . . . . . . . . . . . . . .
Data Types for the snmp_request and snmp_trapsnd Commands . . . .
Parameters for the snmp_trapsnd Command . . . . . . . . . . . . . . . . . . . .
Flags for the snmp_trapsnd Command . . . . . . . . . . . . . . . . . . . . . . . .
snmp_traprcv Command Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interface Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
viii
1–4
1–1
1–2
2–1
4–1
4–2
4–3
4–4
4–5
4–6
5–1
1–6
2–1
4–1
4–3
4–5
4–10
4–10
4–12
5–1
v
Download from Www.Somanuals.com. All Manuals Search And Download.
Download from Www.Somanuals.com. All Manuals Search And Download.
Preface
The Compaq TCP/IP Services for OpenVMS product is the Compaq
implementation of the TCP/IP networking protocol suite and internet services
for OpenVMS Alpha and OpenVMS VAX systems.
A layered software product, TCP/IP Services provides a comprehensive suite
of functions and applications that support industry-standard protocols for
heterogeneous network communications and resource sharing.
This manual describes the features of the Simple Network Managment Protocol
(SNMP) provided with TCP/IP Services. It also describes the extensible SNMP
(eSNMP) application programming interface (API) and development environment.
See the Compaq TCP/ IP Services for OpenVMS Installation and Configuration
manual for information about installing, configuring, and starting this product.
Intended Audience
This manual is for experienced OpenVMS and UNIX system managers and
assumes a working knowledge of TCP/IP networking, TCP/IP terminology, and
some familiarity with the TCP/IP Services product.
Document Structure
This manual contains the following chapters:
•
•
•
•
Chapter 1 describes the implementation of eSNMP provided with Compaq
TCP/IP Services for OpenVMS.
Chapter 2 describes the groups and objects implemented with the Host
Resources MIB and MIB II that are provided with the eSNMP software.
Chapter 3 describes how to use the eSNMP API to create a MIB subagent to
manage entities or applications.
Chapter 4 describes the trap sender, trap receiver, and MIB browser utilities
provided with TCP/IP Services.
•
•
Chapter 5 provides reference information about the eSNMP API routines.
Chapter 6 describes some troubleshooting aids provided with TCP/IP Services.
vii
Download from Www.Somanuals.com. All Manuals Search And Download.
Related Documents
Table 1 lists the documents available with this version of TCP/IP Services.
Table 1 TCP/IP Services Documentation
Manual
Contents
DIGITAL TCP/ IP Services for
OpenVMS Concepts and Planning
This manual provides conceptual information about networking
and the TCP/IP protocol including a description of the Compaq
implementation of the Berkeley Internet Name Domain (BIND)
service and the Network File System (NFS). It outlines general
planning issues to consider before configuring your system to use
the TCP/IP Services software.
This manual also describes the manuals in the documentation
set, provides a glossary of terms and acronyms for the TCP/IP
Services software product, and documents how to contact the
InterNIC Registration Service to register domains and access
Request for Comments (RFCs).
Compaq TCP/ IP Services for OpenVMS This text file describes new features and changes to the software
Release Notes
including installation, upgrade, configuration, and compatibility
information. These notes also describe new and existing software
problems and restrictions, and software and documentation
corrections.
Print this text file at the beginning of the installation procedure
and read it before you install TCP/IP Services.
Compaq TCP/ IP Services for OpenVMS This manual explains how to install and configure the TCP/IP
Installation and Configuration
Services layered application product.
DIGITAL TCP/ IP Services for
OpenVMS User ’s Guide
This manual describes how to use the applications available with
TCP/IP Services such as remote file operations, email, TELNET,
TN3270, and network printing. This manual explains how to use
these services to communicate with systems on private internets
or on the worldwide Internet.
Compaq TCP/ IP Services for OpenVMS This manual describes how to configure and manage the TCP/IP
Management
Services product.
Use this manual with the Compaq TCP/ IP Services for
OpenVMS Management Command Reference manual.
Compaq TCP/ IP Services for OpenVMS This manual describes the TCP/IP Services management
Management Command Reference
commands.
Use this manual with the Compaq TCP/ IP Services for
OpenVMS Management manual.
Compaq TCP/ IP Services for OpenVMS This reference card lists the TCP/IP management commands by
Management Commands Quick
Reference Card
component and describes the purpose of each command.
Compaq TCP/ IP Services for OpenVMS This reference card contains inforomation about commonly
UNIX Commands Quick Reference Card performed network management tasks and their corresponding
TCP/IP management and Compaq Tru64 UNIX command
formats.
DIGITAL TCP/ IP Services for
OpenVMS ONC RPC Programming
This manual presents an overview of high-level programming
using open network computing remote procedure calls (ONC
RPC). This manual also describes the RPC programming
interface and how to use the RPCGEN protocol compiler to
create applications.
(continued on next page)
viii
Download from Www.Somanuals.com. All Manuals Search And Download.
Table 1 (Cont.) TCP/IP Services Documentation
Manual
Contents
Compaq TCP/ IP Services for OpenVMS This manual describes how to use the Sockets API and OpenVMS
Sockets API and System Services
Programming
system services to develop network applications.
Compaq TCP/ IP Services for OpenVMS This manual describes the Simple Network Management Protocol
SNMP Programming and Reference
(SNMP) and the SNMP application programming interface
(eSNMP). It describes the subagents provided with TCP/IP
Services, utilities provided for managing subagents, and how to
build your own subagents.
Compaq TCP/ IP Services for OpenVMS This manual provides information about how to isolate the
Tuning and Troubleshooting
causes of network problems and how to tune the TCP/IP Services
software for the best performance.
Compaq TCP/ IP Services for OpenVMS This manual describes the IPv6 environment, the roles of
Guide to IPv6
systems in this environment, the types and function of the
different IPv6 addresses, and how to configure TCP/IP Services
to access the 6bone network.
For additional information about Compaq OpenVMS products and services, access
the Compaq website at the following location:
http://www.openvms.compaq.com/
For a comprehensive overview of the TCP/IP protocol suite. you might find the
book Internetworking with TCP/ IP: Principles, Protocols, and Architecture, by
Douglas Comer, useful.
Reader’s Comments
Compaq welcomes your comments on this manual. Please send comments to
either of the following addresses:
Internet
Mail
op en vm sd oc@com p a q.com
Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698
How to Order Additional Documentation
Visit the following World Wide Web address for information about how to order
additional documentation:
http://www.openvms.compaq.com/
If you need help deciding which documentation best meets your needs, call
800-282-6672.
Conventions
The name TCP/IP Services means both:
•
•
Compaq TCP/IP Services for OpenVMS Alpha
Compaq TCP/IP Services for OpenVMS VAX
The name UNIX refers to the Compaq Tru64 UNIX operating system.
ix
Download from Www.Somanuals.com. All Manuals Search And Download.
The following conventions are used in this manual. In addition, please note that
all IP addresses are fictitious.
Ctrl/x
PF1 x
Return
A sequence such as Ctrl/x indicates that you must hold down
the key labeled Ctrl while you press another key or a pointing
device button.
A sequence such as PF1 x indicates that you must first press
and release the key labeled PF1 and then press and release
another key or a pointing device button.
In examples, a key name enclosed in a box indicates that
you press a key on the keyboard. (In text, a key name is not
enclosed in a box.)
In the HTML version of this document, this convention appears
as brackets, rather than a box.
. . .
A horizontal ellipsis in examples indicates one of the following
possibilities:
•
•
•
Additional optional arguments in a statement have been
omitted.
The preceding item or items can be repeated one or more
times.
Additional parameters, values, or other information can be
entered.
.
.
.
A vertical ellipsis indicates the omission of items from a code
example or command format; the items are omitted because
they are not important to the topic being discussed.
( )
In command format descriptions, parentheses indicate that you
must enclose choices in parentheses if you specify more than
one.
[ ]
In command format descriptions, brackets indicate optional
choices. You can choose one or more items or no items.
Do not type the brackets on the command line. However,
you must include the brackets in the syntax for OpenVMS
directory specifications and for a substring specification in an
assignment statement.
|
In command format descriptions, vertical bars separate choices
within brackets or braces. Within brackets, the choices are
optional; within braces, at least one choice is required. Do not
type the vertical bars on the command line.
{ }
In command format descriptions, braces indicate required
choices; you must choose at least one of the items listed. Do
not type the braces on the command line.
bold text
italic text
This typeface represents the introduction of a new term. It
also represents the name of an argument, an attribute, or a
reason.
Italic text indicates important information, complete titles
of manuals, or variables. Variables include information that
varies in system output (Internal error number), in command
lines (/PRODUCER=name), and in command parameters in
text (where dd represents the predefined code for the device
type).
UPPERCASE TEXT
Uppercase text indicates a command, the name of a routine,
the name of a file, or the abbreviation for a system privilege.
x
Download from Www.Somanuals.com. All Manuals Search And Download.
Monospace text
Monospace type indicates code examples and interactive screen
displays.
This typeface indicates UNIX system output or user input,
commands, options, files, directories, utilities, hosts, and users.
In the C programming language, this typeface identifies the
following elements: keywords, the names of independently
compiled external functions and files, syntax summaries, and
references to variables or identifiers introduced in an example.
-
A hyphen at the end of a command format description,
command line, or code line indicates that the command or
statement continues on the following line.
numbers
All numbers in text are assumed to be decimal unless
otherwise noted. Nondecimal radixes—binary, octal, or
hexadecimal—are explicitly indicated.
xi
Download from Www.Somanuals.com. All Manuals Search And Download.
Download from Www.Somanuals.com. All Manuals Search And Download.
1
Overview
The Simple Network Management Protocol (SNMP) is the de facto industry
standard for managing TCP/IP networks. The protocol defines the role of a
network management station (NMS) and the SNMP agent. SNMP allows remote
users on an NMS to monitor and manage network entities such as hosts, routers,
X terminals, and terminal servers.
TCP/IP Services provides support for SNMP Version 2, using the Extensible
Simple Network Management Protocol (eSNMP) architecture, under which a
single master agent can support any number of subagents. The TCP/IP Services
implementation of eSNMP includes a master agent, two subagents, an application
programming interface (API), tools used to build additional subagents, startup
and shutdown procedures, and text-based configuration files.
This chapter provides an overview of the Compaq implementation of eSNMP.
Topics include:
•
•
•
eSNMP master agent and subagent architecture (Section 1.1)
The procedure for handling SNMP requests (Section 1.2)
The components of the TCP/IP Services software kit that implement SNMP
(Section 1.3)
•
•
•
•
The files useful in developing your own subagent (Section 1.4)
The eSNMP API (Section 1.5)
The management information base (MIB) compiler (Section 1.6)
The impact of running SNMP Version 1 subagents against the SNMP Version
2 implementation provided with TCP/IP Services (Section 1.7)
•
Sources of additional information about implementing subagents (Section 1.8)
1.1 SNMP Architecture
Figure 1–1 illustrates the SNMP architecture.
Overview 1–1
Download from Www.Somanuals.com. All Manuals Search And Download.
Overview
1.1 SNMP Architecture
Figure 1–1 SNMP Architecture
Master Agent
Subagent 1
Subagent 2
Subagent n
eSNMP API
SNMP/ASN.1
Library
AgentX (TCP/IP V5.1)
TCP/IP Kernel
OpenVMS
VM-0704A-AI
The SNMP environment consists of the following elements:
•
The master agent, a process that runs on the host and handles SNMP
requests from clients over the standard SNMP well-known port 161.
•
One or more subagents, each of which provides access to the MIB data
specified in client requests. In the TCP/IP Services implementation, the
master agent contains two resident subagents, one that handles a subset of
MIB II variables, and another that handles the Host Resources MIB. These
MIBs are described in Chapter 2.
•
•
The SNMP ASN.1 library, used by the master agent to interpret ASN.1
messages.
The eSNMP API, the application programming interface that provides
routines for programming your own subagents. This API runs on the AgentX
routines, which are internal to the SNMP architecture.
•
The TCP/IP kernel running on the OpenVMS operating system.
The master agent and subagents communicate by means of the AgentX
protocol, which is based on RFC 2741.
For information about configuring and managing the SNMP service, refer to the
Compaq TCP/ IP Services for OpenVMS Management guide.
1.2 Request Handling
The eSNMP software manages network communication by having the master
agent listen for requests and then passes the requests to the appropriate
subagent.
Figure 1–2 illustrates communication between the master agent and subagents.
1–2 Overview
Download from Www.Somanuals.com. All Manuals Search And Download.
Overview
1.2 Request Handling
Figure 1–2 eSNMP Data Flow
NMS1
Client
Host 1
Subagent 1
Subagent 2
705
Master Agent
161
Network
Subagent n
NMS2
Host 2
161
Client
Master Agent
Subagent 1
Trap
client
Legend:
Flow of trap notification
Flow of get/set request
Flow of "are_you_there" message
VM-0705A-AI
The process of communication for a request is illustrated with dashed lines and
includes the following steps:
1. The network management station (NMS) (sometimes called the client),
originates SNMP requests to obtain and set information.
Note
The client component is not provided with TCP/IP Services.
To provide access to MIBs and to test SNMP communication, TCP/IP
Services provides the following utilities:
•
•
•
MIB browser
Trap sender
Trap receiver
These utilities are described in Chapter 4.
Overview 1–3
Download from Www.Somanuals.com. All Manuals Search And Download.
Overview
1.2 Request Handling
The network management station sends an SNMP request to the master
agent running on the host, using port 161. An SNMP request is made using
one of the following commands:
•
•
•
•
Get
GetNext
GetBulk
Set
Note
TCP/IP Services does not support the standard SNMP Inform command.
The request specifies the object identifer (OID) of the data to be accessed.
For information about formatting get and set requests, refer to Section 5.2.
Request formats are specified in RFC 1905.
2. The master agent sends the request to the subagent that registered the
subtree containing the OID.
The subagent receives communications from the master agent over the socket
that was assigned when the subagent registered the subtree.
3. The appropriate subagent processes the request.
4. The subagent sends the response message to the master agent using the port
that was assigned when the subagent registered the MIB.
When they are idle, subagents periodically send a message to port 705 to ensure
that the master agent is still running. In Figure 1–2, subagent 1 is sending the
esnmp_are_you_there message.
A
trap is generated by the subagent and sent to the client. In Figure 1–2,
subagent n is generating a trap for the trap client on NMS 2.
The trap and esnmp_are_you_there routines are described in Section 5.1.
1.3 TCP/IP Services Components for SNMP
Table 1–1 lists the components of SNMP and the command procedures for
managing SNMP that are supplied with TCP/IP Services.
Table 1–1 SNMP Component Files
File
Location
Function
TCPIP$ESNMP_SERVER.EXE
TCPIP$OS_MIBS.EXE
SYS$SYSTEM
SYS$SYSTEM
SYS$SYSTEM
Master agent image.
MIB II subagent image.
TCPIP$HR_MIB.EXE
Host Resources MIB
subagent image.
TCPIP$SNMP_REQUEST.EXE
TCPIP$SNMP_TRAPSND.EXE
SYS$SYSTEM
SYS$SYSTEM
Simple MIB browser.
Utility for sending trap
messages.
(continued on next page)
1–4 Overview
Download from Www.Somanuals.com. All Manuals Search And Download.
Overview
1.3 TCP/IP Services Components for SNMP
Table 1–1 (Cont.) SNMP Component Files
File
Location
Function
TCPIP$SNMP_TRAPRCV.EXE
TCPIP$ESNMP_SHR.EXE
SYS$SYSTEM
SYS$SHARE
Utility for receiving trap
messages.
Image file containing eSNMP
application programming
interface (API) routines.
TCPIP$SNMP_STARTUP.COM
TCPIP$SNMP_SYSTARTUP.COM
SYS$STARTUP
SYS$STARTUP
Command procedure
that installs master and
subagent images and runs
TCPIP$SNMP_RUN.COM.
Command procedure
initiated by TCPIP$SNMP_
STARTUP.COM. Provided for
site-specific customizations,
such as parameter settings.
TCPIP$SNMP_RUN.COM
TCPIP$SYSTEM
SYS$STARTUP
SYS$STARTUP
Command procedure that
starts the master agent and
subagents.
TCPIP$SNMP_SHUTDOWN.COM
TCPIP$SNMP_SYSHUTDOWN.COM
Command procedure that
stops the master agent and
subagents.
Command procedure
initiated by TCPIP$SNMP_
SHUTDOWN.COM.
Provided for site-specific
customization, such as
parameter settings.
TCPIP$EXTENSION_MIB_STARTUP.COM
SYS$SYSDEVICE:[TCPIP$SNMP]
Command procedure
invoked by TCPIP$SNMP_
SYSTARTUP.COM to start
custom subagents.
TCPIP$EXTENSION_MIB_
SHUTDOWN.COM
SYS$SYSDEVICE:[TCPIP$SNMP]
Command procedure
invoked by TCPIP$SNMP_
SYSHUTDOWN.COM to
stop custom subagents.
TCPIP$EXTENSION_MIB_RUN.COM
SYS$SYSDEVICE:[TCPIP$SNMP]
Command procedure
invoked by TCPIP$SNMP_
SYSTARTUP.COM when the
service is enabled and starts
detached processes to run
subagents.
1.4 Writing an eSNMP Subagent
Table 1–2 lists the files that are available to help you develop MIBs and
subagents. Except where noted, the files are located in the directory pointed to by
TCPIP$SNMP_EXAMPLES.
Overview 1–5
Download from Www.Somanuals.com. All Manuals Search And Download.
Overview
1.4 Writing an eSNMP Subagent
Table 1–2 Files for Building a Subagent
File
Description
ESNMP.H
Header file used to create a subagent. Located in
TCPIP$ESNMP.
GAWK.EXE
Interpreter for MIB converter.
MIB-CONVERTER.AWK
A UNIX based awk shell script that takes a MIB
definition in ASN.1 notation and converts it to an
.MY file.
RFC1213.MY
RFC1231.MY
RFC1285.MY
RFC1442.MY
MIB II definitions.
IEEE 802.5 Token Ring MIB definitions.
FDDI MIB definitions.
SNMP Version 2 Structure of Management
Information (SMI) definitions.
SNMP-SMI.MY
SNMP Version 2 SMI definitions from RFC 1902
(replaces RFC 1442).
SNMP-TC.MY
SNMP Version 2 SMI definitions from RFC 1903
(replaces RFC 1443).
V2-TC.MY
SNMP Version 2 SMI definitions from RFC 1903
(superset of those in SNMP-TC.MY).
TCPIP$BUILD_CHESS.COM
TCPIP$CHESS_SUBAGENT.OPT
*.C and *.H
Command file that builds the sample chess
subagent.
Options file for use in building the sample chess
subagent.
Source code for chess example. Contains detailed
documentation that explains how the code
functions.
TCPIP$CHESS_SUBAGENT.EXE
TCPIP$ESNMP.OLB
Functioning chess example image.
Object library file containing routines used to
create a subagent. Located in the directory
pointed to by TCPIP$SNMP.
TCPIP$ESNMP_SHR.EXE
UCX$ESNMP_SHR.EXE
Shareable image containing routines used to
create a subagent. Located in the directory
pointed to by SYS$SHARE.
Copy of TCPIP$ESNMP_SHR.EXE, provided for
compatibility with existing customer subagents
linked under TCP/IP Services V4.x. Located in
the directory pointed to by SYS$SHARE.
TCPIP$MIBCOMP.EXE
TCPIP$MOSY.EXE
TCPIP$SNMPI.EXE
Images associated with the MIB compiler.
Located in SYS$SYSTEM.
For information about building a subagent on an OpenVMS system, see
Chapter 3.
1.5 The eSNMP API
The Compaq TCP/IP Services for OpenVMS implementation of the eSNMP
architecture includes an API that provides programmers with many eSNMP
routines they would otherwise have to develop themselves.
The eSNMP API includes interface routines, method routines, and support
routines.
1–6 Overview
Download from Www.Somanuals.com. All Manuals Search And Download.
Overview
1.5 The eSNMP API
Interface routines handle the basic subagent operations, such as:
•
•
•
•
•
•
Subagent initialization and termination
Registration
Polling of the master agent
Trap sending
UNIX system time conversion
Adding and removing subagent capabilities registered with the master agent
The support routines allow the subagent to manipulate the data in the response
to the request, and include the following:
•
•
•
•
•
•
Basic protocol data unit (PDU) handling
Authentication handling
Octet string handling
Variable binding (VARBIND) handling
Object identifier (OID) handling
Buffer handling
Chapter 5 describes the API routines in more detail.
To create a subagent, the programmer must provide modules to implement the
method routines, as described in Chapter 3.
1.5.1 The SNMP Utilities
To provide quick access to information in the MIBs, and to test SNMP operation,
TCP/IP Services provides the following utilities:
•
•
•
TCPIP$SNMP_REQUEST.EXE, a MIB browser that allows you to retrieve
and update objects from the MIBs.
TCPIP$SNMP_TRPSND.EXE, a trap sender that generates traps (messages
that require no response).
TCPIP$SNMP_TRPRCV.EXE, a trap receiver (or ‘‘listener’’) that is used to
detect trap messages.
For information about using the SNMP utilities, see Chapter 4.
1.6 The MIB Compiler
The MIB compiler processes the statements in an ASN.1 file and generates
modules that are used by the developer to create subagent routines. For every
ASN.1 input file that is processed using the MIB compiler, two output files, a
subtree_TBL.H file and a subtree_TBL.C file, are generated, where subtree is the
name from the original MIB definition file (for example, chess). The output files
are described in more detail in Chapter 3.
The subtree_TBL.H file is a header file that contains the following:
•
•
•
•
A declaration of the subtree structure
Index definitions for each MIB variable in the subtree
Enumeration definitions for MIB variables with enumerated values
MIB group data structure definitions
Overview 1–7
Download from Www.Somanuals.com. All Manuals Search And Download.
Overview
1.6 The MIB Compiler
•
Method routine function prototypes
The subtree_TBL.C file is an object file that contains the following:
•
•
•
An array of integers representing the OIDs for each MIB variable
An array of OBJ ECT structures
An initialized SUBTREE structure
1.7 SNMP Versions
The extensible SNMP software supports SNMP Version 2, based on RFCs 1901
through 1908, including:
•
•
•
The SNMP Version 2 structure of management information for SNMP Version
2 (SMI Version 2) and textual conventions.
The eSNMP library API (SNMP Version 2), variable binding exceptions, and
error codes.
SNMP Version 1 and SNMP Version 2 requests. Both versions are handled
by the master agent. SNMP Version 2 specific information from the subagent
is mapped, when necessary, to SNMP Version 1 adherent data (according
to RFC 2089). For example, if a management application makes a request
using SNMP Version 1 PDUs, the master agent replies using SNMP Version
1 PDUs, mapping any SNMP Version 2 SMI items received from subagents.
In most cases, subagents created with a previous version of the eSNMP
API do not require any code changes and do not have to be recompiled. The
circumstances under which recoding or recompiling are required are described
in Section 1.7.1.
1.7.1 Using Existing (SNMP Version 1) MIB Modules
Existing SNMP Version 1 MIB subagent executable files should be compatible
with the current SNMP Version 2 master agent without the need to recompile
and relink, with the following exceptions:
•
Any program that relies on TCP/IP Services Version 4.1 or 4.2 kernel data
structures or access functions may run but may not return valid data. Such
programs should be rewritten.
•
Programs linked against UCX$ACCESS_SHR.EXE, UCX$IPC_SHR.EXE, or
other older shareable images (except for UCX$ESNMP_SHR.EXE, which is
described in the next list item) may not run even when relinked. You may
need to either rewrite or both rewrite and recompile such programs. Note
that the Chess example image (UCX$CHESS_SUBAGENT.EXE) has been
updated and renamed TCPIP$CHESS_SUBAGENT.EXE.
•
For programs linked against certain versions of UCX$ESNMP_SHR.EXE:
–
Images associated with the following versions of TCP/IP Services will run
correctly without the need to relink them:
Version 4.1 ECO 9 and later
Version 4.2 ECO 1 and later
The installation of TCP/IP Services provides a backward-compatible
version of UCX$ESNMP_SHR.EXE in the SYS$SHARE directory. Do not
delete this image.
1–8 Overview
Download from Www.Somanuals.com. All Manuals Search And Download.
Overview
1.7 SNMP Versions
If you have problems running images linked against an older version of
UCX$ESNMP_SHR.EXE, verify that the version in SYS$SHARE is the
latest by entering the following DCL command:
$ DIRECTORY/DATE SYS$SHARE:*$ESNMP_SHR.EXE
The creation dates of the files with the prefix TCPIP$ and UCX$ should
be within a few seconds of each other, and only one version of each file
should exist. Make sure both images include the file protection W:RE.
–
You should relink and perhaps recompile images associated with ECOs for
Version 4.1 or 4.2 other than those discussed in the previous list item.
Images linked against object library (.OLB) files may not need to be relinked,
although you can relink them against the shareable images in this version of the
product to decrease the image size. Relinking against the shareable image allows
you to take advantage of updated versions of the eSNMP API without the need to
relink. Some images linked against the current version of TCP/IP Services may
run under Versions 4.1 and 4.2, but this backward compatibility is not supported
and may not work in future versions of TCP/IP Services.
If an existing subagent does not execute properly, relink it against this version
of TCP/IP Services to produce a working image. Some subagents (such as the
OpenVMS Server MIB) require a minimum version of OpenVMS as well as a
minimum version of TCP/IP Services.
1.8 For More Information
This manual provides the OpenVMS information required for implementing
eSNMP subagents and ensuring their proper operation in that environment.
The eSNMP software for OpenVMS is derived from the Compaq Tru64 UNIX
product. For information about the architecture and for details about the eSNMP
API, refer to the UNIX documentation at the following URL:
http://www.compaq.com/unix
For information about prototypes and definitions for the routines in the eSNMP
API, see the TCPIP$SNMP:ESNMP.H file. Table 1–2 lists files that contain
additional comments and documentation.
Overview 1–9
Download from Www.Somanuals.com. All Manuals Search And Download.
Download from Www.Somanuals.com. All Manuals Search And Download.
2
MIBs Provided with TCP/IP Services
This chapter describes how MIBs are implemented on OpenVMS. The MIBs
provided with TCP/IP Services are:
•
The Host Resources MIB, which manages operating system objects
(Section 2.1)
•
MIB II, which manages TCP/IP kernel objects (Section 2.2)
2.1 Overview of the Host Resources MIB
The Host Resources MIB defines a uniform set of objects useful for the
management of host computers. The Host Resources MIB, described by
RFC 1514, defines objects that are common across many computer system
architectures. The TCP/IP Services implementation of SNMP includes many
of these defined objects. In addition, some objects in MIB II provide host
management functionality.
2.1.1 Defining Host Resources MIB Implemented Objects
This section defines each of the implemented eSNMP objects. Table 2–1
provides a general RFC description and a specific OpenVMS description for
each implemented object.
Table 2–1 Host Resources MIB Objects
Object Name
RFC Description
OpenVMS Description
hrSystemUptime
The amount of time since this Time since system boot (in hundredths of
host was last initialized.
a second).
hrSystemDate
The host’s notion of the local
date and time of day.
Date and time character string with
Coordinated Universal Time (UTC)
information if available.
hrSystemIntialLoadDevice
Index of the hrDeviceEntry
for configured initial
Index of SYS$SYSDEVICE in the device
table.
operating system load.
hrSystemIntialLoadParameters Parameters supplied to the
load device when requesting
A string of boot parameters from the
console (Alpha only).
initial operating system
configuration.
hrSystemNumUsers
Number of user sessions for
which the host is storing
state information.
Number of processes that are neither
owned by another process nor running
detached.
(continued on next page)
MIBs Provided with TCP/IP Services 2–1
Download from Www.Somanuals.com. All Manuals Search And Download.
MIBs Provided with TCP/IP Services
2.1 Overview of the Host Resources MIB
Table 2–1 (Cont.) Host Resources MIB Objects
Object Name
RFC Description
OpenVMS Description
hrSystemProcesses
Number of process contexts
currently loaded or running
on the system.
Number of processes listed using the
SHOW SYSTEM command.
hrSystemMaxProcesses
hrMemorySize
Maximum number of process
contexts the system can
support, or 0 if not applicable.
SYSGEN parameter MAXPROCESSCNT.
The amount of physical main
memory contained in the
host.
The amount of physical main memory
contained in the host.
hrStorageIndex
hrStorageType
A unique value for each
logical storage area contained
in the host.
Index of entry in hrStorageTable.
The type of storage
represented by this entry.
A numeric representation of the
device class and type displayed by the
SHOW DEVICE/FULL command.
hrStorageDescr
hrStorageAllocationUnits
hrStorageSize
A description of the type
and instance of the storage
described by this entry.
Character string device type displayed by
the SHOW DEVICE/FULL command.
The size of the data objects
allocated from this pool (in
bytes).
Always 512 (the size of an OpenVMS disk
block).
The size of storage
in this entry in
hrStorageAllocationUnits.
The total number of blocks on a device
displayed by the SHOW DEVICE/FULL
command.
hrStorageUsed
The allocated amount of
storage in this entry in
hrStorageAllocationUnits.
The total number of used blocks
on a device displayed by the
SHOW DEVICE/FULL command.
hrDeviceIndex
A unique value for each host
or device constant between
agent reinitialization.
Index of entry in hrDeviceTable.
hrDeviceType
An indication of the type of
device. Some of these devices
have corresponding entries in
other tables.
In object identifier format, a numeric
representation of the device class and type
displayed by the SHOW DEVICE/FULL
command.
hrDeviceDesc
A text description of
the device, including
manufacturer and version
number (service, optional).
Character string of the device type
displayed by the SHOW DEVICE/FULL
command.
hrDeviceStatus
hrDeviceErrors
The current operational state
of the device.
A numeric indication of the status of the
device.
The number of errors
detected on the device. The
recommended initial value is
zero.
The number of errors indicated by the
SHOW DEVICE command. This value
is initialized to zero when the device is
recognized by the system instead of when
the master agent is initialized.
hrProcessorFrwID
The product ID of the
firmware associated with
the processor.
An object identifier that corresponds to
the console or PALcode version (Alpha
only).
(continued on next page)
2–2 MIBs Provided with TCP/IP Services
Download from Www.Somanuals.com. All Manuals Search And Download.
MIBs Provided with TCP/IP Services
2.1 Overview of the Host Resources MIB
Table 2–1 (Cont.) Host Resources MIB Objects
Object Name
RFC Description
OpenVMS Description
hrNetworkIfIndex
The value of the ifIndex that
corresponds to this network
device.
The value of the index in the interface
table in the standard MIB that
corresponds to this network device.
hrDiskStorageAccess
Indicates whether the storage This value is set to 2 if the device is
device is read/write or read
only.
read only; otherwise, it is set to 1. (The
SHOW DEVICE/FULL command displays
‘‘software write-locked.’’)
hrDiskStorageMedia
Indicates the storage device
media type.
Indicates device type.
hrDiskStorageRemovable
Indicates whether the disk
can be removed from the
drive.
Indicates whether the disk can be removed
from the drive.
hrDiskStorageCapacity
hrSWRunIndex
The total size of this long-
term storage device.
Half of the value for total blocks displayed
by the SHOW DEVICE/FULL command.
A unique value for each
software product running on
the host.
Process ID.
hrSWRunPath
A description of the location
where this software was
loaded.
Fully qualified name of executable image.
hrSWRunStatus
The status of the software
that is running.
The values and the associated status of
each are:
•
•
•
1 indicates that the current process is
running (CUR)
2 indicates that the process is
computable (COM)
3 indicates that you cannot run the
process.
hrSWRunPerfCPU
hrSWRunPerfMem
The number (in hundredths
of a second) of the total
system’s CPU resources
consumed by this process.
Process elapsed CPU time (in hundredths
of a second).
The total amount of real
system memory allocated to
this process.
Process current working set (in kilobytes).
2.1.2 Restrictions to Host Resources MIB
SNMP requests are not implemented for the following Host Resources MIB
objects:
hrPartitionTable
hrPrinterTable
hrSWInstalled
hrSWInstalledTable
SNMP set requests are not implemented for the following Host Resources MIB
objects:
MIBs Provided with TCP/IP Services 2–3
Download from Www.Somanuals.com. All Manuals Search And Download.
MIBs Provided with TCP/IP Services
2.1 Overview of the Host Resources MIB
hrFSLastFullBackupDate
hrFSLastPartialBackupDate
hrStorageSize
hrSWRunStatus
hrSystemDate
hrSystemInitialLoadDevice
hrSystemInitialLoadParameters
Note
For objects that are not implemented, the Host Resources MIB returns a
NoSuchObject error status.
TCP/IP Services supports the objects in the Host Resources MIB as follows:
•
The hrDeviceTable includes all the devices known to the OpenVMS host
except those with the following characteristics:
Off line
Remote
UCB marked delete-on-zero-reference-count
Mailbox device
Device with remote terminal (DEV$M_RTT characteristic)
Template terminal-class device
LAT device (begins with _LT)
Virtual terminal device (begins with _VT)
Pseudoterminal device (begins with _FT)
Data items in the hrDeviceTable group have the following restrictions:
–
–
hrDeviceID is always null OID (0.0).
hrDeviceErrors is coded as follows:
Code
Condition
warning (3)
Error logging is in progress (OpenVMS UCB value UCB$M_
ERLOGIP).
running (2)
Software is valid and no error logging is in progress (OpenVMS
UCB value UCB$M_VALID).
unknown (1)
Any other OpenVMS status.
The hrDeviceTable now includes template devices (for example, DNFS0 for
NFS and DAD0 for virtual devices).
For network devices, only the template devices (those with unit number 0)
are displayed.
•
•
hrFSMountPoint (1.3.6.1.2.1.25.3.8.1.2) is DNFSn. The device may change
between restarts or after a dismount/mount procedure.
In the hrFSTable group, if no file systems are mounted through NFS or
no information is accessible, a "no such instance" status is returned for a
get request. Browsers respond differently to this message. For example,
2–4 MIBs Provided with TCP/IP Services
Download from Www.Somanuals.com. All Manuals Search And Download.
MIBs Provided with TCP/IP Services
2.1 Overview of the Host Resources MIB
TCPIP$SNMP_REQUEST.EXE responds with no output and returns directly
to the DCL prompt.
After an NFS mount, the following information is returned in response to a
Get request. The data items implemented for OpenVMS (refer to RFC 1514)
are:
–
–
–
–
hrFSIndex.
hrFSMountPoint is the local DNFS device name.
hrFSRemoteMountPoint is the remote file system.
hrFSType is implemented as:
•
OID 1.3.6.1.2.1.25.3.9.1, for OpenVMS if the file system is not a UNIX
style container file system.
•
hrFSNFS, OID 1.3.6.1.2.1.25.3.9.14, if the file system is a TCP/IP
Services container file system or a UNIX host.
–
–
–
–
hrFSAccess, as defined in RFC 1514.
hrFSBootable is always HRM_FALSE (integer 2).
hrFSStorageIndex is always 0.
hrFSLastFullBackupDate is unknown time. This entry is encoded
according to RFC 1514 as a hexadecimal value 00-00-01-01-00-00-00-00
(J anuary 1, 0000).
–
hrFSLastPartialBackupDate is unknown time. This information is not
available for OpenVMS systems. Instead, hexadecimal value 00-00-01-01-
00-00-00-00 (J anuary 1, 0000) applies.
•
hrProcessorFrwID (OID prefix 1.3.6.1.2.1.25.3.3.1.1) is not implemented on
OpenVMS VAX. On this type of system, it returns standard null OID (0.0).
For example:
1.3.6.1.2.1.25.3.3.1.1.1 = 0.0
For OpenVMS Alpha (firmware version 5.56-7), the response is shown in the
following example:
1.3.6.1.2.1.25.3.3.1.1.1 = 1.3.6.1.2.1.25.3.3.1.1.1.5.56.7
•
•
Data items in the hrDiskStorage table have the following restrictions:
–
–
hrDiskStorageMediais always ‘‘unknown’’ (2).
hrDiskStorageRemoveble is always ‘‘false’’ (2). Note the incorrect spelling
of ‘‘removable’’ in hrDiskStorageRemoveble (from RFC 1514).
hrStorageType always contains the value of hrStorageFixedDisk
(1.3.6.1.2.1.25.2.1.4).
2.2 Overview of MIB II
The Standard MIB (MIB II) described in RFC 1213 defines a set of objects useful
for managing TCP/IP Internet entities. MIB II supports network monitoring
and managing from the Transport layer down to the Physical layer of the
TCP/IP internet stack. This MIB also provides information on how connections
are established and how packets are routed through the Internet. For more
information about MIB architecture, see Section 3.2.
MIBs Provided with TCP/IP Services 2–5
Download from Www.Somanuals.com. All Manuals Search And Download.
MIBs Provided with TCP/IP Services
2.2 Overview of MIB II
2.2.1 MIB II Implemented Groups
A gr ou p is a subdivision of a MIB that defines a subtree. SNMP as implemented
by TCP/IP Services supports the following groups:
•
•
•
•
•
•
•
system (1)
interfaces (2)
Internet Protocol (4)
ICMP (5)
TCP (6)
UDP (7)
SNMP (11)
In the SNMP group (1.3.6.1.2.1.11), data elements with the status noted as
obsolete in RFC 1907 are not implemented.
Note
The TCP/IP Services implementation of SNMP does not support the
following defined MIB II groups:
•
•
•
at (address translation) group
EGP (External Gateway Protocol) group
transmission group
2.2.2 Restrictions to MIB II Implementation
SNMP requests are not implemented for the following MIB II objects:
ipRouteMetric1 - ipRouteMetric5
tcpMaxConn
SNMP set requests are not implemented for the following MIB II group objects:
ipDefaultTTL
ipRouteAge
ipRouteDest
ipRouteIfIndex
ipRouteMask
ipRouteNextHop
ipRouteType
The TCP/IP Services implementation of SNMP includes the following MIB II
objects:
•
sysObjectID is returned in the following format:
1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.22.1
where 1.3.6.1.4.1.36.2.15.13.22.1 corresponds to:
iso.org.dod.internet.private.enterprises.dec.ema.SysObjectIds.DEC-OpenVMS.eSNMP
•
The sysORTable elements are under OID prefix 1.3.6.1.2.1.1.9.1. See RFC
1907 for details.
2–6 MIBs Provided with TCP/IP Services
Download from Www.Somanuals.com. All Manuals Search And Download.
MIBs Provided with TCP/IP Services
2.2 Overview of MIB II
When both the TCPIP$OS_MIBS and TCPIP$HR_MIB subagents are
running, a get request on the sysORTable is as follows. Except where
noted, the OIDs conform to RFC 1907.
1.3.6.1.2.1.1.9.1.2.1 = 1.3.6.1.4.1.36.15.3.3.1.1
1.3.6.1.2.1.1.9.1.2.2 = 1.3.6.1.4.1.36.15.3.3.1.2
1.3.6.1.2.1.1.9.1.3.1 = Base o/s agent (OS_MIBS) capabilities
1.3.6.1.2.1.1.9.1.3.2 = Base o/s agent (HR_MIB) capabilities
1.3.6.1.2.1.1.9.1.4.1 = 31 = 0 d 0:0:0
1.3.6.1.2.1.1.9.1.4.2 = 36 = 0 d 0:0:0
This example is from the MIB browser (TCPIP$SNMP_REQUEST.EXE).
•
Under certain conditions, a subagent makes a duplicate entry in sysORTable
when it restarts. For example:
1.3.6.1.2.1.1.9.1.2.1 = 1.3.6.1.4.1.36.15.3.3.1.1
1.3.6.1.2.1.1.9.1.2.2 = 1.3.6.1.4.1.36.15.3.3.1.2
1.3.6.1.2.1.1.9.1.2.1 = Base o/s agent (OS_MIBS) capabilities
1.3.6.1.2.1.1.9.1.2.2 = Base o/s agent (OS_MIBS) capabilities
1.3.6.1.2.1.1.9.1.4.1 = 3256 = 0 d 0:0:32
1.3.6.1.2.1.1.9.1.4.2 = 3256 = 0 d 0:0:32
In this example, the TCPIP$OS_MIBS subagent made two entries with
different ID numbers (OIDs with the prefix 1.3.6.1.2.1.1.9.1.2) that may
show different sysORUpTime (1.3.6.1.2.1.1.9.1.4). The snmp_request program
translates the value received (in hundredths of a second) to the following,
dropping any fractions of seconds:
d n hh:mm:ss
In this format, n represents the number of days, hh represents the number of
hours, mm represents the number of minutes, and ss represents the number
of seconds.
The HR_MIB subagent has not yet successfully started and registered its
capabilities. If it starts, its entries in this example would use the next
available index number.
•
On systems running versions of the operating system prior to OpenVMS
7.1-2, counters for the MIB II ifTable do not wrap back to 9 after reaching
32
the maximum value (
), as defined in RFC 1155. Instead, they behave
like the gauge type and remain at the maximum value until cleared by an
external event, such as a system reboot. The following counters are affected:
ifInDiscards
ifInErrors
ifInNUcastPkts
ifInOctets
ifInUcastPkts
ifInUnknownProtos
ifOutErrors
ifOutNUcastPkts
ifOutOctets
ifOutUcastPkts
Note that for SNMP Version 2, these counters are data type Counter32. The
following ifTable members are always -1 for OpenVMS:
ifOutDiscards (Counter32)
ifOutQLen (Gauge32)
MIBs Provided with TCP/IP Services 2–7
Download from Www.Somanuals.com. All Manuals Search And Download.
Download from Www.Somanuals.com. All Manuals Search And Download.
3
Creating a Subagent Using the eSNMP API
This chapter describes how to use the eSNMP API to create a MIB subagent that
manages entities or applications. Topics included in this chapter are:
•
•
•
•
•
Creating a MIB specification (Section 3.1)
The structure of management information (Section 3.2)
Creating a MIB source file (Section 3.3)
Including the routines and building the subagent (Section 3.4)
Including your subagents in startup and shutdown procedures (Section 3.5)
Note
To use this eSNMP API to create a subagent, you must have a C compiler
running in your development environment.
3.1 Creating a MIB Specification
The creation of a management information base (MIB) begins with data
gathering. During this phase, the developer identifies the information to
manage, based on the entities that the network manager needs to examine and
manipulate. Each resource that a MIB manages is represented by an object.
After gathering the data, the developer uses Abstract Syntax Notation 1 (ASN.1)
to specify the objects in the MIB.
3.2 The Structure of Management Information
The structure of management information (SMI), which is specified in RFCs 1155
and 1902, describes the general framework within which a MIB can be defined
and constructed. The SMI framework identifies the data types that can be used
in the MIB and how resources within the MIB are represented and named.
SMI avoids complex data types to simplify the task of implementation and to
enhance interoperability. To provide a standard representation of management
information, the SMI specifies standard techniques for the following:
•
•
•
Defining the structure of a particular MIB
Defining individual objects, including the syntax and value of each object
Encoding object values
Creating a Subagent Using the eSNMP API 3–1
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.2 The Structure of Management Information
3.2.1 Assigning Object Identification Codes
Each object in a MIB is associated with an identifier of the ASN.1 type, called
an object identifier (OID). OIDs are unique integers that follow a hierarchical
naming convention.
Each OID has two parts:
•
A preassigned portion that is always represented on the SMI tree as 1.3.6.1
or iso (1), org (3), dod (6), Internet (1).
•
A developer-assigned portion for the private development of MIBs.
Note
Your organization may require you to register all newly assigned OIDs.
In addition to an OID, you should also assign a name to each object to help with
human interpretation.
3.2.2 MIB Subtrees
Understanding MIB subtrees is crucial to understanding the eSNMP API and
how your subagent will work.
Note
This manual assumes that you understand the OID naming structure
used in SNMP. If not, refer to RFC 1902: Structure of Management
Information for Version 2 of the Simple Network Management Protocol
(SNMP Version 2).
The information in SNMP is structured hierarchically like an inverted tree. Each
node has a name and a number. Each node can also be identified by an OID,
which is a concatenation of the subidentifiers (nonnegative numbers). These
numbers are on the path from the root node down to that node in the tree. In
this hierarchy, data is associated only with leaf nodes. (A lea f n od e represents a
MIB variable that can have an instance and an associated value.)
An OID must be at least two subidentifiers and at most 128 subidentifiers in
length. The subidentifier ranges are:
•
•
•
Subidentifier 1 values range from 0 to 2, inclusive.
Subidentifier 2 values range from 0 to 39, inclusive.
The remaining subidentifier values can be any nonnegative number.
Figure 3–1 illustrates the SMI hierarchical tree arrangement as specified in RFCs
1155 and 1902.
3–2 Creating a Subagent Using the eSNMP API
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.2 The Structure of Management Information
Figure 3–1 MIB II in SMI Tree Structure
iso (1)
org (3)
dod (6)
internet (1)
directory (1)
mgmt (2)
mib2 (1)
system (1)
interfaces (2)
at (3)
ip (4)
icmp (5)
tcp (6)
udp (7)
egp (8)
transmission (10)
snmp (11)
experimental (3)
private (4)
enterprises (1)
VM-0721A-AI
Creating a Subagent Using the eSNMP API 3–3
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.2 The Structure of Management Information
For example, the chess MIB provided with the sample code in the
[TCPIP$EXAMPLES.SNMP] directory has an element with the name ‘‘chess.’’
The OID for the element chess is 1.3.6.1.4.1.36.2.15.2.99, which is derived from
its position in the hierarchy of the tree:
iso(1)
org(3)
dod(6)
internet(1)
private(4)
enterprise(1)
digital(36)
ema(2)
sysobjects(15)
decosf(2)
chess(99)
Any node in the MIB hierarchy can define a MIB subtree. All elements in the
subtree have an OID that starts with the OID of the subtree base. For example,
if you define chess to be a MIB subtree base, the elements with the same prefix
as the chess OID are all in the MIB subtree:
chess
1.3.6.1.4.1.36.2.15.2.99
chessProductID
chessMaxGames
chessNumGames
gameTable
1.3.6.1.4.1.36.2.15.2.99.1
1.3.6.1.4.1.36.2.15.2.99.2
1.3.6.1.4.1.36.2.15.2.99.3
1.3.6.1.4.1.36.2.15.2.99.4
1.3.6.1.4.1.36.2.15.2.99.4.1
1.3.6.1.4.1.36.2.15.2.99.4.1.1
1.3.6.1.4.1.36.2.15.2.99.4.1.2
1.3.6.1.4.1.36.2.15.2.99.4.1.3
1.3.6.1.4.1.36.2.15.2.99.4.1.4
1.3.6.1.4.1.36.2.15.2.99.5
1.3.6.1.4.1.36.2.15.2.99.5.1
1.3.6.1.4.1.36.2.15.2.99.5.1.1
1.3.6.1.4.1.36.2.15.2.99.5.1.2
1.3.6.1.4.1.36.2.15.2.99.5.1.3
1.3.6.1.4.1.36.2.15.2.99.5.1.4
1.3.6.1.4.1.36.2.15.2.99.6
1.3.6.1.4.1.36.2.15.2.99.6.1
gameEntry
gameIndex
gameDescr
gameNumMoves
gameStatus
moveTable
moveEntry
moveIndex
moveByWhite
moveByBlack
moveStatus
chessTraps
moveTrap
The base of this MIB subtree is registered with the master agent to tell it that
this subagent handles all requests related to the elements in the subtree.
The master agent expects a subagent to handle all objects subordinate to the
registered MIB subtree. This principle guides your choice of MIB subtrees.
For example, registering a subtree of chess is reasonable because it is realistic
to assume that the subagent could handle all requests for elements in this
subtree. Registering an entire application-specific MIB usually makes sense
because the particular application expects to handle all objects defined in the
application-specific MIB.
However, registering a subtree of SNMP (under MIB II) would be a mistake,
because it is unlikely that the subagent is prepared to handle every defined MIB
object subordinate to SNMP (packet counts, errors, trapping, and so on).
A subagent can register as many MIB subtrees as it wants. It can register OIDs
that overlap with other registrations by itself or with other subagents; however,
it cannot register the same OID more than once. Subagents can register and
unregister MIB subtrees at any time after communication with the master agent
is established.
3–4 Creating a Subagent Using the eSNMP API
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.2 The Structure of Management Information
Normally, it is the nonleaf nodes that are registered as a subtree with the master
agent. However, leaf nodes, or even specific instances, can be registered as a
subtree.
The master agent delivers requests to the subagent that has the MIB subtree
with the longest prefix and the highest priority.
3.3 Creating a MIB Source File
Creating the MIB source file requires the following four-step process:
1. Write the ASN.1 input files, as described in Section 3.3.1.
2. Process the input files with the MIB compiler, as described in Section 3.3.2.
3. Compile and link the routines, as described in Section 3.4.
4. Include the subagent, as described in Section 3.5.
3.3.1 Writing the ASN.1 Input File
After you have assigned names and OIDs to all of the objects in the MIB, create
an ASN.1 source file using ASCII statements.
Note
Providing information about ASN.1 syntax and programming is beyond
the scope of this guide. For more information about ASN.1 programming,
refer to one or more of the documents on this subject provided by the
International Organization for Standardization (ISO).
Instead of creating ASN.1 files yourself, you can create .MY files from existing
ASCII files (for example, from RFCs) by using the MIB-converter facility provided
with TCP/IP Services. This facility uses a UNIX awk script, which runs on
OpenVMS as well as on appropriately configured UNIX systems. For details
about the facility, see the MIB-CONVERTER.AWK file, which is located in
the [.SNMP] subdirectory of TCPIP$EXAMPLES. Standard .MY files are also
provided for your convenience.
The custom MIB definition files have the default extension .MY.
3.3.2 Processing the Input File with the MIB Compiler
Process your ASN.1 source files with the MIB compiler using the DCL command
MIBCOMP.
Note
If you are familiar with processing on UNIX systems, you can use the
UNIX utilities snmpi and mosy. See Section 3.3.2.1 for more information.
The compilation process produces two template C programming modules that
are used in building the executable subagent code. When you run the compiler,
specify all the ASN.1 source files for a given subagent. Whenever any of these
source files are updated, you must repeat the compilation process.
The syntax for the MIBCOMP command is as follows:
MIBCOMP MIB-source-file "subtree" [/PREFIX=prefix-name] [/PRINT_TREE] [/SNMPV2]
Creating a Subagent Using the eSNMP API 3–5
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.3 Creating a MIB Source File
The parameters and qualifiers for the MIBCOMP command are as follows:
Parameter or Qualifier
MIB-source-file
Definition
A comma-separated list of MIB definition files. The
standard extension is .MY, but you can specify any valid
OpenVMS file name. You must specify the full file name.
subtree
The text name for the root of your MIB definitions. This
parameter must be enclosed in quotation marks. This name
is used in generating names for template C modules and
also for the names of the files themselves: subtree_tbl.c and
subtree_tbl.h.
/PREFIX=prefix-name
The MIB compiler attaches the prefix-name string to the
beginning of all generated names.
/PRINT_TREE
/SNMPV2
Displays the entire MIB subtree.
Specifies the use of SNMP Version 2 parsing rules.
The following is an example of processing the chess example files using the
/PRINT_TREE qualifier:
$ MIBCOMP RFC1442.MY,CHESS_MIB.MY "chess" /PRINT_TREE
Processing RFC1442.MY
Processing CHESS_MIB.MY
Dump of objects in lexical order
-- This file created by program ’snmpi -p’
ccitt
iso
0
1
internet
directory
mgmt
1.3.6.1
1.3.6.1.1
1.3.6.1.2
experimental
private
enterprises
dec
1.3.6.1.3
1.3.6.1.4
1.3.6.1.4.1
1.3.6.1.4.1.36
1.3.6.1.4.1.36.2
1.3.6.1.4.1.36.2.15
1.3.6.1.4.1.36.2.15.2
1.3.6.1.4.1.36.2.15.2.99
1.3.6.1.4.1.36.2.15.2.99.1
ema
sysobjectids
decosf
chess
chessProductID
read-only
chessMaxGames
read-only
chessNumGames
read-only
gameTable
gameEntry
ObjectID
INTEGER
INTEGER
1.3.6.1.4.1.36.2.15.2.99.2
1.3.6.1.4.1.36.2.15.2.99.3
1.3.6.1.4.1.36.2.15.2.99.4
1.3.6.1.4.1.36.2.15.2.99.4.1
indexes: gameIndex
gameIndex
1.3.6.1.4.1.36.2.15.2.99.4.1.1
INTEGER
read-write
gameDescr
1.3.6.1.4.1.36.2.15.2.99.4.1.2
DisplayString read-write
range: 0 to 255
gameNumMoves
1.3.6.1.4.1.36.2.15.2.99.4.1.3
INTEGER read-write
gameStatus
1.3.6.1.4.1.36.2.15.2.99.4.1.4
INTEGER read-write
3–6 Creating a Subagent Using the eSNMP API
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.3 Creating a MIB Source File
enum: complete
enum: underway
enum: delete
1
2
3
moveTable
moveEntry
1.3.6.1.4.1.36.2.15.2.99.5
1.3.6.1.4.1.36.2.15.2.99.5.1
indexes: gameIndex moveIndex
moveIndex
1.3.6.1.4.1.36.2.15.2.99.5.1.1
INTEGER
read-write
moveByWhite
1.3.6.1.4.1.36.2.15.2.99.5.1.2
DisplayString read-write
range: 0 to 255
moveByBlack
1.3.6.1.4.1.36.2.15.2.99.5.1.3
DisplayString read-write
range: 0 to 255
moveStatus
1.3.6.1.4.1.36.2.15.2.99.5.1.4
INTEGER
read-write
enum: ok
1
2
enum: delete
security
snmpV2
1.3.6.1.5
1.3.6.1.6
1.3.6.1.6.1
1.3.6.1.6.2
1.3.6.1.6.3
2
snmpDomains
snmpProxys
snmpModules
joint_iso_ccitt
--------------------------
11 objects written to chess_tbl.c
11 objects written to chess_tbl.h
3.3.2.1 UNIX Utilities Supplied with TCP/IP Services
For compatibility with UNIX, the mosy and snmpi utilities are provided with
TCP/IP Services for generating the C language code that defines the object tables.
These UNIX utilities are supported on OpenVMS for compatibility with UNIX-
developed procedures. For information about using these utilities, refer to the
Compaq Tru64 UNIX Network Programmer ’s Guide.
3.3.2.2 Object Tables
The MIBCOMP command is used to generate the C language code that defines
the object tables from the MIBs. The object tables are defined in the emitted files
subtree_TBL.H and subtree_TBL.C, which are compiled into your subagent.
These modules are created by the MIBCOMP command or the UNIX utilities.
Compaq recommends that you do not edit them. If the MIBs change or if a
future version of the SNMP development utilities requires your object tables to be
rebuilt, it is easier to rebuild and recompile the files if you did not edit them.
3.3.2.3 The subtree_TBL.H Output File
The subtree_TBL.H file contains the following sections:
1. A declaration of the subtree structure
2. Index definitions for each MIB variable in the subtree
3. Enumeration definitions for MIB variables with enumerated values
4. MIB group data structure definitions
5. Method routine function prototypes
The following sections describe each section of the subtree_TBL.H file.
Creating a Subagent Using the eSNMP API 3–7
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.3 Creating a MIB Source File
1. Declaration Section
The first section of the subtree_TBL.H file is a declaration of the subtree
structure. The subtree is automatically initialized by code in the subtree_TBL.C
file. A pointer to this structure is passed to the esnmp_register routine to
register a subtree with the master agent. All access to the object table for this
subtree is through this pointer. The declaration has the following form:
extern SUBTREE subtree_subtree;
2. Index Definitions Section
The second section of the subtree_TBL.H file contains index definitions for each
MIB variable in the subtree of the form:
#define I_mib-variable nnn
These values are unique for each MIB variable in a subtree and are the index into
the object table for this MIB variable. These values are also generally used to
differentiate between variables that are implemented in the same method routine
so they can be used in a switch operation.
3. Enumeration Definitions Section
The third section of the subtree_TBL.H file contains enumeration definitions for
those integer MIB variables that are defined with enumerated values, as follows:
#define D_mib-variable_enumeration-name value
These definitions are useful because they describe the value that enumerated
integer MIB variables may take on. For example:
/* enumerations for gameEntry group */
#define
#define
#define
D_gameStatus_complete
D_gameStatus_underway
D_gameStatus_delete
1
2
3
4. MIB Group Data Structure Definitions Section
The fourth section of the subtree_TBL.H file contains data structure definitions of
the following form:
typedef structxxx {
type
mib-variable;
.
.
.
char
mib-variable_mark;
.
.
.
} mib-group_type
The MIB compiler generates one of these data structures for each MIB group
in the subtree. Each structure definition contains a field representing each
MIB variable in the group. In addition to the MIB variable fields, the structure
includes a 1-byte mib-variable-mark field for each variable. You can use these for
maintaining status of a MIB variable. For example, the following is the group
structure for the chess MIB:
3–8 Creating a Subagent Using the eSNMP API
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.3 Creating a MIB Source File
typedef struct _chess_type {
OID
int
int
ches;
chessMaxGames;
chessNumGames;
char chessProductID_mark;
char chessMaxGames_mark;
char chessNumGames_mark;
} chess_type;
Although MIB group structures are provided for your use, you are not required to
use them. You can use the structure that works best with your method routines.
5. Method Routine Prototypes Section
The fifth section of the subtree_TBL.H file describes the method routine
prototypes. Each MIB group within the subtree has a method routine prototype
defined. A MIB group is a collection of MIB variables that are leaf nodes and that
share a common parent node.
There is always a function prototype for the method routine that handles the Get
GetNext, and GetBulk operations. If the group contains any writable variables,
there is also a function prototype for the method routine that handles Set
operations. Pointers to these routines appear in the subtree’s object table which
is initialized in the subtree_TBL.C module. You must write method routines for
each prototype that is defined, as follows:
,
extern int mib-group get( METHOD *method );
extern int mib-group set( METHOD *method );
For example:
extern int chess_get( METHOD *method );
extern int chess_set( METHOD *method );
3.3.2.4 The subtree_TBL.C Output Files
The subtree_TBL.C file file contains the following sections:
1. An array of integers representing the OIDs for each MIB variable
2. An array of OBJ ECT structures
3. An initialized SUBTREE structure
4. Routines for allocating and freeing the mib_group_type
The following sections describe each section of the subtree_TBL.C file.
1. Array of Integers Section
The first section of the subtree_TBL.C file is an array of integers used to represent
the OID of each MIB variable in the subtree. For example:
static unsigned int elems[] = {
1, 3, 6, 1, 4, 1, 36, 2, 15, 2, 99,
/* chess */
1, 3, 6, 1, 4, 1, 36, 2, 15, 2, 99, 1, 0, /* chessProductID */
. . .
};
1, 3, 6, 1, 4, 1, 36, 2, 15, 2, 99, 5, 1, 4, 0, /* moveStatus */
The first line represents the root of the tree; the other lines represent specific
variables. The latter groups are all terminated by a zero, a programming
convenience in internal implementations of API routines.
Creating a Subagent Using the eSNMP API 3–9
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.3 Creating a MIB Source File
2. Array of OBJECT Structures Section
The second section of the subtree_TBL.C file is an array of OBJ ECT structures.
Each MIB variable within the subtree has one OBJ ECT. The chess example
produces the following:
static OBJECT objects[] = {
{I_chessProductID
. . .
,{12, &elems[ 11]}, ESNMP_TYPE_ObjectId
,chess_get, NULL},
An OBJ ECT structure represents a MIB variable and has the following fields:
•
object_index — The constant I_mib-variable from the subtree_TBL.H file,
which identifies this variable (in the chess example, I_chessProductID.)
•
oid — The variable’s OID (points to a part of elems[ ]).
This variable is of type OID, which is a structure containing two elements:
the number of elements in the OID and a pointer to the correct starting place
in the array of elements (elems[ ] in the chess example).
In the chess example, oid is designated by {12, &elemens[ 11]}. This
indicates that:
The OID has 12 integers separated by dots in the ASCII text
representation ("1.3.6.1.4.1.36.2.15.2.99.2"
)
The integer with index 11 in the array elems[ ] is the first element.
type — The variable’s eSNMP data type.
•
•
getfunc — The address of the method routine to call for Get requests (null if
no routine exists).
•
setfunc — The address of the method routine to call for Set requests (null if
no routine exists).
The master agent does not access object tables or MIB variables directly. It only
maintains a registry of subtrees. When a request for a particular MIB variable
arrives, it is processed as shown in the following steps (where the MIB variable is
mib_var and the subtree is subtree_1):
1. The master agent finds subtree_1 as the authoritative region for the mib_var
in the register of subtrees. The authoritative region is determined as the
registered MIB subtree that has the longest prefix and the highest priority.
2. The master agent sends a message to the subagent that registered subtree_1
.
3. The subagent consults its list of registered subtrees and locates subtree_1
.
It searches the object table of subtree_1 and locates the following:
•
•
mib_var (for Get and Set routines)
The first object lexicographically after mib_var (for Next or Bulk routines)
4. The appropriate method routine is called. If the method routine completes
successfully, the data is returned to the master agent. If the method routine
fails when doing a Get or Set, an error is returned. If the method routine
fails when doing a GetNext, the code keeps trying subsequent objects in the
object table of subtree_1 until either a method routine returns successfully or
the table is exhausted. In either case, a response is returned.
5. If the master agent detects that subtree_1 could not return data on a Next
routine, it recursively tries the subtree lexicographically after subtree_1 until
a subagent returns a value or the registry of subtrees is exhausted.
3–10 Creating a Subagent Using the eSNMP API
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.3 Creating a MIB Source File
3. Initialized Subtree Structure Section
The third section of the subtree_TBL.C file is the SUBTREE structure itself. A
pointer to this structure is passed to the eSNMP library routine esnmp_register
to register the subtree. It is through this pointer that the library routines find
the object structures. The following is an example of the chess subtree structure:
SUBTREE chess_subtree = { "chess", "1.3.6.1.4.1.36.2.15.2.99",
{ 11, &elems[0] }, objects, I_moveStatus};
The following table describes the elements of the SUBTREE structure, the
definition of each element in the header file (subtree_TBL.H)), and the element in
the chess example:
Header File
Representation
Description
Example
The name of the subtree’s base
element.
name
"chess"
The ASCII string representation
of the subtree’s OID. This is what
actually gets registered.
dots
"1.3.6.1.4.1.36.2.15.2.99"
11, &elems[0] }
The OID structure for the base
node of the subtree. This points
back to the array of integers.
oid
A pointer to the array of objects
in the object table. It is indexed
by the I_xxxx definitions found in
the subtree_TBL.H file.
object_oid
objects
The index of the last object in the
object_TBL file. This is used to
determine when the end of the
table has been reached.
last
I_moveStatus
4. Routines Section
The final section of the subtree_TBL.C file. contains short routines for allocating
and freeing the mib_group_type. These are provided as a convenience and are
not a required part of the API.
3.4 Including the Routines and Building the Subagent
The MIB compiler does not generate code for implementing the method routines
for your subagent. This includes code for processing get set, and other SNMP
,
requests as well as for generating traps. You must write this code yourself. See
the CHESS_MIB.C module for an example.
To produce executable subagent code, follow these steps:
1. Compile the C modules generated by the MIB compiler, along with your
implementation code. Use a command in the following format (derived from
the sample provided for building the chess example in TCPIP$BUILD_
CHESS.COM):
$ CC /INCLUDE=TCPIP$SNMP /PREFIX=ALL /STANDARD=VAX CHESS_METHOD.C, -
_$ CHESS_MIB.C, CHESS_TBL.C
Creating a Subagent Using the eSNMP API 3–11
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.4 Including the Routines and Building the Subagent
Depending on the version of the Compaq C compiler you are using, you might
see warnings that you can ignore. Portions of these warnings are as follows:
%CC-I-SIGNEDKNOWN
In this declaration, DEC C recognizes the ANSI
keyword "signed". This differs from the VAX C behavior.
%CC-I-INTRINSICINT In this statement, the return type for intrinsic
"strlen" is being changed from "size_t" to "int".
2. Link the object modules using a command and options in the following format
(derived from the chess example):
$ LINK SYS$INPUT/OPTIONS
CHESS_METHOD.OBJ
CHESS_MIB.OBJ
CHESS_TBL.OBJ
SYS$SHARE:TCPIP$ESNMP_SHR.EXE/SHARE
To link with the eSNMP object library, enter the following command:
$ LINK SYS$INPUT/OPTIONS
CHESS_METHOD.OBJ
CHESS_MIB.OBJ
CHESS_TBL.OBJ
TCPIP$SNMP:TCPIP$ESNMP.OLB/LIBRARY
TCPIP$LIBRARY:TCPIP$LIB.OLB/LIBRARY
Alternatively, you can link your subagent with the eSNMP API shareable
image (TCPIP$ESNMP_SHR.EXE). The resulting executable image is smaller
and can be run without relinking against any future versions of the shareable
image. To link the example object with the shareable image, enter the
following command:
$ LINK SYS$INPUT/OPTIONS
CHESS_METHOD.OBJ
CHESS_MIB.OBJ
CHESS_TBL.OBJ
SYS$SHARE:TCPIP$ESNMP_SHR.EXE/SHARE
3.5 Including Extension Subagents in the Startup and Shutdown
Procedures
You can add your custom subagents to the SNMP startup and shutdown
procedures by editing the following files:
File Name
Edit Required
TCPIP$EXTENSION_MIB_STARTUP.COM
Edit the example lines to include an INSTALL
CREATE command for custom images that need to
be installed, possibly with privileges. Remove extra
example lines, and adjust the GOTO statement.
TCPIP$EXTENSION_MIB_RUN.COM
Edit the example lines to include a RUN command
for custom images. Remove extra example lines, and
adjust the GOTO statement.
3–12 Creating a Subagent Using the eSNMP API
Download from Www.Somanuals.com. All Manuals Search And Download.
Creating a Subagent Using the eSNMP API
3.5 Including Extension Subagents in the Startup and Shutdown Procedures
File Name
TCPIP$EXTENSION_MIB_SHUTDOWN.COM
Edit Required
Edit the example lines to:
•
Include symbols for the detached processes that
are running custom images. Use the same process
names specified in TCPIP$EXTENSION_MIB_
RUN.COM.
•
•
Modify the IF and THEN statements to include
the new symbols.
Include an INSTALL DELETE command for
images installed in TCPIP$EXTENSION_MIB_
STARTUP.COM.
•
Remove extra example lines, and adjust the GOTO
statement.
Creating a Subagent Using the eSNMP API 3–13
Download from Www.Somanuals.com. All Manuals Search And Download.
Download from Www.Somanuals.com. All Manuals Search And Download.
4
Using the SNMP Utilities
TCP/IP Services includes the following programs, which are useful for testing
applications and for analyzing SNMP problems:
•
•
•
TCPIP$SNMP_REQUEST (MIB browser) (Section 4.1)
TCPIP$SNMP_TRPSND (trap sender) (Section 4.2)
TCPIP$SNMP_TRPRCV (trap receiver) (Section 4.2)
These programs can be invoked by commands that are defined by the
SYS$STARTUP:TCPIP$DEFINE_COMMANDS.COM command procedure.
This chapter describes how to use the supplied SNMP utilities.
4.1 Using the MIB Browser
TCP/IP Services provides the snmp_request MIB browser that acts as a simple
client to handle single SNMP requests for reading and writing to a MIB. The
browser sends SNMP Version 1 and SNMP Version 2 request PDUs to an agent
and displays the agent’s response.
To run the MIB browser, follow these steps:
1. Define a foreign command for the program:
$ snmp_request == "$SYS$SYSTEM:TCPIP$SNMP_REQUEST"
Alternatively, you can run the SYS$MANAGER:TCPIP$DEFINE_
COMMANDS.COM procedure to define all the foreign commands available
with TCP/IP Services.
2. Enter the command using the following format.
snmp_request agent "community" request_type [flags] variable [data-type value]
Section 4.1.1 describes the parameters. Section 4.1.2 describes the flags.
4.1.1 MIB Browser Parameters
Table 4–1 describes the snmp_request parameters.
Table 4–1 snmp_request Command Parameters
Parameter
Function
agent
The host name or IP address (in dot notation) of the managed node to
query.
If you specify 0, 0.0.0.0., 127.0.0.1, or ‘‘localhost,’’ the server on the
browser ’s host is queried.
(continued on next page)
Using the SNMP Utilities 4–1
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.1 Using the MIB Browser
Table 4–1 (Cont.) snmp_request Command Parameters
Parameter
Function
"community"
The community string to be used in the query. This parameter is case
sensitive. Typically, agents are configured to permit read access to
the community string "public". For accurate interpretation, be sure to
enclose the name in quotation marks (" "). Note that if you do not use
quotation marks, the name is changed to lowercase.
request-type
PDU type to send. Can be one of the following SNMP requests:
Get
Sends a Get-Request PDU.
GetNext
GetBulk
Sends a GetNext-Request PDU.
Sends a GetBulk-Request PDU (SNMP Version 2
only).
Set
Sends a Set-Request PDU.
variable
An object identifier (OID) in ASN.1 notation that is associated with
an object in a MIB. For example:
$ snmp_request host1 "public" getnext -d 1.3.6.1.6.3.1.1.6
data-type
value
Data type of the value. This parameter can be specified for Set
requests. The data types are described in Section 4.1.3.
The value to which to set the contents of the OID. This parameter is
used for set requests.
For Set requests, you can specify more than one group of the following:
•
•
•
variable-name
data-type
value
For other requests, you can specify more than one variable name, except when
you specify the -l or -t flag; these flags are valid only with a GetNext or GetBulk
request, for which only one OID is permitted.
4.1.2 MIB Browser Flags
Flags are specified in UNIX format.
Because flags and data types are case sensitive, you should always enter them in
the case that is specified. If a letter or value is specified as uppercase, you must
enclose it in quotation marks. In general, if you use uppercase letters where
lowercase is specified, the results are unpredictable. For example, the flag "-v2C"
functions correctly but the flag "-V2c" does not, because the flag character (
v)
must be lowercase.
If you do not specify a flag, or if you specify an invalid flag, a usage message is
displayed. You must place the flags after the request-type parameter.
Table 4–2 describes the flags for the snmp_request command.
4–2 Using the SNMP Utilities
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.1 Using the MIB Browser
Table 4–2 Flags for the snmp_request Command
Flag
Description
-d
Specifies hexadecimal dump mode. Before displaying a return value, displays
a hexadecimal dump of SNMP packets sent and received. For example:
$ snmp_request host1 "public" getnext -d -v 2c 1.3.6.1.6.3.1.1.6
Sent:
30290201 01040670 75626C69 63A11C02
047BE9C1 BD020100 02010030 0E300C06
082B0601 06030101 060500
0).....public...
.{.........0.0..
.+.........
Received:
30820033 02010104 06707562 6C6963A2
2602047B E9C1BD02 01000201 00308200
16308200 12060A2B 06010603 01010601
00020478 D917FC
0..3.....public.
&..{.........0..
.0.....+........
...x...
1.3.6.1.6.3.1.1.6.1.0 = 2027493372
-i max_ignores
Specifies the number of times the MIB browser listens for a reply packet
to a request if it receives an invalid packet (caused by an invalid packet
identifier, version, or SNMP version and command combination). Specify a
positive integer for the value (max_ignores). If you specify a negative value,
it will be converted to an unsigned positive integer. If you specify 0, no
retries are attempted.
If, after an invalid reply packet is received, a valid reply packet is received,
the ignore counter is reset to the value of max_ignores.
If a timeout occurs after an invalid packet is received, the packet is resent,
the resend counter is decremented, and the ignore counter is reset to the
value of max_ignores.
You cannot use the -i flag when you perform a query with the -l or -t flags
to automatically increment the input OID and continue querying a server
after a general SNMP error has occurred, as may happen with a faulty
server. In this case, the query is terminated even though the end of the MIB
selection has not been reached. You must manually increment the input OID
to skip the error and continue with the query.
(continued on next page)
Using the SNMP Utilities 4–3
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.1 Using the MIB Browser
Table 4–2 (Cont.) Flags for the snmp_request Command
Flag
Description
-l
Specifies loop mode. Note that this flag is the letter l, not the number 1.
Valid only if request-type is GetNext or GetBulk (where flag
0, and flag is set to a number greater than 0).
n
is set to
m
Causes the master agent to traverse all the MIBs registered with the master
agent, starting at the first OID after the one specified in the command.
(Note that you can specify only one variable-name [OID].) Responses are
received one at a time, and for each one, the OID returned by the master
agent is used in a subsequent request. Corresponds to the behavior of
standard mibwalk programs.
The MIB browser reads and displays responses, and issues requests until
the master agent has no more data, times out, or you press Ctrl/Y or Ctrl/C.
If specified with the GetBulk request, the -n and -m flags and associated
values are ignored, and the behavior is identical to that of GetNext
.
When the last OID handled by the master agent is reached, you receive a
response similar to the following for a query on OID 1.3.6.1.6.3.1.1.6.1 using
SNMP Version 1:
1.3.6.1.6.3.1.1.6.1.0 = 693056825
- no such name - returned for variable 1
For a query using SNMP Version 2, the example response is:
1.3.6.1.6.3.1.1.6.1.0 = 693056825
1.3.6.1.6.3.1.1.6.1.0 = - end of mib view -
These examples assume that:
•
•
OID 1.3.6.1.6.3.1.1.6.1.0 is the last OID supported on the target host.
The target host is running an SNMP Version 2 agent.
The statement end of mib view refers to OIDs for all MIBs registered with
the master agent.
-m max_repetitions
-n non_repeaters
Specifies the number of repetitions requested for repeating variables.
Applies only to the GetBulk and GetNext requests.
Note that the resulting display can be confusing because the results for the
repeater OIDs are interleaved. That is, the OIDs are displayed in alternate
progression for faster memory throughput. If you specify GetBulk without
specifying both the -m and -n flags, the results are unpredictable.
Specifies the number of variables for which no repetition is requested.
Applies only to the GetBulk request. If you specify GetBulk without
specifying both the -m and -n flags, the results are unpredictable.
-p port
Specifies the port where the request is to be sent. If not specified, the
request is sent to well-known SNMP port 161.
-r max_retries
Specifies the number of times the MIB browser resends a request packet
if it times out before receiving a reply. Specify a positive integer for the
value (max_retries). If you specify a negative value, it will be converted to an
unsigned positive integer. If you specify 0, no retries are tried.
If, after a timeout and a resend, a reply packet is received, the resend
counter is reset. After another timeout, the specified number of max_retries
is sent.
(continued on next page)
4–4 Using the SNMP Utilities
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.1 Using the MIB Browser
Table 4–2 (Cont.) Flags for the snmp_request Command
Flag
Description
-s sleep_interval
Specifies the number of seconds between iterations of sending a request
(for the -r flag) and listening for a reply (for the -i) flag. The default is
1 second. This flag is ignored if neither the -r flag nor the -i flag are
specified.
The -s flag is useful for specifying a time to wait between resends, which
might be necessary when a server agent is starting up.
-t
Specifies tree mode. Valid only if request-type is GetNext or GetBulk
(where flag
n
is set to 0 and flag
m
is set to a number greater than 0).
Similar to the -l flag. Directs the agent to perform a MIB walk for the
subtree with the variable_name as its root. The program reads and prints
responses and issues requests until the agent has no more data for the
specified subtree, times out, or is interrupted by a user.
-v version
-w max_wait
Specifies the SNMP version to use for sending the PDU. The versions are:
2c or
1
(default). Not case sensitive. You can specify the flag without a
space (-v2c and -v1).
If request_type is getbulk, the version defaults to SNMP Version 2.
If you specify -v 2c to send a message to an SNMP Version 1 agent or
subagent, it is unlikely to respond.
Specifies the maximum seconds the snmp_request program waits for a
reply before timing out. Cannot be 0. The default is 3.
The -i
,
-r, and -s flags apply to individual queries. If you specify the -l or -t
flags also, the values for the -i -r, and -s flags are applied to each iteration.
,
4.1.3 MIB Browser Data Types
The snmp_request and snmp_trapsnd commands support the data types listed in
Table 4–3. These values apply to Set requests only.
Table 4–3 Data Types for the snmp_request and snmp_trapsnd Commands
Data Type
Value
Counter
-c
-l
-D
-g
-i
-a
-N
-d
-o
-q
-t
Counter641
Display string
Gauge
Integer
IP address
NULL
Object identifier
Octet
Opaque string
Time ticks
1For support of trap sender program (TCPIP$SNMP_TRAPSND.EXE) only. Properly defined, MIB
variables of type Counter64 are not writable.
Using the SNMP Utilities 4–5
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.1 Using the MIB Browser
Note
Except for -l (Counter64), the data types are case sensitive. To preserve
uppercase for display strings and NULL, enclose the value in double
quotation marks. For example, ‘‘–D’’ or ‘‘–N’’.
On OpenVMS Alpha systems, you must specify the value of the -l data type as a
64-bit integer. For example:
$ snmp_trapsnd 0.0 mynode 6 33 100 -h mynode -v2c -
_$ 1.3.6.1.2.1.1.4.0 "l" 1311768467294899695
On OpenVMS VAX systems, you must specify the value of the -l data type as a
16-digit hexadecimal value. For example:
$ snmp_trapsnd 0.0 mynode 6 33 100 -h mynode -v2c -
_$ 1.3.6.1.2.1.1.4.0 "l" 0x1234567890ABCDEF
Note that alphabetic characters are not case sensitive when used with the -l data
type.
For more information about the data types, see RFCs 1155 and 1902.
4.1.4 Command Examples for snmp_request
This section presents several examples of using the snmp_request utility. In the
following snmp_request command examples:
•
•
•
The valid host name is marley.dec.com.
The "public" community is type Read, address 0.0.0.0.
The "address_list" community is type Read and Write, with write access for
the host on which the snmp_request program is running.
•
The location has been specified as shown in the following command:
TCPIP> SET CONFIGURATION SNMP -
_TCPIP> /LOCATION=(FIRST="Falcon Building",SECOND="Los Angeles, CA")
•
The command responses have been edited for readability.
Examples
1. The following example shows how to retrieve the value of the MIB II variable
sysDescr.0 (1.3.6.1.2.1.1.1.0). The request is successful because the OID
(
variable_name) provided in the command line exists and is readable. This
OID is returned by the subagent code that resides in the master agent.
$ snmp_request marley.dec.com "public" get 1.3.6.1.2.1.1.1.0
1.3.6.1.2.1.1.1.0 = marley.dec.com AlphaServer 2100 4/200 OpenVMS
V7.1 Digital TCP/IP Services for OpenVMS
2. The following example shows how to retrieve two MIB II variables. This
example is identical to the previous example, except that two OID values are
input and two returned: instance 1 of ifDescr and hrSystemUptime. Note
that the first value comes from the MIB II subagent (TCPIP$OS_MIBS) and
the second comes from the Host Resources MIB subagent (TCPIP$HR_MIB).
4–6 Using the SNMP Utilities
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.1 Using the MIB Browser
$ snmp_request marley.dec.com "public" get 1.3.6.1.2.1.2.2.1.2.1 -
_$ 1.3.6.1.2.1.25.1.1.0
1.3.6.1.2.1.2.2.1.2.1 = LO IP Interface: LO0, OpenVMS Adapter: <none>,
Loopback Port
1.3.6.1.2.1.25.1.1.0 = 6024942 = 0 d 16:44:9
3. The following example shows how to retrieve the next MIB II variable. This
is similar to the command in example 1, except that a GetNext request is
issued and sysObjectID.0 (1.3.6.1.2.1.1.2.0) is returned.
$ snmp_request marley.dec.com "public" getnext 1.3.6.1.2.1.1.1.0
1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1
4. The following example shows how to use the SNMP Version 2 GetBulk
request to retrieve the MIB II variables sysUpTime.0 (1.3.6.1.2.1.1.1.0) and
sysDescr.0 (1.3.6.1.2.1.1.2.0), and for the first three interfaces, the values of
ifDescr (OIDs with the prefix 1.3.6.1.2.1.2.2.1.2) and ifType (OIDs with the
prefix 1.3.6.1.2.1.2.2.1.3).
$ snmp_request marley.dec.com "public" getbulk -n 2 -m 3 -
_$ 1.3.6.1.2.1.1.1 1.3.6.1.2.1.1.2 -
_$ 1.3.6.1.2.1.2.2.1.1 1.3.6.1.2.1.2.2.1.2 1.3.6.1.2.1.2.2.1.3
Warning: using version SNMPv2 for getbulk command.
1.3.6.1.2.1.1.1.0 = marley.dec.com AlphaStation 255/300
OpenVMS V7.1 Digital TCP/IP Services for OpenVMS
1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1
1.3.6.1.2.1.2.2.1.1.1 = 1
1.3.6.1.2.1.2.2.1.2.1 = LO IP Interface: LO0, OpenVMS Adapter: <none>,
Loopback Port
1.3.6.1.2.1.2.2.1.3.1 = 24
1.3.6.1.2.1.2.2.1.1.3 = 3
1.3.6.1.2.1.2.2.1.2.3 = WE IP Interface: WE0, OpenVMS Adapter: EWA0:,
PCI bus Ethernet Adapter
1.3.6.1.2.1.2.2.1.3.3 = 6
1.3.6.1.2.1.2.2.1.1.4 = 4
1.3.6.1.2.1.2.2.1.2.4 = WF IP Interface: WF0, OpenVMS Adapter: FWA0:,
DEFPA PCI bus FDDI Adapter
1.3.6.1.2.1.2.2.1.3.4 = 15
5. The following example shows how to use the GetNext request with the -l
(loop) flag to retrieve all OIDs starting at the first instance after the OID
input and finishing at the end of the MIB view. Note that if an SNMP
Version 2 agent is the server, the results using getbulk are identical (in
general, SNMP Version 1 agents do not support getbulk requests).
$ snmp_request marley.dec.com "public" getnext -l 1.3.6.1.2.1.1.1.0
1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1
1.3.6.1.2.1.1.3.0 = 1280260 = 0 d 3:33:22
1.3.6.1.2.1.1.4.0 = Sam Spade
1.3.6.1.2.1.1.5.0 = marley.dec.com
1.3.6.1.2.1.1.6.0 = Falcon BuildingLos Angeles, CA
1.3.6.1.2.1.1.7.0 = 72
1.3.6.1.2.1.1.8.0 = 0 = 0 d 0:0:0
.
.
.
1.3.6.1.2.1.25.5.1.1.2.294 = 560
1.3.6.1.2.1.25.5.1.1.2.295 = 472
1.3.6.1.6.3.1.1.6.1.0 = 1296505215
- no such name - returned for variable 1
Using the SNMP Utilities 4–7
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.1 Using the MIB Browser
6. The following example uses the same command as in example 5, but it
specifies the -t flag instead of the -l flag. Only OIDs with the prefix
matching the input OID are returned. Note that as with other getnext
request examples, the value for the input OID is not returned. If an SNMP
Version 2 agent is the server, the results using getbulk are identical.
$ snmp_request marley.dec.com "public" getnext -t 1.3.6.1.2.1.1
1.3.6.1.2.1.1.2.0 = 1.3.6.1.4.1.36.2.15.13.7.1
1.3.6.1.2.1.1.3.0 = 1302232 = 0 d 3:37:2
1.3.6.1.2.1.1.4.0 = Sam Spade
1.3.6.1.2.1.1.5.0 = marley.dec.com
1.3.6.1.2.1.1.6.0 = Falcon BuildingLos Angeles, CA
1.3.6.1.2.1.1.7.0 = 72
1.3.6.1.2.1.1.8.0 = 0 = 0 d 0:0:0
1.3.6.1.2.1.1.9.1.2.1 = 1.3.6.1.4.1.36.15.3.3.1.1
1.3.6.1.2.1.1.9.1.2.2 = 1.3.6.1.4.1.36.15.3.3.1.2
1.3.6.1.2.1.1.9.1.3.1 = Base o/s agent (OS_MIBS) capabilities
1.3.6.1.2.1.1.9.1.3.2 = Base o/s agent (HR_MIB) capabilities
1.3.6.1.2.1.1.9.1.4.1 = 0 = 0 d 0:0:0
1.3.6.1.2.1.1.9.1.4.2 = 0 = 0 d 0:0:0
7. The following example shows how to send a Set request. The request succeeds
because the command line specifies the correct type for the variable, and all
the conditions for enabling Set requests are met on the server.
$ snmp_request marley.dec.com "address_list" -
_$ set 1.3.6.1.2.1.1.4.0 "D" "Richard Blaine"
1.3.6.1.2.1.1.4.0 = Richard Blaine
8. The following example shows how to display the contents of packets that
are sent and received. Note that only the SNMP-specific portion of the UDP
packets is displayed.
$ snmp_request marley.dec.com "public" get -d 1.3.6.1.2.1.1.4.0
Sent:
3082002D 02010004 06707562 6C6963A0
2002047B E9C1BD02 01000201 00308200
10308200 0C06082B 06010201 01040005
00
0..-.....public.
..{.........0..
.0.....+........
.
Received:
3082003B 02010004 06707562 6C6963A2
2E02047B E9C1BD02 01000201 00308200
1E308200 1A06082B 06010201 01040004
0E526963 68617264 20426C61 696E65
1.3.6.1.2.1.1.4.0 = Richard Blaine
0..;.....public.
...{.........0..
.0.....+........
.Richard Blaine
4.2 Using the Trap Sender and Trap Receiver Programs
TCP/IP Services provides the following programs that allow you to set up a
simple client on your system to send and receive trap messages:
•
snmp_trapsnd (TCPIP$SNMP_TRAPSND.EXE)
Sends SNMP Version 1 and SNMP Version 2 trap messages. Use only for
testing or to send significant state changes that occur on the managed node.
•
snmp_traprcv (TCPIP$SNMP_TRAPRCV.EXE)
Listens for SNMP trap messages and displays any it receives.
4–8 Using the SNMP Utilities
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.2 Using the Trap Sender and Trap Receiver Programs
By default, these programs use UDP port 162. However, you can specify another
port with the -p flag or set up an SNMP-trap service that specifies the port you
want to use. Note, however, that the use of UDP port 162 is coded into standard
MIBs.
Both programs support the use of the UDP (default) and TCP transports.
However, the standard TCP/IP subagents and the Chess example use UDP
only. Therefore, if you specify the -tcp flag when you enter the snmp_traprcv
command, the program uses TCP to process traps only from the trap sender
program or from a user application written to use TCP.
The following sections explain how to enter commands for both programs.
Because flags and data types are case sensitive, you should always enter them in
the case that is specified. If a letter or value is specified as uppercase, you must
enclose it in quotation marks. In general, if you use uppercase letters where
lowercase is specified, the results are unpredictable. For example, flag "-v2C"
functions correctly but flag "-V2c" does not, because the flag character (v) must
be lowercase.
4.2.1 Entering Commands for the Trap Sender Program
The trap sender program lets you send SNMP Version 1 and SNMP Version 2
trap messages. You should use this program only when you want to test the
client or when significant state changes occur on the managed node.
The trap sender program encodes an SNMP Version 1 trap PDU (see RFCs 1155,
1156, 1157, and 1215) or an SNMP Version 2 trap PDU (see RFCs 1905 and 1908)
into an SNMP message and sends it to the specified hosts. You use parameters
and flags to specify the data fields in the trap PDU.
Traps are uniquely identified in the PDU:
•
•
SNMP Version 1 is identified by a combination of parameters.
SNMP Version 2 is identified by the value of snmpTrapOID
.
To run the trap sender program, do the following:
1. Define a foreign command for the program:
$ snmp_trapsnd == "$SYS$SYSTEM:TCPIP$SNMP_TRAPSND"
Alternatively, you can run the SYS$MANAGER:TCPIP$DEFINE_
COMMANDS.COM procedure to define all the foreign commands available
with TCP/IP Services.
2. Enter a command using the following format:
snmp_trapsnd enterprise agent generic-trap specific-trap timeticks
[-v version] [-c community] [-d] [-h host] [-p port] [-tcp]
[variable_name [data-type value]]
4.2.1.1 Trap Sender Parameters
Table 4–4 describes the snmp_trapsnd parameters. Each parameter is required,
but you can specify zero, as appropriate.
Using the SNMP Utilities 4–9
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.2 Using the Trap Sender and Trap Receiver Programs
Table 4–4 Parameters for the snmp_trapsnd Command
Parameter
Description
enterprise
For SNMP Version 1, specifies the enterprise object identifier (OID) on whose
behalf the trap is being sent. For example, 1.3.6.1.4.1.1. If you specify 0 or 0.0,
the null OID (0.0) is sent. Make sure that any OID you specify conforms to the
OID rules.
For SNMP Version 2, when specified with the -v2c flag, represents the value of
snmpTrapOID.0
.
agent
For SNMP Version 1 traps. Specifies the host name or IP address of the entity on
whose behalf the trap is being generated. You can specify the name local, which
is the same as specifying 0, 0.0, 0.0.0, or 0.0.0.0. In these cases, the address
0.0.0.0 is sent as the agent address in the SNMP Version 1 trap PDU.
If the -v2c flag is specified, this parameter is ignored.
generic-trap
For SNMP Version 1, specifies the generic trap identifier in the form of a number.
Must be one of the following values:
SNMP Version 1
Value
Object
0
1
2
3
4
5
6
coldStart
warmStart
linkDown
linkUp
authenticationFailure
egpNeighborLoss
enterpriseSpecific
For SNMP Version 2, when the -v2c flag is specified, this parameter must
contain a valid OID or 0 as the value of snmpTrapOID
.
specific-trap
timeticks
For SNMP Version 1, specifies the enterprise-specific trap number. A numeric
value greater than 0 must be present but is ignored if the -v2c flag is present or
if generic-trap is a value other than 6 (enterpriseSpecific).
Specifies the timestamp value associated with the generation of the trap
message. The timestamp value is the current time in units of TIMETICKS
(1/100 of a second) since the sending SNMP entity started. A value of 0 causes
snmp_trapsnd to send the time in hundredths of a second since the operating
system was last booted.
variable_name |
Specifies a list of MIB variables to be included in the trap message. For a list of
supported values, including a value for the Counter64 data type, see Table 4–3.
data-type value
4.2.1.2 Trap Sender Flags
Table 4–5 describes the snmp_trapsnd flags.
Table 4–5 Flags for the snmp_trapsnd Command
Flag
Description
-c community
Specifies a community string to be used when sending the trap. The default is
public.
-d
Displays a hexadecimal dump of the encoded packet.
(continued on next page)
4–10 Using the SNMP Utilities
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.2 Using the Trap Sender and Trap Receiver Programs
Table 4–5 (Cont.) Flags for the snmp_trapsnd Command
Flag
Description
-h host
Specifies the host name or IP address (in ASN.1 dot notation format) of the
destination host to receive the trap message. The default is localhost
(127.0.0.1).
-p port
Specifies a port number on the destination host where the message is to be sent.
The default is UDP 162.
-tcp
Specifies that the TCP transport be used instead of the default UDP transport.
If a connection cannot be established, the program displays the warning
connect - : connection refused
Specifies the SNMP version to use for sending the PDU. The valid versions are 2c
or (default). You can specify the flag and value without including a space (for
example, -v2c and -v1).
.
-v version
1
4.2.1.3 Trap Sender Examples
In the following snmp_trapsnd command examples:
•
•
The first line is the snmp_trapsnd command.
The remainder is the display received when running the trap receiver
program (snmp_traprcv) without flags included.
1. The following example generates a trap that originated on the localhost
(specified by the agent parameter) using the default SNMP version (SNMP
Version 1). The -h host parameter is not specified, so the trap will be sent to
the local host.
$ snmp_trapsnd 0.0 local 0 0 0
Message received from 127.0.0.1
SNMPv1-Trap-PDU:
community - 7075626C 6963
public
enterprise - 0.0
agent address - 0.0.0.0
trap type - Cold Start (0)
timeticks - 51938978
2. The following example generates the same trap as in example 1, except that
it specifies the use of SNMP Version 2.
$ snmp_trapsnd 0.0 local 0 0 0 "-v2c"
Message received from 127.0.0.1
SNMPv2-Trap-PDU:
community - 7075626C 6963
public
sysUpTime.0 - 51938968 = 6 d 0:16:29
snmpTrapOID.0 - 0.0
3. The following example sends values to the node mynode with the community
name special
.
$ snmp_trapsnd 1.2.3 marley.dec.com 6 33 100 -c special -h mynode
Message received from 16.20.208.68
SNMPv1-Trap-PDU:
community - 73706563 69616c
special
Using the SNMP Utilities 4–11
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.2 Using the Trap Sender and Trap Receiver Programs
enterprise - 1.2.3
agent address - 6.20.208.53
trap type - Enterprise-specific (6)
enterprise-specific value - (33)
timeticks - 100
4.2.2 Entering Commands for the Trap Receiver Program
The trap receiver program lets you listen for, receive, and display SNMP trap
messages. Until interrupted, the program continues to listen on the specified
port.
If you enter commands using the default port number or another privileged port
number, you must run the program from a privileged account.
To run the trap receiver program, do the following:
1. Define a foreign command for the program:
$ snmp_traprcv == "$SYS$SYSTEM:TCPIP$SNMP_TRAPRCV"
Alternatively, you can run SYS$MANAGER:TCPIP$DEFINE_
COMMANDS.COM to define all the foreign commands available with TCP/IP
Services.
2. Enter a command using the following format:
snmp_traprcv [-d] [-tcp] [-p port]
4.2.2.1 Trap Receiver Flags
Table 4–6 describes the snmp_traprcv flags.
Table 4–6 snmp_traprcv Command Flags
Flag
Description
-d
Displays a hexadecimal and formatted dump of the received packet.
-p port
Specifies the port number on the local host on which to listen for trap
messages. The default is 162.
-tcp
Listens on the TCP port instead of the UDP (default) port. Reads only
a single PDU on an established connection, which is similar to the
behavior using UDP.
4.2.2.2 Setting Up an SNMP Trap Service
To set up an SNMP trap service for use with the trap receiver program, enter a
management command in the following format:
SET SERVICE SNMP-TRAP /PROTOCOL=UDP /USER_NAME=TCPIP$SNMP
/PROCESS_NAME=TCPIP$SNMP-TRAP /FILE=TCPIP$SYSTEM:TCPIP$SNMP-TRAP.COM
In this command, port 170 is used as an alternative for port 162, and traps that
are received on port 162 are ignored.
If you omit the /PROTOCOL qualifier or you use /PROTOCOL=TCP, the service
uses the TCP transport. In this case, when you enter a command to run the trap
receiver program, you must include the -tcp flag.
With the SNMP trap service in place, the trap receiver program queries the
service for the port number instead of using the default port 162. If you specify
a privileged port number (less than 1024) with the /PORT qualifier, make sure
you install the trap receiver program with privileges, or run the program from an
4–12 Using the SNMP Utilities
Download from Www.Somanuals.com. All Manuals Search And Download.
Using the SNMP Utilities
4.2 Using the Trap Sender and Trap Receiver Programs
account that has SYSPRV privilege. Note that the port number must be greater
than zero.
4.2.2.3 Trap Receiver Examples
1. The following example requests trap information on a system that does not
have traps configured and does not have SYSPRV privilege or sufficient
privilege.
$ snmp_traprcv
No snmp-trap service entry, using default port 162.
bind - : permission denied
2. The example, supplied from a nonprivileged account, requests trap
information in hexadecimal dump format on port 1026.
$ snmp_traprcv -d -p 1026
Message received from 127.0.0.1
3082002A 02010004 06707562 6C6963A4
1D060547 81AD4D01 40040000 00000201
00020100 4304032D AED23082 0000
SNMPv1-Trap-PDU:
0..*.....public.
...G..M.@.......
....C..-..0...
community - 7075626C 6963
public
enterprise - 0.0
agent address - 0.0.0.0
trap type - Cold Start (0)
timeticks - 53325522
Using the SNMP Utilities 4–13
Download from Www.Somanuals.com. All Manuals Search And Download.
Download from Www.Somanuals.com. All Manuals Search And Download.
5
eSNMP API Routines
This chapter provides reference information about the following types of
application programming interface (API) routines in the eSNMP developer ’s kit:
•
•
•
Interface routines (Section 5.1)
Method routines (Section 5.2)
Support routines (Section 5.3)
5.1 Interface Routines
The interface routines are for developers writing the portion of the application
programming interface (API) that handles the connection between the agent and
the subagent. The interface routines are listed Table 5–1 and described in the
following pages.
Table 5–1 Interface Routines
Routine
Function
esnmp_init
Initializes the subagent and initiates communication with
the master agent.
esnmp_register
Requests local registration of a MIB subtree.
Cancels local registration of a MIB subtree.
Requests cluster registration of a MIB subtree.
Cancels cluster registration of a MIB subtree.
Adds a subagent’s capabilities to the master agent’s
esnmp_unregister
esnmp_register2
esnmp_unregister2
esnmp_capabilities
sysORTable
Removes a subagent’s capabilities from the master agent’s
sysORTable
.
esnmp_uncapabilities
.
esnmp_poll
Processes a pending request from the master agent.
esnmp_are_you_there
Requests a report from the master agent to indicate it is up
and running.
esnmp_trap
Sends a trap message to the master agent.
esnmp_term
Sends a close message to the master agent.
Converts UNIX system time into a value with the same
esnmp_sysuptime
time base as sysUpTime
.
eSNMP API Routines 5–1
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_init
esnmp_init
Initializes the Extensible SNMP (eSNMP) subagent and initiates communication
with the master agent.
Format
int esnmp_init (int *socket,
char *subagent_identifier ) ;
Arguments
socket
The address of the integer that receives the socket descriptor used by eSNMP.
subagent_identifier
The address of a null-terminated string that uniquely identifies this subagent
(usually a program name).
Description
Call this routine during program initialization or to restart the eSNMP protocol.
If you are restarting, the esnmp_init routine clears all registrations so each
subtree must be registered again.
You should attempt to create a unique subagent identifier, perhaps using the
program name argv[0] and additional descriptive text. The master agent does
not open communications with a subagent whose subagent identifier is already in
use.
This routine does not block waiting for a response from the master agent. After
calling the esnmp_init routine, call the esnmp_register routine for each subtree
that is to be handled by the subagent.
Return Values
ESNMP_LIB_NO_
CONNECTION
Could not initialize or communicate with the
master agent. Try again after a delay.
ESNMP_LIB_OK
The esnmp_init routine has completed
successfully.
ESNMP_LIB_NOTOK
Could not allocate memory for the subagent.
Example
#include <esnmp_h>
int socket;
status = esnmp_init(&socket, "gated");
5–2 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_register
esnmp_register
Requests local registration of a single MIB subtree. This indicates to the master
agent that the subagent instantiates MIB variables within the registered MIB
subtree.
Format
int esnmp_register ( subtree *subtree,
int timeout,
int priority ) ;
Arguments
subtree
A pointer to a subtree structure corresponding to the subtree to be handled.
The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H)
externally declare and initialize the subtree structures. Refer to Chapter 3 for
more information about these files.
Note
All memory pointed to by the subtree fields must have permanent storage
since it is referenced by libesnmp for the duration of the program. You
should use the data declarations emitted by the MIBCOMP program.
timeout
The number of seconds the master agent should wait for responses when
requesting data in this subtree. This value must be between 0 (zero) and
300. If the value is 0, the default timeout is 3 seconds. Compaq recommends
that you use the default. For information about modifying the default subagent
timeout value, refer to Section 6.2.
priority
The registration priority. The priority argument allows you to coordinate
cooperating subagents to handle different configurations. The range is 1 to
255.
The entry with the largest number has the highest priority. The subagent that
registers a subtree with the highest priority over a range of object identifiers gets
all requests for that range of OIDs
.
Subtrees registered with the same priority are considered duplicate, and the
registration is rejected by the master agent.
Description
Call the initialization routine esnmp_init prior to calling the esnmp_register
.
Call the esnmp_register function for each subtree structure corresponding to
each subtree to be handled. At any time, subtrees can be unregistered by calling
esnmp_unregister and then be reregistered by calling the esnmp_register
.
When restarting the eSNMP protocol by calling esnmp_init, all registrations are
cleared. All subtrees must be reregistered.
eSNMP API Routines 5–3
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_register
A subtree is identified by the base MIB name and the corresponding OID number
of the node that is the parent of all MIB variables contained in the subtree. For
example: The MIB II tcp subtree has an OID of 1.3.6.1.2.1.6. All elements
subordinate to this have the same first seven digits and are included in the
subtree’s object table. The subtree can also be a single MIB object (a leaf node) or
even a specific instance.
By registering a subtree, the subagent indicates that it will process eSNMP
requests for all MIB variables (or OIDs) within that subtree’s range. Therefore,
a subagent should register the most fully qualified (longest) subtree that still
contains its instrumented MIB variables.
The master agent does not permit a subagent to register the same subtree more
than once. However, subagents can register subtrees with ranges that overlap
the OID ranges of subtrees previously registered, and subagents can also register
subtrees registered by other subagents.
For example, TCP/IP Services supports MIB II. In the eSNMP environment, the
os_mibs subagent registers the MIB II subtree ip (OID 1.3.6.1.2.1.4).
TCP/IP Services also provides the gated subagent, which registers the
ipRouteEntry MIB subtree (OID 1.3.6.1.2.1.4.21.1).
These MIBs are registered at priority 1. Any subagent that registers at a higher
priority (greater than 1) overrides these registrations.
A request for IpRouteIfIndex (OID 1.3.5.1.2.1.4.21.1.2) is passed to the gated
subagent. Requests for other ip variables, such as ipNetToMediaIfIndex (OID
1.3.5.1.2.1.4.22.1.1) are passed to the os_mibs subagent. If the gated subagent
terminates or unregisters the ipRouteEntry subtree, subsequent requests for
ipRouteIfIndex will go to the os_mibs subagent. This occurs because the ip
subtree, which includes all ipRouteEntry variables, is now the authoritative
region of requests for ipRouteIfIndex
.
Return Values
SNMP_LIB_OK
The esnmp_register routine has completed
successfully.
ESNMP_LIB_BAD_REG
The esnmp_init routine has not been called, the
timeout parameter is invalid, or the subtree has
already been queued for registration.
ESNMP_LIB_LOST_
CONNECTION
The subagent has lost communications with the
master agent.
Note that the return value indicates only the initiation of the request. The actual status returned
in the master agent’s response will be returned in a subsequent call to the esnmp_poll routine in
the state field.
Example
#include <esnmp.h>
#define RESPONSE_TIMEOUT
0
/* use the default time set
in OPEN message */
#define REGISTRATION_PRIORITY 10 /* priority at which subtrees
will register */
int status;
extern SUBTREE ipRouteEntry_subtree;
5–4 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_register
status = esnmp_register( &ipRouteEntry_subtree,
RESPONSE_TIMEOUT,
REGISTRATION_PRIORITY );
if (status != ESNMP_LIB_OK) {
printf ("Could not queue the ’ipRouteEntry’ \n");
printf ("subtree for registration\n");
}
eSNMP API Routines 5–5
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_unregister
esnmp_unregister
Cancels registration of a MIB subtree previously registered with the master
agent.
Format
int esnmp_unregister ( SUBTREE *subtree ) ;
Arguments
subtree
A pointer to a subtree structure corresponding to the subtree to be handled.
The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H)
externally declare and initialize the subtree structures. Refer to Chapter 3 for
more information about these files.
Description
This routine can be called by the application code to tell the eSNMP subagent
not to process requests for variables in this MIB subtree anymore. You can later
reregister a MIB subtree, if needed, by calling the esnmp_register routine.
Return Values
SNMP_LIB_OK
The esnmp_unregister routine has completed
successfully.
ESNMP_LIB_BAD_REG
The MIB subtree was not registered.
ESNMP_LIB_LOST_
CONNECTION
The request to unregister the MIB subtree could
not be sent. You should restart the protocol.
Example
#include <esnmp.h>
int status
extern SUBTREE ipRouteEntry_subtree;
status = esnmp_unregister (&ipRouteEntry_subtree);
switch (status) {
case ESNMP_LIB_OK:
printf ("The esnmp_unregister routine completed successfully.\n");
break;
case ESNMP_LIB_BAD_REG:
printf ("The MIB subtree was not registered.\n");
case ESNMP_LIB_LOST_CONNECTION:
printf ("%s%s%s\n", "The request to unregister the ",
"MIB subtree could not be sent. ",
"You should restart the protocol.\n");
break;
}
5–6 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_register2
esnmp_register2
Requests registration of a single MIB subtree. This indicates to the master agent
that the subagent instantiates MIB variables within the registered MIB subtree.
The esnmp_register2 routine offers extensions to the esnmp_register routine.
Format
int esnmp_register2 ( ESNMP_REG *reg ) ;
Arguments
reg
A pointer to an ESNMP_REG structure that contains the following fields:
Field Name
Description
subtree
A pointer to a subtree structure corresponding to the
MIB subtree to be handled. The subtree structures
are externally declared and initialized in the code
emitted by the MIBCOMP command (subtree_TBL.C
and subtree_TBL.H, where subtree is the name of the
MIB subtree). This code is taken directly from the MIB
document.
All memory pointed to by this field must have
permanent storage since it is referenced by libesnmp
for the duration of the program. You should use the
data declarations emitted by the MIBCOMP command.
priority
The registration priority. The entry with the largest
number has the highest priority. The range is 1 to 255.
The subagent that has registered a MIB subtree with
the highest priority over a range of object identifiers
gets all requests for that range of OIDs.
MIB subtrees that are registered with the same
priority are considered duplicates, and the registration
is rejected by the master agent.
The priority field is a mechanism for cooperating
subagents to handle different configurations.
timeout
The number of seconds the master agent should wait
for responses when requesting data in this MIB
subtree. This value must be between zero and 300.
If the value is zero, the default timeout (3 seconds)
is used. You should use the default. For information
about modifying the default timeout value, refer to
Section 6.2.
range_subid
An integer value that, when nonzero, together with
the range_upper_bound field specifies a range instead
of one of the MIB subtree’s OID subidentifiers. The
range_subid field specifies the OID subidentifier
modified by the range_upper_bound field.
eSNMP API Routines 5–7
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_register2
Field Name
Description
range_upper_bound
An integer value that, with a nonzero range_subid
field, specifies a range instead of one of the MIB
subtree’s OID subidentifiers. The range_upper_bound
field provides the upper bound of the range and the
range_subid field provides the lower bound of the
range, which is the MIB subtree’s OID subidentifier.
options
state
An integer value that, when set to
ESNMP_REG_OPT_CLUSTER, indicates that the
registration is valid clusterwide. When the value is set
to zero, it indicates that the registration is valid for the
local node.
One of the following integer values that provides
the caller with asynchronous updates of the state of
registration of this MIB subtree. After the return of
the esnmp_poll routine, the caller can inspect this
parameter.
ESNMP_REG_STATE_
PENDING
The registration is
currently held locally
while waiting for
connection to the
master agent.
ESNMP_REG_STATE_SENT
The registration was
sent to the master
agent.
ESNMP_REG_STATE_DONE The registration
was successfully
acknowledged by
the master agent.
ESNMP_REG_STATE_
REGDUP
The registration was
rejected by the master
agent because it was a
duplicate.
ESNMP_REG_STATE_
REGNOCLU
The master agent does
not support cluster
registrations.
ESNMP_REG_STATE_REJ
The master agent
rejected the
registration for other
reasons.
reserved
This field is reserved for exclusive use by the eSNMP
library. The caller should not modify it.
Description
The initialization routine (esnmp_init) must be called prior to calling the
esnmp_register2 routine. The esnmp_register2 function must be called for each
subtree structure corresponding to each MIB subtree that it will be handling. At
any time, MIB subtrees can be unregistered by calling esnmp_unregister2 and
then can be reregistered by calling esnmp_register2
.
5–8 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_register2
When restarting the eSNMP protocol by calling esnmp_init, all MIB subtree
registrations are cleared. All MIB subtrees must be reregistered.
A MIB subtree is identified by the base MIB variable name and its corresponding
OID. This tuple represents the parent of all MIB variables that are contained in
the MIB subtree; for example, the MIB II tcp subtree has an OID of 1.3.6.1.2.1.6.
All elements subordinate to this (those that have the same first 7 identifiers) are
included in the subtree’s object table. A MIB subtree can also be a single MIB
object (a leaf node) or even a specific instance.
By registering a MIB subtree, the subagent indicates that it will process SNMP
requests for all MIB variables (or OIDs) within that MIB subtree’s region.
Therefore, a subagent should register the most fully qualified (longest) MIB
subtree that still contains its instrumented MIB variables.
A subagent using the esnmp_register2 routine can register the same MIB
subtree for the local node and for a cluster. To register the MIB subtree
for both, you must call the esnmp_register2 routine twice: once with the
ESNMP_REG_OPT_CLUSTER bit set in the options field and once with the
ESNMP_REG_OPT_CLUSTER bit clear in the options field. Alternatively, you
can register a MIB subtree for the cluster only or for the local node only, by
setting or clearing the ESNMP_REG_OPT_CLUSTER bit, respectively, in the
options field.
A subagent can also register MIB subtrees that overlap the OID range of
MIB subtrees that it previously registered or the OID ranges of MIB subtrees
registered by other subagents.
For example, consider the two subagents os_mibs and gated. The os_mibs
subagent registers the ip MIB subtree (1.3.6.1.2.1.4), and the gated subagent
registers the ipRouteEntry MIB subtree (1.3.6.1.2.1.4.21.1). Both of these
registrations are made with the ESNMP_REG_OPT_CLUSTER bit set in the
options field. Requests for ip MIB variables within ipRouteEntry, such as
ipRouteIfIndex (1.3.6.1.2.1.4.21.1.2), are passed to the gated subagent. Requests
for other ip variables, such as ipNetToMediaIfIndex (1.3.6.1.2.1.4.22.1.1), are
passed to the os_mibs subagent. If the gated subagent terminates or unregisters
the ipRouteEntry MIB subtree, subsequent requests for ipRouteIfIndex go to
the os_mibs subagent. This occurs because the ip MIB subtree, which includes
all ipRouteEntry MIB variables, is now the authoritative region of requests for
ipRouteIfIndex
.
Return Values
SNMP_LIB_OK
The esnmp_register2 routine has completed
successfully.
ESNMP_LIB_BAD_REG
The esnmp_init routine has not been called, the
timeout parameter is invalid, a registration slot
is not available, or this MIB subtree has already
been queued for registration. A message is also
in the log file.
ESNMP_LIB_LOST_
CONNECTION
The subagent lost communication with the
master agent.
Note that the return value indicates only the initiation of the request. The actual
status returned in the master agent’s response will be returned in a subsequent
call to the esnmp_poll routine in the state field.
eSNMP API Routines 5–9
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_register2
Example
#include <esnmp.h>
#define RESPONSE_TIMEOUT
#define REGISTRATION_PRIORITY
#define RANGE_SUBID
0
/* use the default time set
in esnmp_init message */
/* priority at which the MIB
subtree will register */
/* the identifier position in
oid->elements just after mib-2 */
/* the identifier for egp,
under mib-2 */
10
7
#define RANGE_UPPER_BOUND
8
int status
extern SUBTREE ip_subtree;
static ESNMP_REG esnmp_reg_for_ip2egp; /* retain this structure for
a subsequent call to
esnmp_unregister2 */
/*
*
initialize the ESNMP_REG structure
*/
memset(&esnmp_reg_for_ip2egp, 0, sizeof(ESNMP_REG));
esnmp_reg_for_ip2egp.subtree
esnmp_reg_for_ip2egp.priority
esnmp_reg_for_ip2egp.timeout
esnmp_reg_for_ip2egp.range_subid
= &ip_subtree;
= REGISTRATION_PRIORITY;
= RESPONSE_TIMEOUT;
= RANGE_SUBID;
esnmp_reg_for_ip2egp.range_upper_bound = RANGE_UPPER_BOUND;
status = esnmp_register2( &esnmp_reg_for_ip2egp );
if (status != ESNMP_LIB_OK) {
printf("Could not queue the ’ipRouteEntry’ \n");
printf("subtree for registration\n");
}
5–10 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_unregister2
esnmp_unregister2
Cancels registration of a MIB subtree previously established with the master
agent. Use this routine only when the MIB subtree was registered using the
esnmp_register2 routine.
Format
int esnmp_unregister2 ( ESNMP_REG *reg ) ;
Arguments
reg
A pointer to the ESNMP_REG structure that was used when the
esnmp_register2 routine was called.
Description
This routine can be called by the application code to tell the eSNMP subagent
to no longer process requests for variables in this MIB subtree. You can later
reregister a MIB subtree, if needed, by calling the esnmp_register2 routine.
Return Values
ESNMP_LIB_OK
The routine completed successfully.
The MIB subtree was not registered.
ESNMP_LIB_BAD_REG
ESNMP_LIB_LOST_
CONNECTION
The request to unregister the MIB subtree could
not be sent. You should restart the protocol.
Example
#include <esnmp.h>
int status
extern ESNMP_REG esnmp_reg_for_ip2egp;
status = esnmp_unregister2( &esnmp_reg_for_ip2egp );
switch(status) {
case ESNMP_LIB_OK:
printf("The esnmp_unregister2 routine completed successfully.\n");
break;
case ESNMP_LIB_BAD_REG:
printf("The MIB subtree was not registered.\n");
break;
case ESNMP_LIB_LOST_CONNECTION:
printf("%s%s%s\n", "The request to unregister the ",
"MIB subtree could not be sent. ",
"You should restart the protocol.\n");
break;
}
eSNMP API Routines 5–11
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_capabilities
esnmp_capabilities
Adds a subagent’s capabilities to the master agent’s sysORTable. The sysORTable
is a conceptual table that contains an agent’s object resources, and is described in
RFC 1907.
Format
void esnmp_capabilities ( OID *agent_cap_id,
char *agent_cap_descr ) ;
Arguments
agent_cap_id
A pointer to an object identifier that represents an authoritative agent capabilities
identifier. This value is used for the sysORID object in the sysORTable for the
managed node.
agent_cap_descr
A pointer to a null-terminated character string describing agent_cap_id. This
value is used for the sysORDescr object in the sysORTable for the managed node.
Description
This routine is called at any point after initializing eSNMP by a call to the
esnmp_init routine.
5–12 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_uncapabilities
esnmp_uncapabilities
Removes a subagent’s capabilities from the master agent’s sysORTable
.
Format
void esnmp_uncapabilities ( OID *agent_cap_id ) ;
Arguments
agent_cap_id
A pointer to an object identifier that represents an authoritative agent capabilities
identifier. This value is used for the sysORID object in the sysORTable for the
managed node.
Description
This routine is called if a subagent alters its capabilities dynamically. When
a logical connection for a subagent is closed, the master agent automatically
removes the related entries in sysORTable
.
eSNMP API Routines 5–13
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_poll
esnmp_poll
Processes a pending message that was sent by the master agent.
Format
int esnmp_poll ( )
Description
This routine is called after the select( ) call has indicated data is ready on
the eSNMP socket. (This socket was returned from the call to the esnmp_init
routine.)
If a received message indicates a problem, an entry is made to the SNMP log file
and an error status is returned.
If the received message is a request for SNMP data, the object table is checked
and the appropriate method routines are called, as defined by the developer of the
subagent.
Return Values
ESNMP_LIB_OK
The esnmp_poll routine completed successfully.
ESNMP_LIB_BAD_REG
The master agent failed in a previous
registration attempt. See the log file.
ESNMP_LIB_DUPLICATE
A duplicate subagent identifier has already been
received by the master agent.
ESNMP_LIB_NO_
CONNECTION
The master agent’s OPEN request failed. Restart
the connection after a delay. See the log file.
ESNMP_LIB_CLOSE
ESNMP_LIB_NOTOK
A
CLOSE message was received.
An eSNMP protocol error occurred and the
packet was discarded.
ESNMP_LIB_LOST_
CONNECTION
Communication with the master agent was lost.
Restart the connection.
5–14 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_are_you_there
esnmp_are_you_there
Requests the master agent to report immediately that it is up and functioning.
Format
int esnmp_are_you_there ( ) ;
Description
The esnmp_are_you_there routine does not block waiting for a response. The
routine is intended to cause the master agent to reply immediately. The response
should be processed by calling the esnmp_poll routine.
If a response is not received within the timeout period, the application code
should restart the eSNMP protocol by calling the esnmp_init routine. No timers
are maintained by the eSNMP library.
Return Values
ESNMP_LIB_OK
The request was sent.
ESNMP_LIB_LOST_
CONNECTION
The request cannot be sent because the master
agent is down.
eSNMP API Routines 5–15
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_trap
esnmp_trap
Sends a trap message to the master agent.
Format
int esnmp_trap ( int *generic_trap,
int specific_trap,
char *enterprise,
varbind *vb ) 2 ;
Arguments
generic_trap
A generic trap code. Set this argument value to 0 (zero) for SNMPv2 traps.
specific_trap
A specific trap code. Set this argument value to 0 (zero) for SNMPv2 traps.
enterprise
An enterprise OID string in dot notation. Set to the object identifier defined by
the NOTIFICATION-TYPE macro in the defining MIB specification. This value is
passed as the value of SnmpTrapOID.0 in the SNMPv2-Trap-PDU.
vb
A VARBIND list of data (a null pointer indicates no data).
Description
This function can be called any time. If the master agent is not running, traps
are queued and sent when communication is possible.
The trap message is actually sent to the master agent after it responds
to the esnmp_init routine. This occurs with every API call and for most
esnmp_register routines. The quickest process to send traps to the master
agent is to call the esnmp_init, esnmp_poll, and esnmp_trap routines.
The master agent formats the trap into an SNMP trap message and sends it to
management stations based on its current configuration.
The master agent does not respond to the content of the trap. However, the
master agent does return a value that indicates whether the trap was received
successfully.
Return Values
ESNMP_LIB_OK
The routine has completed successfully.
ESNMP_LIB_LOST_
CONNECTION
Could not send the trap message to master agent.
ESNMP_LIB_NOTOK
Something failed and the message could not be
generated.
5–16 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_term
esnmp_term
Sends a close message to the master agent and shuts down the subagent.
Format
void esnmp_term (void) ;
Description
Subagents must call this routine when terminating so that the master agent can
update its MIB registry quickly and so that resources used by eSNMP on behalf
of the subagent can be released.
Return Values
ESNMP_LIB_OK
The esnmp_term routine always returns ESNMP_
LIB_OK, even if the packet could not be sent.
eSNMP API Routines 5–17
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_sysuptime
esnmp_sysuptime
Converts UNIX system time obtained from gettimeofday into a value with the
same time base as sysUpTime
.
Format
unsigned int esnmp_sysuptime ( struct timeval *timestamp ) ;
Argument
timestamp
A pointer to struct timeval, which contains a value obtained from the
gettimeofday system call. The structure is defined in include/sys/time.h
.
A null pointer means return the current sysUpTime
.
Description
This routine provides a mechanism to convert UNIX timestamps into eSNMP
TimeTicks. The function returns the value that sysUpTime held when the passed
timestamp was now
.
This routine can be used as a TimeTicks data type (the time since the eSNMP
master agent started) in hundredths of a second. The time base is obtained from
the master agent in response to esnmp_init, so calls to this function before that
time will not be accurate.
Return Values
0
An error occurred because a gettimeofday
function failed. Otherwise, timestamp contains
the time in hundredths of a second since the
master agent started.
Example
#include <sys/time.h>
#include <esnmp.h>
struct timeval timestamp;
gettimeofday(×tamp, NULL);
.
.
.
o_integer(vb, object, esnmp_sysuptime(×tamp));
5–18 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
5.2 Method Routines
5.2 Method Routines
SNMP requests may contain many encoded MIB variables. The libsnmp code
executing in a subagent matches each VariableBinding with an object table
entry. The object table’s method routine is then called. Therefore, a method
routine is called to service a single MIB variable. Since a single method routine
can handle a number of MIB variables, the same method routine may be called
several times during a single SNMP request.
The method routine calling interface contains the following functions:
•
•
*_get—respond to Get, GetNext, and GetBulk requests
*_set—respond to Set requests
eSNMP API Routines 5–19
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_get Routine
*_get Routine
The *_get routine is a method routine for the specified MIB item, which is
typically a MIB group (for example, system in MIB II) or a table entry (for
example, ifEntry in MIB II).
Format
int mib-group_get ( METHOD *method ) ;
Arguments
method
A pointer to a METHOD structure that contains the following fields:
Field Name
Description
action
One of ESNMP_ACT_GET, ESNMP_ACT_
GETNEXT, or ESNMP_ACT_GETBULK.
serial_num
An integer number that is unique to this SNMP
request. Each method routine called while
servicing a single SNMP request receives the
same value of serial_num. New SNMP requests
are indicated by a new value of serial_num.
repeat_cnt
Used for GetBulk only. This value indicates
the current iteration number of a repeating
VARBIND. This number increments from 1 to
max_repetitions and is 0 (zero) for nonrepeating
VARBIND structures.
max_repetitions
The maximum number of repetitions to
perform. Used for GetBulk only. This will be 0
(zero) for nonrepeating VARBIND structures.
You can optimize subsequent processing by
knowing the maximum number repeat calls will
be made.
varbind
A pointer to the VARBIND structure for
which you must fill in the OID and data
fields. Upon entry of the method routine,
the method->varbind->name field is the OID
that was requested.
Upon exit of the method routine, the
method->varbind field contains the requested
data, and the method->varbind->name field is
updated to reflect the actual instance OID for
the returned VARBIND structure.
The support routines (o_integer o_string,
,
o_oid, and o_octet) are generally used
to load data. The libsnmp instance2oid
routine is used to update the OID in the
method->varbind->name field.
5–20 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_get Routine
Field Name
Description
object
A pointer to the object table entry for
the MIB variable being referenced. The
method->object->object_index field is this
object’s unique index within the object table
(useful when one method routine services many
objects).
The method->object->oid field is the OID
defined for this object in the MIB. The
instance requested is derived by comparing
this OID with the OID in the request found
in the method->varbind->name field. The
oid2instance function is useful for this.
Description
These types of routines call whatever routine is specified for Get operations in the
object table identified by the registered subtree.
This function is pointed to by some number of elements of the subagent object
table. When a request arrives for an object, its method routine is called. The
*_get method routine is called in response to a Get request.
Return Values
ESNMP_MTHD_noError
The routine completed successfully.
ESNMP_MTHD_
noSuchObject
The requested object cannot be returned or does
not exist.
ESNMP_MTHD_
noSuchInstance
The requested instance of an object cannot be
returned or does not exist.
ESNMP_MTHD_genErr
A general processing error.
eSNMP API Routines 5–21
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_set Routine
*_set Routine
The *_set method routine for a specified MIB item, which is typically a MIB
group (for example, system in MIB II) or a table entry (for example, ifEntry in
MIB II).
Format
int mib-group_set ( METHOD *method ) ;
Arguments
method
A pointer to a METHOD structure that contains the following fields:
Field Name
Description
action
One of ESNMP_ACT_SET,
ESNMP_ACT_UNDO, or ESNMP_ACT_
CLEANUP.
serial_num
varbind
object
An integer number that is unique to this SNMP
request. Each method routine called while
servicing a single SNMP request receives the
same value as serial_num. New SNMP requests
are indicated by a new value of serial_num.
A pointer to the VARBIND structure that
contains the MIB variable’s supplied data value
and name (OID). The instance information has
already been extracted from the OID and placed
in the method->row->instance field.
A pointer to the object table entry for
the MIB variable being referenced. The
method->object->object-index field is this
object’s unique index within the object table
(useful when one method routine services many
objects).
The method->object->oid field is the OID
defined for this object in the MIB.
flags
A read-only integer bitmask set by the
libesnmp routine. If set, the ESNMP_FIRST_
IN_ROW bit indicates that this call is the first
object to be set in the row. If set, the ESNMP_
LAST_IN_ROW bit indicates that this call
is the last object to be set in the row. Only
METHOD structures with the ESNMP_LAST_
IN_ROW bit set are passed to the method
routines for commit, undo, and cleanup phases.
5–22 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_set Routine
Field Name
Description
row
A pointer to a ROW_CONTEXT structure
(defined in the ESNMP.H header file). All Set
requests to the method routine that refer to the
same group and that have the same instance
number will be presented with the same row
structure. The method routines can accumulate
information in the row structures during Set
requests for use during the commit and undo
phases. The accumulated data can be released
by the method routines during the cleanup
phase.
The ROW_CONTEXT structure contains the
following fields:
instance
An address of an array
containing the instance OID
for this conceptual row. The
libesnmp routine builds this
array by subtracting the
object OID from the requested
variable binding OID.
instance_len
context
The size of the
method->row->instance field.
A pointer to be used privately
by the method routine to
reference data needed for
processing this request.
save
state
A pointer to be used privately
by the method routine to
reference data needed for
undoing this request.
An integer to be used
privately by the method
routine for holding any state
information it requires.
Description
The libesnmp routines call whatever routine is specified for Set operations in the
object table identified by the registered subtree.
This function is pointed to by some number of elements of the subagent object
table. When a request arrives for an object, its method routine is called. The
*_set method routine is called in response to a Set request.
eSNMP API Routines 5–23
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_set Routine
Return Values
ESNMP_MTHD_noError
The routine completed successfully.
ESNMP_MTHD_notWritable
The requested object cannot be set or was not
implemented.
ESNMP_MTHD_wrongType
The data type for the requested value is the
wrong type.
ESNMP_MTHD_
wrongLength
The requested value is the wrong length.
ESNMP_MTHD_
wrongEncoding
The requested value is represented incorrectly.
ESNMP_MTHD_wrongValue
ESNMP_MTHD_noCreation
The requested value is out of range.
The requested instance can never be created.
ESNMP_MTHD_
inconsistentName
The requested instance cannot currently be
created.
ESNMP_MTHD_
inconsistentValue
The requested value is not consistent.
ESNMP_MTHD_
A failure due to some resource constraint.
resourceUnavailable
ESNMP_MTHD_genErr
A general processing error.
The commit phase failed.
ESNMP_MTHD_
commitFailed
ESNMP_MTHD_undoFailed
The undo phase failed.
5.2.1 Processing *_set Routines
This following is the sequence of operations performed for *_set routines
1. Every variable binding is parsed and its object is located in the object table. A
METHOD structure is created for each VARBIND structure. These METHOD
structures point to a ROW_CONTEXT structure, which is useful for handling
these phases. Objects in the same conceptual row all point to the same ROW_
CONTEXT structure. This determination is made by checking the following:
•
•
The referenced objects are in the same MIB group.
The VARBIND structures have the same instance OIDs.
2. Each ROW_CONTEXT structure is loaded with the instance information
for that conceptual row. The ROW_CONTEXT structure context and save
fields are set to NULL, and the state field is set to ESNMP_SET_UNKNOWN
structure.
3. The method routine for each object is called and is passed its METHOD
structure with an action code of ESNMP_ACT_SET.
If all method routines return success, a single method routine (the last
one called for the row) is called for each row, with method->action equal to
ESNMP_ACT_COMMIT.
5–24 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_set Routine
If any row reports failure, all rows that were successfully committed are told
to undo the phase. This is accomplished by calling a single method routine
for each row (the same one that was called for the commit phase), with a
method->action equal to ESNMP_ACT_UNDO.
4. Each row is released. The same single method routine for each row is called
with a method->action equal to ESNMP_ACT_CLEANUP. This occurs for
every row, regardless of the results of previous processing.
The action codes are processed as follows:
•
ESNMP_ACT_SET
Each object’s method routine is called during the SET phase, until all objects
are processed or a method routine returns an error status value. (This is the
only phase during which each object’s method routine is called.) For variable
bindings in the same conceptual row, method->row points to a common ROW_
CONTEXT.
The method->flags bitmask has the ESNMP_LAST_IN_ROW bit set, if this is
the last object being called for this ROW_CONTEXT. This enables you to do a
final consistency check, because you have seen every variable binding for this
conceptual row.
The method routine’s job in this phase is to determine whether the Set
request will work, to return the correct SNMP error code if it does not, and to
prepare any context data it needs to actually perform the Set request during
the COMMIT phase.
The method->row->context field is private to the method routine; libesnmp
does not use it. A typical use is to store the address of an emitted structure
that has been loaded with the data from the VARBIND for the conceptual
row.
•
ESNMP_ACT_COMMIT
Even though several variable bindings may be in a conceptual row, only the
last one in order of the Set request is processed. Of all the method routines
that point to a common row, only the last method routine is called.
This method routine must have available to it all necessary data and
context to perform the operation. It must also save a snapshot of current
data or whatever it needs to undo the Set operation, if required. The
method->row->save field is intended to hold a pointer to whatever data is
needed to accomplish this. A typical use is to store the address of a structure
that has been loaded with the current data for the conceptual row. The
structure is one that has been automatically generated by the MIBCOMP
command.
The method->row->save field is also private to the method routine; libesnmp
does not use it.
If this operation succeeds, return ESNMP_MTHD_noError; otherwise, return a
value of ESNMP_MTHD_commitFailed
.
If any errors were returned during the COMMIT phase, libesnmp enters the
UNDO phase; if not, it enters the CLEANUP phase.
Note
If the Set request spans multiple subagents and another subagent fails,
the UNDO phase may occur even if the Set operation is successful
eSNMP API Routines 5–25
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_set Routine
•
ESNMP_ACT_UNDO
For each conceptual row that was successfully committed, the same method
routine is called with method->action equal to ESNMP_ACT_UNDO. The
ROW_CONTEXT structures that have not yet been called for the COMMIT
phase are not called for the UNDO phase; they are called for CLEANUP
phase.
The method routine should attempt to restore conditions to what they were
before it executed the COMMIT phase. (This is typically done using the data
pointed to by the method->row->save field.)
If successful, return ESNMP_MTHD_noError; otherwise, return ESNMP_
MTHD_undoFail.
•
ESNMP_ACT_CLEANUP
Regardless of what else has happened, at this point each ROW_CONTEXT
participates in cleanup phase. The same method routine that was
called for in the COMMIT phase is called with method->action equal to
ESNMP_ACT_CLEANUP.
This indicates the end of processing for the set request. The method routine
should perform whatever cleanup is required; for instance, freeing dynamic
memory that might have been allocated and stored in method->row->context
and method->row->save fields, and so on.
The function return status value is ignored for the CLEANUP phase.
5.2.2 Method Routine Applications Programming
You must write the code for the method routines declared in the subtree_TBL.H
file. Each method routine has one argument, which is a pointer to the METHOD
structure, as follows:
int mib_group_get(
METHOD *method int mib_group_set(
METHOD *method );
The Get method routines are used to perform Get GetNext, and GetBulk
,
operations.
The Get method routines perform the following tasks:
•
Extract the instance portion of the requested OID. You can do this manually
by comparing the method->object->oid field (the object’s base OID) to
the method->varbind->name field (the requested OID). You can use the
oid2instance support routine to do this.
•
•
Determine the instance validity. The instance OID can be null or any length,
depending on what was requested and how your object was selected. You may
be able to reject the request immediately by checking on the instance OID.
Extract the data. Based on the instance OID and method->action field,
determine what data, if any, is to be returned.
5–26 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_set Routine
•
•
Load the response OID back into the method routine’s VARBIND structure.
Set the method->varbind field with the OID of the actual MIB variable
instance you are returning. This is usually accomplished by loading an
array of integers with the instance OID you wish to return and calling the
instance2OID support routine.
Load the response data back into the method routine’s VARBIND structure.
Use one of the support routines with the corresponding data type to load the
method->varbind field with the data to return:
•
•
•
•
o_integer
o_string
o_octet
o_oid
These routines make a copy of the data you specify. The libesnmp function
manages any memory associated with copied data. The method routine must
manage the original data’s memory.
The routine does any necessary conversions to the type defined in the
object table for the MIB variable and copies the converted data into the
method->varbind field. See Section 5.2.3 for information on data value
representation.
•
Return the correct status value, as follows:
ESNMP_MTHD_noError
The routine completed successfully or
no errors were found.
ESNMP_MTHD_noSuchInstance
There is no such instance of the
requested object.
ESNMP_MTHD_noSuchObject
ESNMP_MTHD_ genErr
No such object exists.
An error occurred and the routine did
not complete successfully.
5.2.3 Value Representation
The values in a VARBIND structure for each data type are represented as follows.
(Refer to the ESNMP.H file for a definition of the OCT and OID structures.)
•
ESNMP_TYPE_Integer32 (varbind->value.sl field)
This is a 32-bit signed integer. Use the o_integer routine to insert an integer
value into the VARBIND structure. Note that the prototype for the value
argument is unsigned long; therefore, you may need to cast this to a signed
integer.
•
ESNMP_TYPE_DisplayString, ESNMP_TYPE_Opaque
ESNMP_TYPE_OctetString (varbind->value.oct field)
This is an octet string. It is contained in the VARBIND structure as an OCT
structure that contains a length and a pointer to a dynamically allocated
character array.
eSNMP API Routines 5–27
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_set Routine
The displaystring is different only in that the character array can be
interpreted as ASCII text, but the octetstring can be anything. If the
octetstring contains bits or a bit string, the OCT structure contains the
following:
A length equal to the number of bytes needed to contain the value that is
((qty-bits - 1)/8 + 1)
A pointer to a buffer containing the bits of the bitstring in the form
bbbbb..bb, where the bb octets represent the bitstring itself, bit 0 comes
first, and so on. Any unused bits in the last octet are set to zero.
Use the o_string support routine to insert a value into the VARBIND
structure, which is a buffer and a length. New space is allocated and the
buffer is copied into the new space.
Use the o_octet routine to insert a value into the VARBIND structure, which
is a pointer to an OCT structure. New space is allocated and the buffer
pointed to by the OCT structure is copied.
•
ESNMP_TYPE_ObjectId (varbind->value.oid and the varbind->name fields)
This is an object identifier. It is contained in the VARBIND structure as
an OID structure that contains the number of elements and a pointer to a
dynamically allocated array of unsigned integers, one for each element.
The varbind->name field is used to hold the object identifier and the instance
information that identifies the MIB variable. Use the OID2Instance function
to extract the instance elements from an incoming OID on a request. Use
the instance2oid function to combine the instance elements with the MIB
variable’s base OID to set the VARBIND structure’s name field when building
a response.
Use the o_oid function to insert an object identifier into the VARBIND
structure when the OID value to be returned as data is in the form of a
pointer to an OID structure.
Use the o_string function to insert an OID into the VARBIND structure
when the OID value to be returned as data is in the form of a pointer
to an ASCII string containing the OID in dot format; for example:
1.3.6.1.2.1.3.1.1.2.0.
•
•
ESNMP_TYPE_NULL
This is the NULL, or empty, type. This is used to indicate that there is no
value. The length is zero and the value in the VARBIND structure is zero
filled.
The incoming VARBIND structures on a Get GetNext, and GetBulk will
have this data type. A method routine should never return this value. An
incoming Set request never has this value in a VARBIND structure.
,
ESNMP_TYPE_IpAddress (varbind->value.oct field)
This is an IP address. It is contained in the VARBIND structure in an OCT
structure that has a length of 4 and a pointer to a dynamically allocated
buffer containing the 4 bytes of the IP address in network byte order.
Use the o_integer function to insert an IP address into the VARBIND
structure when the value is an unsigned integer in network byte order.
Use the o_string function to insert an IP address into the VARBIND
structure when the value is a byte array (in network byte order). Use a
length of 4.
5–28 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
*_set Routine
•
ESNMP_TYPE_Integer32
ESNMP_TYPE_Counter32
ESNMP_TYPE_<Gauge32 (varbind->value.ul field)
The 32-bit counter and 32-bit gauge data types are stored in the VARBIND
structure as an unsigned integer.
Use the o_integer function to insert an unsigned value into the VARBIND
structure.
•
•
ESNMP_TYPE_TimeTicks (varbind->value.ul field)
The 32-bit timeticks type values are stored in the VARBIND structure as an
unsigned integer.
Use the o_integer function to insert an unsigned value into the VARBIND
structure.
ESNMP_TYPE_Counter64 (varbind->value.ul64 field)
The 64-bit counter is stored in a VARBIND structure as an unsigned
longword, which, on an OpenVMS Alpha system, has a 64-bit value.
Use the o_integer function to insert an unsigned longword (64 bits) into the
VARBIND structure.
eSNMP API Routines 5–29
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
5.3 Support Routines
5.3 Support Routines
The support routines are provided as a convenience for developers writing method
routines that handle specific MIB elements. The following support routines are
provided:
Routine
Function
o_integer
Loads an integer value.
o_octet
Loads an octet value.
o_oid
Loads an OID value.
o_string
Loads a string value.
o_counter64
str2oid
Loads a Counter64 variable into the varbind
Converts a string OID to dot notation.
Converts an OID into a string.
Creates a full OID for a value.
Extracts an instance and loads an array.
Returns an IP address for an OID.
Compares two OIDs.
.
sprintoid
instance2oid
oid2instance
inst2ip
cmp_oid
cmp_oid_prefix
clone_oid
Compares an OID’s prefix.
Makes a copy of an OID.
free_oid
Frees a buffer.
clone_buf
Duplicates a buffer.
mem2oct
Converts a string to an oct structure.
Compares two octets.
cmp_oct
clone_oct
Makes a copy of an oct structure.
Frees a buffer attached to an oct structure.
Frees the fields in the VARBIND structure.
Sets the logging level.
free_oct
free_varbind_date
set_debug_level
is_debug_level
ESNMP_LOG
Tests the logging level.
Directs log messages.
print_varbind
set_select_limit
_ _set_progname
Displays the varbind and its structure.
Sets the error limit for SNMP client requests.
Sets the program name to be displayed in log
messages.
_ _restore_progname
_ _parse_progname
Resets the program name back to the previous name.
Parses the application file name to determine the
program name.
esnmp_cleanup
Closes a socket that is used by a subagent for
communicating with the master agent.
5–30 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
o_integer
o_integer
Loads an integer value into the VARBIND structure with the appropriate type.
This function does not allocate the VARBIND structure.
Format
int o_integer ( VARBIND *vb,
OBJECT *obj,
unsigned long value );
Arguments
vb
A pointer to the VARBIND structure that is supposed to receive the data.
obj
A pointer to the OBJECT structure for the MIB variable associated with the OID in
the VARBIND structure.
value
The value to be inserted into the VARBIND structure.
The real type as defined in the object structure must be one of the following;
otherwise, an error is returned.
ESNMP_TYPE_Integer32
ESNMP_TYPE_Counter32
ESNMP_TYPE_Gauge32
ESNMP_TYPE_TimeTicks
ESNMP_TYPE_UInteger32
ESNMP_TYPE_Counter64
ESNMP_TYPE_IpAddress
32-bit integer
32-bit counter (unsigned)
32-bit gauge (unsigned)
32-bit timeticks (unsigned)
32-bit integer (unsigned)
64-bit counter (unsigned)
Implicit octet string (4)
Note
If the real type is IpAddress, then eSNMP assumes that the 4-byte
integer is in network byte order and packages it into an octet string.
Return Values
ESNMP_MTHD_noError
ESNMP_MTHD_genErr
The routine completed successfully.
An error has occurred.
eSNMP API Routines 5–31
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
o_integer
Example
#include <esnmp.h>
#include "ip_tbl.h" <-- for ipNetToMediaEntry_type definition
VARBIND
OBJECT
*vb
= method->varbind;
= method->object;
*object
ipNetToMediaEntry_type *data;
:
: assume buffer and structure member assignments occur here
:
switch(arg) {
case I_atIfIndex:
return o_integer(vb, object, data->ipNetToMediaIfIndex);
5–32 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
o_octet
o_octet
Loads an octet value into the VARBIND structure with the appropriate type. This
function does not allocate the VARBIND structure.
Format
int o_octet ( VARBIND *vb,
OBJECT *obj,
unsigned long value );
Arguments
vb
A pointer to the VARBIND structure that is supposed to receive the data.
If the original value in the vb field is not null, this routine attempts to free it. So
if you dynamically allocate memory or issue the malloc command to allocate your
own VARBIND structure, fill the structure with zeros before using it.
obj
A pointer to the OBJ ECT structure for the MIB variable associated with the OID
in the VARBIND structure.
value
The value to be inserted into the VARBIND structure.
The real type as defined in the object structure must be one of the following;
otherwise, an error is returned.
ESNMP_TYPE_OCTET_STRING
ESNMP_TYPE_IpAddress
Octet string (ASN.1)
Implicit octet string (4) (in octet form,
network byte order)
ESNMP_TYPE_DisplayString
ESNMP_TYPE_Opaque
DisplayString (textual convention)
Implicit octet string
Return Values
ESNMP_MTHD_noError
The routine completed successfully.
An error occurred.
ESNMP_MTHD_genErr
Example
#include <esnmp.h>
#include "ip_tbl.h" <-- for ipNetToMediaEntry_type definition
VARBIND
OBJECT
*vb
= method->varbind;
= method->object;
*object
ipNetToMediaEntry_type *data;
:
: assume buffer and structure member assignments occur here
:
switch(arg) {
case I_atPhysAddress:
return o_octet(vb, object, &data->ipNetToMediaPhysAddress);
eSNMP API Routines 5–33
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
o_oid
o_oid
Loads an OID value into the VARBIND structure with the appropriate type. This
function does not allocate the VARBIND structure.
Format
int o_oid ( VARBIND *vb,
OBJECT *obj,
OID *oid );
Arguments
vb
A pointer to the VARBIND structure that is supposed to receive the data.
If the original value in the VARBIND structure is not null, this routine attempts
to free it. So if you dynamically allocate memory or issue the malloc command to
allocate your own VARBIND structure, fill the structure with zeros before using
it.
obj
A pointer to the OBJ ECT structure for the MIB variable associated with the OID
in the VARBIND structure.
oid
The value to be inserted into the VARBIND structure as data. For more
information about OID length and values, see Chapter 3.
The real type as defined in the object structure must be ESNMP_TYPE_OBJ ECT_
IDENTIFIER.
Return Values
ESNMP_MTHD_noError
The routine completed successfully.
An error occurred.
ESNMP_MTHD_genErr
Example
#include <esnmp.h>
#include "ip_tbl.h" <-- for ipNetToMediaEntry_type definition
VARBIND
OBJECT
*vb
= method->varbind;
= method->object;
*object
ipNetToMediaEntry_type *data;
:
: assume buffer and structure member assignments occur here
:
switch(arg) {
case I_atObjectID:
return o_oid(vb, object, &data->ipNetToMediaObjectID);
5–34 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
o_string
o_string
Loads a string value into the VARBIND structure with the appropriate type. This
function does not allocate the VARBIND structure.
Format
int o_string ( VARBIND *vb,
OBJECT *obj,
unsigned character *ptr,
int len );
Arguments
vb
A pointer to the VARBIND structure that is supposed to receive the data.
If the original value in the VARBIND structure is not null, this routine attempts
to free it. So if you dynamically allocate memory or issue the malloc command to
allocate your own VARBIND structure, fill the structure with zeros before using
it.
obj
A pointer to the OBJ ECT structure for the MIB variable associated with the OID
in the VARBIND structure.
ptr
The pointer to the buffer containing data to be inserted into the VARBIND
structure as data.
len
The length of the data in buffer pointed to by ptr.
The real type as defined in the object structure must be one of the following;
otherwise, an error is returned.
ESNMP_TYPE_OCTET_
STRING
Octet string (ASN.1)
ESNMP_TYPE_IpAddress
Implicit octet string (4) (in octet form, network
byte order)
ESNMP_TYPE_DisplayString
ESNMP_TYPE_NsapAddress
ESNMP_TYPE_Opaque
DisplayString (textual convention)
Implicit octet string
Implicit octet string
ESNMP_TYPE_OBJ ECT_
IDENTIFIER
Object identifier (ASN.1) (in dot notation, for
example: 1.3.4.6.3)
Return Values
ESNMP_MTHD_noError
ESNMP_MTHD_genErr
The routine completed successfully.
An error occurred.
eSNMP API Routines 5–35
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
o_string
Example
#include <esnmp.h>
#include "ip_tbl.h" <-- for ipNetToMediaEntry_type definition
VARBIND
OBJECT
*vb
= method->varbind;
= method->object;
*object
ipNetToMediaEntry_type *data;
:
: assume buffer and structure member assignments occur here
:
switch(arg) {
case I_atPhysAddress:
return o_string(vb, object, data->ipNetToMediaPhysAddress.ptr,
data->ipNetToMediaPhysAddress.len);
5–36 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
o_counter64
o_counter64
Loads a counter64 value into the VARBIND structure.
Format
int o_counter64 ( VARBIND *vb,
OBJECT *obj,
uint64 value ); (for Alpha)
uint64_vax value ; (for VAX))
Arguments
vb
A pointer to the VARBIND structure that is supposed to receive the data.
obj
A pointer to the OBJ ECT structure for the MIB variable associated with the OID
in the VARBIND structure.
value
The 8-byte value to be inserted into the VARBIND structure, passed as an array
of two integers.
The real type as defined in the object structure must be
ESNMP_TYPE_Counter64. Otherwise, an error is returned.
Example
See the example for the o_integer routine.
Return Values
ESNMP_MTHD_noError
ESNMP_MTHD_genErr
No error was generated.
An error was generated.
eSNMP API Routines 5–37
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
str2oid
str2oid
Converts a null-terminated string OID in dot notation to an OID structure. The
str2oid routine does not allocate an OID structure.
Format
oid *str2oid ( oid *oid,
char *s );
Arguments
oid
The value to be inserted as data into the VARBIND structure. For more
information about OID length and values, see Chapter 3.
s
A null string or empty string returns an OID structure that has one element of
zero.
Description
The routine dynamically allocates the buffer and inserts its pointer into the OID
structure passed in the call. The caller must explicitly free this buffer. The OID
can have a maximum of 128 elements.
Return Values
null
An error occurred. Otherwise, the pointer to the
OID structure (its first argument) is returned.
Example
include <esnmp.h>
OID abc;
if (stroid (&abc, "1.2.5.4.3.6") == NULL
DPRINTF((WARNING, "It did not work...\n");
5–38 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
sprintoid
sprintoid
Converts an OID into a null-terminated string.
Format
char *sprintoid ( char *buffer,
oid *oid );
Description
An OID can have up to 128 elements. A full-sized OID can require a large buffer.
Return Values
The return value points to its first argument.
Example
#include <esnmp.h>
#define SOMETHING_BIG 1024
OID abc;
char buffer[SOMETHING_BIG];
:
: assume abc gets initialized with some value
:
printf("dots=%s\n", sprintoid(buffer, &abc));
eSNMP API Routines 5–39
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
instance2oid
instance2oid
Copies the object’s base OID and appends a copy of the instance array to make
a complete OID for a value. This routine does not allocate an OID structure. It
only allocates the array containing the elements.
Format
oid instance2oid ( oid *new,
object *obj,
unsigned int *instance,
int *len );
Arguments
new
A pointer to the OID that is to receive the new OID value.
obj
A pointer to the object table entry for the MIB variable being obtained. The first
part of the new OID is the OID from this MIB object table entry.
instance
A pointer to an array of instance values. These values are appended to the base
OID obtained from the MIB object table entry to construct the new OID.
len
The number of elements in the instance array.
Description
The instance array may be created by oid2instance or constructed from key
values as a result of a GetNext command (see Chapter 1).
This routine dynamically allocates the buffer and inserts its pointer into the OID
structure passed in the call. The caller must explicitly free the buffer.
You should point to the OID structure receiving the new values and then call the
instance2oid routine. Previous values in the OID structure are freed (that is,
free_oid is called first), and then the new values are dynamically allocated and
inserted. Be sure the initial value of the new OID is all zeros. If you do not want
the initial value freed, make sure the new OID structure is all zeros.
Return Values
null
An error occurred. Otherwise, the pointer to the
OID structure (new) is returned.
5–40 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
instance2oid
Example
#include <esnmp.h>
VARBIND *vb;
<-- filled in
OBJECT *object; <-- filled in
unsigned int instance[6];
-- Construct the outgoing OID in a GETNEXT
--
-- Instance is N.1.A.A.A.A where A’s are IP address --
instance[0] = data->ipNetToMediaIfIndex;
instance[1] = 1;
for (i = 0; i < 4; i++) {
instance[i+2]=((unsigned char *)(&data->ipNetToMediaNetAddress))[i];
}
instance2oid(&vb->name, object, instance, 6);
eSNMP API Routines 5–41
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
oid2instance
oid2instance
Extracts the instance values from an OID structure and copies them to the
specified array of integers. The routine then returns the number of elements in
the array.
Format
int oid2instance ( oid *oid,
object *obj,
unsigned int *instance,
int *max_len );
Arguments
oid
A pointer to an incoming OID containing an instance or part of an instance.
obj
A pointer to the object table entry for the MIB variable.
instance
A pointer to an array of unsigned integers where the index is placed.
max_len
The number of elements in the instance array.
Description
The instance values are the elements of an OID beyond those that identify the
MIB variable. These elements identify a specific instance of a MIB value.
If there are more elements in the OID structure than specified by the max_len
parameter, the function copies the number of elements specified by max_len only
and returns the total number of elements that would have been copied had there
been space.
Return Values
Less than zero
An error occurred. This is not returned if the
object was obtained by looking at this OID.
Zero
No instance elements.
Greater than zero
The returned value indicates the number of
elements in the index. This could be larger than
the max_len parameter.
5–42 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
oid2instance
Example
#include <esnmp.h>
OID
*incoming = &method->varbind->name;
*object = method->object;
instLength;
OBJECT
int
unsigned int instance[6];
-- in a GET operation --
-- Expected Instance is N.1.A.A.A.A where A’s are IP address --
instLength = oid2instance(incoming, object, instance, 6);
if (instLength != 6)
return ESNMP_MTHD_noSuchInstance;
The N will be in instance[0] and the IP address will be in instance[2]
,
instance[3] instance[4], and instance[5].
,
eSNMP API Routines 5–43
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
inst2ip
inst2ip
Returns an IP address derived from an OID instance.
Format
int inst2ip ( unsigned int *instance,
int *length,
unsigned int *ipaddr,
int *exact,
int *carry );
Arguments
instance
A pointer to an array of unsigned int containing the instance numbers returned
by the oid2instance routine to be converted to an IP address.
The range for elements is between zero and 255. Using the EXACT mode, the
routine returns 1 if an element is out of range. Using the NEXT mode, a value
greater than 255 causes that element to overflow. In this case, the value is set
to 0 and the next most significant element is incremented; therefore, it returns a
lexically equivalent value of the next possible ipaddr.
length
The number of elements in the instance array. Instances beyond the fourth are
ignored. If the length is less than four, the missing values are assumed to be
zero. A negative length results in an ipaddr value of zero. For an exact match
(such as Get), there must be exactly four elements.
ipAddr
A pointer indicating where to return the IP address value. This routine is in
network byte order (the most significant element is first).
exact
Can either be TRUE or FALSE
.
TRUE means do an EXACT match. If any element is greater than 255 or if there
are not exactly four elements, a value of 1 is returned. The carry argument is
ignored.
FALSE means do a NEXT match. That is, the lexically next IP address is returned,
if the carry value is set and the length is at least four. If there are fewer than
four elements, this function assumes the missing values are zero. If any one
element contains a value greater than 255, the value is zeroed and the next most
significant element is incremented. Returns a 1 (one) only when there is a carry
from the most significant (the first) value.
carry
Adds to the IP address on a NEXT match. If you are trying to determine the next
possible IP address, pass in a one. Otherwise, pass in a zero. A length of less
than 4 cancels the carry.
5–44 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
inst2ip
Description
Use the EXACT mode for evaluating an instance for Get and Set operations. For
GetNext and GetBulk operations, use the NEXT mode. When using NEXT mode,
this routine assumes that the search for data will be performed using greater
than or equal to matches.
Return Values
Carry value is 0
Carry value is 1
The routine completed successfully.
For EXACT match, an error occurred. For NEXT
match, there was a carry. (If there was a carry,
the returned ipaddr is 0.)
Examples
1. The following example converts an instance to an IP address for a Get
operation, which is an EXACT match.
#include <esnmp.h>
OID
*incoming = &method->varbind->name;
*object = method->object;
OBJECT
int instLength;
unsigned int instance[6];
unsigned int ip_addr;
int
iface;
-- The instance is N.1.A.A.A.A where the A’s are the IP address--
instLength = oid2instance(incoming, object, instance, 6);
if (instLength == 6 && !inst2ip(&instance[2], 4, &ip_addr, TRUE,0)) {
iface = (int) instance[0];
}
else
return ESNMP_MTHD_noSuchInstance;
2. The following example shows a GetNext operation in which there is only
one key or in which the ipaddr value is the least significant part of the
key. This is a NEXT match; therefore, a value of 1 is passed back for the
carry value.
#include <esnmp.h>
OID
*incoming = &method->varbind->name;
*object = method->object;
OBJECT
int instLength;
unsigned int instance[6];
unsigned int ip_addr;
int
iface;
-- The instance is N.1.A.A.A.A where the A’s are the IP address--
instLength = oid2instance(incoming, object, instance, 6);
iface = (instLength < 1) ? 0 :(int) instance[0];
iface += inst2ip(&instance[2], instLength - 2, &ip_addr, FALSE, 1);
3. In the following example, the search key consists of multiple parts. If
you are doing a GetNext operation, you must find the next possible value
for the search key, so that you can perform a cascaded greater-than or
equal-to search.
eSNMP API Routines 5–45
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
inst2ip
The search key consists of a number and two ipaddr values. These are
represented in the instance part of the OID as n.A.A.A.A.B.B.B.B, where:
•
•
•
n is a single value integer.
The A.A.A.A portion makes up one IP address.
The B.B.B.B portion makes up a second IP address.
If all elements are given, the total length of the search key is 9. In this
case, you perform the operation as follows:
•
Convert the least significant part of the key (that is, the B.B.B.B
portion), by calling the inst2ip routine, passing it a 1 for the carry
and (length - 5) for the length.
•
•
If the conversion of the B.B.B.B portion generates a carry (that is,
returns 1), you pass it to the next most significant part of the key.
Convert the A.A.A.A portion by calling the inst2ip routine, passing it
(length - 1) for the length and the carry returned from the conversion
of the B.B.B.B portion.
•
The most significant element n is a number; therefore, add the carry
from the A.A.A.A conversion to the number. If the result overflows,
then the search key is not valid.
#include <esnmp.h>
OID
*incoming = &method->varbind->name;
*object = method->object;
OBJECT
int instLength;
unsigned int instance[9];
unsigned int ip_addrA;
unsigned int ip_addrB;
int
int
iface;
carry;
-- The instance is N.A.A.A.A.B.B.B.B --
instLength = oid2instance(incoming, object, instance, 9);
iface = (instLength < 1) ? 0 :(int) instance[0];
carry = inst2ip(&instance[1], instLength - 1, &ip_addrB, FALSE, 1);
carry = inst2ip(&instance[5], instLength - 5, &ip_addrA, FALSE, carry);
iface += carry;
if (iface > carry) {
-- a carry caused an overflow in the most significant element
return ESNMP_MTHD_noSuchInstance;
}
5–46 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
cmp_oid
cmp_oid
Compares two OID structures.
Format
int cmp_oid ( oid *q,
oid *p );
Description
This routine does an element-by-element comparison, from the most significant
element (element 0) to the least significant element. If all other elements are
equal, the OID with the least number of elements is considered less.
Return Values
-1
0
The OID q is less than OID p
The OID q is in OID p
The OID q is greater than OID p
.
.
1
.
eSNMP API Routines 5–47
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
cmp_oid_prefix
cmp_oid_prefix
Compares an OID against a prefix.
Format
int cmp_oid_prefix ( oid *q,
oid *prefix );
Description
A prefix could be the OID on an object in the object table. The elements beyond
the prefix are the instance information.
This routine does an element-by-element comparison, from the most significant
element (element 0) to the least significant element. If all elements of the prefix
OID match exactly with corresponding elements of the OID q structure, it is
considered an even match if the OID q structure contains additional elements.
The OID q structure is considered greater than the prefix if the first nonmatching
element is larger. It is considered smaller if the first nonmatching element is less.
Return Values
-1
0
The OID is less than the prefix.
The OID is in prefix.
1
The OID is greater than the prefix.
Example
#include <esnmp.h>
OID *q;
OBJECT *object;
if (cmp_oid_prefix(q, &object->oid) == 0)
printf("matches prefix\n");
5–48 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
clone_oid
clone_oid
Makes a copy of the OID. This routine does not allocate an OID structure.
Format
oid clone_oid ( oid *new,
oid *oid );
Arguments
Description
new
A pointer to the OID structure that is to receive the copy.
oid
A pointer to the OID structure where the data is to be obtained.
This routine dynamically allocates the buffer and inserts its pointer into the OID
structure received. The caller must explicitly free this buffer.
Point to the OID structure that is to receive the new OID values and call
this routine. Any previous value in the new OID structure is freed (using the
free_oid routine) and the new values are dynamically allocated and inserted. To
preserve an existing OID structure, initialize the new OID structure with zeros.
If the old OID structure is null or contains a null pointer to its element buffer, a
new OID of [0.0] is generated.
Return Values
Null
An error or the pointer to the OID is returned.
Example
#include <esnmp.h>
OID oid1;
OID oid2;
:
: assume oid1 gets assigned a value
:
memset(&oid2, 0, sizeof(OID));
if (clone_oid(&oid2, &oid1) == NULL)
DPRINTF((WARNING, "It did not work\n"));
eSNMP API Routines 5–49
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
free_oid
free_oid
Frees the OID structure’s buffer. This routine does not deallocate the OID
structure itself; it deallocates the elements buffer attached to the structure.
Format
void free_oid ( oid *oid );
Description
This routine frees the buffer pointed to by the OID->elements field and zeros the
field and the NELEM structure.
Example
include <esnmp.h>
OID oid;
:
: assume oid was assigned a value (perhaps with clone_oid()
: and we are now finished with it.
:
free_oid(&oid);
5–50 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
clone_buf
clone_buf
Duplicates a buffer in a dynamically allocated space.
Format
char clone_buf ( char *str,
int *len );
Arguments
Description
str
A pointer to the buffer to be duplicated.
len
The number of bytes to be copied.
One extra byte is always allocated at the end and is filled with zeros. If the
length is less than zero, the duplicate buffer length is set to zero. A buffer pointer
is always returned, unless there is a malloc error.
Return Values
Null
A
malloc error. Otherwise, the pointer to the
allocated buffer that contains a copy of the
original buffer is returned.
Example
#include <esnmp.h>
char *str = "something nice";
char *copy;
copy = clone_buf(str, strlen(str));
eSNMP API Routines 5–51
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
mem2oct
mem2oct
Converts a string (a buffer and length) to an oct structure with the new buffer ’s
address and length.
Format
oct *mem2oct ( oct *new,
char *buffer,
int *len );
Arguments
new
A pointer to the oct structure receiving the data.
buffer
Pointer to the buffer to be converted.
len
Length of buffer to be converted.
Description
The mem2oct routine dynamically allocates the buffer and inserts its pointer into
the oct structure. The caller must explicitly free this buffer.
This routine does not allocate an oct structure and does not free data previously
pointed to in the oct structure before making the assignment.
Return Values
Null
An error occurred. Otherwise, the pointer to the
oct structure (the first argument) is returned.
Example
#include <esnmp.h>
char buffer;
int len;
OCT abc;
...buffer and len are initialized to something...
memset(&abc, 0, sizeof(OCT));
if (mem2oct(&abc, buffer, len) == NULL)
DPRINTF((WARNING,"It did not work...\n"));
5–52 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
cmp_oct
cmp_oct
Compares two octet strings.
Format
int cmp_oct ( oct *oct1,
oct *oct2 );
Arguments
Description
oct1
Pointer to the first octet string.
oct2
Pointer to the second octet string.
The two octet strings are compared byte-by-byte to determine the length of the
shortest octet string. If all bytes are equal, the lengths are compared. An octet
with a null pointer is considered the same as a zero-length octet.
Return Values
-1
The string pointed to by the first oct is less than
the second.
0
1
The string pointed to by the first oct is equal to
the second.
The string pointed to by the first oct is greater
than the second.
Example
#include <esnmp.h>
OCT abc, efg;
...abc and efg are initialized to something...
if (cmp_oct(&abc, &efg) > 0)
DPRINTF((WARNING,"octet abc is larger than efg...\n"));
eSNMP API Routines 5–53
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
clone_oct
clone_oct
Makes a copy of the data in an oct structure. This routine does not allocate an
oct structure; it allocates the buffer pointed to by the oct structure.
Format
oct clone_oct ( oct *new,
oct *old );
Arguments
new
A pointer to the oct structure receiving the data.
old
A pointer to the oct structure where the data is to be obtained.
Description
The clone_oct routine dynamically allocates the buffer, copies the data, and
updates the oct structure with the buffer ’s address and length. The caller must
free this buffer.
The previous value of the buffer on the new oct structure is freed prior to the
new buffer being allocated. If you do not want the old value freed, initialize the
new oct structure before cloning.
Return Values
Null
An error occurred. Otherwise, the pointer to the
oct structure (the first argument) is returned.
Example
#include <esnmp.h>
OCT octet1;
OCT octet2;
:
: assume octet1 gets assigned a value
:
memset(&octet2, 0, sizeof(OCT));
if (clone_oct(&octet2, &octet1) == NULL)
DPRINTF((WARNING, "It did not work\n"));
5–54 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
free_oct
free_oct
Frees the buffer attached to an oct structure. This routine does not deallocate
the oct structure; it deallocates the buffer to which the oct structure points.
Format
void free_oct ( oct *oct );
Description
This routine frees the dynamically allocated buffer to which the oct structure
points, and zeros the pointer and length on the oct structure. If the oct structure
is already null, this routine does nothing.
If the buffer attached to the oct structure is already null, this routine sets the
length field of the oct structure to zero.
Example
#include <esnmp.h>
OCT octet;
:
: assume octet was assigned a value (perhaps with mem2oct()
: and we are now finished with it.
:
free_oct(&octet);
eSNMP API Routines 5–55
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
free_varbind_data
free_varbind_data
Frees the dynamically allocated fields in the VARBIND structure. However, this
routine does not deallocate the VARBIND structure itself; it deallocates the name
and data buffers to which the VARBIND structure points.
Format
void free_varbind_data ( varbind *vb );
Description
This routine performs a free_oid (vb->name) operation. If indicated by the
vb->type field, it then frees the vb->value data using either the free_oct or the
free_oid routine.
Example
#include <esnmp.h>
VARBIND *vb;
vb = (VARBIND*)malloc(sizeof(VARBIND));
clone_oid(&vb->name,oid);
clone_oct(&vb->value.oct,data);
:
: some processing that uses vb occurs here
:
free_varbind_data(vb);
free(vb);
5–56 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
set_debug_level
set_debug_level
Sets the logging level, which dictates what log messages are generated. The
program or module calls the routine during program initialization in response to
run-time options.
Format
void set_debug_level ( int stat,
unsigned integer null );
Arguments
stat
The logging level. The following values can be set individually or in combination:
Level
Meaning
ERROR
Used when a bad error occurred; requires a restart.
WARNING
Used when a packet cannot be handled; also implies
ERROR. This is the default.
TRACE
Used when tracing all packets; also implies ERROR and
WARNING.
null
This parameter is not used by OpenVMS. It is supplied for compatibility with
UNIX.
Description
The logging level will be ERROR, WARNING, or TRACE.
If you specify TRACE, all three types of errors are generated. If you specify
ERROR, only error messages are generated. If you specify WARNING, both error
and warning messages are generated.
To specify logging levels for the messages in your subagent, use the ESNMP_LOG
routine.
Example
#include <esnmp.h>
if (strcmp("-t", argv[1] {
set_debug_level(TRACE,NULL);
} else {
set_debug_level(WARNING,NULL);
}
eSNMP API Routines 5–57
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
is_debug_level
is_debug_level
Tests the logging level to see whether the specified logging level is set. You can
test the logging levels as follows:
Level
Meaning
ERROR
Used when a bad error occurs, requiring restart.
WARNING
Used when a packet cannot be handled; this also implies
ERROR.
TRACE
Used when tracing all packets; this also implies ERROR
and WARNING.
Format
int is_debug_level ( int type );
Return Values
TRUE
The requested level is set and the ESNMP_LOG
will generate output, or output will go to the
specified destination.
FALSE
The logging level is not set.
Example
#include <esnmp.h>
if (is_debug_level(TRACE))
dump_packet();
5–58 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
ESNMP_LOG
ESNMP_LOG
This is an error declaration C macro defined in the ESNMP.H header file. It
gathers the information that it can obtain and sends it to the log.
Format
ESNMP_LOG ( level,
format, ... );
Description
The esnmp_log routine is called using the ESNMP_LOG macro, which uses the
helper routine esnmp_logs to format part of the text. Do not use these functions
without the ESNMP_LOG macro. For example:
#define ESNMP_LOG(level, x) if (is_debug_level(level)) { \
esnmp_log(level, esnmp_logs x, __LINE__, __FILE__);}
Where:
•
•
x is a text string; for example, a printf statement.
level is one of the following:
ERROR
Declares an error condition.
WARNING
TRACE
Declares a warning.
Puts a message in the log file if trace is active.
For more information about configuration options for logging and tracing, refer to
the Compaq TCP/ IP Services for OpenVMS Management guide.
Example
#include <esnmp.h>
ESNMP_LOG( ERROR, ("Cannot open file %s\n", file));
eSNMP API Routines 5–59
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
__print_varbind
__print_varbind
Displays the VARBIND and its contents. This routine is used for debugging
purposes. To use this routine, you must set the debug level to TRACE. Output is
sent to the specified file.
Format
_ _print_varbind ( VARBIND *vb,
int indent );
Arguments
vb
The pointer to the VARBIND structure to be displayed. If the vb pointer is
NULL, no output is generated.
indent
The number of bytes of white space to place before each line of output.
5–60 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
set_select_limit
set_select_limit
Sets the eSNMP select error limit. For more information, see Section 6.1.
Format
set_select_limit ( char *progname );
Arguments
progname
The subagent name. This argument is valid with DPI versions only. With
AgentX, the argument is NULL because subagents do not get names.
Return Values
ESNMP_MTHD_noError
ESNMP_MTHD_genErr
No error was generated.
An error was generated.
eSNMP API Routines 5–61
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
__set_progname
__set_progname
Specifies the program name that will be displayed in log messages. This routine
should be called from the main during program initialization. It needs to be
called only once.
Format
_ _set_progname ( char *prog );
Arguments
prog
The program name as taken from argv[0], or some other identification for
entity-calling logging routines.
Example
#include "esnmp.h"
__set_progname(argv[0]);
5–62 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
__restore_progname
__restore_progname
Restores the program name from the second application of the set. This routine
should be called only after the _ _set_progname routine has been called. You can
use this to restore the most recent program name only.
Format
_ _restore_progname ( );
Example
#include "esnmp.h"
__restore_progname();
eSNMP API Routines 5–63
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
__parse_progname
__parse_progname
Parses the full file specification to extract only the file name and file extension.
Format
_ _parse_progname ( file-specification );
Arguments
file-specification
The full file specification for the subagent.
Example
#include "esnmp.h"
static char Progname[100];
sprintf (Progname, "%s%.8X", __parse_progname(prog), getpid());
5–64 eSNMP API Routines
Download from Www.Somanuals.com. All Manuals Search And Download.
eSNMP API Routines
esnmp_cleanup
esnmp_cleanup
Closes open sockets that are used by the subagent for communicating with the
master agent.
Format
esnmp_cleanup ( );
Example
#include "esnmp.h"
int rc = ESNMP_LIB_OK;
rc = esnmp_cleanup();
Return Values
ESNMP_LIB_NOTOK
ESNMP_LIB_OK
There was no socket.
Success.
eSNMP API Routines 5–65
Download from Www.Somanuals.com. All Manuals Search And Download.
Download from Www.Somanuals.com. All Manuals Search And Download.
6
Troubleshooting eSNMP Problems
The eSNMP modules provided with TCP/IP Services include troubleshooting
features that are useful in controlling the way your subagent works.
This chapter describes:
•
•
•
How to modify the subagent error limit (Section 6.1)
How to modify the default subagent timeout value (Section 6.2)
Log files (Section 6.3)
For additional information about troubleshooting SNMP problems, see the
Compaq TCP/ IP Services for OpenVMS Tuning and Troubleshooting guide.
6.1 Modifying the Subagent Error Limit
In certain circumstances, some subagent programs might enter a loop where a
select( ) call repeatedly returns a -1 error value. (Note that standard SNMP
subagents and the Chess example provided in TCPIP$EXAMPLES should not
exhibit this behavior.)
You can define the logical name TCPIP$SNMP_SELECT_ERROR_LIMIT to
modify the number of times a -1 error value can be returned from a select( )
call.
The valid TCPIP$SNMP_SELECT_ERROR_LIMIT values range from 1 to less
32
than
(default 100). When defining the error limit, remember:
•
•
•
Do not use commas when defining the number.
If you defined the limit as 0, no limit is set.
A defined value greater than or equal to 4000000000 triggers warning
messages.
For example, to define TCPIP$SNMP_SELECT_ERROR_LIMIT to limit the
number of times a -1 error value is returned to 1,000, enter the following
command:
$ DEFINE/SYSTEM TCPIP$SNMP_SELECT_ERROR_LIMIT 1000
6.2 Modifying the Subagent Timeout
You can define the logical name TCPIP$ESNMP_DEFAULT_TIMEOUT to modify
the default time allowed (3 seconds) before timeout occurs because of the lack of
response by the subagent to the master agent. The ability to define the timeout is
especially useful for slower systems and systems with heavy network traffic. The
logical name is translated at startup time.
Troubleshooting eSNMP Problems 6–1
Download from Www.Somanuals.com. All Manuals Search And Download.
Troubleshooting eSNMP Problems
6.2 Modifying the Subagent Timeout
The TCPIP$ESNMP_DEFAULT_TIMEOUT value is from 0 to 60 seconds. (You
should use 0 only for testing purposes, such as simulating problems on a heavily
loaded host or network.) If the value you specify contains nonnumeric digits or is
outside the allowed range, the default value of 3 seconds is used.
For example, to define TCPIP$ESNMP_DEFAULT_TIMEOUT to time out after 6
seconds of inactivity between the master agent and subagents, enter the following
command:
$ DEFINE/SYSTEM TCPIP$ESNMP_DEFAULT_TIMEOUT 6
When a subagent registers with the master agent, it can specify a value that
overrides the value you set with logical name TCPIP$ESNMP_DEFAULT_
TIMEOUT. The standard MIB II and Host Resources MIB subagents use the
default value of 3 seconds. Refer to the description of the esnmp_register routine
for more information.
6.3 Log Files
All output redirected from SYS$OUTPUT for the SNMP agent process is logged to
*.LOG files in the SYS$SYSDEVICE:[TCPIP$SNMP] directory. Output redirected
from SYS$ERROR is logged to *.ERR files in the same directory.
Output redirected from SYS$OUTPUT for the agent process is logged to the
following files:
•
•
•
TCPIP$ESNMP.LOG (for the master agent)
TCPIP$OS_MIBS.LOG (for the MIB II)
TCPIP$HR_MIB.LOG (for the Host Resources MIB)
Output redirected from SYS$ERROR is logged to the following files:
•
•
•
TCPIP$ESNMP.ERR (for the master agent)
TCPIP$OS_MIBS.ERR (for the MIB II)
TCPIP$HR_MIB.ERR (for the Host Resources MIB)
Data is flushed to the log files when the corresponding process terminates.
Each invocation of the TCPIP$SNMP_RUN.COM procedure purges these files,
retaining at least the last seven versions (the exact number depends on the value
of the CLUSTER_NODES system parameter).
The log files are located in the SYS$SYSDEVICE:[TCPIP$SNMP] directory along
with the TCPIP$SNMP_CONF.DAT file, which is a text representation of the
SNMP configuration data generated by the master agent during startup.
The contents of the SNMP log files are written to
SYS$SYSDEVICE:[TCPIP$SNMP] when the process stops or when you stop
it (for example, by entering the STOP/ID=xxx command). After a process restarts,
it creates a new version of the files. If a process executes without errors, *.ERR
files might not be created.
Writing to SYS$OUTPUT and SYS$ERROR from custom subagents is controlled
by qualifiers on the RUN command in the TCPIP$EXTENSION_MIB_RUN.COM
procedure. See Chapter 3 for information about including extension subagent
commands in the startup procedure.
Custom subagents that do not write to SYS$OUTPUT and SYS$ERROR might
not produce a .LOG or .ERR file.
6–2 Troubleshooting eSNMP Problems
Download from Www.Somanuals.com. All Manuals Search And Download.
Troubleshooting eSNMP Problems
6.3 Log Files
TCP/IP Services does not support writing log files to locations other than the
SYS$SYSDEVICE:[TCPIP$SNMP] directory.
The log files contain startup and event information and additional messages,
depending on the logging level specified for an agent. The SNMP logging facility
uses three logging levels:
•
•
•
TRACE (logs trace, warning, and error messages)
WARNING (logs warning and error messages)
ERROR
For the master agent and standard subagents, the logging level is WARNING.
Log files for these processes include messages for WARNING and ERROR
events. The chess example does not have a default log level. Therefore, no log
messages appear. To specify a default log level for custom subagents, you can use
the standard API call set_debug_level (see Chapter 5 for more information).
Because the chess example subagent does not use a default, messages are
captured only if you specify tracing. For information about getting trace logs,
refer to the Compaq TCP/ IP Services for OpenVMS Management guide.
Troubleshooting eSNMP Problems 6–3
Download from Www.Somanuals.com. All Manuals Search And Download.
Download from Www.Somanuals.com. All Manuals Search And Download.
Index
A
F
AgentX protocol, 1–2
API functionality, 1–6
ASN.1 files, 3–5
free_oct support routine, 5–55
free_oid support routine, 5–50
free_varbind_data support routine, 5–56
C
G
C compiler, 3–1
*_get method routine, 5–20
Chess example
Groups
tree structure, 3–4
MIB, 2–6
clone_buf support routine, 5–51
clone_oct support routine, 5–54
clone_oid support routine, 5–49
cmp_oct support routine, 5–53
cmp_oid support routine, 5–47
cmp_oid_prefix support routine, 5–48
H
Header files, 3–7
Host Resources MIB, 2–1
hrDeviceTable
,
,
2–4
2–5
2–4
hrDiskStorage
hrFSMountPoint
,
D
hrFSTable
hrProcessorFrwID
hrStorageType 2–5
,
2–4
Default timeout value, 6–1
,
2–5
,
objects implemented by TCP/IP Services, 2–1
restrictions to definition, 2–3
E
Error logs, 6–2
hrDeviceTable
,
,
2–4
2–5
2–4
eSNMP, description, 1–1
hrDiskStorage
esnmp_are_you_there interface routine, 5–15
esnmp_capabilites interface routine, 5–12
esnmp_cleanup support routine, 5–65
esnmp_init interface routine, 5–2
ESNMP_LOG support routine, 5–59
esnmp_poll interface routine, 5–14
esnmp_register2 interface routine, 5–7
esnmp_register interface routine, 5–3
esnmp_sysuptime interface routine, 5–18
esnmp_term interface routine, 5–17
esnmp_trap interface routine, 5–16
esnmp_uncapabilities interface routine, 5–13
esnmp_unregister2 interface routine, 5–11
esnmp_unregister interface routine, 5–6
Event logging, 6–2
hrFSMountPoint
,
hrFSTable
,
2–4
hrProcessorFrwID
,
2–5
hrStorageType
,
2–5
I
ifTable
,
2–7
inst2ip support routine, 5–44
instance2oid support routine, 5–40
L
Logging output, 6–2
Extensibility, 1–1
Index–1
Download from Www.Somanuals.com. All Manuals Search And Download.
M
R
Management information base (MIB), 1–1
Master agent, 1–1
_ _restore_progname support routine, 5–63
RFCs
mem2oct support routine, 5–52
method routines
1155, 2–7, 3–1, 3–2, 4–6
1213, 2–5
routine reference, 5–19 to 5–24
MIB browser, 4–1
1514, 2–1, 2–5
1901 - 1908, 1–8
1902, 3–1, 3–2, 4–6
1907, 2–6, 2–7
command examples, 4–6
command flags, 4–2
command parameters, 4–1
data types, 4–5
2089, 1–8
2741, 1–2
using, 4–1
MIBCOMP
S
command example, 3–6
command syntax, 3–5
MIB compiler functionality, 1–7
MIB II, 2–5
*_set method routine, 5–22
set_debug_level support routine, 5–57
_ _set_progname support routine, 5–62
set_select_limit support routine, 5–61
SMI, 3–1
groups supported under TCP/IP Services, 2–6
ifTable
,
2–7
assigning ID codes, 3–2
hierarchical tree structure, 3–1
registering ID codes, 3–2
objects defined under TCP/IP Services, 2–6
restrictions to definition, 2–6
sysObjectID
,
2–6
2–7
snmpi utility, 3–7
sysORTable
,
sprintoid support routine, 5–39
sysORTable object, 2–6
tree structure, 3–2
str2oid support routine, 5–38
MIBs
Structure of management information
Host Resources, 2–1
MIB II, 2–5
provided with TCP/IP Services, 2–1
subtrees, 3–2
See SMI
Subagent error limit, 6–1
Subagents, 1–1
including in startup and shutdown, 3–12
writing, 1–5, 3–5
Subtrees, 3–2
MIB specifications
creating, 3–1
MIB variable fields, 3–10
mosy utility, 3–7
registering, 3–4
subtree_TBL.C output file, 3–9
subtree_TBL.H output file, 3–7
support routines
O
routine reference, 5–30 to 5–65
Object identification codes (See OIDs)
Object library files, 1–6
Object tables, 3–7
oid2instance support routine, 5–42
OIDs
sysObjectID
,
2–6
2–7, 5–12
sysORTable
,
sysORTable object, 2–6
T
assigning, 3–2
o_counter support routine, 5–37
o_integer support routine, 5–31
o_octet support routine, 5–33
o_oid support routine, 5–34
o_string support routine, 5–35
Timeout, default, 6–1
Trap messages
data types, 4–5
receiving, 4–13
sending and receiving, 4–8
setting up a trap service, 4–12
Trap receiver, 4–1
P
command parameters, 4–12
examples, 4–13
running, 4–12
_ _parse_progname support routine, 5–64
_ _print_varbind support routine, 5–60
Problems
Trap sender, 4–1
See Troubleshooting features
command examples, 4–11
command flags, 4–10
Index–2
Download from Www.Somanuals.com. All Manuals Search And Download.
Trap sender (cont’d)
command parameters, 4–9
running, 4–9
Troubleshooting features, 6–1
W
Writing subagents
compiling, 3–5
creating source files, 3–5
including in startup and shutdown, 3–12
linking and building, 3–11
object tables, 3–7
U
UNIX utilities, 3–7
using ASN.1, 3–5
using UNIX utilities, 3–7
Index–3
Download from Www.Somanuals.com. All Manuals Search And Download.
Download from Www.Somanuals.com. All Manuals Search And Download.
|