Internet Draft Andy Bierman
Cisco Systems, Inc.
15 February 2001
Script Execution Environment Specification
For Distributed Management Platforms
<draft-bierman-disman-see-00.txt>
Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026 [RFC2026].
Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF), its areas, and its working groups. Note that other groups
may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet- Drafts as reference material
or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Distribution of this document is unlimited. Please send comments to the
author <abierman@cisco.com>.
1. Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
Internet Draft SEE Specification February 2001
2. Abstract
This memo defines an experimental portion of the Management Information
Base (MIB) for use with network management protocols in the Internet
community. In particular, it describes managed objects used for
characterizing and configuring a well-constrained execution environment
for the Script MIB [RFC2592], suitable for use on agent and mid-level
manager platforms.
3. Table of Contents
1 Copyright Notice ................................................ 1
2 Abstract ........................................................ 2
3 Table of Contents ............................................... 2
4 The SNMP Network Management Framework ........................... 4
5 Overview ........................................................ 5
5.1 Current Script Environment Components ......................... 6
5.2 New Script Environment Components ............................. 7
5.3 Problems That Scripts Can Address ............................. 9
5.4 Solution Approach ............................................. 10
5.5 Terms ......................................................... 10
5.6 Relationship to the Script MIB ................................ 12
5.7 Relationship to the Scheduling MIB ............................ 12
6 System Description .............................................. 12
6.1 Execution Environment Features ................................ 15
6.1.1 Script Language ............................................. 15
6.1.2 Application Profiles ........................................ 15
6.1.3 System Libraries ............................................ 16
6.1.4 Environment Variables ....................................... 17
6.1.5 Object Identifier Expressions ............................... 17
6.1.6 SNMP PDU Generation and Reception ........................... 17
6.1.7 Management Task Debugging Support ........................... 18
6.2 Script Execution Environment MIB .............................. 18
7 Definitions ..................................................... 19
7.1 Programming Language .......................................... 19
7.1.1 Tokens ...................................................... 19
7.1.2 Keywords .................................................... 20
7.1.3 Data Types .................................................. 20
7.1.3.1 Mapping of the 'BITS' Data Type ........................... 21
7.1.3.2 Mapping of the 'boolean' Data Type ........................ 22
7.1.3.3 Mapping of the 'char' Data Type ........................... 23
7.1.3.4 Mapping of the 'float' Data Type .......................... 23
7.1.3.5 Mapping of the 'int' Data Type ............................ 24
7.1.3.6 Mapping of the 'long' Data Type ........................... 24
7.1.3.7 Mapping of the 'OID' Data Type ............................ 25
Expires August 15, 2001 [Page 2]
Internet Draft SEE Specification February 2001
7.1.3.8 Mapping of the 'STRING' Data Type ......................... 26
7.1.3.9 Mapping of the 'uint' Data Type ........................... 27
7.1.3.10 Mapping of the 'ulong' Data Type ......................... 28
7.1.4 Local Variables ............................................. 28
7.1.5 Identifiers ................................................. 29
7.1.5.1 Mapping of the 'identifier' Token ......................... 30
7.1.5.2 Identifier Scope .......................................... 30
7.1.6 Constants ................................................... 30
7.1.7 OBJECT IDENTIFIER Expressions ............................... 32
7.1.7.1 Expression Forms .......................................... 32
7.1.7.2 OID Fragment Data Representations ......................... 33
7.1.7.3 OID Expression Examples ................................... 34
7.1.8 Extended BNF Notation ....................................... 36
7.2 Environment Variables ......................................... 47
7.2.1 Predefined Environment Variables ............................ 48
7.2.1.1 Agent Scope ............................................... 48
7.2.1.2 Group Scope ............................................... 48
7.2.1.3 Task Scope ................................................ 48
7.3 Runtime Execution Model ....................................... 49
7.3.1 Trigger Frame ............................................... 50
7.4 Application Profiles .......................................... 52
7.4.1 Watched Variable Profile .................................... 52
7.4.2 Periodic Profile ............................................ 55
7.4.3 Calendar Profile ............................................ 58
7.4.4 Notification Filter Profile ................................. 60
7.4.4.1 Example Notification Filter Script ........................ 64
7.4.5 Notification Receiver Profile ............................... 69
7.4.6 Virtual Get Profile ......................................... 73
7.4.7 Manual Profile .............................................. 75
7.5 System Libraries .............................................. 77
7.5.1 Library Versioning .......................................... 78
7.5.2 Library Documentation Requirements .......................... 79
7.5.2.1 Mapping of the LIBRARY-TYPE Macro ......................... 81
7.5.2.2 Mapping of the 'func-def' Construct ....................... 84
7.5.2.3 Library Versioning Example ................................ 86
7.6 Log Message Formats ........................................... 88
7.7 Script Execution Environment MIB .............................. 88
7.8 Initial System Library Definitions ............................ 129
8 External MIB Implementation Requirements ........................ 164
8.1 Script MIB .................................................... 164
8.1.1 Mapping of the smLangTable .................................. 164
8.1.2 Mapping of the smExtsnTable ................................. 165
8.1.2.1 Entry for the SEE MIB ..................................... 165
8.1.2.2 Entry for Each System Library ............................. 166
8.1.3 Mapping of the smScriptTable ................................ 166
Expires August 15, 2001 [Page 3]
Internet Draft SEE Specification February 2001
8.1.4 Mapping of the smCodeTable .................................. 167
8.1.5 Mapping of the smLaunchTable ................................ 168
8.1.6 Mapping of the smRunTable ................................... 168
8.1.7 Mapping of the Script MIB Notifications ..................... 169
8.2 Scheduling MIB ................................................ 169
8.2.1 Mapping of the schedLocalTime object ........................ 169
8.2.2 Mapping of schedTable ....................................... 169
9 Open Issues ..................................................... 171
10 Intellectual Property .......................................... 173
11 References ..................................................... 174
12 Security Considerations ........................................ 177
13 Author's Address ............................................... 177
14 Full Copyright Statement ....................................... 178
4. The SNMP Network Management Framework
The SNMP Management Framework presently consists of five major
components:
o An overall architecture, described in RFC 2571 [RFC2571].
o Mechanisms for describing and naming objects and events for the
purpose of management. The first version of this Structure of
Management Information (SMI) is called SMIv1 and described in
RFC 1155 [RFC1155], RFC 1212 [RFC1212] and RFC 1215 [RFC1215].
The second version, called SMIv2, is described in RFC 2578
[RFC2578], RFC 2579 [RFC2579] and RFC 2580 [RFC2580].
o Message protocols for transferring management information. The
first version of the SNMP message protocol is called SNMPv1 and
described in RFC 1157 [RFC1157]. A second version of the SNMP
message protocol, which is not an Internet standards track
protocol, is called SNMPv2c and described in RFC 1901 [RFC1901]
and RFC 1906 [RFC1906]. The third version of the message
protocol is called SNMPv3 and described in RFC 1906 [RFC1906],
RFC 2572 [RFC2572] and RFC 2574 [RFC2574].
o Protocol operations for accessing management information. The
first set of protocol operations and associated PDU formats is
described in RFC 1157 [RFC1157]. A second set of protocol
operations and associated PDU formats is described in RFC 1905
[RFC1905].
o A set of fundamental applications described in RFC 2573
[RFC2573] and the view-based access control mechanism described
Expires August 15, 2001 [Page 4]
Internet Draft SEE Specification February 2001
in RFC 2575 [RFC2575].
A more detailed introduction to the current SNMP Management Framework
can be found in RFC 2570 [RFC2570].
Managed objects are accessed via a virtual information store, termed
the Management Information Base or MIB. Objects in the MIB are
defined using the mechanisms defined in the SMI.
This memo specifies a MIB module that is compliant to the SMIv2. A
MIB conforming to the SMIv1 can be produced through the appropriate
translations. The resulting translated MIB must be semantically
equivalent, except where objects or events are omitted because no
translation is possible (use of Counter64). Some machine readable
information in SMIv2 will be converted into textual descriptions in
SMIv1 during the translation process. However, this loss of machine
readable information is not considered to change the semantics of the
MIB.
5. Overview
The Script MIB [RFC2592] and Scheduling MIB [RFC2591] provide
standardized mechanisms to delegate and manage remote procedural logic
in the form of scripts. These MIBs are intentionally independent of any
particular programming language or execution environment.
Unfortunately, this has hindered deployment of these MIBs in SNMP
manageable networking devices. If application developers cannot reuse
script logic on different platforms, there is little incentive for them
to initially invest in this technology.
There is a need for a standardized programming language and well-
constrained execution environment, for use with these MIBs, suitable for
implementation on embedded or open SNMP agent platforms and distributed
mid-level manager platforms.
A well-constrained architecture and operational model for extensible
procedural logic will provide better mechanisms to cope with some of the
inherent complexities of network device management.
Expires August 15, 2001 [Page 5]
Internet Draft SEE Specification February 2001
5.1. Current Script Environment Components
The Script MIB and Scheduling MIB already provide some standard
execution environment features. Most of these components are retained in
the new script execution environment.
Figure 1: Current Scripting Components
----------------------------------------
+--------------------------------+
| Script MIB | Scheduling MIB
| +----------+ +-----------+ |
| | | | | | +-------------+
| | Language | | Language | | | local time |
| | Registry | | Extension | | +-------------+
| | | | Registry | |
| +----------+ +-----------+ | +-------------+
| | | scheduler |
| | +-------------+
| +---------+ +---------+ |
| | Script | | Script | |
| | Storage | | Launch | |
| +---------+ +---------+ |
| +---------+ +---------+ |
| | Script | | Script | |
| | Traps | | Run Log | |
| +---------+ +---------+ |
| |
+--------------------------------+
+-------------------+
| Host and Target |
| Platform |
+-------------------+
The Script MIB components (see figure 1) currently include registries to
enumerate languages and language extensions supported by the agent.
There are also mechanisms to transfer and store scripts. These
components of the Script MIB are used by the SEE MIB defined in this
document. The rest of the functionality from the Script MIB is either
replaced by the SEE MIB or removed.
The Scheduling MIB includes a time of day scalar object and a calendar-
style scheduler. This MIB is used in the SEE MIB (in the 'Calendar'
application profile) in the same manner as the Script MIB.
Expires August 15, 2001 [Page 6]
Internet Draft SEE Specification February 2001
5.2. New Script Environment Components
An improved framework is needed to support evolutionary extensions to
the execution environment. New application profiles and system libraries
need to be added over time, in a controlled manner. The current script
launch and run mechanisms do not provide enough automated features or
enough traditional programming environment features. There is too much
manual control and not enough embedded control of script execution
environment. The script execution defined in this document adds several
new components to the scripting execution environment (see figure 2).
Figure 2: Proposed Scripting Components
-----------------------------------------
+--------------------------------+------------------+
| Script MIB | Scheduling MIB |
| +----------+ +-----------+ | |
| | | | | | +-------------+ |
| | Language | | Language | | | local time | |
| | Registry | | Extension | | +-------------+ |
| | | | Registry | | +-------------+ |
| +----------+ +-----------+ | | scheduler | |
| | +-------------+ |
| +----------------+------------------+
| +---------+ |
| | Script | | +-------------+ +---------+
| | Storage | | | application | | task |
| +---------+ | | profiles | | control |
| | +-------------+ +---------+
+---------------+ | environment | | task |
| variables | | logging |
+-------------+ +-------------+ +---------+
| programming | | OID alias & | | task |
| language | | expressions | | traps |
+-------------+ +-------------+ +---------+
+-------------+ | system |
| data types | | libraries |
+-------------+ +-------------+
+-----------+
+-+---------+ |
+----------+ +-+---------+ | |
| Host | | Target | +-+
| Platform | | Platforms +-+
+----------+ +-----------+
Expires August 15, 2001 [Page 7]
Internet Draft SEE Specification February 2001
Programming Language
A standard programming language is needed in order to increase the
likelihood that a single script will be usable on multiple
platforms.
Data Types
Special data types (such as BITS, OID, and STRING) are needed to
simplify SNMP related programming logic. A floating-point data type
is also needed for increased numeric range and support for non-
integral numbers. This data type needs to be optional to
accommodate embedded platforms without this capability.
Application Profiles
A small set of specialized application profiles are needed as part
of an overall execution environment framework.
Environment Variables
A unix-style environment variable facility is needed to pass named
parameters to tasks. The string variables need to be sharable
between tasks in a controlled way.
OID Aliases and Expressions
Special facilities are needed to simplify the manipulation of
OBJECT IDENTIFIERs.
System Libraries
A structured set of specialized functional extensions is needed, in
the form of libraries of functions, that may be invoked from
scripts. These functions provide access to the underlying system
and SNMP engine features.
Task Control
New script execution control mechanisms are needed to allow
additional (automatic) modes of task invocation, within an
execution environment framework.
Task Logging
New task logging facilities and debug trace requirements are needed
to allow script text output to be collected and examined by an
external application, as script results and/or debugging
information.
Task Traps
New 'task' notifications are needed to replace the 'script'
notifications, in order to the change the OBJECTS clause.
Expires August 15, 2001 [Page 8]
Internet Draft SEE Specification February 2001
5.3. Problems That Scripts Can Address
A powerful scripting environment can be used on mid-level managers
and/or large networking devices to address some important network
management issues.
Reduce Centralized Polling
Current agent polling strategies, the limited data definition
capabilities of SMIv2, and the arbitrary complexity of particular
network devices, make it impractical to poll MIBs via SNMP (from a
centralized management station) exclusively to monitor and control
these devices. Better mechanisms are needed to reduce network
device polling latency, overhead, and necessity.
Reduce Device and Mechanism Complexity
It is difficult to manage a large group of devices as a class
(i.e., 'network-wide' configuration), with the current SNMP
management framework. New mechanisms are needed to provide a
stable and generic device and mechanism independent programmable
interface. Such an interface may need to be arbitrarily complex,
since actual feature implementations are very likely to have only
device and mechanism specific management interfaces and (internal)
instrumentation interfaces. Abstraction mechanisms are needed to
better manage the device and mechanism specific complexity inherent
in each network device.
Task Automation
It is desirable to automate small and medium sized device
management and monitoring tasks by embedding extended control logic
in network devices and/or mid-level managers. This can allow
device and network conditions to be monitored and acted upon
intelligently, even when network connectivity is lost between a
centralized management application and the managed device.
Incident Response Latency
It is desirable to reduce the time and effort required to respond
to changes in network conditions or device behavior (e.g.,
unauthorized or unintended configuration changes and bugs in the HW
or SW). Even when the network is stable, limitations due to
polling overhead and network scale introduce considerable incident
detection latency into network management. It is possible to
dramatically reduce the latency for some incident types to
virtually zero time, by providing awareness and even remedy
handling 'inline' with the capabilities of the network device
itself.
Expires August 15, 2001 [Page 9]
Internet Draft SEE Specification February 2001
5.4. Solution Approach
This document conceptually extends the Script MIB, in order to configure
and control a specialized execution environment, suitable for networking
devices or mid-level managers with SNMP agents and/or CLI interfaces.
The specified programming language requirements and execution
environment are intended for use in SNMP agents which also implement the
Script MIB and (optionally) the Scheduling MIB [RFC2591].
The task invocation control mechanisms defined in the Script MIB (i.e.
smLaunchTable and smRunTable) are no longer used to execute scripts.
The management task control table (seeTaskControlTable) replaces the
'manual' execution model defined in the Script MIB with a small set of
automated application profiles.
There are difficult and subjective trade-offs to be made between
richness of features and ease of deployment. This document is intended
to be a relatively simple, but not minimal, starting point for this
work.
5.5. Terms
This document uses some terms that need introduction:
Application Profile
The set of execution environment characteristics, intended to
support a specific application type, which is shared by all
management tasks of the same application type. Each application
profile defines its own:
- functional requirements (e.g. purpose)
- system runtime permissions (e.g. 'max-access')
- local SNMP engine access requirements
- target SNMP engine restrictions
- invocation conditions (e.g. trigger event type)
- configuration requirements (e.g. MIB parameters)
- invocation inputs (e.g. read-only environment variables)
- invocation outputs (e.g. script return value)
- logging and debugging requirements
- implementation requirements and restrictions
The initial set of application profiles is defined in section 7.4.
Base Fragment
This term refers to an OBJECT IDENTIFIER fragment which identifies
Expires August 15, 2001 [Page 10]
Internet Draft SEE Specification February 2001
a position in the MIB tree, starting from the root. Base fragments
may contain instance A 'complete' base fragment refers to an OBJECT
IDENTIFIER fragment which identifies a terminal node, and therefore
a single object (but potentially many instances) in the MIB tree.
An 'incomplete' base fragment refers to an OBJECT IDENTIFIER which
identifies an (inaccessible) interior node, and therefore
potentially many objects in the MIB tree.
Execution Environment
This term refers to the entire set of services which the SEE agent
provides to a management task.
Host Engine
Also 'Host' or 'Host SNMP Engine'; Refers to the SNMP agent which
contains the Script, Scheduling, and SEE MIBs, and provides the
script execution platform.
Instance Fragment
This term refers to an OBJECT IDENTIFIER fragment which identifies
all or part of the instance portion of a particular MIB object, or
set of objects with similar indexing. An instance fragment must be
appended to a complete base fragment to identify a specific
instance of a MIB object. A 'complete' instance fragment is an
OBJECT IDENTIFIER fragment, which when appended to a complete base
fragment, represents potentially one instance of one object in the
MIB tree. An 'incomplete' instance fragment refers to an OBJECT
IDENTIFIER fragment, which when appended to a complete base
fragment, represents potentially many instances of one object in
the MIB tree.
Management Task
The conceptual 'container' of work, running in the script execution
environment, which is represented in MIBs as the set of control
parameters, and procedural logic needed to accomplish a pre-defined
task. An individual script can be used for an arbitrary number of
management tasks, with each task running in its own execution
context.
OID Alias
This term refers to a user-defined OBJECT IDENTIFIER string
replacement token. OBJECT IDENTIFIER to identifier token mappings
are configured in the seeOidAliasTable.
Target Engine
Also 'Target' or 'Target SNMP Engine'; Refers to one of potentially
Expires August 15, 2001 [Page 11]
Internet Draft SEE Specification February 2001
many SNMP engines which a script may act upon, which are
potentially different than the Host Engine.
Trigger Event
The type of system behavior that will cause the agent to start
execution of a particular management task.
Trigger Frame
The execution context for a single invocation of a management task.
A trigger frame also defines a time interval which begins with the
start of the trigger event, and ends when all processing on behalf
of that trigger event is completed.
Type Identifier
A textual string used to associate specific encoding algorithms
with particular STRING values. Certain system library functions
(e.g. snmp_getnext) use these string tokens to identify the actual
types of retrieved MIB objects. Refer to the SeeTypeIdentifier
textual convention (in the SEE-MIB module) for details.
5.6. Relationship to the Script MIB
Portions of the Script MIB are utilized in the SEE MIB defined in this
document. The SEE MIB replaces the script invocation functionality and
the notifications, but retains the language registries, script download
and storage facilities, error codes, and MIB table indexing structure.
Refer to section 8.1 for details.
5.7. Relationship to the Scheduling MIB
The Scheduling MIB is utilized in the SEE MIB defined in this document
in the same manner it is used in the Script MIB (e.g. to schedule script
invocation at a specified time of day).
Implementation of every object in this MIB (but not all possible values
for every object) is required by implementations of the SEE MIB that
support the 'Calendar' application profile. Refer to section 8.2 for
details.
6. System Description
This section describes the components and functional behavior of the
script execution environment and associated script language.
Expires August 15, 2001 [Page 12]
Internet Draft SEE Specification February 2001
Figure 3: Current Device Management Model
------------------------------------------
+---------+ +---------+ +---------+
| | | | | |
| Mgmt | | Mgmt | | Mgmt |
| App A | | App B | | App C |
| | | | | |
+---------+ +---------+ +---------+
| | |
Access | | |
Mechanisms | | |
V V V
+---------------------------+
| System Instrumentation |
+---------------------------+
Network Device n
Currently, networks are managed with a mixture of specialized management
applications, using a variety of access mechanisms, such as a command
line interface (CLI) or a a programmable interface such as SNMP, to
access device instrumentation and configuration directly.
A "meta-logic" management layer is needed, which would enable small
procedural scripts to be executed in response to scheduled and
unscheduled events, on behalf of one or more network devices. These
scripts cannot be used to create new instrumentation on a platform, but
rather to monitor the existing instrumentation and control the existing
configuration mechanisms.
This meta-logic layer needs to be as platform-independent as possible.
This document defines two modes of operation for an agent to address
this requirement. In the 'local mode', (see figure 4) the host SNMP
engine and the target SNMP engine are the same, and in 'remote mode',
(see figure 5) they are different values. Most of the application
profiles defined in this document can be used in either mode, but some
profiles (e.g Notification Filter) only apply to the local mode.
Expires August 15, 2001 [Page 13]
Internet Draft SEE Specification February 2001
Figure 4: 'Local Mode' SEE Platform
-------------------------------------
+---------+ +---------+ +---------+
| | | | | |
| Mgmt | | Mgmt | | Mgmt |
| App A | | App B | | App C |
| | | | | |
+---------+ +---------+ +---------+
| | |
Access | | |
Mechanisms | | |
| V |
| +----------------+ |
| | SEE/Script MIB | |
V | Mgmt Layer | V
+----+----------------+----+
| System Instrumentation |
+--------------------------+
Target Platform n
Figure 5: 'Remote Mode' SEE Platform
-------------------------------------
+---------+ +---------+ +---------+
| | | | | |
| Mgmt | | Mgmt | | Mgmt |
| App A | | App B | | App C |
| | | | | |
+---------+ +---------+ +---------+
| | |
Access | | |
Mechanisms | | |
| V |
| +----------------+ |
| | SEE/Script MIB | |
| | Mgmt Layer | |
| +----------------+ |
| | |
V V V
+----+----------------+----+
| System Instrumentation |
+--------------------------+
Target Platform n
Expires August 15, 2001 [Page 14]
Internet Draft SEE Specification February 2001
6.1. Execution Environment Features
The script execution environment defined in this document provides a
specialized execution with the following features.
6.1.1. Script Language
A simple programming grammar is needed in order to constrain the
capabilities of the language and make it easier to use. The grammar
defined in this document is similar to the ANSI C Programming Language
[ANSI_C_89].
Many complex capabilities of typical programming languages are removed,
such as pre-processing, address manipulation, arbitrarily complex data
structures, and complex data scoping. Only essential features are
provided, such as full arithmetic and boolean expression evaluation,
conditional iteration, assignment, variable and function declarations, a
small set of basic data types and operators.
The C programming language is also extended, in order to simplify some
of the operations specific to SNMP based network management
applications. Three special (non-scalar) data types are added, called
'BITS', 'OID', and 'STRING', which correspond to the BITS, OBJECT
IDENTIFIER, and OCTET STRING ASN.1 data types. A special construct,
called an <OID-expression>, is added to the language to allow complex
OBJECT IDENTIFIER manipulation using a minimal amount of code.
6.1.2. Application Profiles
The limited number of application profiles defined in this document is
intended as a starting point for this work. It is expected that this
set may be extended in the future, outside the scope of this document.
This section is intended to introduce each application profile. Refer
to section 7.4 for more details.
Watched Variable Profile
This application profile allows a script to be invoked when the
value of (potentially) any instance of a specified MIB object
changes value. This mode is intended for monitoring objects which
are not expected to change frequently, such as an enumerated status
object (e.g. ifOperStatus). The 'periodic' application profile
should be used instead to examine objects which are likely to
change frequently, such as an octet or packet counter (e.g.
ifInOctets).
Expires August 15, 2001 [Page 15]
Internet Draft SEE Specification February 2001
Periodic Profile
This application profile allows a script to be invoked once per
specified time interval. This mode is intended for monitoring
arbitrarily complex system conditions on a periodic basis.
Calendar Profile
This application profile allows a script to be invoked via the
Scheduling MIB [RFC2591]. This mode is intended for monitoring
arbitrarily complex system conditions on an ad-hoc basis.
Notification Filter Profile
This application profile allows a script to be invoked just before
a particular notification is generated, acting as a filter for the
local notification originator application, within the SNMP engine
hosting the SEE MIB. This mode is intended for arbitrarily complex
event-focused monitoring. A script running in this application
profile may also suppress notifications, augment notifications with
additional varbinds, and/or take immediate action on the outgoing
notification.
Notification Receiver Profile
This application profile allows a script to be invoked when a
particular notification is received by the local SNMP engine. This
mode is intended for arbitrarily complex notification-focused
monitoring of remote notification originator applications.
Virtual Get Profile
This application profile allows a script to be invoked when a
particular MIB object is retrieved by an NMS application. The
script must provide a new return value upon each invocation. This
mode is intended to allow a read-only script to be used to evaluate
arbitrarily complex expressions.
Manual Profile
This application profile allows a script to be invoked when a
particular MIB object is set (run-button) by an NMS application.
This mode is intended to replace the existing manual run-mode
provided in the Script MIB. A script run manually from the Script
MIB cannot utilize any of the execution environment features
defined in this MIB.
6.1.3. System Libraries
The execution environment must be useful and implementable on embedded
network devices and open platforms. System libraries allow specific
Expires August 15, 2001 [Page 16]
Internet Draft SEE Specification February 2001
functionality to be added incrementally to the execution environment.
They allow a script to be easily ported from one execution platform to
another one, since each library function is intended to behave the same
across all implementations.
System libraries are the primary feature extensibility mechanism in the
execution environment. They are conceptually equivalent to ANSI C
Function Libraries and can provide the same sort of functionality
contained in the scripts themselves. However, their source code is not
visible for debugging purposes and they cannot be installed by
management applications at runtime.
6.1.4. Environment Variables
Environment variables are label-identified string variables available to
scripts for inspection and data storage. A set of pre-defined
environment variables are visible to a script, depending on the
application profile and task configuration. Most system environment
variables are used as read-only script invocation parameters, either
common to all application profiles, or specific to one or more profiles.
An exception is the special read-write _SCRATCHPAD variable, which
provides a static amount of persistent memory for each management task
to use across task invocations. Management tasks can be configured to
utilize an arbitrary number of additional environment variables.
Environment variables can be defined at three different scoping levels
(agent, group, and task) in order to share them between management tasks
in a controlled fashion. Write access to environment variables (if
granted at all) can be restricted to an individual task or task group.
6.1.5. Object Identifier Expressions
SNMP-specific applications must be capable of manipulating OBJECT
IDENTIFIER values in various ways. The programming language provides a
powerful OBJECT IDENTIFIER expression syntax, and a new 'OID' data type.
The execution environment also provides for 'OID Alias' string
constants, as configured in the seeOidAliasTable. These features allow
developers to write simpler and more readable script logic in order to
manipulate OBJECT IDENTIFIER values in complex ways.
6.1.6. SNMP PDU Generation and Reception
The execution environment includes system libraries which allow a script
(if permitted by its application profile) to cause the local SNMP engine
to generate SNMP PDUs (e.g. notifications) on its behalf. Only
Expires August 15, 2001 [Page 17]
Internet Draft SEE Specification February 2001
synchronous command execution (for each management task) is provided at
this time. Asynchronous GetResponse PDU handling is a topic left for
future work.
6.1.7. Management Task Debugging Support
The execution environment provides four different modes of operation for
each application profile: normal, trace, debug and validation modes.
In normal mode, only the messages generated by the management task
itself will appear in the log file for that task. All system function
calls behave normally.
In trace mode, system messages (in addition to any messages generated by
the management task itself) will appear in the log file for that task.
All system function calls behave normally, except that each invocation
also causes a trace message to be generated. Log message formats are
defined to allow some level of machine parsing by applications. Task
invocation start and stop events are also recorded in the log output in
this mode.
In debug mode, system messages are logged, just as in the trace mode,
except that system library functions are not permitted to actually emit
any PDUs or write any system configuration data. This mode allows some
degree of protected debugging capability, in addition to the unprotected
capabilities of the trace mode.
In validation mode, no code is actually executed. Instead, the agent
will examine the entire script for correctness. A 'run button' MIB
object is used by an application to cause the agent to perform a
validation check on a particular script. Summary information, and any
error messages will be output to the associated log entry for the task.
6.2. Script Execution Environment MIB
A new MIB module, called the Script Execution Environment (SEE) MIB is
defined to allow a management application to configure management tasks
and execution environment attributes.
Capabilities Group
The MIB includes a small set of scalar objects to help identify the
capabilities of the SEE agent.
Environment Group
This group includes the seeEnvVarTable to configure environment
Expires August 15, 2001 [Page 18]
Internet Draft SEE Specification February 2001
variables and the seeOidAliasTable to configure OID alias strings.
Execution Group
This group includes the seeTaskControlTable to configure management
tasks.
Diagnostics Group
This group includes the seeLogTable to collect management task
logging output.
Notifications Group
The seeTaskAbort and seeTaskAlarm notifications replace the
smScriptAbort and smScriptResult notifications defined in the
Script MIB, because the MIB variables included in the old OBJECTS
clause are no longer used.
7. Definitions
This section defines the system behavior and functional requirements for
conforming implementations.
7.1. Programming Language
This section describes the initial version of a programming language
which can be used in the script execution environment, called the Script
Execution Environment (SEE) Language. It is similar to the ANSI C
language specification.
[ed. - This is intended as a starting point, and is not really specified
in enough detail for a developer to implement the required behavior for
each programming construct. Unless otherwise stated, these constructs
have the same functional requirements as defined in the ANSI C
programming language. There may be some unresolved and un-addressed
technical issues raised by unintended consequences of subsetting and
extending the features found in the C grammar.]
7.1.1. Tokens
The language contains the following token types:
- keyword
- identifier
- string-literal
- operator
- punctuator
Expires August 15, 2001 [Page 19]
Internet Draft SEE Specification February 2001
7.1.2. Keywords
The following keywords are reserved tokens within the language:
- BITS
- boolean
- break
- case
- char
- continue
- default
- do
- else
- float
- for
- if
- IN
- INOUT
- INREF
- int
- long
- OID
- OUT
- return
- STRING
- switch
- uint
- ulong
- void
- while
7.1.3. Data Types
The language supports the following scalar data types:
- boolean
- char
- float
- int
- long
- uint
- ulong
The 'float' data type is optional, and should be supported if the agent
is capable of performing floating point arithmetic.
Expires August 15, 2001 [Page 20]
Internet Draft SEE Specification February 2001
The language also supports the following non-scalar data types:
- BITS == array of boolean
- OID == array of uint
- STRING == array of char
7.1.3.1. Mapping of the 'BITS' Data Type
The 'BITS' data type is a special string variant which allows simplified
manipulation of MIB objects encoded in SNMP messages with the 'BITS'
syntax. It is conceptually equivalent to an array of boolean values,
which are limited to the range (0..1). An agent must support variable
definitions of this data type up to a maximum size of 128 elements, and
should support larger maximum sizes. The intrinsic 'sizeof' function
will return the statically defined maximum size of the specified BITS
variable.
Operators
Individual bit values may be accessed with the array operator (e.g.
'bitvar[3] = 1' to set the 4th bit or 'bitvar[3] = 0' to clear the 4th
bit). The first bit position and the first array element is numbered
zero. Individual bits may also be assigned or compared with variables
of type 'boolean'.
The following operators are valid for variable identifiers of type BITS:
operator function example
----------------------------------------------
= Assignment var1 = var2
== Equals var1 == var2
!= Not Equals var1 != var2
|= Bit OR Assign var1 |= var2
&= Bit AND Assign var1 &= var2
^= Bit XOR Assign var1 ^= var2
<<= Shift Left Assign var1 <<= 4
>>= Shift Right Assign var1 >>= 4
~ Unary 1-s Complement ~var1
! Unary Boolean NOT !var
STRING Conversion
Expires August 15, 2001 [Page 21]
Internet Draft SEE Specification February 2001
Variables of this type are converted to the STRING format, and
associated with the 'BITS' Type Identifier, by encoding a series of
ASCII digits, one for each bit position represented in the BITS object.
If the bit position is set, then the ASCII char '1' is encoded,
otherwise the ASCII char '0' is encoded. Bits are encoded left to right,
in ascending order.
SNMP Message Encoding
Objects of this type are encoded as varbinds in SNMP messages with the
BITS data type.
7.1.3.2. Mapping of the 'boolean' Data Type
The 'boolean' data type is the base data type for the BITS data type.
It is conceptually equivalent to a single bit, which is limited to the
range (0..1). The intrinsic 'sizeof' function will return the constant
'1' for a boolean variable.
The following intrinsic constants are defined to use with the boolean
data type:
TRUE == 1
FALSE == 0
Operators
The following operators are valid for variable identifiers of type
boolean:
operator function example
----------------------------------------------
= Assignment var1 = var2
== Equals var1 == var2
!= Not Equals var1 != var2
|= Bit OR Assign var1 |= var2
&= Bit AND Assign var1 &= var2
^= Bit XOR Assign var1 ^= var2
! Unary Boolean NOT !var
STRING Conversion
Expires August 15, 2001 [Page 22]
Internet Draft SEE Specification February 2001
Variables of this type are converted to the STRING format, and
associated with the 'boolean' Type Identifier, by encoding a single
ASCII digit. If the boolean variable is set, then the ASCII char '1' is
encoded, otherwise the ASCII char '0' is encoded.
SNMP Message Encoding
Objects of this type are encoded as varbinds in SNMP messages with the
INTEGER data type.
7.1.3.3. Mapping of the 'char' Data Type
The 'char' data type is the base data type for the non-scalar STRING
data type. It is conceptually equivalent to an unsigned integer,
limited to the range (0..255). The intrinsic 'sizeof' function will
return the constant '1' for a char variable.
Operators
All operators valid for the 'char' data type in the C language are valid
for this data type.
STRING Conversion
Variables of this type are converted to the STRING format, and
associated with the 'char' Type Identifier, by encoding a single octet
with the value of the char to the ASCII representation for the numeric
value. If no such valid representation exists, then the value is
encoded as an <escape-sequence> token, as defined in section 7.1.8.
SNMP Message Encoding
Objects of this type are encoded as varbinds in SNMP messages as an
OCTET STRING of size '1'.
7.1.3.4. Mapping of the 'float' Data Type
The 'float' data type provides floating point (non-integral) numbers, to
allow ratios and other formulas to be precisely calculated. [ed. - Min
and max values ???] The intrinsic 'sizeof' function will return the
constant '8' for a float variable.
Operators
Expires August 15, 2001 [Page 23]
Internet Draft SEE Specification February 2001
All operators valid for the 'float' data type in the C language are
valid for this data type.
STRING Conversion
Variables of this type are converted to the STRING format, and
associated with the 'float' Type Identifier, by encoding the ASCII
representation of the value of the float variable, using the same
encoding rules as defined for the <floating-constant> construct in
section 7.1.8.
SNMP Message Encoding
This data type is not available in the SMI at this time. Varbinds
representing floating point numbers cannot be encoded in SNMP messages.
7.1.3.5. Mapping of the 'int' Data Type
The 'int' data type provides 32-bit signed integers. Variables of this
type are limited to the value range (-2147483648..2147483647). The
intrinsic 'sizeof' function will return the constant '4' for an int
variable.
Operators
All operators valid for the 'int' data type in the C language are valid
for this data type.
STRING Conversion
Variables of this type are converted to the STRING format, and
associated with all 32-bit signed integer based Type Identifiers (e.g.
'Integer32', 'INTEGER'), by encoding the ASCII string representation for
the numeric value. If the value is less than zero, then the string will
begin with the minus '-' character. Leading zeros are not allowed.
SNMP Message Encoding
Objects of this type are encoded as varbinds in SNMP messages with the
INTEGER data type.
7.1.3.6. Mapping of the 'long' Data Type
The 'long' data type provides 64-bit signed integers. Variables of this
type are limited to the value range ( -2^^63 .. 2^^63-1 ). The
Expires August 15, 2001 [Page 24]
Internet Draft SEE Specification February 2001
intrinsic 'sizeof' function will return the constant '8' for a long
variable.
Operators
All operators valid for the 'long' data type in the C language are valid
for this data type.
STRING Conversion
Variables of this type are converted to the STRING format, and
associated with all 64-bit signed integer based Type Identifiers, by
encoding the ASCII string representation for the numeric value. If the
value is less than zero, then the string will begin with the minus '-'
character. Leading zeros are not allowed.
SNMP Message Encoding
This data type is not available in the SMI at this time. Varbinds
representing large negative numbers cannot be encoded in SNMP messages.
7.1.3.7. Mapping of the 'OID' Data Type
The 'OID' data type is a special string variant which allows simplified
manipulation of MIB objects encoded in SNMP messages with the 'OBJECT
IDENTIFIER' syntax. It is conceptually equivalent to an array of
unsigned integer values, which are limited to the range (0..4294967295).
An agent must support variable definitions of this data type up to a
maximum size of 128 elements, and should support larger maximum sizes.
The intrinsic 'sizeof' function will return the statically defined
maximum size of the specified OID variable.
Individual OID component values may be accessed with the array operator
(e.g. 'oidvar[11] = 4' to set the 12th component to the value '4'). The
first component position and the first array element is numbered zero.
Operators
Individual OID component values may be accessed with the array operator
(e.g. 'oidvar[11] = 4' to set the 12th component to the value '4'). The
first component position and the first array element is numbered zero.
Substrings of type OID, or individual components of type 'uint' may be
appended to a specified OID variable with the "+=" operator. For
example, 'oidvar += 4' creates a new last element in the 'oidvar'
Expires August 15, 2001 [Page 25]
Internet Draft SEE Specification February 2001
variable with the value '4', and 'oidvar += 1.2.3.4' creates 4 new last
elements in the 'oidvar' variable with the values '1'. '2'. '3', and
'4'.
A runtime error will occur if the 'oidvar' variable would exceed its
maximum length if the specified append operation was performed.
The following operators are valid for variable identifiers of type OID:
operator function example
--------------------------------------------------
= Assignment var1 = ifOutOctets.3
< Lexi-Order Less var 1 < var2
> Lexi-Order More var 1 > var2
== Equals var1 == ifInOctets.4
!= Not Equals var1 != var2
+= Append Assign var1 += 1.2.3.4
Variables of this data type may be used in OBJECT IDENTIFIER
expressions, as defined by the <OID-expression> construct in the
Language Definitions sections.
STRING Conversion
Variables of this type are converted to the STRING format, and
associated with all OBJECT IDENTIFIER based Type Identifiers, by
encoding a series of ASCII-encoded integers, separated by the dot '.'
character. Components are encoded left to right, starting with the
first OID component, followed by the dot separator, until there are no
more components. The last component is not terminated with the dot
character. The first character of the string must not be the dot
character.
SNMP Message Encoding
Objects of this type are encoded as varbinds in SNMP messages with the
OBJECT IDENTIFIER data type.
7.1.3.8. Mapping of the 'STRING' Data Type
The 'STRING' data type is a special string variant which allows
simplified manipulation of MIB objects encoded in SNMP messages with any
object based on the 'OCTET STRING' syntax. It is conceptually
equivalent to an array of 'char' values, in which each octet is limited
to the range (0..255).
Expires August 15, 2001 [Page 26]
Internet Draft SEE Specification February 2001
Note that these strings are not zero-terminated. The agent will
maintain an internal length field associated with each string based
object, which may be accessed with the 'strlen' library function. Also,
the leading and trailing double quote characters present in <string-
literal> declarations are not actually stored in STRING variables.
An agent must support variable definitions of this data type up to a
maximum size of 255 elements, and should support larger maximum sizes.
The intrinsic 'sizeof' function will return the statically defined
maximum size of the specified STRING variable.
Operators
Individual STRING character values may be accessed with the array
operator (e.g. 'strvar[11] = 'c' to set the 12'th character to the
character 'c').
The following operators are valid for variable identifiers of type
STRING:
operator function example
------------------------------------------------
= Assignment var1 = "test one"
== Equals var1 == var2
!= Not Equals var1 != var2
+= Append Assign var1 += " test two"
SNMP Message Encoding
Objects of this type are encoded as varbinds in SNMP messages with the
OCTET STRING data type.
7.1.3.9. Mapping of the 'uint' Data Type
The 'uint' data type provides 32-bit unsigned integers. Variables of
this type are limited to the value range (0..4294967295). The intrinsic
'sizeof' function will return the constant "4" for an uint variable.
Operators
All operators valid for the 'unsigned int' data type in the C language
are valid for this data type.
Expires August 15, 2001 [Page 27]
Internet Draft SEE Specification February 2001
STRING Conversion
Variables of this type are converted to the STRING format, and
associated with all unsigned integer based Type Identifiers (e.g.
'Unsigned32', 'Gauge32', 'Counter32'), by encoding the ASCII string
representation for the numeric value. Leading zeros are not allowed.
SNMP Message Encoding
Objects of this type are encoded as varbinds in SNMP messages with the
Unsigned32 data type.
7.1.3.10. Mapping of the 'ulong' Data Type
The 'ulong' data type provides 64-bit unsigned integers. Variables of
this type are limited to the value range ( 0 .. 2^^64-1). The intrinsic
'sizeof' function will return the constant "8" for an uint variable.
Operators
All operators valid for the 'unsigned long' data type in the C language
are valid for this data type.
STRING Conversion
Variables of this type are converted to the STRING format, and
associated with all ASN.1 data types which resolve to a 64-bit unsigned
integer, (such as the 'Counter64' data type) by encoding the ASCII
string representation for the numeric value of the variable. Leading
zeros are not allowed.
SNMP Message Encoding
Objects of this type are encoded as varbinds in SNMP messages with the
Counter64 data type.
7.1.4. Local Variables
Functions may declare an arbitrary number of local variables at the
start of the function, but local variables cannot be declared within
nested blocks within a function. The intrinsic data types are divided
into two groups: 'scalars' and 'non-scalars'.
Scalars
Scalar data types have static sizes, and include the simple base
Expires August 15, 2001 [Page 28]
Internet Draft SEE Specification February 2001
types such as all numeric forms, a single character or a single
bit. These types may also be used in array declarations.
These data types are defined in the same manner as in the ANSI C
language, as defined by the <scalar-declaration> construct in the
language specification. E.g.:
boolean test_bit;
long count, port_counters[20];
int index1, index2;
float avg, last_avg[10], cur_avg[10];
Non-scalars
Non-scalar data types do not have static sizes. Only one class of
non-scalar data type is supported at this time, the linear array.
There are three data types defined in this class: BITS, OID, and
STRING. Each of these intrinsic types is a simple array of a
particular scalar data type. This feature allows these common
structures to be used in simple and complex expressions without the
need for address manipulation operators.
Local variable declarations for these data types must include the
number of array elements (just like in the C language), using an
'array operator' expression. This requirement adds one extra level
of array indexing to the BITS, OID, and STRING data types. These
variables may also be used in complex array declarations. E.g.:
BITS test_bits[18]; /* 1 BITS w/ 18 boolean elements */
OID cntr_oid[32]; /* 1 OID w/ 32 uint elements */
OID cntr_oids[10][32]; /* 10 OIDs w/ 32 uint elements */
STRING username[8]; /* 1 STRING w/ 8 char elements */
STRING usernames[20][8]; /* 20 STRINGs w/ 8 char elements */
7.1.5. Identifiers
Identifier tokens are used to name specific functions, local variables,
environment variables, OID aliases, and type identifiers. They must
follow the format specified in section 7.1.8 for the <identifier>
construct.
Identifiers may be a maximum of 48 characters in length. They may only
be concatenated with operator and punctuator tokens. Identifiers must be
separated by whitespace characters, when they are adjacent to other
Expires August 15, 2001 [Page 29]
Internet Draft SEE Specification February 2001
identifiers, or any keyword, constant, or string-literal tokens.
7.1.5.1. Mapping of the 'identifier' Token
The syntax defined for the <identifier> token applies to the
SeeIdentifierString textual convention, as well as to tokens within SEE
scripts. MIB values of type SeeIdentifierString and SEE <identifier>
tokens with the same value represent the same programming entity.
7.1.5.2. Identifier Scope
Each identifier must be unique within a particular scope. The execution
environment supports three levels of identifier scoping. The higher the
priority number in parenthesis, the higher the precedence when deciding
if an identifier is valid in a given scope.
Agent Scope (1)
Identifiers which are visible to all management tasks in the system
(e.g. OID Aliases have agent scope).
Group Scope (2)
Identifiers, which are only visible within the execution
environment of a specified group of management tasks.
Task Scope (3)
Identifiers, which are only visible within the execution
environment of a specified management task (e.g. the _SCRATCHPAD
environment variable has task scope).
7.1.6. Constants
Constants are permitted in many programming constructs, such as
expressions, switch 'case' statements, and assignment statements.
Constants must only be preceded or followed by operator tokens,
punctuator tokens, or whitespace.
Integer
Leading zeroes are not permitted in integer constants, but they are
permitted in hexadecimal constants. All numeric constants are
positive in value. The minus ('-') unary operator must be used to
represent negative integer values.
The following data types may be used with integer constants:
- boolean
Expires August 15, 2001 [Page 30]
Internet Draft SEE Specification February 2001
- char
- int
- uint
- long
- ulong
The following intrinsic integer constants are defined:
TRUE == 1
FALSE == 0
NO_ERROR == 0
NOT_SET == 1
HALTED == 2
LIFETIME_EXCEEDED == 3
NO_RESOURCES_LEFT == 4
LANGUAGE_ERROR == 5
RUNTIME_ERROR == 6
INVALID_ARGUMENT == 7
SECURITY_VIOLATION == 8
GENERIC_ERROR == 9
TRIGGER_OVERFLOW == 10
Floating Point
Floating point constants are formatted textual strings, which are
used to represent non-integral numbers. Support of floating-point
constants is required if the 'float' data type is supported. Refer
to the <floating-constant> construct for more details.
Character
Character constants consist of a printable character in single
quotes (e.g. 'a'). The following data types may be used with
character constants:
- char
- int
- uint
- long
- ulong
Refer to the <character-constant> construct for more details.
String Literals
String literal tokens are textual strings, which may contain escape
sequences. Only the 'STRING' data type may be used with string
Expires August 15, 2001 [Page 31]
Internet Draft SEE Specification February 2001
literal constants. Refer to the <string-literal> construct for
more details.
Escape Sequences
These special constants are used to identify character sequences
that cannot easily be represented in the source language set. The
grammar supports the "printf" type of escape sequences, such as ""
for a tab character, as well as hexadecimal escape sequences, which
represent arbitrary binary values, including unprintable
characters.
7.1.7. OBJECT IDENTIFIER Expressions
One of the specialized features of the execution environment is the
macro-like capabilities for expressing and manipulating OBJECT
IDENTIFIERs.
7.1.7.1. Expression Forms
An object identifier expression can be defined in several ways, based on
<OID-expression> construct in section 7.1.8. There are two basics forms
of an OBJECT IDENTIFIER expression, the canonical form and the complex
form.
Canonical or Dotted ASCII Form
A well-formed complete OID or OID fragment string, encoded entirely
in the dotted-ASCII OBJECT IDENTIFIER notation, is considered to be
the canonical representation of that OBJECT IDENTIFIER.
This familiar notation is defined as a sequence of numeric
constants (in ASCII representation) in the range (0..4294967295)
separated by the dot ('.') character (e.g. "1.3.6.1.2.1.2.2.1.10").
The string must not begin or end with the dot character. The OID
component sequence is read left to right, and represents an
absolute or relative position in the MIB tree.
Complex Form
A complex OID Expression can be evaluated by the agent to produce
an OID expression in the canonical form. Two different complex OID
expressions cannot be compared, and multiple complex OID
expressions may resolve to the same canonical value. Only one
representation type may be used within a single OID component (i.e.
between the dots). Sub-strings must resolve to some integral
number of OID components, and are allowed to resolve to zero
components.
Expires August 15, 2001 [Page 32]
Internet Draft SEE Specification February 2001
An agent must convert any complex form of an OID String into its
canonical form, before storing it in local script variables of type
'OID', or executing any script function with any parameters of type
'OID'. An agent may wish to preserve complex forms for logging purposes,
but this is not required. The agent will insert or remove the dot
character automatically between sub-strings, as needed, as it converts a
complex string to a canonical string.
7.1.7.2. OID Fragment Data Representations
An object identifier expression component can be defined in the
following ways:
OID Alias Identifier Token Notation
This is the familiar MIB descriptor label representation (e.g.,
'ifInOctets') of an OBJECT IDENTIFIER, in which a single identifier
token represents an arbitrary sequence of OID components. Only OID
alias identifier tokens which are defined and configured in the
seeOidAliasTable will be recognized by the agent.
Environment Variable Notation
The contents of an environment variable string may be used to
represent a OID sub-string Only environment variables which are
defined and configured in the seeEnvVarTable will be recognized by
the agent. The STRING must conform to the rules for a dotted-ASCII
notation OID fragment.
Variable Notation
Local variables of type 'uint' or 'OID' may be used in OBJECT
IDENTIFIER expressions. A 'uint' identifier will resolve to a
single OID component, and a 'OID' identifier will resolve to 0 or
more OID components. If the OID variable contains an empty string,
then the OID component is removed.
Numeric Constant Notation
A string conforming to the syntax for the <decimal-constant>
construct may be used as an OBJECT IDENTIFIER component. The
canonical form must only contain this notation.
Character Constant Notation
A string conforming to the syntax for the <character-constant>
construct may be used as an OBJECT IDENTIFIER component.
Expires August 15, 2001 [Page 33]
Internet Draft SEE Specification February 2001
7.1.7.3. OID Expression Examples
Some valid OID expressions include:
local_oid_var
local_oid_var[2]
ifInOctets.1
ifInOctets.local_uint_var
acmeInOctets.local_uint_var.local_oid_var[4].1.11.2
local_uint_var1.local_uint_var1.2
1.3.1.2.1.6.local_uint_var2.1
seeTaskControlRunMode.3.'j'.'o'.'e'.5.'t'.'a'.'s'.'k'.'5'.11
The following example function demonstrates how local RMON services, OID
aliases, and the complex form of the OID expression can be used to
create a utility function which 'finds' an appropriate entry in the
RMON-2 Application Matrix Table, and returns the OBJECT IDENTIFIERs for
the HTTP alMatrixSD counter objects.
/* semi-hardwired utility function to get the
* RMON-2 alMatrixSDPkts,Octets OIDs for HTTP
* between 2 IPv4 hosts on a specific interface
* from the local RMON agent
*
* returns 0 for success, 1 for failure
*/
uint get_rmon2_http_almatrix_oids (
IN uint if_index,
IN OID src_ip, /* e.g 1.2.3.4 */
IN OID dst_ip, /* e.g. 1.2.3.5 */
OUT OID pkts_oid,
OUT OID octets_oid,
OUT OID rev_pkts_oid,
OUT OID rev_octets_oid)
{
uint ctl_index, nl_pdir_index, al_pdir_index;
/* the OID Alias for alMatrixSDPkts could be
* created via the seeOidAliasTable or inline,
* assume these aliases already created
*
* oid_alias_set("hlMatrixControlEntry",
* 1.3.6.1.2.1.16.15.1.1, TRUE);
* oid_alias_set("alMatrixSDEntry",
* 1.3.6.1.2.1.16.17.1.1, TRUE); */
Expires August 15, 2001 [Page 34]
Internet Draft SEE Specification February 2001
/* get the control row index for an HL control entry
* for the specified index */
ctl_index = rmon_control_index(
"", _TARGET_CONTEXT_NAME, 0, "",
hlMatrixControlEntry, if_index, 1);
if (!ctl_index) {
return 1; /* no hlMatrix collection found */
}
nl_pdir_index = rmon_pdir_index_by_name(
"", _TARGET_CONTEXT_NAME, 0, "", "wild-ether2.ip");
if (!nl_pdir_index) {
return 1; /* protocolDirLocalIndex not found */
}
al_pdir_index = rmon_pdir_index_by_name(
"", _TARGET_CONTEXT_NAME, 0, "", "wild-ether2.ip.tcp.http");
if (!al_pdir_index) {
return 1; /* protocolDirLocalIndex not found */
}
/* check length but not OID component range
* of the src and dest IP address strings */
if (oidlen(src_ip) != 4 || oidlen(dst_ip) != 4) {
return 1; /* wrong OID length */
}
/* construct the counter OID return values
* timemark = 0 to make sure the counter is returned
* make alMatrixSDPkts & Octets OIDs for both directions
*
* alMatrixSDEntry (from [RFC2021]):
* INDEX { hlMatrixControlIndex, alMatrixSDTimeMark,
* protocolDirLocalIndex,
* nlMatrixSDSourceAddress, nlMatrixSDDestAddress,
* protocolDirLocalIndex }
*/
pkts_oid = alMatrixSDEntry.2.ctl_index.0;
pkts_oid += nl_pdir_index.4.src_ip.4.dst_ip.al_pdir_index;
octets_oid = alMatrixSDEntry.3.ctl_index.0;
octets_oid += nl_pdir_index.4.src_ip.4.dst_ip.al_pdir_index;
rev_pkts_oid = alMatrixSDEntry.2.ctl_index.0;
rev_pkts_oid += nl_pdir_index.4.dst_ip.4.src_ip.al_pdir_index;
Expires August 15, 2001 [Page 35]
Internet Draft SEE Specification February 2001
rev_octets_oid = alMatrixSDEntry.3.ctl_index.0;
rev_octets_oid += nl_pdir_index.4.dst_ip.4.src_ip.al_pdir_index;
return 0; /* success */
}
7.1.8. Extended BNF Notation
The following is the extended BNF notation for the grammar with starting
symbol <translation-unit>, This grammar has been derived from text in
Appendix A of the ANSI C definition, version X3.159-1989.
-- C style comments
--
-- note that comments are not actually part of the language
-- comments are relevant is the source char space
-- but not the language token space. The following
-- syntax is defined for completeness, but the <comment>
-- token does not actually exist in the language.
<comment> = "/*" <c-char-sequence> "*/"
<c-char-sequence> =
( <c-char> |
<c-char-sequence> <c-char> )
<c-char> =
any member of the source character set
-- Identifiers
--
-- The <identifier> token defines the syntax for
-- the SeeIdentifierString TC
<identifier> =
( <nondigit> |
<identifier> <digit> |
<identifier> <nondigit> )
<nondigit> =
( "a" .. "z" |
"A" .. "Z" |
"_" ) -- underscore
Expires August 15, 2001 [Page 36]
Internet Draft SEE Specification February 2001
<digit> =
( <nonzero-digit> | "0" )
<nonzero-digit> =
( "1" | "2" | "3" | "4" |
"5" | "6" | "7" | "8" | "9" )
-- Constants
--
-- includes all forms except the <enumeration-constant>
-- double floating point, and long character constants
<constant> =
( <floating-constant> |
<integer-constant> |
<character-constant> )
-- this construct is only present if the 'float'
-- data type is supported
<floating-constant> =
( <fractional-constant> [<exponent-part>] |
<digit-sequence> <exponent-part> )
<fractional-constant> =
( [<digit-sequence>] "." <digit-sequence> |
<digit-sequence> "." )
<exponent-part> =
( "E" [<sign>] <digit-sequence> |
"e" [<sign>] <digit-sequence> )
<sign> =
( "+" | "-" )
<digit-sequence> =
( <digit> |
<digit-sequence> <digit> )
<integer-constant> =
( <decimal-constant> | hexadecimal-constant> )
<decimal-constant> =
( <nonzero-digit> | <decimal-constant> <digit> )
Expires August 15, 2001 [Page 37]
Internet Draft SEE Specification February 2001
<hexadecimal-constant> =
( "0x" <hexadecimal-digit> |
"0X" <hexadecimal-digit> |
<hexadecimal-constant> <hexadecimal-digit> )
<hexadecimal-digit> =
( <digit> | <hex-letter> )
<hex-letter> =
( "a" | "b" | "c" | "d" | "e" | 'f" |
"A" | "B" | "C" | "D" | "E" | 'F" )
<character-constant> =
"'" <c-char-sequence> "'"
-- Escape Sequences
--
-- does not includes octal constants
<escape-sequence> =
( <simple-escape-sequence> |
<hexadecimal-escape-sequence> )
<simple-escape-sequence> =
( "\'" | -- backslash, single quote
"\"" | -- backslash, double quote
"\?" | -- backslash, question mark
"\\" | -- backslash, backslash
"\a" | -- backslash, lowercase-a
"\b" | -- backslash, lowercase-b
"\f" | -- backslash, lowercase-f
"\n" | -- backslash, lowercase-n
"\r" | -- backslash, lowercase-r
"\t" | -- backslash, lowercase-t
"\v" ) -- backslash, lowercase-v
<hexadecimal-escape-sequence> =
( "\x" <hexadecimal-digit> |
<hexadecimal-escape-sequence> <hexadecimal-digit> )
-- String Literals
--
-- does not include long (unicode) string constants
<string-literal> =
Expires August 15, 2001 [Page 38]
Internet Draft SEE Specification February 2001
""" [ <s-char-sequence> ] """
<s-char-sequence> =
( <s-char> | <s-char-sequence> <s-char> )
<s-char> =
( <source-char> | <escape-sequence> )
<source-char> =
Any member of the source character set except
the double quote ('"'), backslash (''), or
newline character. [ed. want to support UTF-8 here]
-- operators
-- list included for completeness
-- The following 5 operators are not included:
-- ->
-- ?
-- :
-- #
-- ##
<operator> =
( "[" | "]" | "(" | ")" | "." | "++" | "--" |
"&" | "*" | "+" | "-" | "~" | "!" | "/" |
"%" | "<<" | ">>" | "<" | ">" | "<=" | ">=" |
"==" | "!=" | "^" | "|" | "&&" | "||" | "=" |
"*=" | "/=" | "%=" | "+=" | "-=" | "<<=" |
">>=" | "&=" | "^=" | "|=" | "," | "sizeof" )
-- expression statements
--
-- The constructs derived from the <primary-expression>
-- implicitly define the operator precedence hierarchy
--
-- The following constructs are not included:
-- <postfix-expression> "." <identifier>
-- <postfix-expression> "->" <identifier>
-- cast expressions
-- unary operators: & *
-- <logical-OR-expression> "?" <expression> ":"
-- <conditional-expression>
-- <expression> "," <assignment-expression>
<primary-expression> =
Expires August 15, 2001 [Page 39]
Internet Draft SEE Specification February 2001
( <identifier> |
<constant> |
<string-literal> |
"(" <expression> ")" )
<postfix-expression> =
( <primary-expression> |
<postfix-expression> "[" <expression> "]" |
<postfix-expression> "(" <argument-expression-list> ")" |
<postfix-expression> "++" |
<postfix-expression> "--" )
<argument-expression-list> =
( <constant-expression> |
<argument-expression-list> "," <constant-expression> )
<unary-expression> =
( <postfix-expression> |
"++" <unary-expression> |
"--" <unary-expression> )
<unary-operator> =
( "+" | "-" | "~" | "!" )
<multiplicative-expression> =
( <unary-expression> |
<multiplicative-expression> "*" <unary-expression> |
<multiplicative-expression> "/" <unary-expression> |
<multiplicative-expression> "%" <unary-expression> )
<additive-expression> =
( <multiplicative-expression> |
<additive-expression> "+" <multiplicative-expression> |
<additive-expression> "-" <multiplicative-expression> )
<shift-expression> =
( <additive-expression> |
<shift-expression> "<<" <additive-expression> |
<shift-expression> ">>" <additive-expression> )
<relational-expression> =
( <shift-expression> |
<relational-expression> "<" <shift-expression> |
<relational-expression> ">" <shift-expression> |
<relational-expression> "<=" <shift-expression> |
Expires August 15, 2001 [Page 40]
Internet Draft SEE Specification February 2001
<relational-expression> ">=" <shift-expression> )
<equality-expression> =
( <relational-expression> |
<equality-expression> "==" <relational-expression> |
<equality-expression> "!=" <relational-expression> )
<AND-expression> =
( <equality-expression> |
<AND-expression> "&" <equality-expression> )
<exclusive-OR-expression> =
( <AND-expression> |
<exclusive-OR-expression> "^" <AND-expression> )
<inclusive-OR-expression> =
( <exclusive-OR-expression> |
<inclusive-OR-expression> "|" <exclusive-OR-expression> )
<logical-AND-expression> =
( <inclusive-OR-expression> |
<logical-AND-expression> "&&" <inclusive-OR-expression> )
<logical-OR-expression> =
( <logical-AND-expression> |
<logical-OR-expression> "||" <logical-AND-expression> )
<conditional-expression> =
<logical-OR-expression>
<assignment-expression> =
( <conditional-expression> |
<unary-expression> <assignment-operator>
<assignment-expression> )
<assignment-operator> =
( "=" | "*=" | "/=" | "%=" | "+=" | "-=" |
"<<=" | ">>=" | "&=" | "^=" | "|=" )
<expression> =
<assignment-expression>
-- OID variable assignment expressions
--
Expires August 15, 2001 [Page 41]
Internet Draft SEE Specification February 2001
-- this construct is included to define the subset of the
-- assignment expression that applies to OID variables.
-- The 'identifier' must reference a variable of type OID
--
-- The '=' operator is supported to assign (i.e. replace)
-- an <OID-part> value as the contents of an OID variable.
--
-- The '+=' operator is supported to append an <OID-part>
-- value to the contents of an OID variable.
<OID-assign-expression> =
( <identifier> "=" <OID-expression> |
<identifier> "+=" <OID-expression> )
-- OID expressions are comprised of OID parts,
-- Leading or trailing dot '.' tokens are not allowed
<OID-expression> =
( <OID-part> |
<OID-expression> "." <OID-part> )
--
-- OID parts
--
-- The 'identifier' must reference a variable of type OID
-- or type 'uint' or an OID alias identifier token
-- The 'array sub-expression' may be present to indicate
-- a single component of an OID variable. It must not
-- be present if the identifier refers to a 'uint'
-- variable or an OID Alias
-- The 'decimal constant' must be a value in the range
-- (0..2147483647)
-- the 'character constant' should be a single printable
-- character, but all forms of this construct are permitted
<OID-part> =
( <identifier> |
<identifier> "[" <conditional-expression> "]" |
<decimal-constant> |
<character-constant> )
<constant-expression> =
( <conditional-expression> |
Expires August 15, 2001 [Page 42]
Internet Draft SEE Specification February 2001
<OID-expression> )
--
-- Declarations
--
-- Features not included:
-- <init-declarator-list> not optional
-- storage class specifiers
-- type qualifiers
-- 'short' data type
-- 'void *' data type
-- 'enum' data type
-- 'double' data type
-- structs and unions
-- typedefs
-- Constant declaration explicitly defined since
-- variable <type-qualifiers> like 'const' are not supported
<declaration-list> =
( <declaration> |
<declaration-list> <declaration> )
<declaration> =
( <constant-declaration> |
<scalar-declaration> |
<nonscalar-declaration> )
-- only the simple scalar constants are supported
-- at this time, such as 'const int foo = 6;'
-- non-scalar constant declarations are TBD
<constant-declaration> =
"const" <scalar-specifier>
<identifier> "=" <constant> ";"
<scalar-declaration> =
<scalar-specifier> <init-scalar-declarator-list> ";"
<init-scalar-declarator-list> =
( <identifier> |
<init-scalar-declarator-list> "," <identifier> )
<nonscalar-declaration> =
Expires August 15, 2001 [Page 43]
Internet Draft SEE Specification February 2001
<nonscalar-specifier> <init-nonscalar-declarator-list> ";"
<init-nonscalar-declarator-list> =
( <nonscalar-declarator> |
<init-scalar-declarator-list> "," <nonscalar-declarator> )
-- New Construct: <nonscalar-declarator>
-- e.g.:
-- BITS testbits[6];
-- declares a local variable named 'testbits'
-- with 6 bits in it, numbered 0..5
-- the <integer-constant> must be greater than zero
<nonscalar-declarator> =
<identifier> "[" <integer-constant> "]"
-- type definitions simplified
-- new data types can be represented in C
-- with '#define' statements
-- the float data type is optional
<type-specifier> =
( <scalar-specifier> | <nonscalar-specifier> )
<scalar-specifier> =
( "boolean" |
"char" |
"float" |
"int" |
"long" |
"uint" |
"ulong" |
"void" )
<nonscalar-specifier> =
( "BITS" |
"OID" |
"STRING" )
-- Statements
--
-- Features not included:
-- labeled statements for 'goto'
-- declaration lists nested within compound statements
-- goto form of jump-statement
Expires August 15, 2001 [Page 44]
Internet Draft SEE Specification February 2001
<statement> =
( <labeled-statement> |
<compound-statement> |
<expression-statement> |
<selection-statement> |
<iteration-statement> |
<jump-statement> )
<labeled-statement> =
( "case" <constant-expression> ":" <statement> |
"default" ":" <statement> )
<compound-statement> =
"{" [ <statement-list> ] "}"
<statement-list> =
( <statement> |
<statement-list> <statement> )
<expression-statement> =
[ <expression> ] ";"
<selection-statement> =
( "if" "(" <expression> ")" "{" <statement> "}" |
"if" "(" <expression> ")" "{" <statement> "}"
"else" "{" <statement> "}" |
"switch" "(" <expression> ")" <statement> )
<iteration-statement> =
( "while" "(" <expression> ")" <statement> |
"do" <statement> "while" "(" <expression> ")" ";" |
"for" "(" [ <expression> ] ";" [ <expression> ] ";"
[ <expression> ] ")" <statement> )
<jump-statement> =
( "continue" ";" |
"break" ";" |
"return" [ <expression> ] ";" )
-- Function Syntax
--
-- The function syntax is hardwired to the simplest
Expires August 15, 2001 [Page 45]
Internet Draft SEE Specification February 2001
-- ANSI-compatible form. The 'IN' and 'OUT' keywords
-- are added to adjust for lack of pointers
--
-- Features Not Supported:
-- <pointer> variants of the <declarator> token
-- complex forms of <direct-declarator>
-- complex forms of <parameter-declaration>
<declarator> =
<identifier> "(" [ <parameter-type-list> ] ")"
<parameter-type-list> =
( <parameter-list> |
<parameter-list> "," "..." )
<parameter-list> =
( <parameter-declaration> |
<parameter-list> "," <parameter-declaration> )
-- only simple <identifier> token can be used as the
-- name of a parameter; complex forms not supported
<parameter-declaration> =
( <parameter-direction>
<type-specifier>
<identifier> )
-- IN attribute:
-- indicates parameter passed by value
-- INREF attribute:
-- indicates read-only parameter passed by reference
-- INOUT attribute:
-- indicates read-write parameter passed by reference
-- OUT attributes:
-- indicates write-only parameter passed by reference
<parameter-direction> =
( "IN" |
"INREF" |
"INOUT" |
"OUT" )
-- Top Level: See Script Definition
--
-- Features not supported:
Expires August 15, 2001 [Page 46]
Internet Draft SEE Specification February 2001
-- function declaration-specifiers are not optional
-- (no implied 'int' data type if none specified)
-- syntax simplified by removing <declarator> token
-- and allowing only the <identifier> variant
<translation-unit> =
( <external-declaration> |
<translation-unit> <external-declaration> )
<external-declaration> =
( <function-definition> |
<declaration> )
-- local parameters can only be defined at the
-- top level of a function block,
-- not within nested blocks
<function-definition> =
<type-specifier> <declarator>
"{" [<declaration-list>] [ <statement-list> ] "}"
7.2. Environment Variables
Environment variables are string variables (i.e. 'STRING' data type)
which are declared at load-time or run-time. They are used as a
parameter passing mechanism as well as local persistent storage within
the execution environment.
The SEE agent maintains a set of built-in environment variables, and
each management task may also be configured with additional environment
variables. Write access (if granted at all) may be restricted to a
single task or a single task group, depending on the variable scope and
configuration.
Environment variables are stored as arrays of STRING objects. An
individual STRING object must not exceed the length specified by the
seeCapsMaxEnvStringLen object. Some system defined environment
variables (e.g. _TRIGGER_NOTIF_VB_VAL) must also conform to encoding
rules according to a specified Type Identifier string.
These variables may be accessed directly in SEE <statement> clauses, in
the same manner as any variable identifier token. They may also be
accessed indirectly via functions in the 'EnvVarLib' system library, and
configured externally with SNMP via the seeEnvVarTable.
Expires August 15, 2001 [Page 47]
Internet Draft SEE Specification February 2001
7.2.1. Predefined Environment Variables
These environment variables are defined by the agent for all management
tasks. They may not be replaced or deleted via script or configuration
action. Almost all of them are read-only variables, set algorithmically
by the agent.
7.2.1.1. Agent Scope
The agent defines the following variable, which contains the same static
value for all management tasks.
_HOST_ENGINE_ID
The SNMP engine hosting the SEE and Script MIBs and local script
execution environment.
7.2.1.2. Group Scope
There are no system environment variables with 'Group' scope defined at
this time.
7.2.1.3. Task Scope
The following read-only variables are common to all application
profiles. They are set upon task invocation, in the manner described
below:
_HOST_CONTEXT_NAME
The SNMP context containing the SEE and Script MIBs.
_TARGET_ENGINE_ID
The seeTaskControlEngineId value associated with the invoked task.
_TARGET_CONTEXT_NAME
The seeTaskControlContextName value associated with the invoked
task.
_TASK_OWNER
The smScriptOwner value associated with the invoked task.
_TASK_NAME
The smScriptName value associated with the invoked task.
_TASK_ID
The seeTaskControlIndex value associated with the invoked task.
Expires August 15, 2001 [Page 48]
Internet Draft SEE Specification February 2001
_TRIGGER_SYS_UPTIME
The value of sysUptime when the agent detected the trigger event.
This is the sysUpTime value of the local agent, within the context
indicated by the _HOST_ENGINE_ID and _HOST_CONTEXT_NAME values.
_TRIGGER_TIME_OF_DAY
The time of day value when the agent detected the trigger event.
This is the value of schedLocalTime on the local agent, within the
context indicated by the _HOST_ENGINE_ID and _HOST_CONTEXT_NAME
values. If the system does not support the Scheduling MIB, then
this variable will contain a zero length string.
The following read-write variable is common to all application profiles.
_SCRATCHPAD
Each management task is provided a small amount of scratchpad
memory. This special environment variable is an array of 'N'
strings, where 'N' is the value of the associated
seeTaskControlScratchpadSize MIB object.
Each string contained in the array is initialized at row activation
time to a zero-length string. The agent will retain values written
to this variable across task invocations, and will maintain the
contents of the variable as long as the associated task control
entry remains active.
7.3. Runtime Execution Model
The runtime system contains several conceptual components and features:
Management Tasks
Each system has a set of management tasks, which may be configured
by the agent and/or management applications in the
seeTaskControlTable. More than one task can be configured to
utilize the same script.
Management Task Groups
Each management task can be administratively assigned to belong to
exactly one task group. This grouping is independent of the script
owner and script name grouping inherent in the Script MIB and SEE
MIB indexing. Tasks with the same Group ID are capable of sharing
the same access rights to environment variables.
Underlying Access Mechanisms
Each network device is expected to have an underlying configuration
Expires August 15, 2001 [Page 49]
Internet Draft SEE Specification February 2001
interface, based on SNMP. An optional command line interface (CLI)
is also supported, via the 'CliLib' system library.
Scripts
Programming logic is organized in scripts, with each script written
in a single scripting language. A script must conform to the
specification for its indicated language specification.
It is an implementation-specific matter as to the time and extent
that the script correctness is verified. An agent should verify
script correctness as soon as possible, in order to simplify script
debugging. The agent must be capable of reporting such errors, as
they are detected. The 'validation' run mode is provided to force
an agent to check an entire script for correctness, but other run
modes do not require complete script validation in a specific
manner. In these other run modes, the agent may stop processing at
the first syntax error, rather than find all syntax errors when a
script is processed. This simplification allows some syntax
debugging support while avoiding complex MIB and implementation
requirements.
The error code definitions defined in the Script MIB for the
smRunExitCode object are used for return status codes between
scripts and the execution environment. These error codes have been
moved to the SeeResultCode textual convention to allow the
semantics to be shared by multiple MIB objects. ,ip "Script
Repository" The MIB utilizes the Script MIB for storage of scripts.
Scripts are stored as abstract 'script chunks', which allows
scripts to be arbitrarily large. Section 8.1 defines the Script
MIB implementation requirements.
7.3.1. Trigger Frame
The execution environment provided to a single management task is called
a trigger frame. Script invocation begins with a trigger event, which
causes a predefined script in a particular application profile to be
executed to perform management tasks allowed within that application
profile.
Expires August 15, 2001 [Page 50]
Internet Draft SEE Specification February 2001
Figure 6: Trigger Frame Processing Model
-----------------------------------------
|<------------------------ e -------------------------->|
| |
| +-------------------------------------+ |
| | management script processing | |
|<-a->|<-b->|<---------------- c ---------------->|<-d->|
| | | | |
| | | | |
| | | | |
T0 T1 T2 T3 T4
Time Description
------------------------------------------------
T0 = trigger event occurs. For synchronous tasks,
this represents the desired polling interval.
For asynchronous tasks, this represents the
time the actual trigger event took place.
T1 = agent detects that the trigger event occurred;
_TRIGGER_SYS_UPTIME = _TRIGGER_TIME_OF_DAY = T1
T2 = script execution starts
T3 = script execution completes
T4 = trigger frame cleanup completes
Interval Description
------------------------------------------------
a = for asynchronous tasks, the internal trigger event
discovery latency. For synchronous tasks, the
value of T1 should be equal to T0.
b = internal script invocation latency and startup
c = script invocation lifetime, must not
exceed seeTaskControlLifetime
d = internal script termination and cleanup
e = entire trigger frame, For synchronous tasks,
this should not exceed seeTaskControlTriggerInt
A trigger frame begins with a synchronous or asynchronous trigger event,
at time T0 (see figure 6). After some internal latency (interval 'a'),
the agent detects the trigger event at time T1. After some more internal
latency (interval 'b') to set the environment variable values and other
internal tasks, the associated management script is executed at time T2,
Expires August 15, 2001 [Page 51]
Internet Draft SEE Specification February 2001
and completes at time T3. After some internal cleanup latency (interval
'd'), the trigger frame ends at time T4.
7.4. Application Profiles
This section defines an initial set of application profiles.
7.4.1. Watched Variable Profile
This mode allows a particular script to be invoked when one or more
instances of the specified MIB object changes value.
The agent will poll the specified (or implied) instances once per
polling interval. After an initial polling interval, if the value of any
indicated instance changes, then the agent will invoke the specified
script, which may examine the changed values and take appropriate
action.
Configuration Requirements
The seeTaskControlEntry objects are described, as they pertain to this
application profile:
seeTaskControlAppProfile
The constant 'appWatchedVar(1)'.
seeTaskControlRunButton
Not used.
seeTaskControlEngineId
This object may reference the local SNMP engine or a remote SNMP
engine.
seeTaskControlContextName
This object may reference any context.
seeTaskControlTriggerOid
The watched MIB object, which must be a complete base fragment
OBJECT IDENTIFIER.
seeTaskControlTriggerInt
The watched object polling interval, in seconds.
seeTaskControlTriggerOvflAct
This object may be set to any value.
Expires August 15, 2001 [Page 52]
Internet Draft SEE Specification February 2001
Invocation Inputs
The following function template is used by all tasks of this profile as
the script entry point. The 'seeTaskControlStartFn' object must
identify a function matching this prototype:
void <identifier> ( void );
The following common environment variables are available to tasks of
this application profile. Refer to section 7.2.1 for details on these
variables.
_HOST_ENGINE_ID
_HOST_CONTEXT_NAME
_TARGET_ENGINE_ID
_TARGET_CONTEXT_NAME
_TASK_OWNER
_TASK_NAME
_TASK_ID
_TRIGGER_SYS_UPTIME
_TRIGGER_TIME_OF_DAY
_SCRATCHPAD []
The Watched Variable application profile defines some additional
variables, which are only used for tasks of this application profile:
_TRIGGER_OID_BASE
The value of the seeTaskControlTriggerOid object for this entry.
The base OBJECT IDENTIFIER fragment of the watched object, which is
defined in the context indicated by the _TARGET_ENGINE_ID and
_TARGET_CONTEXT_NAME environment variables. This OID base fragment
must identify an represent a single MIB object for which read
access is permitted. This object must not contain a base fragment
which may potentially expand to more than one MIB object. The base
fragment may contain instance components.
_TRIGGER_OID_INST_CNT
The number of strings (array elements) contained in the associated
_TRIGGER_OID_INST, _TRIGGER_OID_CUR_VAL, _TRIGGER_OID_CUR_VAL_TS,
_TRIGGER_OID_LAST_VAL, and _TRIGGER_OID_LAST_VAL_TS environment
variables.
_TRIGGER_OID_INST []
An array of complete OBJECT IDENTIFIERS which identify specific
watched instances that have changed during the last polling
Expires August 15, 2001 [Page 53]
Internet Draft SEE Specification February 2001
interval. Note that these elements are not instance fragments, but
complete identifiers. They include the _TRIGGER_OID_BASE value and
the complete instance identifier, and identify a MIB instance in
the context indicated by the _TARGET_ENGINE_ID and
_TARGET_CONTEXT_NAME environment variables.
_TRIGGER_OID_VAL_TYPE []
An array of Type Identifier strings associated with the MIB
instances in the _TRIGGER_OID_INST array.
_TRIGGER_OID_CUR_VAL []
An array of the current polled values associated with the instances
identified in the _TRIGGER_OID_INST array. If no current value
exists, but a value existed on the previous polling interval, then
that element will contain a zero length string, and the associated
_TRIGGER_OID_VAL_TYPE entry will contain the special value 'Null'.
_TRIGGER_OID_CUR_VAL_TS []
An array of timestamp values for the current polling interval. The
value of sysUptime (in the context indicated by the
_TARGET_ENGINE_ID and _TARGET_CONTEXT_NAME environment variables)
is recorded at the time the corresponding _TRIGGER_OID_CUR_VAL
array element is updated.
_TRIGGER_OID_LAST_VAL []
An array of the previous polled values associated with the
instances identified in the _TRIGGER_OID_INST array. If no
previous value exists, then that element will contain a zero length
string, and the associated _TRIGGER_OID_VAL_TYPE entry will contain
the special value 'Null'. These values are copies from the
_TRIGGER_OID_CUR_VAL array before the polled values are updated,
during each polling interval.
_TRIGGER_OID_LAST_VAL_TS []
An array of timestamp values for the previous polling interval.
These values are copies from the _TRIGGER_OID_CUR_VAL_TS array
before the polled values are updated, during each polling interval.
Invocation Outputs
None
Runtime Permissions
Expires August 15, 2001 [Page 54]
Internet Draft SEE Specification February 2001
Scripts running in this profile have full access to the execution
environment features. Table 1 lists the allowable settings for the
seeTaskControlExecPermissions object.
Note that individual tasks may be activated in this application profile
with a lower set of permissions.
Table 1: Watched Variable Profile Runtime Permissions
Permission Enum Max. Setting
--------------------------------------
agentEnvVars(0) 1
groupEnvVars(1) 1
taskEnvVars(2) 1
notificationPDUs(3) 1
getPDUs(4) 1
setPDUs(5) 1
writeConfig(6) 1
diagnostics(7) 1
oidAliases(8) 1
Refer to the SeeExecPermissions textual convention for the definition of
each permission BIT.
Implementation Restrictions
The agent may choose to restrict:
o the number of watched instances that may be implied by a single
entry. The minimum value for a conforming implementation is '1'.
o the number of changed values reported on each script invocation.
The minimum value for a conforming implementation is '1'.
o the granularity of the timestamps reported on each invocation.
The minimum granularity is one second.
7.4.2. Periodic Profile
This mode allows a particular script to be invoked periodically, at a
fixed time interval.
The agent will invoke the specified script once per polling interval.
This mode is intended for monitoring arbitrarily complex system
conditions on a periodic basis.
Expires August 15, 2001 [Page 55]
Internet Draft SEE Specification February 2001
Configuration Inputs
The seeTaskControlEntry objects are described, as they pertain to this
application profile:
seeTaskControlAppProfile
The constant 'appPeriodic(2)'.
seeTaskControlRunButton
Not used.
seeTaskControlEngineId
This object may reference the local SNMP engine or a remote SNMP
engine.
seeTaskControlContextName
This object may reference any context.
seeTaskControlTriggerOid
Not used.
seeTaskControlTriggerInt
The amount of time to wait between each task invocation. Note that
this value is an absolute elapsed time, and includes the script
execution time.
seeTaskControlTriggerOvflAct
This object may be set to any value.
Invocation Inputs
The following function template is used by all tasks of this profile as
the script entry point. The 'seeTaskControlStartFn' object must
identify a function matching this prototype:
void <identifier> ( void );
The following common environment variables are available to tasks of
this application profile. Refer to section 7.2.1 for details on these
variables.
_HOST_ENGINE_ID
_HOST_CONTEXT_NAME
_TARGET_ENGINE_ID
_TARGET_CONTEXT_NAME
Expires August 15, 2001 [Page 56]
Internet Draft SEE Specification February 2001
_TASK_OWNER
_TASK_NAME
_TASK_ID
_TRIGGER_SYS_UPTIME
_TRIGGER_TIME_OF_DAY
_SCRATCHPAD []
The Periodic application profile does not define any additional profile-
specific system variables.
Invocation Outputs
None
Runtime Permissions
Scripts running in this profile have full access to the execution
environment features. Table 2 lists the allowable settings for the
seeTaskControlExecPermissions object.
Note that individual tasks may be activated in this application profile
with a lower set of permissions.
Table 2: Periodic Profile Runtime Permissions
Permission Enum Max. Setting
--------------------------------------
agentEnvVars(0) 1
groupEnvVars(1) 1
taskEnvVars(2) 1
notificationPDUs(3) 1
getPDUs(4) 1
setPDUs(5) 1
writeConfig(6) 1
diagnostics(7) 1
oidAliases(8) 1
Refer to the SeeExecPermissions textual convention for the definition of
each permission BIT.
Implementation Restrictions
The agent may restrict the value of the seeTaskControlTriggerInt object,
but must allow this object to be greater than or equal to the value of
the seeCapsMinPollInterval object.
Expires August 15, 2001 [Page 57]
Internet Draft SEE Specification February 2001
7.4.3. Calendar Profile
This application profile allows a script to be invoked via the
Scheduling MIB [RFC2591]. This mode is intended for delegating
arbitrarily complex system control logic, and invoking it automatically,
on an ad-hoc basis.
The Scheduling MIB portion of the agent will invoke the specified script
via the seeTaskControlRunButton object.
Configuration Requirements
This profile relies on the proper configuration of the Scheduling MIB in
order to function. Refer to section 8.2 for complete Scheduling MIB
implementation requirements.
The seeTaskControlEntry objects are described, as they pertain to this
application profile:
seeTaskControlAppProfile
The constant 'appCalendar(3)'.
seeTaskControlRunButton
If the associated task is not already running, then it will be
invoked when this object is set to the value 'runTask(1)'.
seeTaskControlEngineId
This object may reference the local SNMP engine or a remote SNMP
engine.
seeTaskControlContextName
This object may reference any context.
seeTaskControlTriggerOid
Not used.
seeTaskControlTriggerInt
Not used.
seeTaskControlTriggerOvflAct
This object may be set to any value.
Invocation Inputs
Expires August 15, 2001 [Page 58]
Internet Draft SEE Specification February 2001
The following function template is used by all tasks of this profile as
the script entry point. The 'seeTaskControlStartFn' object must
identify a function matching this prototype:
void <identifier> ( void );
The following common environment variables are available to tasks of
this application profile. Refer to section 7.2.1 for details on these
variables.
_HOST_ENGINE_ID
_HOST_CONTEXT_NAME
_TARGET_ENGINE_ID
_TARGET_CONTEXT_NAME
_TASK_OWNER
_TASK_NAME
_TASK_ID
_TRIGGER_SYS_UPTIME
_TRIGGER_TIME_OF_DAY
_SCRATCHPAD []
The Calendar application profile does not define any additional profile-
specific system variables.
Invocation Outputs
None
Runtime Permissions
Scripts running in this profile have full access to the execution
environment features. Table 3 lists the allowable settings for the
seeTaskControlExecPermissions object.
Note that individual tasks may be activated in this application profile
with a lower set of permissions.
Table 3: Calendar Profile Runtime Permissions
Permission Enum Max. Setting
--------------------------------------
agentEnvVars(0) 1
groupEnvVars(1) 1
taskEnvVars(2) 1
notificationPDUs(3) 1
Expires August 15, 2001 [Page 59]
Internet Draft SEE Specification February 2001
getPDUs(4) 1
setPDUs(5) 1
writeConfig(6) 1
diagnostics(7) 1
oidAliases(8) 1
Refer to the SeeExecPermissions textual convention for the definition of
each permission BIT.
Implementation Restrictions
The schedTable should not be configured in such a way as to schedule
repeated invocations of the same management task more frequently than
the number of seconds indicated by the seeCapsMinPollInterval object.
7.4.4. Notification Filter Profile
This application profile allows a script to be invoked when a
notification originator application generates a request to the message
dispatcher to emit a notification message (i.e Trap PDU or Inform PDU).
This mode is intended for extending notification varbind lists,
throttling notifications, or handling notifications locally.
The agent will invoke the associated script just before the local
message dispatcher is about to emit a notification (Trap or Inform PDU).
The script may act upon the information in the notification (conveyed in
environment variables) immediately, add varbinds to the notification, or
suppress the notification generation.
If the implementation allows, notification filter tasks may be chained,
i.e. more than one task configured to handle the same notification type.
Configuration Requirements
The seeTaskControlEntry objects are described, as they pertain to this
application profile:
seeTaskControlAppProfile
The constant 'appNotifyFilter(4)'.
seeTaskControlRunButton
Not used.
Expires August 15, 2001 [Page 60]
Internet Draft SEE Specification February 2001
seeTaskControlEngineId
This object must be set to a zero length string to indicate the
local SNMP engine.
seeTaskControlContextName
This object may reference any local context. If it is set to a non-
zero length string, then only notifications with the same value
'contextName' value (or 'community' for SNMPv1) will cause the
associated script to be invoked.
seeTaskControlTriggerOid
The registration OBJECT IDENTIFIER base fragment identifying the
particular notification(s) that this task should filter. This may
be an incomplete base fragment, identifying potentially many or all
notification types supported by the agent.
seeTaskControlTriggerInt
Not used.
seeTaskControlTriggerOvflAct
This object may be set to any value except 'dropNotifyTrigger(2)'.
Invocation Inputs
The following function template is used by all tasks of this profile as
the script entry point. The 'seeTaskControlStartFn' object must
identify a function matching this prototype:
boolean <identifier> ( void );
The following common environment variables are available to tasks of
this application profile. Refer to section 7.2.1 for details on these
variables.
_HOST_ENGINE_ID
_HOST_CONTEXT_NAME
_TARGET_ENGINE_ID
_TARGET_CONTEXT_NAME
_TASK_OWNER
_TASK_NAME
_TASK_ID
_TRIGGER_SYS_UPTIME
_TRIGGER_TIME_OF_DAY
_SCRATCHPAD []
Expires August 15, 2001 [Page 61]
Internet Draft SEE Specification February 2001
The Notification Filter application profile defines some additional
variables, which are only used for tasks related to notifications (i.e
Notification Filters and Notification Receivers).
_TRIGGER_NOTIF_BASE
The value of the seeTaskControlTriggerOid object for this entry.
An empty string should be configured to select all notification
types.
_TRIGGER_NOTIF_ID
The registration OBJECT IDENTIFIER value for the particular
notification associated with the current task invocation.
_TRIGGER_NOTIF_CONTEXT
The contextName value for the notification PDU associated with the
current task invocation. The community string value will be used
instead for community-based SNMP messages.
_TRIGGER_NOTIF_VB_CNT
The number of strings (array elements) contained in the associated
_TRIGGER_NOTIF_VB_OID, _TRIGGER_NOTIF_VB_VAL, and
_TRIGGER_NOTIF_VB_TYPE environment variables.
_TRIGGER_NOTIF_VB_OID []
An array of complete OBJECT IDENTIFIER strings, which identify the
specific MIB instances comprising the varbind list, associated with
the notification. The instances in the array are contained within
the context indicated by the _TARGET_ENGINE_ID (i.e local SNMP
engine) and _TRIGGER_NOTIF_CONTEXT values.
_TRIGGER_NOTIF_VB_VAL []
An array containing the string representation of the values of
particular MIB instances contained in the _TRIGGER_NOTIF_VB_OID
array.
_TRIGGER_NOTIF_VB_TYPE []
An array containing the Type Identifier strings associated with the
values contained in the _TRIGGER_NOTIF_VB_VAL array.
Invocation Outputs
The script is expected to return a 'boolean' status code to the agent
upon task completion.
The value FALSE is returned to indicate that the Message Dispatcher
Expires August 15, 2001 [Page 62]
Internet Draft SEE Specification February 2001
should proceed with the generation of this notification PDU.
The value TRUE is returned to indicate that the Message Dispatcher
should not proceed with the generation of this notification PDU. The
message dispatcher will never receive the notification PDU in this case.
Runtime Permissions
Scripts running in this profile have limited access to the execution
environment features. Table 4 lists the allowable settings for the
seeTaskControlExecPermissions object.
Note that individual tasks may be activated in this application profile
with a lower set of permissions, but they may not be activated with a
higher set.
Table 4: Notification Filter Profile Runtime Permissions
Permission Enum Max. Setting
--------------------------------------
agentEnvVars(0) 1
groupEnvVars(1) 1
taskEnvVars(2) 1
notificationPDUs(3) 0
getPDUs(4) 1
setPDUs(5) 0
writeConfig(6) 1
diagnostics(7) 1
oidAliases(8) 1
Refer to the SeeExecPermissions textual convention for the definition of
each permission BIT.
Implementation Restrictions
In the event multiple Notification Filter tasks are configured to
receive the same notification type, the following rules apply:
task order
The tasks are invoked in the same order every time. Specifically,
the tasks are invoked in ascending order, starting with the lowest
value of seeTaskControlIndex (e.g. _TASK_ID environment variable).
filter chaining
The first task to return a non-zero status (indicating the
Expires August 15, 2001 [Page 63]
Internet Draft SEE Specification February 2001
notification PDU should be dropped) will cause the agent to
terminate filter processing at that point. If a task returns a
zero status, then the agent will continue to the next appropriate
seeTaskControl entry, or pass the outbound notification to the
message dispatcher for processing.
The agent may restrict the number of management tasks that are
configured to filter a particular notification type.
The agent may restrict the number and size of varbinds that may be added
to the outgoing notification, via functions in the 'SnmpMsgLib' system
library.
Note that the agent is not required to check for a possible 'TooBig'
error status as varbinds are added to the varbind list.
The message dispatcher may attempt to generate the original notification
PDU, without any varbind additions by the called script(s), if
generation of an 'extended' Trap or Inform PDU fails with a 'tooBig'
error status.
7.4.4.1. Example Notification Filter Script
The following example script 'registers' for 'linkUp' notifications
(from the IF-MIB), and adds the 'best' interface counters to the
notification varbind list, along with the sysUpTime and
ifCounterDiscontinuityTime objects.
These will be used by the notification receiver application as the
'snapshot' counters it normally would retrieve upon receiving a 'linkUp'
notification.
The script identified by the smScriptOwner value of "joe" and the
smScriptName value of "test1" is configured in the smCodeTable (commands
not shown).
The following SEE MIB configuration is used in this example:
These OID Aliases are configured in the seeOidAliasTable:
sysUpTime = "1.3.6.1.2.1.1.3"
ifIndex = "1.3.6.1.2.1.2.2.1.1"
ifInOctets = "1.3.6.1.2.1.2.2.1.10"
ifInUcastPkts = "1.3.6.1.2.1.2.2.1.11"
* ifInNUcastPkts = "1.3.6.1.2.1.2.2.1.12"
Expires August 15, 2001 [Page 64]
Internet Draft SEE Specification February 2001
ifInDiscards = "1.3.6.1.2.1.2.2.1.13"
ifInErrors = "1.3.6.1.2.1.2.2.1.14"
ifInUnknownProtos = "1.3.6.1.2.1.2.2.1.15"
ifOutOctets = "1.3.6.1.2.1.2.2.1.16"
ifOutUcastPkts = "1.3.6.1.2.1.2.2.1.17"
* ifOutNUcastPkts = "1.3.6.1.2.1.2.2.1.18"
ifOutDiscards = "1.3.6.1.2.1.2.2.1.19"
ifOutErrors = "1.3.6.1.2.1.2.2.1.20"
ifInMulticastPkts = "1.3.6.1.2.1.31.1.1.1.2"
ifInBroadcastPkts = "1.3.6.1.2.1.31.1.1.1.3"
ifOutMulticastPkts = "1.3.6.1.2.1.31.1.1.1.4"
ifOutBroadcastPkts = "1.3.6.1.2.1.31.1.1.1.5"
ifHCInOctets = "1.3.6.1.2.1.31.1.1.1.6"
ifHCInUcastPkts = "1.3.6.1.2.1.31.1.1.1.7"
ifHCInMulticastPkts = "1.3.6.1.2.1.31.1.1.1.8"
ifHCInBroadcastPkts = "1.3.6.1.2.1.31.1.1.1.9"
ifHCOutOctets = "1.3.6.1.2.1.31.1.1.1.10"
ifHCOutUcastPkts = "1.3.6.1.2.1.31.1.1.1.11"
ifHCOutMulticastPkts = "1.3.6.1.2.1.31.1.1.1.12"
ifHCOutBroadcastPkts = "1.3.6.1.2.1.31.1.1.1.13"
ifCounterDiscontinuityTime = "1.3.6.1.2.1.31.1.1.1.19"
The following task control entry is configured in the
seeTaskControlTable for the instance "3.'joe'.5.'test1'.1":
seeTaskControlDescr = "IF-MIB counters example"
seeTaskControlAppProfile = 'appNotifyFilter(4)'
seeTaskControlExecPermissions = { getPDUs(4) }
seeTaskControlGroupId = 100
seeTaskControlRunMode = 'normalRunMode(1)'
seeTaskControlStartFn = "linkUp_main"
seeTaskControlLifetime = 5
seeTaskControlEngineId = ""
seeTaskControlContextName = ""
seeTaskControlTriggerOid = "1.3.6.1.6.3.1.1.5.4"
seeTaskControlTriggerInt = 0
seeTaskControlTriggerOvflAct = 'queueTrigger(3)'
seeTaskControlScratchpadSize = 0
seeTaskControlResultType = "Null"
seeTaskControlLogWriteMode = 'WrapWhenFull(2)'
seeTaskControlMaxLogSize = 1000000
seeTaskControlMaxLogChunkSize = 1000
seeTaskControlStorageType = 'nonVolatile(3)'
The following script is configured in the smCodeTable for
Expires August 15, 2001 [Page 65]
Internet Draft SEE Specification February 2001
the instance prefix of "3.'joe'.5.'test1'":
/*
* IF-MIB linkUp Notification Filter
* version 1.0
* Adds ifXTable or ifTable MIB counters if available
* returns 1 (true) if notification should be dropped
*
* IF-MIB Counter preference: only the most relevant
* counters are added to the outgoing linkUp notification
* whichs informs application which IF_MIB counters to
* poll for the specified interface.
*
* 1st choice 2nd choice 3rd choice
* -------------------------------------------------------
*
* ifHCInOctets ifInOctets
* ifHCInUcastPkts ifInUcastPkts
* ifHCInMulticastPkts ifInMulticastPkts ifInNUcastPkts
* ifHCInBroadcastPkts ifInBroadcastPkts
* ifInDiscards
* ifInErrors
* ifInUnknownProtos
* ifHCOutOctets ifOutOctets
* ifHCOutUcastPkts ifOutUcastPkts
* ifHCOutMulticastPkts ifOutMulticastPkts ifOutNUcastPkts
* ifHCOutBroadcastPkts ifOutBroadcastPkts
* ifOutDiscards
* ifOutErrors
* ifCounterDiscontinuityTime
* sysUpTime
*/
int add_varbinds (IN int vb_count, INREF vb_oid)
{
boolean any_null;
int res, err_idx;
STRING vb_type[16][32];
STRING vb_val[16][32];
if (vb_count > 15) {
return INVALID_ARGUMENT;
}
Expires August 15, 2001 [Page 66]
Internet Draft SEE Specification February 2001
/* try to get the MIB objects */
res = snmp_get("", "", 0, "", vb_count, vb_oid,
err_idx, any_null, vb_type, vb_val);
if (res != NO_ERROR) {
return res;
} else if (any_null) {
/* all-or-none simple example */
return GENERIC_ERROR;
}
/* add the counters to the outgoing notification */
return snmp_notify_add_varbinds(
vb_count, vb_oid, vb_type, vb_val);
}
boolean linkUp_main (void)
{
boolean done;
int vb_cnt, res, i;
uint ifindex;
OID vb[128], vb_oid[10][32];
/* get the varbind count */
res = str2int(_TRIGGER_NOTIF_VB_CNT, "Integer32", vb_cnt);
if (res != NO_ERROR) {
return FALSE; /* error - should not happen */
}
/* look for the ifIndex varbind, should be first */
done = FALSE;
for (i=0; i<vb_cnt && !done; i++) {
res = str2oid(_TRIGGER_NOTIF_VB_OID[i], vb);
if (res != NO_ERROR) {
return FALSE; /* error - should not happen */
}
if (oidlen(vb) != oidlen(ifIndex)+1) {
continue; /* not ifIndex.I */
}
if (!oidncmp(ifIndex, vb)) {
/* grab the I in ifIndex.I */
if_index = vb[oidlen(vb)-1];
done = TRUE;
}
}
if (!done || if_index==0) {
Expires August 15, 2001 [Page 67]
Internet Draft SEE Specification February 2001
return FALSE; /* not correct but permit send anyway! */
}
/* 1st choice : ifX HC counters */
vb_oid[0] = ifHCInOctets.ifindex;
vb_oid[1] = ifHCInUcastPkts.ifindex;
vb_oid[2] = ifHCInMulticastPkts.ifindex;
vb_oid[3] = ifHCInBroadcastPkts.ifindex;
vb_oid[4] = ifHCOutOctets.ifindex;
vb_oid[5] = ifHCOutUcastPkts.ifindex;
vb_oid[6] = ifHCOutMulticastPkts.ifindex;
vb_oid[7] = ifHCOutBroadcastPkts.ifindex;
vb_oid[8] = ifCounterDiscontinuityTime.ifindex;
res = add_varbinds(9, vb_oid);
if (res != NO_ERROR) {
/* didn't work; try the 2nd choice counters */
vb_oid[0] = ifInMulticastPkts.ifindex;
vb_oid[1] = ifInBroadcastPkts.ifindex;
vb_oid[2] = ifOutMulticastPkts.ifindex;
vb_oid[3] = ifOutBroadcastPkts.ifindex;
vb_oid[4] = ifCounterDiscontinuityTime.ifindex;
res = add_varbinds(5, vb_oid);
if (res != NO_ERROR) {
/* try the 3rd choice (deprecated) counters */
vb_oid[0] = ifInNUcastPkts.ifindex;
vb_oid[1] = ifOutNUcastPkts.ifindex;
res = add_varbinds(2, vb_oid);
/* ignore return value */
}
/* add rest of 2nd choice counters */
vb_oid[0] = ifInOctets.ifindex;
vb_oid[1] = ifInUcastPkts.ifindex;
vb_oid[2] = ifOutOctets.ifindex;
vb_oid[3] = ifOutUcastPkts.ifindex;
res = add_varbinds(4, vb_oid);
/* ignore return value */
}
/* add 1st choice ifTable counters */
vb_oid[0] = ifInDiscards.ifindex;
vb_oid[1] = ifInErrors.ifindex;
vb_oid[2] = ifInUnknownProtos.ifindex;
Expires August 15, 2001 [Page 68]
Internet Draft SEE Specification February 2001
vb_oid[3] = ifOutDiscards.ifindex;
vb_oid[4] = ifOutErrors.ifindex;
vb_oid[5] = sysUpTime.0;
res = add_varbinds(6, vb_oid);
/* ignore return value */
return FALSE; /* send the notification */
}
7.4.5. Notification Receiver Profile
This application profile allows a script to be registered as a
notification receiver application within the local SNMP engine.
The agent will invoke the associated script when the specified
notification types are received by the local SNMP engine. The script
has full system access to act upon the information contained in the
notification.
If the implementation allows, notification receiver tasks may be
chained, i.e., more than one task configured to handle the same
notification type.
Configuration Requirements
The seeTaskControlEntry objects are described, as they pertain to this
application profile:
seeTaskControlAppProfile
The constant 'appNotifyReceiver(5)'.
seeTaskControlRunButton
Not used.
seeTaskControlEngineId
This object must be set to a zero length string to indicate the
local SNMP engine.
seeTaskControlContextName
This object may reference any local context. If it is set to a non-
zero length string, then only notifications with the same value
'contextName' value will cause the associated script to be invoked.
Expires August 15, 2001 [Page 69]
Internet Draft SEE Specification February 2001
seeTaskControlTriggerOid
The registration OBJECT IDENTIFIER base fragment identifying the
particular notification(s) that this task should receive. This may
be an incomplete base fragment, identifying potentially many or all
notification types supported by the agent. An empty string should
be configured to select all notification types.
seeTaskControlTriggerInt
Not used.
seeTaskControlTriggerOvflAct
This object may be set to any value except 'dropNotifyTrigger(2)'.
Invocation Inputs
The following function template is used by all tasks of this profile as
the script entry point. The 'seeTaskControlStartFn' object must
identify a function matching this prototype:
void <identifier> ( void );
The following common environment variables are available to tasks of
this application profile. Refer to section 7.2.1 for details on these
variables.
_HOST_ENGINE_ID
_HOST_CONTEXT_NAME
_TARGET_ENGINE_ID
_TARGET_CONTEXT_NAME
_TASK_OWNER
_TASK_NAME
_TASK_ID
_TRIGGER_SYS_UPTIME
_TRIGGER_TIME_OF_DAY
_SCRATCHPAD []
The Notification Receiver application profile defines some additional
variables, which are only used for tasks of this profile.
_TRIGGER_NOTIF_ENGINE_ID
The value of the contextEngineId field from the received
notification. The empty string will be used for community-based
SNMP messages.
Expires August 15, 2001 [Page 70]
Internet Draft SEE Specification February 2001
_TRIGGER_NOTIF_ADDR_TYPE
The value of the 'InetAddressType' (encoded as a STRING) for the
notification source address contained in the _TRIGGER_NOTIF_ADDR
environment variable.
_TRIGGER_NOTIF_ADDR
The value of the 'InetAddress' associated with the network source
address found in the received notification.
The Notification Receiver application profile also uses the set of
environment variables defined for Notification Filter tasks, except that
the variables refer to a received notification instead of an outbound
notification.
_TRIGGER_NOTIF_BASE
The value of the seeTaskControlTriggerOid object for this entry.
_TRIGGER_NOTIF_ID
The registration OBJECT IDENTIFIER value for the particular
notification associated with the current task invocation.
_TRIGGER_NOTIF_CONTEXT
The contextName value for the notification PDU associated with the
current task invocation. The community string value will be used
instead for community-based SNMP messages.
_TRIGGER_NOTIF_VB_CNT
The number of strings (array elements) contained in the associated
_TRIGGER_NOTIF_VB_OID, _TRIGGER_NOTIF_VB_VAL, and
_TRIGGER_NOTIF_VB_TYPE environment variables.
_TRIGGER_NOTIF_VB_OID []
An array of complete OBJECT IDENTIFIER strings, which identify the
specific MIB instances comprising the varbind list, associated with
the notification. The instances in the array are contained within
the context indicated by the _TRIGGER_NOTIF_ENGINE_ID and
_TRIGGER_NOTIF_CONTEXT values.
_TRIGGER_NOTIF_VB_VAL []
An array containing the string representation of the values of
particular MIB instances contained in the _TRIGGER_NOTIF_VB_OID
array.
_TRIGGER_NOTIF_VB_TYPE []
An array containing the Type Identifier strings associated with the
Expires August 15, 2001 [Page 71]
Internet Draft SEE Specification February 2001
values contained in the _TRIGGER_NOTIF_VB_VAL array.
Invocation Outputs
None.
Runtime Permissions
Scripts running in this profile have full access to the execution
environment features. Table 5 lists the allowable settings for the
seeTaskControlExecPermissions object.
Note that individual tasks may be activated in this application profile
with a lower set of permissions.
Table 5: Notification Receiver Profile Runtime Permissions
Permission Enum Max. Setting
--------------------------------------
agentEnvVars(0) 1
groupEnvVars(1) 1
taskEnvVars(2) 1
notificationPDUs(3) 1
getPDUs(4) 1
setPDUs(5) 1
writeConfig(6) 1
diagnostics(7) 1
oidAliases(8) 1
Refer to the SeeExecPermissions textual convention for the definition of
each permission BIT.
Implementation Restrictions
In the event multiple Notification Receiver tasks are configured to
receive the same notification type, the following rule applies:
task order
The tasks are invoked in the same order every time. Specifically,
the tasks are invoked in ascending order, starting with the lowest
value of seeTaskControlIndex (e.g. _TASK_ID environment variable).
The agent may restrict the number of management tasks that are
configured to receive a particular notification type.
Expires August 15, 2001 [Page 72]
Internet Draft SEE Specification February 2001
7.4.6. Virtual Get Profile
This profile allows a particular script to be invoked as a 'secondary'
command responder application, when the associated
seeTaskControlLastResult object is retrieved by a command generator
application.
The agent will invoke the specified script when the internal command
responder application receives a request for the associated instance of
the seeTaskControlLastResult object. The read-only script will return a
string encoded value. The base encoding of the script result is
contained in the associated seeTaskControlResultType object.
This mode is intended for monitoring arbitrarily complex system
conditions via runtime-loadable meta-logic.
Configuration Inputs
The seeTaskControlEntry objects are described, as they pertain to this
application profile:
seeTaskControlAppProfile
The constant 'appVirtualGet(6)'.
seeTaskControlRunButton
Not used.
seeTaskControlEngineId
This object must be set to a zero length string to indicate the
local SNMP engine.
seeTaskControlContextName
This object may reference any local context. If it is set to a non-
zero length string, then only Get* PDUs with the same value
'contextName' value (or 'community' for SNMPv1) will cause the
associated script to be invoked.
seeTaskControlTriggerOid
Not used.
seeTaskControlTriggerInt
Not used.
seeTaskControlTriggerOvflAct
This object must be set to 'dropTrigger(1)'. If a trigger overflow
Expires August 15, 2001 [Page 73]
Internet Draft SEE Specification February 2001
event occurs, the agent will return an empty string for the
seeTaskControlLastResult object which caused the event (not the
event in progress), and set the associated seeTaskControlResCode to
the constant 'triggerOverflowError(10)'.
Invocation Inputs
The following function template is used by all tasks of this profile as
the script entry point. The 'seeTaskControlStartFn' object must
identify a function matching this prototype:
STRING <identifier> ( void );
The following common environment variables are available to tasks of
this application profile. Refer to section 7.2.1 for details on these
variables.
_HOST_ENGINE_ID
_HOST_CONTEXT_NAME
_TARGET_ENGINE_ID
_TARGET_CONTEXT_NAME
_TASK_OWNER
_TASK_NAME
_TASK_ID
_TRIGGER_SYS_UPTIME
_TRIGGER_TIME_OF_DAY
_SCRATCHPAD []
The Virtual Get application profile does not define any additional
profile-specific system variables.
Invocation Outputs
The script is expected to return a STRING value to the agent upon task
completion. This must contain a properly formatted string conversion of
the Type Identifier indicated by the associated seeTaskControlResultType
object.
Runtime Permissions
Scripts running in this profile have read-only access to the execution
environment features. Table 6 lists the allowable settings for the
seeTaskControlExecPermissions object.
Table 6: Virtual Get Profile Runtime Permissions
Expires August 15, 2001 [Page 74]
Internet Draft SEE Specification February 2001
Permission Enum Max. Setting
--------------------------------------
agentEnvVars(0) 0
groupEnvVars(1) 0
taskEnvVars(2) 0
notificationPDUs(3) 0
getPDUs(4) 1
setPDUs(5) 0
writeConfig(6) 0
diagnostics(7) 0
oidAliases(8) 0
Refer to the SeeExecPermissions textual convention for the definition of
each permission BIT.
Implementation Restrictions
None.
7.4.7. Manual Profile
This application profile allows a script to be invoked manually by a
management application.
This mode is intended for delegating arbitrarily complex system control
logic, and invoking it manually, on an ad-hoc basis. It is identical to
the Calendar application profile except an external command generator
application initiates task invocation instead of a Scheduling MIB
implementation on the local SNMP engine.
This mode is intended for delegating arbitrarily complex system control
commands to a local system, in order to hide the localized complexity of
particular management operations. It may also be used to debug
management tasks of other application profiles.
The agent will invoke the associated script on behalf of a particular
management task, if that task is not already running, when the
associated seeTaskControlRunButton is set to 'runTask(1)'.
Configuration Requirements
The seeTaskControlEntry objects are described, as they pertain to this
application profile:
Expires August 15, 2001 [Page 75]
Internet Draft SEE Specification February 2001
seeTaskControlAppProfile
The constant 'appManual(7)'.
seeTaskControlRunButton
If the associated task is not already running, then it will be
invoked when this object is set to the value 'runTask(1)'.
seeTaskControlEngineId
This object may reference the local SNMP engine or a remote SNMP
engine.
seeTaskControlContextName
This object may reference any context.
seeTaskControlTriggerOid
Not used.
seeTaskControlTriggerInt
Not used.
seeTaskControlTriggerOvflAct
This object must be set to 'dropTrigger(1)'. If a trigger overflow
event occurs, the agent will return an 'inconsistentValue' error
Response PDU to the command generator application which is
currently setting the seeTaskControlRunButton object.
Invocation Inputs
The following function template is used by all tasks of this profile as
the script entry point. The 'seeTaskControlStartFn' object must
identify a function matching this prototype:
void <identifier> ( void );
The following common environment variables are available to tasks of
this application profile. Refer to section 7.2.1 for details on these
variables.
_HOST_ENGINE_ID
_HOST_CONTEXT_NAME
_TARGET_ENGINE_ID
_TARGET_CONTEXT_NAME
_TASK_OWNER
_TASK_NAME
_TASK_ID
Expires August 15, 2001 [Page 76]
Internet Draft SEE Specification February 2001
_TRIGGER_SYS_UPTIME
_TRIGGER_TIME_OF_DAY
_SCRATCHPAD []
The Manual application profile does not define any additional profile-
specific system variables.
Invocation Outputs
None
Runtime Permissions
Scripts running in this profile have full access to the execution
environment features. Table 7 lists the allowable settings for the
seeTaskControlExecPermissions object.
Note that individual tasks may be activated in this application profile
with a lower set of permissions.
Table 7: Manual Profile Runtime Permissions
Permission Enum Max. Setting
--------------------------------------
agentEnvVars(0) 1
groupEnvVars(1) 1
taskEnvVars(2) 1
notificationPDUs(3) 1
getPDUs(4) 1
setPDUs(5) 1
writeConfig(6) 1
diagnostics(7) 1
oidAliases(8) 1
Refer to the SeeExecPermissions textual convention for the definition of
each permission BIT.
Implementation Restrictions
None.
7.5. System Libraries
System libraries are groupings of related functions. They are
identified with a registration OBJECT IDENTIFIER and a version number.
Expires August 15, 2001 [Page 77]
Internet Draft SEE Specification February 2001
All system library names must be unique within agent scope, and should
be globally unique. All function names within a library must be unique.
An agent must not permit multiple libraries to be present which contain
functions with identical names.
The system library is the minimum granularity of conformance available
in the architecture. A conforming agent must implement all the
functions defined within a given version of a library, in order to list
that library in the smExtsnTable.
There are three support levels defined for system libraries (as
identified by the LIBRARY-TYPE macro SUPPORT clause).
Mandatory Libraries
A library should be considered mandatory if the chance of useful
multi-vendor interoperability will be seriously diminished if the
library is not supported. Mandatory libraries are expected to be
added very infrequently over time.
Conditionally Mandatory Libraries
Conditionally mandatory libraries are supported, such that an
implementation is expected to support the complete library
specification for this type of library, if particular underlying
system features are available.
Optional Libraries
Optional libraries are supported, such that a developer may choose
to support the library or not, based on particular product
requirements.
7.5.1. Library Versioning
Library versioning is supported, in order to keep the identifier for a
given library stable over time. The functions within a library cannot
be changed or deleted over time. The only recognized modification to a
system library is the addition of new functions, in order to enforce
backwards compatibility with previous versions of the library.
An agent must support the fully specified semantics for every function
defined in a library (for the specified version) in order to be
considered a complete and conforming implementation.
It is an implementation-specific matter as to when a missing library
function is detected, and flagged as a fatal runtime error. It is
possible this condition will not be detected by an agent unless an
Expires August 15, 2001 [Page 78]
Internet Draft SEE Specification February 2001
running task actually attempts to call a missing function. An exception
is the 'Validate' run mode, in which the agent is required to validate
the correctness of an entire script.
7.5.2. Library Documentation Requirements
A new construct is introduced in this section for the documentation of
system libraries. The 'LIBRARY-TYPE' macro is used to document various
attributes of a library and the functions it contains.
-- a file containing one or more library definitions
<lib-file> =
( <lib-definition> | <lib-file> <lib-definition> )
-- a library definition
<lib-definition> =
<lib-name> "LIBRARY-TYPE" "::="
"BEGIN"
"STATUS" <status-val>
"SUPPORT" <support-val>
"IDENTITY" "{" <lib-id> "}"
"VERSION" <string-literal>
"LIB-DESCR" <string-literal>
[ "OBSOLETES" <lib-id> ]
<func-lists>
<import-lists>
<func-defs>
"END"
<lib-name> =
<identifier>
<status-val> =
( "current" | "deprecated" | "obsolete" )
<support-val> =
( "mandatory" | "conditional" | "optional" )
<import-lists> =
( <import-list> | <import-lists> <import-list> )
<import-list> =
"IMPORTS" string <imports> ";"
<imports> =
Expires August 15, 2001 [Page 79]
Internet Draft SEE Specification February 2001
( <import> | <imports> <import> )
<import> =
<identifier-list> "FROM" <mib-name>
<func-lists> =
( <func-list> | <func-lists> <func-list> )
<func-list> =
"FUNC-LIST" string
"{" <identifier-list> "}"
<identifier-list> =
( <identifier> | <identifier-list> "," <identifier> )
<mib-name> =
( <mib-letter> |
<mib-name> <digit> |
<mib-name> <mib-nondigit> )
<mib-letter> =
( "a" .. "z" | "A" .. "Z" )
<mib-nondigit> =
( "a" .. "z" |
"A" .. "Z" |
"-" ) -- single dash char
<lib-id> =
value(OBJECT IDENTIFIER)
<func-defs> =
( <func-def> | <func-defs> <func-def> )
<func-def> =
"FUNCTION" <identifier>
"FUNC-DECL" """ <func-decl> """
"FUNC-DESCR" <string-literal>
"ACCESS-BITS" "{" <named-bits> "}"
[ "ACCESS-DESCR" <string-literal> ]
[ <params> ]
[ <return> ]
<named-bits> =
( <named-bit> | <named-bits> "," <named-bit> )
Expires August 15, 2001 [Page 80]
Internet Draft SEE Specification February 2001
<named-bit> =
<identifier> "(" <integer-constant> ")"
<params> =
( <param> | <params> <param> )
<param> =
"PARAM" ( <identifier> | "..." ) <type-constraint>
<string-literal>
<return> =
"RETURN" <type-constraint> <string-literal>
-- very simple type constraint expressions in this version
<type-constraint> =
"{" [ ( <identifier> | <range-part> | <value-list> ) ]
[ <array-part> ] "}"
-- the 2 constants must be the same type, and the 2nd one
-- must represent a value greater than the first one
<range-part> =
<constant> ".." <constant>
-- all constants in the list must be the same type
-- and the same value must not appear more than once
<value-list> =
( <constant> |
<value-list> "," <constant> )
-- the array-part is mandatory for array parameters
-- and not allowed for non-array parameters
<array-part> =
"[" <integer-constant> "]"
-- <identifier>, <string-literal>, <constant>,
-- and <integer-constant> tokens defined in section 7.2.1
7.5.2.1. Mapping of the LIBRARY-TYPE Macro
This macro-like construct is used as a documentation template for system
libraries. This section describes the individual fields of this macro.
Expires August 15, 2001 [Page 81]
Internet Draft SEE Specification February 2001
lib-name field
This string must conform to the SeeIdentifierString syntax, and
identify the name of the system library. It should be globally
unique, if possible. This field should be included in the string
for the smExtsnDescr MIB object.
STATUS Clause
This field is used exactly as with the OBJECT-TYPE macro. The
normal status for a system library is 'current'. In the event, a
new library is defined to replace an existing library, then the new
library will be defined with current status, and a new version of
the old library is defined with 'deprecated' status. Over time, a
deprecated library can be removed, and the status changed to
'obsolete'.
SUPPORT Clause
The support clause identifies the implementation requirements for
the library. The value 'mandatory' indicates that all agent
platforms must support the library. The value 'conditional'
indicates that some agent platforms must support the library, based
on specific agent platform capabilities and features. The 'LIB-
DESCR' clause must include a description of the pre-conditions and
system requirements related to the library, in this case. The
value 'optional' indicates that implementation of the library is
optional.
IDENTITY Clause
The registration OBJECT IDENTIFIER used as the stable, global
identifier for the library. Note that the IDENTITY and VERSION
clauses are used together to completely identify a particular
library, not the IDENTITY clause alone.
VERSION Clause
The version string is not a formatted string, however all version
strings over time for a given value must be unique. The versioning
sequence should be self-evident, so that it if two different
version strings are examined for the same library, it is easy to
tell which one represents the newer version. This value is used
for the smExtsnVersion object in the smExtsnEntry for the library.
LIB-DESCR Clause
A textual description of the library purpose, features, and
implementation requirements.
Expires August 15, 2001 [Page 82]
Internet Draft SEE Specification February 2001
OBSOLETES Clause
If this library is intended to replace an existing library then
this clause must be present. The <lib-id> field identifies the
registration OBJECT IDENTIFIER of the obsolete library. This clause
indicates that all versions of the specified library are replaced
by the library containing the OBSOLETES clause. Only libraries
with a 'deprecated' or 'obsolete' STATUS should be identified in an
OBSOLETES clause.
FUNC-LIST Clause
A list of the functions associated with a particular version of the
library. These clauses are not removed over time. Instead, new ones
are added, which contain only the functions added in that library
version.
At least one FUNC-LIST clause must be present (i.e. the first
version), but a new FUNC-LIST clause is added only if new functions
are actually added in that version.
The string parameter is a version string, containing the contents
of the VERSION clause when the FUNC-LIST clause is added to the
LIBRARY-TYPE macro.
IMPORTS Clause
A list of external identifiers used in a particular version of the
library. Each textual convention based Type Identifier declared
within a PARAM or RETURN clause must be declared in the IMPORTS
clause, to identify the source of all definitions referenced. This
is required, since textual conventions may not be globally unique.
The string parameter is a version string, containing the contents
of the VERSION clause when the IMPORTS clause is added to the
LIBRARY-TYPE macro, which exactly matches the version string for
the corresponding FUNC-LIST clause.
At most one IMPORTS clause may be present for each FUNC-LIST clause
specified, as identified by matching version string parameters.
The same imported identifier must only appear once in any of the
IMPORTS clauses. If no new external identifiers are needed for a
new library version, then the IMPORTS clause must not be present
for that version.
Expires August 15, 2001 [Page 83]
Internet Draft SEE Specification February 2001
7.5.2.2. Mapping of the 'func-def' Construct
Each function identified in a FUNC-LIST macro must be documented using
the <func-def> construct, within the LIBRARY-TYPE macro. This section
describes the individual fields of this construct.
FUNCTION Clause
The string identifies the function name, and matches the associated
string in exactly one FUNC-LIST clause within the LIBRARY-TYPE
macro.
FUNC-DECL Clause
The string contains the programming language function declaration
for this function. This must include the return type, the
identifier used in the FUNCTION clause, and all function
parameters.
FUNC-DESCR Clause
A textual description of the function.
ACCESS-BITS Clause
A set of system access permission bits related to the function.
The <named-bits> portion of this clause must name zero or more
named bits from the SeeExecPermissions TC. Listing a named bit
indicates that the related system access privilege is needed by a
calling task in order for the function to succeed. It is possible
that different parameter combinations imply different system access
privileges, so the ACCESS-DESCR clause is used to indicate any
conditions placed on each of the bits named in this clause.
ACCESS-DESCR Clause
A textual description of the system access privileges and related
implementation requirements, for the specified function. This
clause may be omitted if the associated ACCESS-BITS clause is
empty.
Type Constraint Construct
The PARAM and RETURN clauses both include this construct, which
identifies any value constraints placed on the base type
(identified in the FUNC-DECL clause). An empty set of braces
indicates that all values of the specified base type are
potentially valid values for the parameter or return value.
If applicable, a textual convention name should be declared (e.g.
'SeeResultCode' or 'SnmpAdminString'). If no textual convention
Expires August 15, 2001 [Page 84]
Internet Draft SEE Specification February 2001
applies, then a Type Identifier should be specified (e.g.
'Counter32' or 'TimeTicks') to indicate the most appropriate 'MIB
data type' for the parameter, if applicable. If the semantics of
the base type (e.g. 'int' or 'long') fully describe the type
constraints, then this field should be left empty.
If the parameter is an array of an arbitrary number of values, then
the string "[]" must follow the first field. If the parameter is
an array of a specific maximum number of values, then the string
"[n]", where n is an integer constant identifying the maximum
number of array elements allowed in the parameter, must follow the
first field.
Any Type Identifier which would normally need to be imported (i.e.
all TCs and most base SMIv2 types) must be specified in an IMPORTS
clause.
Some examples of valid Type Constraint clauses include:
{ } -- one base type value
{ [30] } -- an array of base type values
{ OBJECT IDENTIFIER } -- not in IMPORTS
{ BITS } -- not in IMPORTS
{ Counter32 [] }
{ SnmpAdminString }
{ SnmpAdminString [20] }
PARAM Clause
A description of a function parameter, indicated by the 'additional
parameters' token ('...') or an <identifier> token. which must
match a corresponding parameter listed in the FUNC-DECL clause.
The type qualifier clause must be present, as described in the
previous section, The string field in this clause should describe
the purpose and implementation requirements for the parameter.
RETURN Clause
A description of the return value type, identified in the FUNC-DECL
clause. The type qualifier clause is described in the previous
section, and may only be present if the return type is something
other than 'void'. The string contents in this clause should
describe the purpose and implementation requirements for the return
value.
Expires August 15, 2001 [Page 85]
Internet Draft SEE Specification February 2001
7.5.2.3. Library Versioning Example
The following LIBRARY-TYPE macro illustrates how a library may be
versioned over time.
ExampleTestLib LIBRARY-TYPE ::=
BEGIN
STATUS current
SUPPORT optional
IDENTITY { acmeDiagLibraries 3 }
VERSION "1.2"
LIB-DESCR
"Contains functions for testing the Acme switch HW."
FUNC-LIST "1.0" {
test_switch,
test_port
}
FUNC-LIST "1.1" {
test_vlan
}
FUNC-LIST "1.2" {
reset_switch
}
IMPORTS "1.0"
TestResult, SwitchId, SlotId, PortId
FROM ACME-SWITCH-MIB;
IMPORTS "1.1"
VlanId
FROM ACME-VLAN-MIB;
FUNCTION test_switch
FUNC-DECL "uint test_switch (IN switch_id);"
FUNC-DESCR
"Run pre-installed tests on all ports of
the specified switch."
ACCESS-BITS { diagnostics(7) }
ACCESS-DESCR
"Diagnostics test access required."
PARAM switch_id { SwitchId }
"The globally unique ID of the switch to test."
RETURN { TestResult }
"The test result code."
Expires August 15, 2001 [Page 86]
Internet Draft SEE Specification February 2001
FUNCTION test_port
FUNC-DECL "uint test_port (IN switch_id,
IN slot_id, IN port_id);"
FUNC-DESCR
"Run pre-installed tests on one port on the
specified switch."
ACCESS-BITS { diagnostics(7) }
ACCESS-DESCR
"Diagnostics test access required."
PARAM switch_id { SwitchId }
"The globally unique ID of the switch to test."
PARAM slot_id { SlotId }
"The slot number on the specified switch to test."
PARAM port_id { PortId }
"The port number on the specified slot to test."
RETURN { TestResult }
"The test result code."
FUNCTION test_vlan
FUNC-DECL "uint test_vlan (IN switch_id, IN vlan_id);"
FUNC-DESCR
"Run pre-installed tests on a VLAN on the
specified switch."
ACCESS-BITS { diagnostics(7) }
ACCESS-DESCR
"Diagnostics test access required."
PARAM switch_id { SwitchId }
"The globally unique ID of the switch to test."
PARAM vlan_id { VlanId }
"The globally unique ID of the switch to test."
RETURN { TestResult }
"The test result code."
FUNCTION reset_switch
FUNC-DECL "uint reset_switch (IN switch_id);"
FUNC-DESCR
"Reset the specified switch."
ACCESS-BITS { writeConfig(6) }
ACCESS-DESCR
"Write access to system configuration data is required."
PARAM switch_id { SwitchId }
"The globally unique ID of the switch to reset."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
Expires August 15, 2001 [Page 87]
Internet Draft SEE Specification February 2001
that occurred."
END
7.6. Log Message Formats
TBD
7.7. Script Execution Environment MIB
SEE-MIB DEFINITIONS ::= BEGIN
IMPORTS
MODULE-IDENTITY, OBJECT-TYPE, Integer32,
Unsigned32, Counter32, NOTIFICATION-TYPE,
experimental
FROM SNMPv2-SMI
MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP
FROM SNMPv2-CONF
RowStatus, TimeStamp, TEXTUAL-CONVENTION,
TruthValue, StorageType, DateAndTime
FROM SNMPv2-TC
SnmpAdminString
FROM SNMP-FRAMEWORK-MIB
SnmpEngineIdOrNone
FROM ENTITY-MIB
smScriptOwner, smScriptName, smLanguageGroup,
smScriptGroup, smCodeGroup
FROM DISMAN-SCRIPT-MIB;
seeMIB MODULE-IDENTITY
LAST-UPDATED "200012240000Z"
ORGANIZATION "Cisco Systems, Inc."
CONTACT-INFO
" Andy Bierman
Cisco Systems, Inc.
Postal: 170 West Tasman Drive
San Jose, CA USA 95134
Tel: +1 408 527-3711
E-mail: abierman@cisco.com
Send comments to <abierman@cisco.com>"
DESCRIPTION
"This module defines MIB variables related to the operation
Expires August 15, 2001 [Page 88]
Internet Draft SEE Specification February 2001
of the Script Execution Environment."
REVISION "200012240000Z"
DESCRIPTION
"Initial version of the Script Execution Environment MIB
module."
::= { experimental xxx }
seeMibObjects OBJECT IDENTIFIER ::= { seeMIB 1 }
seeNotifications OBJECT IDENTIFIER ::= { seeMIB 2 }
seeConformance OBJECT IDENTIFIER ::= { seeMIB 3 }
seeCapsObjects OBJECT IDENTIFIER ::= { seeMibObjects 1 }
seeEnvObjects OBJECT IDENTIFIER ::= { seeMibObjects 2 }
seeExecObjects OBJECT IDENTIFIER ::= { seeMibObjects 3 }
seeRegistrations OBJECT IDENTIFIER ::= { seeMibObjects 4 }
--
-- SEE Textual Conventions
--
SeeAppProfile ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"This TC describes an enumerated integer that identifies an
individual application profile.
The value 'appWatchedVar' indicates the Watched Variable
application profile, which allows a script to be executed if
instances of a polled MIB object changes value.
The value 'appPeriodic' indicates the Periodic application
profile, which allows a script to be executed repeatedly,
once per specified polling interval.
The value 'appCalendar' indicates the Calendar application
profile, which allows a script to be executed on an ad-hoc
basis, with the Scheduling MIB.
The value 'appNotifyFilter' indicates the Notification
Filter application profile, which allows a script to be
executed just before particular notifications are generated
by the SNMP Entity hosting the script execution environment.
Expires August 15, 2001 [Page 89]
Internet Draft SEE Specification February 2001
The value 'appNotifyReceiver' indicates the Notification
Receiver application profile, which allows a script to be
executed when particular notifications are received by the
SNMP Entity hosting the script execution environment.
The value 'appVirtualGet' indicates the Virtual Get
application profile, which allows a read-only script to be
executed if an associated MIB object is retrieved by a
command generator application.
The value 'appManual' indicates this the Manual application
profile, which allows a script to be executed by management
application action only."
SYNTAX INTEGER {
appWatchedVar(1),
appPeriodic(2),
appCalendar(3),
appNotifyFilter(4),
appNotifyReceiver(5),
appVirtualGet(6),
appManual(7)
}
SeeExecPermissions ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"This TC describes a BITS object that identifies the
specific runtime permissions on the host SNMP engine for a
particular management task execution environment.
If the 'agentEnvVars' BIT is set, then this task may create
and destroy environment variables with agent scope.
If the 'groupEnvVars' BIT is set, then this task may create
and destroy environment variables with group scope, and only
for the group identified by the associated
seeTaskControlGroupId object.
If the 'taskEnvVars' BIT is set, then this task may create
and destroy environment variables with group scope, and only
for this task, identified by the associated
seeTaskControlTaskIndex object.
If the 'notificationPDUs' BIT is set, and the application
Expires August 15, 2001 [Page 90]
Internet Draft SEE Specification February 2001
profile for this entry permits notification generation, then
this task may emit notifications via the 'SnmpMsgLib' system
library functions.
If the 'getPDUs' BIT is set, then this task may conduct SNMP
data retrieval transactions via the 'SnmpMsgLib' system
library functions.
If the 'setPDUs' BIT is set, then this task may conduct SNMP
Set transactions via the system library functions.
If the 'writeConfig' BIT is set, and write access is
permitted by the application profile for this entry, then
this task may call system library functions which
(potentially) change configuration parameters in the host
SNMP engine.
If the 'diagnostics' BIT is set, and write access is
permitted by the application profile for this entry, then
this task may call system library functions which invoke
(potentially intrusive) diagnostics tests on the host SNMP
engine.
If the 'oidAlias' BIT is set, and write access is permitted
by the application profile for this entry, then this task
may call system library functions which create, delete, or
mmodify the set of OID Alias identifier tokens available to
all tasks (i.e. agent scope)."
SYNTAX BITS {
agentEnvVars(0),
groupEnvVars(1),
taskEnvVars(2),
notificationPDUs(3),
getPDUs(4),
setPDUs(5),
writeConfig(6),
diagnostics(7),
oidAliases(8)
}
SeeLogOutput ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"This TC describes a log fragment.
Expires August 15, 2001 [Page 91]
Internet Draft SEE Specification February 2001
Because debug log messages may become too large too download
in a single SNMP PDU, log files may need to be fragmented in
a configurable manner.
An agent may limit the size of actual MIB instances of this
type, based on the resource or transport layer limitations
of the operating environment."
SYNTAX OCTET STRING (SIZE(0..65535))
SeeGroupIdentifier ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"This TC describes an integer that represents an
administratively assigned 'task group' identifier. All
management tasks in the same group share access to
environment variables defined with 'group scope'."
SYNTAX Integer32 (1..2147483647)
SeeTypeIdentifier ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"This TC describes a string that represents a globally
unique data type identifier string. The agent uses this
string for type conversion and data validation purposes
within the execution environment.
This is a case-sensitive string that is not null-terminated.
It must contain the name of a base data type from the
SMIv2-SMI, or a base data type from the SEE language.
The intrinsic Type Identifier 'Null' is used to
differentiate between an empty string and an unset string.
There are three 'read-only' variants of the 'Null' Type
Identifier, which may be present in Response PDU varbind
lists to clarify the semantics of a zero length value
string:
'NoSuchName'
'NoSuchInstance'
'EndOfMibView'
The following list contains the list of valid Base Type
Identifiers, derived from the SMIv2 [RFC2578], and the SEE
Expires August 15, 2001 [Page 92]
Internet Draft SEE Specification February 2001
language definition.
'BITS'
'char'
'Counter32'
'Counter64'
'EndOfMibView'
'float'
'Gauge32'
'int'
'INTEGER'
'Integer32'
'IpAddress' (deprecated)
'long'
'NoSuchInstance'
'NoSuchName'
'Null'
'OBJECT IDENTIFIER'
'OCTET STRING'
'OID'
'Opaque' (deprecated)
'STRING'
'TimeTicks'
'uint'
'ulong'
'Unsigned32' "
SYNTAX OCTET STRING (SIZE (1..32))
SeeIdentifierString ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"This TC describes a string that conforms to the syntax
requirements for an <identifier> token in the SEE language
specification. Identifiers in the SEE MIB are restricted to
the underscore character (_), numeric characters ([0..9]),
and the letters of the alphabet ([a..z] | [A..Z])."
SYNTAX OCTET STRING (SIZE (1..48))
SeeStringLiteral ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"This TC describes an arbitrary string value that conforms
to the syntax requirements for a <string-literal> token in
Expires August 15, 2001 [Page 93]
Internet Draft SEE Specification February 2001
the SEE language specification, except that the double
quotes that start and end the string and not saved in
objects of this type, in order to remain consistent with
'SNMP strings'."
SYNTAX OCTET STRING (SIZE (0..65535))
SeeResultCode ::= TEXTUAL-CONVENTION
STATUS current
DESCRIPTION
"This TC describes a script or function result code. This
enumerated list is derived from smRunExitCode object in the
Script MIB, It is used here as a TC, to allow these
semantics to be shared by multiple objects. The enumeration
'noError' has been changed from the value '1' to the value
'0' to be consistent with the C programming language. The
value '1' as been changed to 'notSet'. An additional
enumeration (triggerOverflowError) has also been added.
An object of this type may have one of the following values:
- `noError', which indicates that the script or function
completed successfully without errors;
- `notSet', which does not indicate any error condition;
- `halted', which indicates that the script or function
was halted by a request from an authorized manager;
- `lifeTimeExceeded', which indicates that the script or
function exited because a time limit was exceeded;
- `noResourcesLeft', which indicates that the script or
function exited because it ran out of resources,
(e.g. memory);
- `languageError', which indicates that the script or
function exited because of a language error (e.g. a
syntax error in an interpreted language);
- `runtimeError', which indicates that the script or
function exited due to a runtime error (e.g. a
division by zero);
- `invalidArgument', which indicates that the script or
Expires August 15, 2001 [Page 94]
Internet Draft SEE Specification February 2001
function could not be run because of invalid arguments;
- `securityViolation', which indicates that the script or
function exited due to a security violation;
- `genericError', which indicates that the script or
function exited for an unspecified reason.
- `triggerOverflowError', which indicates that the
management task or function did not execute because an
invocation of that task was already in progress, and
the trigger event was dropped instead of queued.
If the script has not yet begun running, or is currently
running, the value will be `notSet'."
SYNTAX INTEGER {
noError(0),
notSet(1),
halted(2),
lifeTimeExceeded(3),
noResourcesLeft(4),
languageError(5),
runtimeError(6),
invalidArgument(7),
securityViolation(8),
genericError(9),
triggerOverflowError(10)
}
--
-- SEE Agent System Resource Capabilities
--
seeCapsTodClock OBJECT-TYPE
SYNTAX INTEGER {
noTodClock(1),
todClock(2),
todClockAndTz(3)
}
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"An indication of the Time of Day clock capabilities of this
Expires August 15, 2001 [Page 95]
Internet Draft SEE Specification February 2001
agent.
If this object is equal to 'noTodClock(1)', then this agent
does not have a Time of Day clock, and therefore does not
support the 'TimeLib' system library, the schedLocalTime MIB
object, or the _TRIGGER_TIME_OF_DAY environment variable.
If this object is equal to 'todClock(2)', then this agent
has a Time of Day clock, but does not know the local
timezone, (i.e. supports the 8 octet variant of the
TimeAndDate textual convention). The agent therefore
supports the TimeLib system library and _TRIGGER_TIME_OF_DAY
environment variable, but does not support the
schedLocalTime MIB object.
If this object is equal to 'todClockAndTz(3)', then this
agent has a Time of Day clock, and also knows the local
timezone, (i.e. supports the 11 octet variant of the
TimeAndDate textual convention). The agent therefore
supports the TimeLib system library, schedLocalTime MIB
object, and the _TRIGGER_TIME_OF_DAY environment variable.
The agent must set this object during system initialization
and not change the value without reinitializing the agent."
::= { seeCapsObjects 1 }
seeCapsFloatDataType OBJECT-TYPE
SYNTAX TruthValue
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"An indication of the floating point arithmetic capabilities
of this agent.
If this object is equal to 'false', then the agent does not
support the 'float' data type defined in the scripting
language.
If this object is equal to 'true', then the agent does
support the 'float' data type defined in the scripting
language.
The agent must set this object during system initialization
and not change the value without reinitializing the agent."
::= { seeCapsObjects 2 }
Expires August 15, 2001 [Page 96]
Internet Draft SEE Specification February 2001
seeCapsMinPollInterval OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
UNITS "seconds"
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The minimum polling interval that this SEE agent will
support. Implementations are permitted to set their own
minimum polling interval, based on the capabilities of the
system. The agent should set this object as closely as
possible to the value '1'.
The agent must set this object during system initialization
and not change it without reinitializing the agent."
::= { seeCapsObjects 3 }
seeCapsMaxEnvStringLen OBJECT-TYPE
SYNTAX Integer32 (64..2147483647)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The maximum length of an individual environment variable
string that this SEE agent will support.
The agent must set this object during system initialization
and not change it without reinitializing the agent."
::= { seeCapsObjects 4 }
seeCapsAllowedTargets OBJECT-TYPE
SYNTAX INTEGER {
localTarget(1),
remoteTargets(2),
localAndRemoteTargets(3)
}
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"An indication of the target platform types that this agent
can support.
If this object is equal to 'localTarget(1)', then this agent
only supports application profiles which run on behalf of
the local SNMP engine. The agent will only allow the
seeTaskControlEngineId object to contain an empty string
(indicating that the target SNMP engine is the host SNMP
Expires August 15, 2001 [Page 97]
Internet Draft SEE Specification February 2001
engine).
If this object is equal to 'remoteTargets(2)', then this
agent only supports application profiles which run on behalf
of remote SNMP engines (e.g. the agent is a mid-level
manager containing only the MIB objects required to
configure itself). The agent will only allow the
seeTaskControlEngineId object to contain a non-zero length
string, not equal to the snmpEngineId for the local agent.
If this object is equal to 'localAndRemoteTargets(3)', then
this agent supports application profiles which run on behalf
of local or remote SNMP engines. The agent will allow the
seeTaskControlEngineId object to contain any valid value.
The agent must set this object during system initialization
and not change it without reinitializing the agent."
::= { seeCapsObjects 5 }
--
-- SEE Environment Configuration Scalars
--
seeTaskAbortNotifyEnabled OBJECT-TYPE
SYNTAX TruthValue
MAX-ACCESS read-write
STATUS current
DESCRIPTION
"If this object contains the value 'true', then the agent
will allow generation of seeTaskAbort notifications to
occur.
Otherwise, the agent will not generate any seeTaskAbort
notifications."
::= { seeEnvObjects 1 }
seeTaskAlarmNotifyEnabled OBJECT-TYPE
SYNTAX TruthValue
MAX-ACCESS read-write
STATUS current
DESCRIPTION
"If this object contains the value 'true', then the agent
will allow generation of seeTaskAlarm notifications to
occur.
Expires August 15, 2001 [Page 98]
Internet Draft SEE Specification February 2001
Otherwise, the agent will not generate any seeTaskAlarm
notifications."
::= { seeEnvObjects 2 }
--
-- SEE Environment Variable Strings
--
seeEnvVarTable OBJECT-TYPE
SYNTAX SEQUENCE OF SeeEnvVarEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"Contains the environment variable definitions used on this
SEE agent. An environment variable is represented as an
array of 'STRING' data elements. The number of strings is
identified by the seeEnvVarArraySize object (in this table)
and the maximum size of each string is identified by the
seeCapsMaxEnvStringLen scalar object.
The SEE agent will recognize the SeeIdentifierString
specified in each entry as an environment variable array
identifier token with the same value.
The indexing of this table allows three different scopes in
which a given environment variable may be visible - agent,
group, and task.
Scope seeEnvVarGroupId seeEnvVarTaskId
Name INDEX INDEX
--------------------------------------------
agent zero zero
group non-zero zero
task zero non-zero
INVALID non-zero non-zero
Agent Scope: 1 instance of the env var per agent
Group Scope: 1 instance of the env var per group
Task Scope: 1 instance of the env var per task
When a task requests access to an environment variable (via
the 'EnvVarLib' System Library), the agent will determine
the proper identifier scope by searching this table for the
correct task, group, or agent scoped entry.
Expires August 15, 2001 [Page 99]
Internet Draft SEE Specification February 2001
The binding between management task and the proper set of
environment variables is done (conceptually) just before
each invocation of the associated script.
Applications should not delete entries which are currently
in use by one or more seeTaskControlEntries."
::= { seeEnvObjects 3 }
seeEnvVarEntry OBJECT-TYPE
SYNTAX SeeEnvVarEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A conceptual row in the seeEnvVarTable.
Entries are created in this table by agent or management
station action. Entries may also be created by scripts via
the 'env_create' function from the 'EnvVarLib' system
library. Note that the size of this table may be restricted
either statically or dynamically, due to limited agent
resources.
An agent should include all environment variables available
in the execution environment in this table."
INDEX { seeEnvVarGroup, seeEnvVarTask, seeEnvVarName }
::= { seeEnvVarTable 1 }
SeeEnvVarEntry ::= SEQUENCE {
seeEnvVarGroup Integer32,
seeEnvVarTask Integer32,
seeEnvVarName SeeIdentifierString,
seeEnvVarArraySize Integer32,
seeEnvVarPermissions INTEGER,
seeEnvVarWriteGroup Integer32,
seeEnvVarWriteTask Integer32,
seeEnvVarInitType INTEGER,
seeEnvVarInitValue SeeStringLiteral,
seeEnvVarStorageType StorageType,
seeEnvVarStatus RowStatus
}
seeEnvVarGroup OBJECT-TYPE
SYNTAX Integer32 (0..2147483647)
MAX-ACCESS not-accessible
STATUS current
Expires August 15, 2001 [Page 100]
Internet Draft SEE Specification February 2001
DESCRIPTION
"The group scope identifier for this environment variable.
If the associated seeEnvVarTask object is greater than zero,
this this object must equal zero.
If this object is equal to zero, and the associated
seeEnvVarTask object is equal to zero, then the indicated
environment variable is visible to all groups for read
access.
If this object is greater than zero, and the associated
seeEnvVarTask object is equal to zero, then the indicated
environment variable is visible in to management tasks with
the same seeTaskControlGroupId value."
::= { seeEnvVarEntry 1 }
seeEnvVarTask OBJECT-TYPE
SYNTAX Integer32 (0..2147483647)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The task scope identifier for this environment variable.
If this object is equal to zero, then the associated
seeEnvVarGroup identifies the scope of this entry (i.e
either group or agent scope).
If this object is greater than zero, then the indicated
environment variable is visible only to the management task
with the same seeTaskControlIndex value as this object."
::= { seeEnvVarEntry 2 }
seeEnvVarName OBJECT-TYPE
SYNTAX SeeIdentifierString
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The environment variable identifier token value associated
with this entry."
::= { seeEnvVarEntry 3 }
seeEnvVarArraySize OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
MAX-ACCESS read-create
Expires August 15, 2001 [Page 101]
Internet Draft SEE Specification February 2001
STATUS current
DESCRIPTION
"The number of strings contained in the environment variable
represented by this entry. Each array element is identified
by an dense index value, starting from zero and ending with
'seeEnvVarArraySize - 1'.
Individual elements can be referenced with the array
operator following the Identifier token (e.g. 'foo[3]'). In
order to maintain syntax consistency within scripts, the
Identifier token may be used alone to indicate the first
array element (i.e. 'foo' and 'foo[0]' reference the same
string).
The value of this object may be retrieved by a script with
the 'env_string_count' function from the 'EnvVarLib' system
library.
Note that the agent must reserve storage for all the array
elements indicated by this object. Applications should keep
array sizes to the minimum required for the particular
management task, in order to conserve agent resources.
This object may not be modified if the associated
seeEnvVarStatus object is equal to active."
::= { seeEnvVarEntry 4 }
seeEnvVarPermissions OBJECT-TYPE
SYNTAX INTEGER {
readOnly(1),
readWrite(2)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The type of access permissions allowed for the environment
variable associated with this entry, within the environment
variable scope defined for this entry.
The value 'readOnly(1)' identifies a environment variable
which may only be read by scripts. Any script within the
scope of this environment variable which attempts to modify
the contents of an environment variable of this type will
terminate with an 'securityViolation' error status. The
associated seeEnvVarWriteGroup and seeEnvVarWriteTask
Expires August 15, 2001 [Page 102]
Internet Draft SEE Specification February 2001
objects are not used in this case.
The value 'readWrite(2)' identifies a environment variable
which may be read or modified by one or more scripts,
depending on the scope of the environment variable
(determined by the seeEnvVarGroup and seeEnvVarTask index
values) and the associated seeEnvVarWriteGroup and
seeEnvVarWriteTask objects.
This object may not be modified if the associated
seeEnvVarStatus object is equal to active."
::= { seeEnvVarEntry 5 }
seeEnvVarWriteGroup OBJECT-TYPE
SYNTAX Integer32 (0..2147483647)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object can be used to limit write access of a
particular environment variable to a specific task group.
It is only relevant if the associated seeEnvVarPermissions
object is equal to 'readWrite'. Otherwise this object is
not used.
If this object is equal to zero, then write access of this
entry is not limited to a single task group. Otherwise, the
associated seeEnvVarWriteTask object must be equal to zero,
and this object identifies the seeTaskControlGroupId value
of the tasks that are allowed to write to this environment
variable.
This object may not be modified if the associated
seeEnvVarStatus object is equal to active."
::= { seeEnvVarEntry 6 }
seeEnvVarWriteTask OBJECT-TYPE
SYNTAX Integer32 (0..2147483647)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object can be used to limit write access of a
particular environment variable to a specific management
task. It is only relevant if the associated
seeEnvVarPermissions object is equal to 'readWrite'.
Expires August 15, 2001 [Page 103]
Internet Draft SEE Specification February 2001
If this object is equal to zero, then write access to this
entry is not restricted to a single task. Otherwise, the
associated seeEnvVarWriteGroup object must be equal to zero,
and this object identifies the seeTaskControlIndex value of
the one task that is allowed to write to this environment
variable.
This object may not be modified if the associated
seeEnvVarStatus object is equal to active."
::= { seeEnvVarEntry 7 }
seeEnvVarInitType OBJECT-TYPE
SYNTAX INTEGER {
initAlgorithmic(1),
initStatic(2)
}
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The manner in which the agent will initialize this
environment variable.
The value 'initAlgorithmic' identifies a system environment
variable which is set by the agent in some algorithmic
manner. In this case, the envVarInitValue object is not
used.
The value 'initStatic' identifies an environment variable
array which is initialized by the agent with the associated
seeEnvVarInitValue, at the time this entry is activated."
::= { seeEnvVarEntry 8 }
seeEnvVarInitValue OBJECT-TYPE
SYNTAX SeeStringLiteral
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The initial value used for the environment variable
associated with this entry.
If the associated seeEnvVarInitType object equals
'initStatic', then the agent will initialize each element of
the the indicated environment variable with this value.
This object may not be modified if the associated
Expires August 15, 2001 [Page 104]
Internet Draft SEE Specification February 2001
seeEnvVarStatus object is equal to active."
::= { seeEnvVarEntry 9 }
seeEnvVarStorageType OBJECT-TYPE
SYNTAX StorageType
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The type on non-volatile storage behavior associated with
this entry."
::= { seeEnvVarEntry 10 }
seeEnvVarStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of this entry. This object must be equal to
active for the associated environment variable to be
recognized within the script execution environment.
Upon activation, the agent will make the environment
variable visible in the indicated scope with the specified
initial value.
Note that if this row is activated and later deactivated,
scripts which attempt to access the environment variable
identified by this entry will terminate with a
'runtimeError' error status."
::= { seeEnvVarEntry 11 }
--
-- SEE OID Alias Table
--
seeOidAliasTable OBJECT-TYPE
SYNTAX SEQUENCE OF SeeOidAliasEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"Contains the OBJECT IDENTIFIER Alias definitions used on
this SEE agent. An OID Alias variable is represented as a
single read-only 'STRING' data element.
The SEE agent will recognize the SeeIdentifierString
Expires August 15, 2001 [Page 105]
Internet Draft SEE Specification February 2001
specified in each entry as an OID Alias identifier token (in
agent scope) with the same value. OID Alias identifier
tokens can be used with any 'read-only' operator that is
valid for a local variable of type 'OID'."
::= { seeEnvObjects 4 }
seeOidAliasEntry OBJECT-TYPE
SYNTAX SeeOidAliasEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A conceptual row in the seeOidAliasTable.
Entries are created in this table by agent or management
station action. Entries may also be created by scripts via
the 'oid_alias_set' function from the 'SysLib' system
library. Note that the size of this table may be restricted
either statically or dynamically, due to limited agent
resources.
An agent should include all OID aliases available in the
execution environment in this table."
INDEX { seeOidAliasString }
::= { seeOidAliasTable 1 }
SeeOidAliasEntry ::= SEQUENCE {
seeOidAliasString SeeIdentifierString,
seeOidAliasOID OBJECT IDENTIFIER,
seeOidAliasStorageType StorageType,
seeOidAliasStatus RowStatus
}
seeOidAliasString OBJECT-TYPE
SYNTAX SeeIdentifierString
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The unique identifier token string that is the target of
this entry. When the agent encounters an identifier token in
a script that exactly matches this string, that identifier
token will be replaced with the contents of the associated
seeOidAliasOID object. This token replacement will be done
for processing purposes only, as the script itself will not
be modified."
::= { seeOidAliasEntry 1 }
Expires August 15, 2001 [Page 106]
Internet Draft SEE Specification February 2001
seeOidAliasOID OBJECT-TYPE
SYNTAX OBJECT IDENTIFIER
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The OBJECT IDENTIFIER to use as a replacement token when
the identifier token identified by this entry is encountered
in a script.
This object may not be modified if the associated
seeOidAliasStatus object is equal to active."
::= { seeOidAliasEntry 2 }
seeOidAliasStorageType OBJECT-TYPE
SYNTAX StorageType
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The type on non-volatile storage behavior associated with
this entry."
::= { seeOidAliasEntry 3 }
seeOidAliasStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of this entry. All values must be set
appropriately before this row may be activated."
::= { seeOidAliasEntry 4 }
--
-- SEE Task Control Table
--
seeTaskControlTable OBJECT-TYPE
SYNTAX SEQUENCE OF SeeTaskControlEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"Controls the operation of each task within the execution
environment. Entries in this table operate independently of
one another. Administrators must configure this table
carefully, since it is possible for management tasks to
interact with each other, since the underlying system
Expires August 15, 2001 [Page 107]
Internet Draft SEE Specification February 2001
parameters and status are shared by all tasks.
The multi-threading mechanisms required to support multiple
active entries in this table are beyond the scope of this
document. Read-only scripts should be written to operate in
a multi-threaded environment. Read-write scripts may be
configured to 'run to completion' or run in a multi-threaded
mode."
::= { seeExecObjects 1 }
seeTaskControlEntry OBJECT-TYPE
SYNTAX SeeTaskControlEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A conceptual row in the seeTaskControlTable.
Entries are created in this table by agent or management
station action. Entries are retained by the agent, as
indicated by the seeTaskControlStorageType object.
The smScriptOwner and smScript objects (from the Script MIB)
identify the particular script associated with each
management task entry."
INDEX { smScriptOwner, smScriptName, seeTaskControlIndex }
::= { seeTaskControlTable 1 }
SeeTaskControlEntry ::= SEQUENCE {
seeTaskControlIndex Integer32,
seeTaskControlDescr SnmpAdminString,
seeTaskControlAppProfile SeeAppProfile,
seeTaskControlExecPermissions SeeExecPermissions,
seeTaskControlGroupId SeeGroupIdentifier,
seeTaskControlRunMode INTEGER,
seeTaskControlRunButton INTEGER,
seeTaskControlStartFn SeeIdentifierString,
seeTaskControlLifetime Integer32,
seeTaskControlEngineId SnmpEngineIdOrNone,
seeTaskControlContextName SnmpAdminString,
seeTaskControlTriggerOid OBJECT IDENTIFIER,
seeTaskControlTriggerInt Integer32,
seeTaskControlTriggerOvflAct INTEGER,
seeTaskControlScratchpadSize Integer32,
seeTaskControlResultType SeeTypeIdentifier,
seeTaskControlLogWriteMode INTEGER,
Expires August 15, 2001 [Page 108]
Internet Draft SEE Specification February 2001
seeTaskControlMaxLogSize Integer32,
seeTaskControlMaxLogChunkSize Integer32,
seeTaskControlLogClearButton INTEGER,
seeTaskControlNumExecOks Counter32,
seeTaskControlNumExecFails Counter32,
seeTaskControlLastResCode SeeResultCode,
seeTaskControlLastResult OCTET STRING,
seeTaskControlLastSEIndex Unsigned32,
seeTaskControlLastSEOffset Integer32,
seeTaskControlTaskRunning TruthValue,
seeTaskControlLastTrigTime TimeStamp,
seeTaskControlCurLogSize Gauge32,
seeTaskControlLostLogOctets Counter32,
seeTaskControlLastLogWriteTime TimeStamp,
seeTaskControlStorageType StorageType,
seeTaskControlStatus RowStatus
}
seeTaskControlIndex OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"An arbitrary index for this management task entry, which is
unique for all values of smScriptOwner and smScriptName.
This index allows multiple management tasks to be be
configured which use the same script, as well as providing a
unique integer identifier for each management task. These
index values may be reused by management applications or the
agent. There is no requirement to retain the semantics of an
active seeTaskControlEntry once the seeTaskControlRowStatus
is set to 'destroy'."
::= { seeTaskControlEntry 1 }
seeTaskControlDescr OBJECT-TYPE
SYNTAX SnmpAdminString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"An administratively assigned textual description of this
management task."
::= { seeTaskControlEntry 2 }
seeTaskControlAppProfile OBJECT-TYPE
SYNTAX SeeAppProfile
Expires August 15, 2001 [Page 109]
Internet Draft SEE Specification February 2001
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The application profile for this management task. The
associated script will be invoked, and runtime constraints
enforced, according to the rules for the application profile
indicated by this object.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 3 }
seeTaskControlExecPermissions OBJECT-TYPE
SYNTAX SeeExecPermissions
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The execution permissions set for this management task.
The associated script will be invoked, and runtime
constraints enforced, according to the particular
permissions enabled in this bit string. Note that this
object does not override any characteristics indicated by
the associated seeTaskControlAppProfile object. Instead, it
allows further constraint of the specific execution
environment and system library features available to script
(on behalf of this entry).
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 4 }
seeTaskControlGroupId OBJECT-TYPE
SYNTAX SeeGroupIdentifier
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The task group identifier for this entry.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 5 }
seeTaskControlRunMode OBJECT-TYPE
SYNTAX INTEGER {
normalRunMode(1),
Expires August 15, 2001 [Page 110]
Internet Draft SEE Specification February 2001
traceRunMode(2),
debugRunMode(3),
validateMode(4)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"Controls the manner in which the script associated with
this task is executed. There are four run modes defined,
which allow some level of control over log messages, script
debugging, and system access.
The value 'normalRunMode' identifies a management task
running in the 'normal' operational mode, in which system
library function logging is disabled. Note that a script
may emit logging messages via library functions, regardless
of the value of this object. This mode only disables trace
logging of system activity.
The value 'traceRunMode' identifies a management task
running in the 'trace' operational mode, in which system
activity, such as calls to library functions, are logged in
the seeLogControlTable.
The value 'debugRunMode' identifies a management task
running in the 'debug' operational mode, in which trace
logging is active, except no read-write library functions
are actually invoked. This allows an administrator some
ability to determine the impact of a new script on the
existing environment, without risking system disruption.
Note that scripts which modify and then inspect system
behavior may behave unexpectedly in this 'no-op' run mode.
The value 'validateMode' identifies a management task that
is installed in validation mode. Instead of executing the
associated script, the agent will examine the entire script
for correctness. Problems such as syntax errors and
unresolved function names should be detected in this mode.
Note that an implementation cannot completely validate OID
Alias and environment variable identifier usage, since these
identifier tokens can be installed dynamically, by scripts
or management applications.
After the validation check is done, the
seeTaskControlLastResCode, seeTaskControlLastSEIndex, and
Expires August 15, 2001 [Page 111]
Internet Draft SEE Specification February 2001
seeTaskControlLastSEOffset objects will be set to non-zero
values if any problems are found. The agent will also
output error messages to the seeLogTable for the script.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
DEFVAL { normalRunMode }
::= { seeTaskControlEntry 6 }
seeTaskControlRunButton OBJECT-TYPE
SYNTAX INTEGER {
runTask(1),
notPressed(2)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object allows the associated script to be executed
manually by a management application.
This object is only used if the associated
seeTaskControlAppProfile object is equal to 'appManual', or
if the associated seeTaskControlRunMode is equal to
'validateMode'. It is ignored by the agent in other
situations.
Setting this object to the value 'runTask(1)' will cause the
script for this entry to be executed once, unless it is
currently running. In that case, the agent will return an
'inconsistentValue' error instead of starting the script on
behalf of this entry. As soon as the script is restarted,
the agent will set this object to the value 'notPressed(2)'.
An application may examine the associated
seeTaskControlTaskRunning object to determine if the task is
currently running.
Setting this object to the value 'notPressed(2)' has no
effect whatsoever."
::= { seeTaskControlEntry 7 }
seeTaskControlStartFn OBJECT-TYPE
SYNTAX SeeIdentifierString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
Expires August 15, 2001 [Page 112]
Internet Draft SEE Specification February 2001
"The unique identifier token string that identifies the
script entry point for this management task entry.
Upon script invocation, the agent will attempt to execute
the script function with this name. If the function does not
exist, or if its inputs or return type does not match the
application profile indicated by the associated
seeTaskControlAppProfile object, then the agent will
terminate the script invocation with a 'languageError'
return status.
Only two function prototype forms are supported at this
time. The specific prototype to use depends on the
application profile.
Without return value:
'void <seeTaskControlStartFn> (void);'
With return value:
'<type-specifier> <seeTaskControlStartFn> (void);'
Note that this object is ignored by the agent if the
associated seeTaskControlRunMode is equal to
'validateMode(4)', since the agent will validate the entire
script, not just this function and all possible code-paths.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 8 }
seeTaskControlLifetime OBJECT-TYPE
SYNTAX Integer32 (0..2147483647)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object indicates the maximum number of seconds that
may elapse before the script associated with this entry is
aborted by the agent with a 'lifeTimeExceeded' error status.
This timeout mechanism applies to each invocation of a
script on behalf of a specific seeTaskControlEntry.
If this object is equal to zero, then the timeout mechanism
is not used, and no maximum script invocation lifetime will
be enforced by the agent.
If this object is greater than zero, then the agent will
Expires August 15, 2001 [Page 113]
Internet Draft SEE Specification February 2001
wait until at least this number of seconds elapses before
terminating the current invocation of the script with a
'lifeTimeExceeded' error status.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 9 }
seeTaskControlEngineId OBJECT-TYPE
SYNTAX SnmpEngineIdOrNone
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object identifies the 'primary target' SNMP engine for
this management task entry. This object, together with the
associated seeTaskControlContextName object, defines the
context associated with the seeTaskControlTriggerOid object.
If this object contains a zero length string, then the local
agent will be used as the target of management operations
executed by the associated script. The agent will limit the
value of this object to a zero-length string if the
seeCapsAllowedTargets object is equal to 'localTarget'.
Otherwise, this object identifies the SNMP entity of the
'primary target' for script logic embodied in the associated
task. Note that a task is not limited to communication with
this target. The agent will create the _TARGET_ENGINE_ID
environment variable in task scope, upon activation of this
entry, set to the value of this object.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 10 }
seeTaskControlContextName OBJECT-TYPE
SYNTAX SnmpAdminString
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object identifies the 'primary target' context for
this management task entry. This object, together with the
associated seeTaskControlEngineId object, defines the
context associated with the seeTaskControlTriggerOid object.
Expires August 15, 2001 [Page 114]
Internet Draft SEE Specification February 2001
The agent will create the _TARGET_CONTEXT_NAME environment
variable (array size of one) in task scope, upon activation
of this entry, with the value of this object.
If the associated seeTaskControlAppProfile object is equal
to 'appNotifyFilter' or 'appNotifyReceiver', and this object
contains a non-zero length string, then this object selects
only notifications with the same contextName (or community),
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 11 }
seeTaskControlTriggerOid OBJECT-TYPE
SYNTAX OBJECT IDENTIFIER
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"An OBJECT IDENTIFIER indicating a particular OBJECT
IDENTIFIER base fragment associated with the trigger event
for this management task entry. This object represents
different OBJECT IDENTIFIER parameters in different modes.
The _TRIGGER_OID_BASE environment variable will be set to
the canonical string representation for this object at the
start of each trigger frame executed on behalf of this
entry.
Each application profile may define restrictions on the
values which may be assigned to this object, such as whether
complete or incomplete base fragments are permitted.
The agent might not be able to validate the contents of this
object at the time the object is set, since the
seeTaskControlAppProfile may not be known at the time this
object is set. The agent must verify the contents of this
object before the associated seeTaskControlStatus is set to
'active'.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 12 }
seeTaskControlTriggerInt OBJECT-TYPE
SYNTAX Integer32 (0..2147483647)
Expires August 15, 2001 [Page 115]
Internet Draft SEE Specification February 2001
UNITS "seconds"
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"An interval of time that should pass between successive
periodic evaluations of the trigger condition.
If the associated seeTaskControlAppProfile object is equal
to 'appWatchedVar' or 'appPeriodic', then this object
identifies the minimum number of seconds that should elapse
between trigger events executed on behalf of this control
entry, and the value zero is not allowed.
For other values of seeTaskControlAppProfile, this object is
ignored by the agent, and should contain the value zero.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 13 }
seeTaskControlTriggerOvflAct OBJECT-TYPE
SYNTAX INTEGER {
dropTrigger(1),
dropNotifyTrigger(2),
queueTrigger(3)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"Controls how the agent handles a trigger overflow condition
on behalf of this management task, i.e. a new trigger event
occurs which should be dispatched to this management task,
but cannot because the execution on behalf of the previous
trigger event has not finished.
The value 'dropTrigger' indicates that a new trigger event
will be dropped if a trigger overflow occurs, and a
'triggerOverflow' log message will be generated if logging
is active for this entry.
The value 'dropNotifyTrigger' indicates that a new trigger
event will be dropped if a trigger overflow occurs. A
'triggerOverflow' log message will be generated if logging
is active for this entry, and a 'seeTaskAlarm' notification
will also be generated.
Expires August 15, 2001 [Page 116]
Internet Draft SEE Specification February 2001
The value 'queueTrigger' indicates that the agent will
attempt to save a new trigger event if a trigger overflow
occurs. If the agent cannot queue the trigger event, then a
trigger overflow is handled as defined by the
'dropNotifyTrigger' enumeration. If the agent can queue the
trigger event, then the event order must be preserved, and
the associated script should be invoked with any queued
events as soon as possible.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 14 }
seeTaskControlScratchpadSize OBJECT-TYPE
SYNTAX Integer32 (0..65535)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object identifies the number of array elements that
the _SCRATCHPAD environment variable for this task will
contain.
The agent will create this number of strings in the
_SCRATCHPAD environment variable. The maximum length of each
string is defined by the seeCapsMaxEnvStringLen object. An
agent is not required to allocate (or reserve) the requested
data storage until this entry is activated.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
DEFVAL { 1 }
::= { seeTaskControlEntry 15 }
seeTaskControlResultType OBJECT-TYPE
SYNTAX SeeTypeIdentifier
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object identifies the base type of the script result
stored in the associated seeTaskControlLastResult object.
This allows the script result string to be formatted in
specific ways, so it can be converted to a type other than
'STRING' in a standard way. Refer to the SeeTypeIdentifier
TC for more details.
Expires August 15, 2001 [Page 117]
Internet Draft SEE Specification February 2001
Note that the agent is not required to enforce the
formatting syntax requirements specified for each Type
Identifier value. This object is provided as a 'formatting
hint' to applications only.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 16 }
seeTaskControlLogWriteMode OBJECT-TYPE
SYNTAX INTEGER {
wrapWhenFull(1),
stopWhenFull(2)
}
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The type of behavior the agent will take on behalf of this
entry, when the total number of octets of log output in the
associated seeLogTable equals or exceeds the associated
seeTaskControlMaxLogSize value for this entry.
If this object contains the value 'wrapWhenFull' and the the
maximum log size is exceeded, then the agent will delete
enough of the oldest seeLogEntries (with all the same
seeTaskControlIndex major index value) to make room for the
new entry.
If this object contains the value 'stopWhenFull(2)', and the
the maximum log size is exceeded, then the agent will stop
adding seeLogEntries. Instead, the associated
seeTaskControlLostLogOctets object will be incremented by
the size of the seeLogChunk object that would have been
created.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 17 }
seeTaskControlMaxLogSize OBJECT-TYPE
SYNTAX Integer32 (-1..2147483647)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The maximum number of octets that may be written to
Expires August 15, 2001 [Page 118]
Internet Draft SEE Specification February 2001
seeLogEntries on behalf of this entry.
If this object contains the value '-1', then no maximum size
will be enforced for the associated seeLogTable. The size
of the log table is subject to only to agent resources.
If this object contains the value '0', then logging will be
disabled for this entry.
Otherwise, this object identifies the maximum allowed size
of the combined lengths of the associated seeLogChunk OCTET
STRING objects, created in the seeLogTable on behalf of this
entry. Refer to the seeTaskControlLogWriteMode for a
description of agent behavior when the log size is equal or
larger in size to the value specified by this object.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 18 }
seeTaskControlMaxLogChunkSize OBJECT-TYPE
SYNTAX Integer32 (255..65535)
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The maximum number of octets that may be written to any
seeLogChunk object created on behalf of this entry. An
application should limit the value of this object in order
to prevent a 'tooBig' SNMP PDU error to be generated for get
requests of the seeLogChunk object.
The agent must not create entries larger than this number of
octets in the seeLogTable on behalf of this entry. Note
that an agent may choose to fragment log entries at values
lower than indicated by this object.
This object may not be modified if the associated
seeTaskControlStatus object is equal to active."
::= { seeTaskControlEntry 19 }
seeTaskControlLogClearButton OBJECT-TYPE
SYNTAX INTEGER {
clearLog(1),
notPressed(2)
}
Expires August 15, 2001 [Page 119]
Internet Draft SEE Specification February 2001
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"This object allows the contents of the seeLogTable created
on behalf of this entry to be deleted.
If this object is set to the value 'clearLog' the agent will
delete all related entries in the seeLogTable, and then set
the value of this object to the value 'notPressed'.
Setting this object to the value 'notPressed(2)' has no
effect whatsoever."
::= { seeTaskControlEntry 20 }
seeTaskControlNumExecOks OBJECT-TYPE
SYNTAX Counter32
UNITS "script invocation events"
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"This counter is incremented by one, each time the script
associated with this control entry is executed, and
completed with a return status of 'noError'."
::= { seeTaskControlEntry 21 }
seeTaskControlNumExecFails OBJECT-TYPE
SYNTAX Counter32
UNITS "script invocation events"
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"This counter is incremented by one, each time the script
associated with this control entry is executed, and
completed with a return status other than 'noError'."
::= { seeTaskControlEntry 22 }
seeTaskControlLastResCode OBJECT-TYPE
SYNTAX SeeResultCode
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The system result status value obtained the last time the
associated script was executed."
::= { seeTaskControlEntry 23 }
Expires August 15, 2001 [Page 120]
Internet Draft SEE Specification February 2001
seeTaskControlLastResult OBJECT-TYPE
SYNTAX OCTET STRING
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The string result value obtained the last time the
associated script was executed. This object may contain a
value in a different data type, string-encoded according to
the encoding rules for the Type Identifier indicated by the
associated seeTaskControlResultType object.
If the seeTaskControlAppProfile object for this entry is
equal to 'appVirtualGet', and the seeTaskControlStatus is
equal to 'active', then the associated script will be be
invoked each time this object is retrieved.
The empty string is returned if no return value is available
on behalf of this entry."
::= { seeTaskControlEntry 24 }
seeTaskControlLastSEIndex OBJECT-TYPE
SYNTAX Unsigned32 (1..4294967295)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The smCodeIndex value of the SEE script chunk, in which the
first script syntax error was found during the execution of
the associated script.
If no syntax error has been detected, or if a particular
script has not yet been executed by the agent, then this
object will contain the value zero."
::= { seeTaskControlEntry 25 }
seeTaskControlLastSEOffset OBJECT-TYPE
SYNTAX Integer32 (-1..1023)
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The offset position within the associated smCodeText OCTET
STRING in which the first script syntax error was found
during the execution of the associated script.
If no syntax error has been detected, or if a particular
script has not yet been executed by the agent, then this
Expires August 15, 2001 [Page 121]
Internet Draft SEE Specification February 2001
object will contain the value '-1'.
Otherwise, this object identifies the number of octets into
the script code string identified by the associated
seeTaskControlLastSEIndex object.
Note that position of the first octet in the string is
identified by the value '0', not the value '1'."
::= { seeTaskControlEntry 26 }
seeTaskControlTaskRunning OBJECT-TYPE
SYNTAX TruthValue
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"Indicates whether the agent is currently running the
associated script on behalf of this management task entry.
The value 'true' indicates this task is currently running."
::= { seeTaskControlEntry 27 }
seeTaskControlLastTrigTime OBJECT-TYPE
SYNTAX TimeStamp
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The value of sysUpTime the last time a trigger event for
this entry occurred, or zero if no such event has occurred."
::= { seeTaskControlEntry 28 }
seeTaskControlCurLogSize OBJECT-TYPE
SYNTAX Gauge32
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The current number of octets contained in all seeLogChunk
instances, existing in the seeLogTable on behalf of this
entry."
::= { seeTaskControlEntry 29 }
seeTaskControlLostLogOctets OBJECT-TYPE
SYNTAX Counter32
MAX-ACCESS read-only
STATUS current
DESCRIPTION
Expires August 15, 2001 [Page 122]
Internet Draft SEE Specification February 2001
"An indication that log entries on behalf of this task are
not being captured in the seeLogTable.
This counter is incremented by the number of octets which
would have been written to the associated seeLogTable on
behalf of this entry, but were not written, for whatever
reason."
::= { seeTaskControlEntry 30 }
seeTaskControlLastLogWriteTime OBJECT-TYPE
SYNTAX TimeStamp
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The value of sysUpTime the last time an entry was added to
the seeLogTable on behalf of this task.
A management application can use this object to determine
when new log output has been written for this task. This
timestamp will be updated when a seeLogEntry is successfully
added to the seeLogTable on behalf of this entry.
Initially, this object will contain the value zero."
::= { seeTaskControlEntry 31 }
seeTaskControlStorageType OBJECT-TYPE
SYNTAX StorageType
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The type on non-volatile storage behavior associated with
this entry."
::= { seeTaskControlEntry 32 }
seeTaskControlStatus OBJECT-TYPE
SYNTAX RowStatus
MAX-ACCESS read-create
STATUS current
DESCRIPTION
"The status of this entry. All values must be set
appropriately before this row may be activated. All valid
row creation states should be supported, including
'createAndWait' and 'notInService'."
::= { seeTaskControlEntry 33 }
Expires August 15, 2001 [Page 123]
Internet Draft SEE Specification February 2001
--
-- SEE Log Table
--
-- contains a controlled number of limited length
-- log chunks for each entry configured in the
-- seeTaskControlTable
--
seeLogTable OBJECT-TYPE
SYNTAX SEQUENCE OF SeeLogEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"Contains the individual output chunks which comprise the
log output for the associated seeTaskControlEntry."
::= { seeExecObjects 2 }
seeLogEntry OBJECT-TYPE
SYNTAX SeeLogEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A conceptual row in the seeLogTable.
Entries are created in this table by agent or script action.
The management task associated with the log output contained
in this table is identified by the seeTaskControlIndex value
in the INDEX clause."
INDEX { seeTaskControlIndex,
seeLogIndex }
::= { seeLogTable 1 }
SeeLogEntry ::= SEQUENCE {
seeLogIndex Integer32,
seeLogCreateTOD DateAndTime,
seeLogCreateTime TimeStamp,
seeLogChunk SeeLogOutput
}
seeLogIndex OBJECT-TYPE
SYNTAX Integer32 (1..2147483647)
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
Expires August 15, 2001 [Page 124]
Internet Draft SEE Specification February 2001
"The minor index for this log entry. The agent should use
consecutive index values until the maximum value is reached,
before reusing index values. However, this object should be
'reset' to the value '1' if the associated
seeTaskControlLogClearButton object is set to 'clearLog'."
::= { seeLogEntry 1 }
seeLogCreateTOD OBJECT-TYPE
SYNTAX DateAndTime
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The current time of day (e.g. value of schedLocalTime) at
the time this log entry was added to this table. If the
seeCapsTodClock object is equal to 'noTodClock', then this
object will contain the empty string."
::= { seeLogEntry 2 }
seeLogCreateTime OBJECT-TYPE
SYNTAX TimeStamp
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"The value of sysUpTime at the time this log entry was added
to this table."
::= { seeLogEntry 3 }
seeLogChunk OBJECT-TYPE
SYNTAX SeeLogOutput
MAX-ACCESS read-only
STATUS current
DESCRIPTION
"A log fragment created on behalf of the associated
seeTaskControlEntry. This object will not be greater in
length than the associated seeTaskControlMaxLogChunkSize
object."
::= { seeLogEntry 4 }
--
-- Registrations
--
seeLanguage OBJECT IDENTIFIER ::= { seeRegistrations 1 }
seeLibraries OBJECT IDENTIFIER ::= { seeRegistrations 2 }
Expires August 15, 2001 [Page 125]
Internet Draft SEE Specification February 2001
--
-- Notifications Section
--
seeTraps OBJECT IDENTIFIER ::= { seeNotifications 0 }
-- this replaces the smScriptAbort notification
seeTaskAbort NOTIFICATION-TYPE
OBJECTS { seeTaskControlAppProfile,
seeTaskControlLastResCode }
STATUS current
DESCRIPTION
"This notification is generated whenever a management task
terminates with a result status other than 'noError', if the
seeTaskAbortNotifyEnabled object is equal to 'true'.
The seeTaskControlAppProfile identifies the type of
application that terminated with an error status, and the
seeTaskControlLastResCode identifies the specific error that
occurred.
An implementation may restrict the frequency that these
notifications are actually emitted by the agent."
::= { seeTraps 1 }
-- this replaces the smScriptResult notification
seeTaskAlarm NOTIFICATION-TYPE
OBJECTS { seeTaskControlAppProfile }
STATUS current
DESCRIPTION
"This notification is generated by script action (on behalf
of a particular management task) via the 'SnmpMsgLib' system
library, if the seeTaskAlarmNotifyEnabled object is equal to
'true'.
The seeTaskControlAppProfile object is always encoded first,
as a means of identifying the type of application and the
seeTaskControlEntry. Individual tasks will likely add other
varbinds as well.
An implementation may restrict the frequency that these
notifications are actually emitted by the agent."
Expires August 15, 2001 [Page 126]
Internet Draft SEE Specification February 2001
::= { seeTraps 2 }
--
-- Conformance Section
--
seeCompliances OBJECT IDENTIFIER ::= { seeConformance 1 }
seeGroups OBJECT IDENTIFIER ::= { seeConformance 2 }
seeCompliance MODULE-COMPLIANCE
STATUS current
DESCRIPTION
"Describes the requirements for conformance to the Script
Execution Environment MIB."
MODULE -- this module
MANDATORY-GROUPS { seeCapsGroup,
seeEnvGroup,
seeExecGroup,
seeNotificationsGroup,
smLanguageGroup,
smScriptGroup,
smCodeGroup
}
::= { seeCompliances 1 }
seeCapsGroup OBJECT-GROUP
OBJECTS {
seeCapsTodClock,
seeCapsFloatDataType,
seeCapsMinPollInterval,
seeCapsMaxEnvStringLen,
seeCapsAllowedTargets
}
STATUS current
DESCRIPTION
"A collection of objects used to identify some SEE runtime
capabilities provided by this agent."
::= { seeGroups 1 }
seeEnvGroup OBJECT-GROUP
OBJECTS {
seeTaskAbortNotifyEnabled,
seeTaskAlarmNotifyEnabled,
seeEnvVarArraySize,
seeEnvVarPermissions,
Expires August 15, 2001 [Page 127]
Internet Draft SEE Specification February 2001
seeEnvVarWriteGroup,
seeEnvVarWriteTask,
seeEnvVarInitType,
seeEnvVarInitValue,
seeEnvVarStorageType,
seeEnvVarStatus,
seeOidAliasOID,
seeOidAliasStorageType,
seeOidAliasStatus
}
STATUS current
DESCRIPTION
"A collection of objects used to control the configuration
of the execution environment."
::= { seeGroups 2 }
seeExecGroup OBJECT-GROUP
OBJECTS {
seeTaskControlDescr,
seeTaskControlAppProfile,
seeTaskControlExecPermissions,
seeTaskControlGroupId,
seeTaskControlRunMode,
seeTaskControlRunButton,
seeTaskControlStartFn,
seeTaskControlLifetime,
seeTaskControlEngineId,
seeTaskControlContextName,
seeTaskControlTriggerOid,
seeTaskControlTriggerInt,
seeTaskControlTriggerOvflAct,
seeTaskControlScratchpadSize,
seeTaskControlResultType,
seeTaskControlLogWriteMode,
seeTaskControlMaxLogSize,
seeTaskControlMaxLogChunkSize,
seeTaskControlLogClearButton,
seeTaskControlNumExecOks,
seeTaskControlNumExecFails,
seeTaskControlLastResCode,
seeTaskControlLastResult,
seeTaskControlLastSEIndex,
seeTaskControlLastSEOffset,
seeTaskControlTaskRunning,
seeTaskControlLastTrigTime,
Expires August 15, 2001 [Page 128]
Internet Draft SEE Specification February 2001
seeTaskControlCurLogSize,
seeTaskControlLostLogOctets,
seeTaskControlLastLogWriteTime,
seeTaskControlStorageType,
seeTaskControlStatus,
seeLogCreateTOD,
seeLogCreateTime,
seeLogChunk
}
STATUS current
DESCRIPTION
"A collection of objects used to control the execution of
management tasks."
::= { seeGroups 3 }
seeNotificationsGroup NOTIFICATION-GROUP
NOTIFICATIONS {
seeTaskAbort,
seeTaskAlarm
}
STATUS current
DESCRIPTION
"The notifications emitted by the SEE MIB."
::= { seeGroups 4 }
END
7.8. Initial System Library Definitions
The following system libraries are initially defined. Note that
implementations are not constrained to the libraries specified here.
SysLib LIBRARY-TYPE ::=
BEGIN
STATUS current
SUPPORT mandatory
IDENTITY { seeLibraries 1 }
VERSION "1.0"
LIB-DESCR
"Contains general functions for basic system
operations within the script execution environment."
FUNC-LIST "1.0" {
printf,
sprintf,
Expires August 15, 2001 [Page 129]
Internet Draft SEE Specification February 2001
strlen,
strclr,
strncmp,
str2bits,
str2boolean,
str2int,
str2long,
str2oid,
str2uint,
str2ulong,
boolean2str,
int2str,
uint2str,
long2str,
ulong2str,
bitsclr,
bitscmp,
bits2str,
oidlen,
oidclr,
oidncmp,
oid2str,
oid_alias_exists,
oid_alias_set,
oid_alias_delete,
set_exit_code
}
IMPORTS "1.0"
SeeResultCode, SeeStringLiteral, SeeIdentifierString
FROM SEE-MIB;
FUNCTION printf
FUNC-DECL
"int printf (INREF STRING format, ...);"
FUNC-DESCR
"Writes formatted output to the logTable for the
calling task."
ACCESS-BITS { }
PARAM format { SeeStringLiteral }
"The syntax and semantics of the 'format' STRING
are the same as for the 'printf' function in the
ANSI C 'STDIO' library ('stdio.h')."
PARAM ... { }
"For each parameter replacement token specified in
Expires August 15, 2001 [Page 130]
Internet Draft SEE Specification February 2001
the 'format' parameter string (e.g. '%d'), a
corresponding value replacement parameter will
be passed in the function call. The format string
is examined for replacement tokens from left to right,
and the value parameter order must correspond to this
order."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION sprintf
FUNC-DECL
"int sprintf (OUT STRING buffer, INREF STRING format, ...);"
FUNC-DESCR
"Writes formatted output to the specified output buffer."
ACCESS-BITS { }
PARAM buffer { }
"The output buffer for the formatted output produced
by this function call."
PARAM format { SeeStringLiteral }
"The syntax and semantics of the 'format' STRING
are the same as for the 'sprintf' function in the
ANSI C 'STDIO' library ('stdio.h')."
PARAM ... { }
"For each parameter replacement token specified in
the 'format' parameter string (e.g. '%d'),
a corresponding value replacement
parameter will be passed in the function call.
The format string is examined for replacement tokens
from left to right, and the value parameter order must
correspond to this order."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION strlen
FUNC-DECL
"uint strlen (INREF STRING str_var);"
FUNC-DESCR
"Returns the number of octets currently contained in
the specified variable of type STRING."
ACCESS-BITS { }
PARAM str_var { }
Expires August 15, 2001 [Page 131]
Internet Draft SEE Specification February 2001
"The STRING variable that should be checked."
RETURN { }
"The number of array elements currently contained in
the specified STRING variable."
FUNCTION strclr
FUNC-DECL
"void strclr (OUT STRING str_var);"
FUNC-DESCR
"Sets the current length of the specified STRING
variable to zero. Any previously set elements become
undefined."
ACCESS-BITS { }
PARAM str_var { }
"The STRING variable that should be cleared."
FUNCTION strncmp
FUNC-DECL
"int strncmp (INREF STRING str1,
INREF STRING str2,
IN uint max_cmp);"
FUNC-DESCR
"Compares a limited number of elements of two STRING
variables, and returns the result."
ACCESS-BITS { }
PARAM str1 { }
"The first STRING variable that should be compared."
PARAM str2 { }
"The second STRING variable that should be compared."
PARAM max_cmp { }
"The maximum number of octets that should be compared."
RETURN { -1 .. 1 }
"The compare result:
-1 == sub-str1 < sub-str2
0 == sub-str1 == sub-str2
1 == sub-str1 > sub-str2 "
FUNCTION str2bits
FUNC-DECL
"int str2bits (INREF STRING string_var,
OUT BITS bits_var);"
FUNC-DESCR
"Converts a STRING encoded with the BITS Type Identifier
to a BITS value."
ACCESS-BITS { }
Expires August 15, 2001 [Page 132]
Internet Draft SEE Specification February 2001
PARAM string_var { }
"The STRING variable to be decoded."
PARAM bits_var { }
"The BITS variable to contain the converted value.
This must be large enough to hold the encoded object
or an error will be returned."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION str2boolean
FUNC-DECL
"int str2boolean (INREF STRING string_var,
OUT boolean boolean_var);"
FUNC-DESCR
"Converts a STRING encoded with the boolean Type Identifier
to a boolean value."
ACCESS-BITS { }
PARAM string_var { }
"The STRING variable to be decoded."
PARAM boolean_var { }
"The boolean variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION str2int
FUNC-DECL
"int str2int (INREF STRING string_var,
OUT int int_var);"
FUNC-DESCR
"Converts a STRING encoded with the int, Integer32,
or INTEGER Type Identifier to an int value."
ACCESS-BITS { }
PARAM string_var { }
"The STRING variable to be decoded."
PARAM int_var { }
"The int variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
Expires August 15, 2001 [Page 133]
Internet Draft SEE Specification February 2001
FUNCTION str2long
FUNC-DECL
"int str2long (INREF STRING string_var,
OUT long long_var);"
FUNC-DESCR
"Converts a STRING encoded with the long Type Identifier
to a long value."
ACCESS-BITS { }
PARAM string_var { }
"The STRING variable to be decoded."
PARAM long_var { }
"The long variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION str2oid
FUNC-DECL
"int str2oid (INREF STRING string_var,
OUT OID oid_var);"
FUNC-DESCR
"Converts a STRING encoded with the OBJECT IDENTIFIER
or OID Type Identifier to an OID value."
ACCESS-BITS { }
PARAM string_var { }
"The STRING variable to be decoded."
PARAM oid_var { }
"The OID variable to contain the converted value.
This must be large enough to hold the encoded object
or an error will be returned."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNC-DECL
"int str2uint (INREF STRING string_var,
OUT uint uint_var);"
FUNC-DESCR
"Converts a STRING encoded with the Gauge32, Unsigned32,
or uint Type Identifier to a uint value."
ACCESS-BITS { }
PARAM string_var { }
"The STRING variable to be decoded."
Expires August 15, 2001 [Page 134]
Internet Draft SEE Specification February 2001
PARAM uint_var { }
"The uint variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNC-DECL
"int str2ulong (INREF STRING string_var,
OUT ulong ulong_var);"
FUNC-DESCR
"Converts a STRING encoded with the Counter64,
Unsigned64, or ulong Type Identifier to a ulong value."
ACCESS-BITS { }
PARAM string_var { }
"The STRING variable to be decoded."
PARAM ulong_var { }
"The ulong variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION boolean2str
FUNC-DECL
"int boolean2str (IN boolean boolean_var,
OUT STRING string_var);"
FUNC-DESCR
"Converts a boolean value to a STRING value, according
to the boolean Type Identifier encoding rules."
ACCESS-BITS { }
PARAM boolean_var { }
"The boolean variable to be encoded."
PARAM string_var { }
"The STRING variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION int2str
FUNC-DECL
"int int2str (IN int int_var,
OUT STRING string_var);"
FUNC-DESCR
Expires August 15, 2001 [Page 135]
Internet Draft SEE Specification February 2001
"Converts an integer value to a STRING value, according
to the int Type Identifier encoding rules."
ACCESS-BITS { }
PARAM int_var { }
"The integer variable to be encoded."
PARAM string_var { }
"The STRING variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION uint2str
FUNC-DECL
"int uint2str (IN uint uint_var,
OUT STRING string_var);"
FUNC-DESCR
"Converts an unsigned integer value to a STRING value,
according to the uint Type Identifier encoding rules."
ACCESS-BITS { }
PARAM uint_var { }
"The unsigned integer variable to be encoded."
PARAM string_var { }
"The STRING variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION long2str
FUNC-DECL
"int long2str (IN long long_var,
OUT STRING string_var);"
FUNC-DESCR
"Converts a long integer value to a STRING value,
according to the long Type Identifier encoding rules."
ACCESS-BITS { }
PARAM long_var { }
"The long integer variable to be encoded."
PARAM string_var { }
"The STRING variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
Expires August 15, 2001 [Page 136]
Internet Draft SEE Specification February 2001
FUNCTION ulong2str
FUNC-DECL
"int ulong2str (IN ulong long_var,
OUT STRING string_var);"
FUNC-DESCR
"Converts an unsigned long integer value to a STRING value,
according to the ulong Type Identifier encoding rules."
ACCESS-BITS { }
PARAM long_var { }
"The unsigned long integer variable to be encoded."
PARAM string_var { }
"The STRING variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION bitsclr
FUNC-DECL
"void bitsclr (OUT BITS bitsvar);"
FUNC-DESCR
"Sets all boolean elements in the specified BITS variable
to zero."
ACCESS-BITS { }
PARAM bitsvar { }
"The BITS variable that should be cleared."
FUNCTION bitscmp
FUNC-DECL
"boolean bitscmp (INREF BITS bits1,
INREF BITS bits2,
INREF BITS cmp_mask);"
FUNC-DESCR
"Compares a limited number of elements of two BITS
variables, and returns the result."
ACCESS-BITS { }
PARAM bits1 { }
"The first BITS variable that should be compared."
PARAM bits2 { }
"The second BITS variable that should be compared."
PARAM cmp_mask { }
"The specific bit elements that should be compared
between the 'bits1' and 'bits2' parameters. Only the
bit positions set in this mask will be compared. If
any missing bit positions in any of the parameters
Expires August 15, 2001 [Page 137]
Internet Draft SEE Specification February 2001
are encountered (due to different static lengths)
the agent will conceptually replace the missing bit
positions with the value '0'."
RETURN { }
"The compare result:
FALSE == all compared bits were the same
TRUE == not all compared bits were the same."
FUNCTION bits2str
FUNC-DECL
"int bits2str (INREF BITS bits_var,
OUT STRING string_var);"
FUNC-DESCR
"Converts a BITS value to a STRING value, according
to the BITS Type Identifier encoding rules."
ACCESS-BITS { }
PARAM bits_var { }
"The BITS variable to be encoded."
PARAM string_var { }
"The STRING variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION oidlen
FUNC-DECL
"uint oidlen (INREF OID oidvar);"
FUNC-DESCR
"Returns the number of elements currently contained
in the specified variable of type OID."
ACCESS-BITS { }
PARAM oidvar { }
"The OID variable that should be checked."
RETURN { }
"The number of array elements currently contained in
the specified OID variable."
FUNCTION oidclr
FUNC-DECL
"void oidclr (OUT OID oidvar);"
FUNC-DESCR
"Sets the current length of the specified OID variable
to zero. All elements are cleared (i.e. set to the
value '0')."
Expires August 15, 2001 [Page 138]
Internet Draft SEE Specification February 2001
ACCESS-BITS { }
PARAM oidvar { }
"The OID variable that should be cleared."
FUNCTION oidncmp
FUNC-DECL
"int oidncmp (INREF OID oid1,
INREF OID oid2,
IN uint max_cmp);"
FUNC-DESCR
"Compares a limited number of elements of two OID
variables, and returns the result."
ACCESS-BITS { }
PARAM oid1 { }
"The first OID variable that should be compared."
PARAM oid2 { }
"The second OID variable that should be compared."
PARAM max_cmp { }
"The maximum number of elements that should be
lexicographically compared."
RETURN { -1 .. 1 }
"The compare result:
-1 == sub-oid1 < sub-oid2
0 == sub-oid1 == sub-oid2
1 == sub-oid1 > sub-oid2 "
FUNCTION oid2str
FUNC-DECL
"int oid2str (INREF OID oid_var,
OUT STRING string_var);"
FUNC-DESCR
"Converts a OID value to a STRING value, according
to the OID Type Identifier encoding rules."
ACCESS-BITS { }
PARAM oid_var { }
"The OID variable to be encoded."
PARAM string_var { }
"The STRING variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION oid_alias_exists
FUNC-DECL
Expires August 15, 2001 [Page 139]
Internet Draft SEE Specification February 2001
"boolean oid_alias_exists (INREF STRING alias_name);"
FUNC-DESCR
"Checks if the specified OID alias identifier token
is currently configured in the execution environment."
ACCESS-BITS { }
PARAM alias_name { SeeIdentifierString }
"The OID alias name that should be checked."
RETURN { }
"True if the OID alias exists; false otherwise."
FUNCTION oid_alias_set
FUNC-DECL
"int oid_alias_set (INREF STRING alias_name
INREF OID alias_value,
IN boolean nv_store);"
FUNC-DESCR
"Create a new OID Alias string or change the value of
an existing OID Alias string in the execution
environment."
ACCESS-BITS { oidAliases(8) }
ACCESS-DESCR
"The calling task must be permitted to write to
the set of OID Aliases."
PARAM alias_name { SeeIdentifierString }
"The OID alias name that should be created or modified."
PARAM alias_value { }
"The OID alias value to be used as the replacement
value when the specified OID alias identifier token
is encountered in a script."
PARAM nv_store { }
"This parameter should be TRUE to indicate that this
OID alias should be saved in non-volatile memory
and re-created after a system restart. It should
be FALSE otherwise."
RETURN { SeeResultCode }
"The return status. Zero indicates the OID Alias
identifier token was successfully written. A non-zero
value indicates the specific error that occurred."
FUNCTION oid_alias_delete
FUNC-DECL
"int oid_alias_delete (INREF STRING alias_name);"
FUNC-DESCR
"Delete a specified OID Alias string from the execution
environment."
Expires August 15, 2001 [Page 140]
Internet Draft SEE Specification February 2001
ACCESS-BITS { oidAliases(8) }
ACCESS-DESCR
"The calling task must be permitted to write to
the set of OID Aliases."
PARAM alias_name { SeeIdentifierString }
"The OID alias name that should be deleted."
RETURN { SeeResultCode }
"The return status. Zero indicates the OID Alias
identifier token was successfully deleted.
A non-zero value indicates the specific error
that occurred."
FUNCTION set_exit_code
FUNC-DECL
"void set_exit_code (IN int exit_code);"
FUNC-DESCR
"Sets the application return code, used by the
agent for the seeTaskControlLastResCode object.
This function does not need to be called unless
some application error occurred (e.g. noResourcesLeft).
The default return value of 'noError' will be recorded
if this function is not called during a task
invocation. If called multiple times, the last
value recorded will be used."
ACCESS-BITS { }
PARAM exit_code { SeeResultCode }
"The error code value to return to the agent,
which will be used to set the associated
seeTaskControlLastResCode object."
END
EnvVarLib LIBRARY-TYPE ::=
BEGIN
STATUS current
SUPPORT mandatory
IDENTITY { seeLibraries 2 }
VERSION "1.0"
LIB-DESCR
"Contains functions for accessing environment variables."
FUNC-LIST "1.0" {
env_create,
env_delete,
Expires August 15, 2001 [Page 141]
Internet Draft SEE Specification February 2001
env_string_count,
env_print,
env_dump
}
IMPORTS "1.0"
SeeIdentifierString, SeeStringLiteral, SeeResultCode
FROM SEE-MIB;
FUNCTION env_create
FUNC-DECL
"int env_create (IN int group_index,
IN int task_index,
INREF STRING name,
IN int array_size,
IN int write_group,
IN int write_task,
INREF STRING init_value,
IN boolean nv_store);"
FUNC-DESCR
"Creates an environment variable with the specified
attributes. Set write_group and write_task to '0'
to create a read-only environment variable. Use
inline code to set the value of any of the array
elements after the variable is created."
ACCESS-BITS { agentEnvVars(0),
groupEnvVars(1),
taskEnvVars(2)
}
ACCESS-DESCR
"Depending on the specified scope level, indicated
by the group_index and task_index values, the
appropriate '*EnvVars' BIT must be set in the
seeTaskControlExecPermissions object for the
calling task."
PARAM group_index { 0..2147483647 }
"The 'seeEnvVarGroup' INDEX component value for
the entry to be created."
PARAM task_index { 0..2147483647 }
"The 'seeEnvVarTask' INDEX component value for
the entry to be created."
PARAM name { SeeIdentifierString }
"The environment variable identifier token value; also
the 'seeEnvVarName' INDEX component value for the
entry to be created."
Expires August 15, 2001 [Page 142]
Internet Draft SEE Specification February 2001
PARAM array_size { 1..2147483647 }
"The number of strings in this environment string array."
PARAM write_group { 0..2147483647 }
"The task group given write permission to this environment
variable. If 'agent scope' is indicated by the index
values, then this parameter may be any value, otherwise
it must be zero or the same value as the
seeTaskControlGroupId for the calling task."
PARAM write_task { 0..2147483647 }
"The task index given write permission to this environment
variable. If 'agent scope' or 'group scope' is indicated
by the index values, then this parameter may be any value,
otherwise it must be zero or the same value as the
seeTaskControlIndex for the calling task."
PARAM init_value { SeeStringLiteral [65535] }
"The array of values to write to the initial contents
of the specified variable. The default value of an
empty string will be used for any array element not
specified in the init_value array."
PARAM nv_store { }
"This parameter should be TRUE to indicate that this
environment variable should be saved in non-volatile
memory and re-created after a system restart. It
should be FALSE otherwise."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION env_delete
FUNC-DECL
"int env_delete (IN int group_index,
IN int task_index,
INREF STRING name);"
FUNC-DESCR
"Deletes an environment variable from the
seeEnvVarTable with the specified index values."
ACCESS-BITS { agentEnvVars(0),
groupEnvVars(1),
taskEnvVars(2)
}
ACCESS-DESCR
"Depending on the specified scope level, indicated
by the group_index and task_index values, the
appropriate '*EnvVars' BIT must be set in the
Expires August 15, 2001 [Page 143]
Internet Draft SEE Specification February 2001
seeTaskControlExecPermissions object for the
calling task."
PARAM group_index { 0..2147483647 }
"The 'seeEnvVarGroup' INDEX component value for
the entry to be deleted."
PARAM task_index { 0..2147483647 }
"The 'seeEnvVarTask' INDEX component value for
the entry to be deleted."
PARAM name { SeeIdentifierString }
"The 'seeEnvVarName' INDEX component value for
the entry to be deleted."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION env_string_count
FUNC-DECL
"int env_string_count (INREF STRING name);"
FUNC-DESCR
"Returns the number of strings in the array identified
by the 'name' parameter."
ACCESS-BITS { }
ACCESS-DESCR
"If the variable exists in multiple scopes, then the
agent will select the appropriate version, based on the
seeTaskControlGroupId and seeTaskControlIndex values
associated with the calling task."
PARAM name { SeeIdentifierString }
"The environment variable identifier value. This must
be a simple <identifier> token, such as 'foo'."
RETURN { 0..2147483647 }
"The number of array elements in the specified environment
variable. The value zero indicates some error occurred,
or the variable is not visible to the calling task."
FUNCTION env_print
FUNC-DECL
"int env_print (INREF STRING name);"
FUNC-DESCR
"Print the contents of a specified environment variable
string to the logTable output for the calling task, using
the log output format '<name> = <value>'."
ACCESS-BITS { }
ACCESS-DESCR
Expires August 15, 2001 [Page 144]
Internet Draft SEE Specification February 2001
"If the variable exists in multiple scopes, then the agent
will select the appropriate version, based on the
seeTaskControlGroupId and seeTaskControlIndex values
associated with the calling task."
PARAM name { SeeIdentifierString }
"The environment variable identifier value. This may
be an identifier such as 'foo' or an array element
identifier such as 'foo[3]'."
RETURN { SeeResultCode }
"The return status. Zero indicates the environment
variable identifier was found and the output string
was successfully logged. A non-zero value indicates
that the specific error that occurred."
FUNCTION env_dump
FUNC-DECL
"int env_dump (void);"
FUNC-DESCR
"Print the contents of all the environment variable
strings visible to the calling task to the logTable,
using the log output format '<name> = <value>'
or '<name>[n] = <value>' notation."
ACCESS-BITS { }
ACCESS-DESCR
"If the variable exists in multiple scopes, then the
agent will select the appropriate version, based on the
seeTaskControlGroupId and seeTaskControlIndex values
associated with the calling task."
RETURN { SeeResultCode }
"The return status. Zero indicates the environment
output strings were successfully logged. A non-zero
value indicates that the specific error that occurred."
END
FloatLib LIBRARY-TYPE ::=
BEGIN
STATUS current
SUPPORT conditional
IDENTITY { seeLibraries 3 }
VERSION "1.0"
LIB-DESCR
"Contains functions for manipulating the float data type.
This library is mandatory if the float data type is
Expires August 15, 2001 [Page 145]
Internet Draft SEE Specification February 2001
supported (i.e. the seeCapsFloatDataType object is
equal to 'true')."
FUNC-LIST "1.0" {
float2str,
str2float
}
IMPORTS "1.0"
SeeResultCode
FROM SEE-MIB;
FUNCTION float2str
FUNC-DECL
"int float2str (IN float float_var,
OUT STRING string_var);"
FUNC-DESCR
"Converts a float value to a STRING value, according
to the float Type Identifier encoding rules."
ACCESS-BITS { }
PARAM float_var { }
"The float variable to be encoded."
PARAM string_var { }
"The STRING variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
FUNCTION str2float
FUNC-DECL
"int str2float (INREF STRING string_var,
OUT float float_var);"
FUNC-DESCR
"Converts a STRING encoded with the float Type Identifier
to a float value."
ACCESS-BITS { }
PARAM string_var { }
"The STRING variable to be decoded."
PARAM float_var { }
"The float variable to contain the converted value."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates the specific failure
that occurred."
Expires August 15, 2001 [Page 146]
Internet Draft SEE Specification February 2001
END
TimeLib LIBRARY-TYPE ::=
BEGIN
STATUS current
SUPPORT conditional
IDENTITY { seeLibraries 4 }
VERSION "1.0"
LIB-DESCR
"Contains calendar functions for manipulating strings
in the DateAndTime TC data format. This library is
mandatory for implementations for which the
seeCapsTodClock object is equal to 'todClock'
or 'todClockAndTz'."
FUNC-LIST "1.0" {
time_get_cur_datetime,
time_print_cur_datetime
}
IMPORTS "1.0"
DateAndTime
FROM SNMPv2-TC
SeeResultCode
FROM SEE-MIB;
FUNCTION time_get_cur_datetime
FUNC-DECL "int time_get_cur_date_time (OUT STRING ret_buff);"
FUNC-DESCR
"Retrieve the current time on the host platform."
ACCESS-BITS { }
PARAM ret_buff { DateAndTime }
"The buffer which to contain the current time
in DateAndTime format. The length of the encoded
string will be 8 octets if the seeCapsTodClock object
is equal to 'todClock(2)', and 11 octets if it is
equal to 'todClockAndTz(3)'.
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
FUNCTION time_print_cur_datetime
Expires August 15, 2001 [Page 147]
Internet Draft SEE Specification February 2001
FUNC-DECL "int time_print_cur_date_time (void);"
FUNC-DESCR
"Print one line containing the current time on
the host platform to the log table for the calling task
in unix 'date' command format. E.g.:
'Sat Dec 16 14:42:47 PST 2000.'
The printed string will contain the timezone if
the seeCapsTodClock is equal to 'todClockAndTz(3)'."
ACCESS-BITS { }
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
END
SnmpMsgLib LIBRARY-TYPE
STATUS current
SUPPORT conditional
IDENTITY { seeLibraries 5 }
VERSION "1.0"
LIB-DESCR
"Contains functions for executing synchronous SNMP
transactions with local or remote targets, by
providing a high-level interface to the message
dispatcher within the host engine.
If the target platform identified in each function call
is the same as the host platform, then the agent
is not required to construct actual SNMP PDU messages
for the transactions, and may choose instead to interface
directly with the Message Dispatcher in the local
SNMP engine.
The following parameter values must be accepted to access
local target objects, if the seeCapsAllowedTargets object
is equal to 'localTarget(1)' or 'localAndRemoteTargets(3)',
for all functions in this library:
target_engine = zero-length string
target_addr_type = 'unknown(0)'
target_addr = zero-length string "
FUNC-LIST "1.0" {
Expires August 15, 2001 [Page 148]
Internet Draft SEE Specification February 2001
snmp_get,
snmp_getnext,
snmp_getbulk,
snmp_set,
snmp_notify,
snmp_notify_add_varbinds
}
IMPORTS "1.0"
VariablePointer
FROM SNMPv2-TC
SnmpAdminString
FROM SNMP-FRAMEWORK-MIB
SnmpEngineIdOrNone
FROM ENTITY-MIB
InetAddressType, InetAddress
FROM INET-ADDRESS-MIB
SnmpPduErrorStatus
FROM DISMAN-SCHEDULE-MIB
SeeTypeIdentifier, SeeResultCode
FROM SEE-MIB;
FUNCTION snmp_get
FUNC-DECL "int snmp_get (INREF STRING target_engine,
INREF STRING target_context,
IN int target_addr_type,
INREF STRING target_addr,
IN uint vb_count,
INREF OID vb_list [],
OUT int error_index,
OUT boolean any_vb_null,
OUT STRING vb_type_list [],
OUT STRING vb_val_list [] );"
FUNC-DESCR
"Perform an SNMP Get transaction with the command
responder application on the specified target
platform."
ACCESS-BITS { getPDUs(4) }
ACCESS-DESCR
"The calling task must be permitted to conduct SNMP Get
transactions in order to use this function."
PARAM target_engine { SnmpEngineIdOrNone }
"The SNMP engine containing the MIB objects to query.
An empty string indicates that the host engine should
Expires August 15, 2001 [Page 149]
Internet Draft SEE Specification February 2001
be used."
PARAM target_context { SnmpAdminString }
"The SNMP contextName containing the MIB objects to query."
PARAM target_addr_type { InetAddressType }
"The type of formatted address string contained in
the target_addr parameter."
PARAM target_addr { InetAddress }
"The formatted string specifying the network address
of the target for this SNMP transaction."
PARAM vb_count { 1..2147483647 }
"The number of varbinds that are contained in the
associated vb_list, vb_type_list, and vb_val_list arrays."
PARAM vb_list { VariablePointer [2147483648] }
"The list of object instances that should be retrieved."
PARAM error_index { 0..2147483647 }
"The error-index field value returned in the Response PDU."
PARAM any_vb_null { }
"This variable will be TRUE if the function return
code is noError(0), but one or more varbinds returned
an exception (i.e. NoSuchName, NoSuchException, or
EndOfMibView) instead of a valid value. It will
be FALSE otherwise."
PARAM vb_type_list { SeeTypeIdentifier [2147483648] }
"The list of Type Identifier strings associated with
each retrieved varbind in the Response PDU."
PARAM vb_val_list { STRING [2147483648] }
"The list of retrieved values for the associated MIB object
in the vb_list array. This value is converted to STRING
format as specified by the associated element in the
vb_type_list array."
RETURN { SnmpPduErrorStatus }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
FUNCTION snmp_getnext
FUNC-DECL "int snmp_getnext (
INREF STRING target_engine,
INREF STRING target_context,
IN int target_addr_type,
INREF STRING target_addr,
IN uint vb_count,
INREF OID vb_list [],
OUT int error_index,
Expires August 15, 2001 [Page 150]
Internet Draft SEE Specification February 2001
OUT boolean any_vb_null,
OUT OID vb_ret_list [],
OUT STRING vb_type_list [],
OUT STRING vb_val_list [] );"
FUNC-DESCR
"Perform an SNMP GetNext transaction with the command
responder application on the specified target
platform."
ACCESS-BITS { getPDUs(4) }
ACCESS-DESCR
"The calling task must be permitted to conduct SNMP Get
transactions in order to use this function."
PARAM target_engine { SnmpEngineIdOrNone }
"The SNMP engine containing the MIB objects to query."
PARAM target_context { SnmpAdminString }
"The SNMP contextName containing the MIB objects to query."
PARAM target_addr_type { InetAddressType }
"The type of formatted address string contained in
the target_addr parameter."
PARAM target_addr { InetAddress }
"The formatted string specifying the network address
of the target for this SNMP transaction."
PARAM vb_count { 1 .. 2147483647 }
"The number of varbinds that are contained in the associated
vb_list, vb_type_list, and vb_val_list arrays."
PARAM vb_list { VariablePointer [2147483648] }
"The list of object instances to be retrieved, that should be
used for the 'variable-bindings' field in the Request PDU."
PARAM error_index { 0..2147483647 }
"The error-index field value returned in the Response PDU."
PARAM any_vb_null { }
"This variable will be TRUE if the function return
code is noError(0), but one or more varbinds returned
an exception (i.e. EndOfMibView) instead of a valid value.
It will be FALSE otherwise."
PARAM vb_ret_list { VariablePointer [2147483648] }
"The list of retrieved object instances in the Response PDU."
PARAM vb_type_list { SeeTypeIdentifier [2147483648] }
"The list of Type Identifier strings associated with
each retrieved varbind."
PARAM vb_val_list { STRING [2147483648] }
"The list of retrieved values for the associated MIB object
in the vb_list array. This value is converted to STRING format
as specified by the associated element in the vb_type_list
Expires August 15, 2001 [Page 151]
Internet Draft SEE Specification February 2001
array."
RETURN { SnmpPduErrorStatus }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
FUNCTION snmp_getbulk
FUNC-DECL "int snmp_getbulk (
INREF STRING target_engine,
INREF STRING target_context,
IN int target_addr_type,
INREF STRING target_addr,
IN uint vb_count,
INREF OID vb_list [],
IN int non_repeaters,
IN int max_repetitions,
OUT int error_index,
OUT boolean any_vb_null,
OUT uint vb_ret_count,
OUT OID vb_ret_list [],
OUT STRING vb_type_list [],
OUT STRING vb_val_list [] );"
FUNC-DESCR
"Perform an SNMP GetBulk transaction with the command
responder application on the specified target
platform."
ACCESS-BITS { getPDUs(4) }
ACCESS-DESCR
"The calling task must be permitted to conduct SNMP Get
transactions in order to use this function."
PARAM target_engine { SnmpEngineIdOrNone }
"The SNMP engine containing the MIB objects to query."
PARAM target_context { SnmpAdminString }
"The SNMP contextName containing the MIB objects to query."
PARAM vb_count { 1 .. 2147483647 }
"The number of varbinds that are contained in the
associated vb_list, vb_type_list, and vb_val_list arrays."
PARAM target_addr_type { InetAddressType }
"The type of formatted address string contained in
the target_addr parameter."
PARAM target_addr { InetAddress }
"The formatted string specifying the network address
of the target for this SNMP transaction."
Expires August 15, 2001 [Page 152]
Internet Draft SEE Specification February 2001
PARAM non_repeaters { 0 .. 2147483647 }
"The value to use in the 'non-repeaters' field in the
BulkPDU."
PARAM max_repetitions { 0 .. 2147483647 }
"The value to use in the 'max-repetitions' field in the
BulkPDU."
PARAM vb_list { VariablePointer [2147483648] }
"The list of object instances to be retrieved, that should
be used for the 'variable-bindings' field in the Request PDU."
PARAM error_index { 0..2147483647 }
"The error-index field value returned in the Response PDU."
PARAM any_vb_null { }
"This variable will be TRUE if the function return
code is noError(0), but one or more varbinds returned
an exception (i.e. NoSuchName, NoSuchException, or
EndOfMibView) instead of a valid value. It will
be FALSE otherwise."
PARAM vb_ret_count { 0 .. 2147483647 }
"The number of varbinds that are contained in the associated
vb_ret_list, vb_type_list, and vb_val_list arrays."
PARAM vb_ret_list { VariablePointer [2147483648] }
"The list of retrieved object instances in the Response PDU."
PARAM vb_type_list { SeeTypeIdentifier [2147483648] }
"The list of Type Identifier strings associated with
each retrieved varbind."
PARAM vb_val_list { STRING [2147483648] }
"The list of retrieved values for the associated MIB object
in the vb_list array. This value is converted to STRING format
as specified by the associated element in the vb_type_list
array."
RETURN { SnmpPduErrorStatus }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
FUNCTION snmp_set
FUNC-DECL "int snmp_set (
INREF STRING target_engine,
INREF STRING target_context,
IN int target_addr_type,
INREF STRING target_addr,
IN uint vb_count,
INREF OID vb_list [],
INREF STRING vb_type_list [],
Expires August 15, 2001 [Page 153]
Internet Draft SEE Specification February 2001
INREF STRING vb_val_list [],
OUT int error_index);"
FUNC-DESCR
"Perform an SNMP Set transaction with the command
responder application on the specified target
platform."
ACCESS-BITS { setPDUs(5),
writeConfig(6) }
ACCESS-DESCR
"The calling task must be permitted to conduct SNMP Set
transactions in order to use this function.
The 'writeConfig' bit must also be set if the local host
platform is specified as the target platform."
PARAM target_engine { SnmpEngineIdOrNone }
"The SNMP engine containing the MIB objects to set."
PARAM target_context { SnmpAdminString }
"The SNMP contextName containing the MIB objects to set."
PARAM target_addr_type { InetAddressType }
"The type of formatted address string contained in
the target_addr parameter."
PARAM target_addr { InetAddress }
"The formatted string specifying the network address
of the target for this SNMP transaction."
PARAM vb_count { 1 .. 2147483647 }
"The number of varbinds that are contained in the associated
vb_list, vb_type_list, and vb_val_list arrays."
PARAM vb_list { VariablePointer [2147483648] }
"The list of object instances to encode into
the 'variable-bindings' field in the Request PDU."
PARAM vb_type_list { SeeTypeIdentifier [2147483648] }
"The list of Type Identifier strings associated with
each varbind in the vb_list parameter. The agent uses
this parameter to resolve the base ASN.1 encoding
type for the 'variable-bindings' field in the Request PDU."
PARAM vb_val_list { STRING [2147483648] }
"The list of STRING-encoded values associated with
each varbind in the vb_list parameter."
PARAM error_index { 0..2147483647 }
"The error-index field value returned in the Response PDU."
RETURN { SnmpPduErrorStatus }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
Expires August 15, 2001 [Page 154]
Internet Draft SEE Specification February 2001
FUNCTION snmp_notify
FUNC-DECL "int snmp_notify (
INREF STRING target_context,
IN int target_addr_type,
INREF STRING target_addr,
IN int notify_type,
INREF OID notif_reg_id,
IN uint vb_count,
INREF OID vb_list [],
INREF STRING vb_type_list [],
INREF STRING vb_val_list [],
OUT int error_index);"
FUNC-DESCR
"Perform an SNMP Inform transaction or generate an SNMP
Trap PDU with the notification receiver application
on the specified target platform."
ACCESS-BITS { notificationPDUs(3) }
ACCESS-DESCR
"The calling task must be permitted to conduct SNMP Notify
transactions in order to use this function."
PARAM target_context { SnmpAdminString }
"The SNMP contextName value to use in ScopedPDU."
PARAM target_addr_type { InetAddressType }
"The type of formatted address string contained in
the target_addr parameter."
PARAM target_addr { InetAddress }
"The formatted string specifying the network address
of the target for this SNMP transaction.
[ed. - should this be SnmpTagValue instead, and
therefore rely on the snmpNotifyTable?]"
PARAM notify_type { 1..2 }
"The type of notification transaction to perform:
1 = trap PDU
2 = inform transaction "
PARAM notif_reg_id { VariablePointer }
"The registration OBJECT IDENTIFIER value to include
in the Trap or InformRequest PDU."
PARAM vb_count { 1 .. 2147483647 }
"The number of varbinds that are contained in the associated
vb_list, vb_type_list, and vb_val_list arrays."
PARAM vb_list { VariablePointer [2147483648] }
"The list of object instances to encode into
the 'variable-bindings' field in the Trap or Inform PDU."
PARAM vb_type_list { SeeTypeIdentifier [2147483648] }
"The list of Type Identifier strings associated with
Expires August 15, 2001 [Page 155]
Internet Draft SEE Specification February 2001
each varbind in the vb_list parameter. The agent uses
this parameter to resolve the base ASN.1 encoding
type for the 'variable-bindings' field."
PARAM vb_val_list { STRING [2147483648] }
"The list of STRING-encoded values associated with
each varbind in the vb_list parameter."
PARAM error_index { 0..2147483647 }
"The error-index field value returned in the Response PDU."
RETURN { SnmpPduErrorStatus }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
FUNCTION snmp_notify_add_varbinds
FUNC-DECL "int snmp_notify_add_varbinds (
IN uint vb_count,
INREF OID vb_list [],
INREF STRING vb_type_list [],
INREF STRING vb_val_list [] );"
FUNC-DESCR
"Append a list of specified varbinds to the Trap or
InformRequest PDU that is currently being generated
by the local agent. This function only applies to
management tasks with a seeTaskControlAppProfile
value of 'seeNotifFilter(4)'. This function will
return an error if invoked by a script of a different
application profile."
ACCESS-BITS { }
PARAM vb_count { 1 .. 2147483647 }
"The number of varbinds that are contained in the
associated vb_list, vb_type_list, and vb_val_list arrays."
PARAM vb_list { VariablePointer [2147483648] }
"The list of object instances to encode into the
'variable-bindings' field in the outgoing PDU."
PARAM vb_type_list { SeeTypeIdentifier [2147483648] }
"The list of Type Identifier strings associated with
each varbind in the vb_list parameter. The agent uses
this parameter to resolve the base ASN.1 encoding
type for the 'variable-bindings' field."
PARAM vb_val_list { STRING [2147483648] }
"The list of STRING-encoded values associated with
each varbind in the vb_list parameter."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
Expires August 15, 2001 [Page 156]
Internet Draft SEE Specification February 2001
a non-zero value indicates that the specific error
that occurred."
END
RmonLib LIBRARY-TYPE ::=
BEGIN
STATUS current
SUPPORT optional
IDENTITY { seeLibraries 6 }
VERSION "1.0"
LIB-DESCR
"Contains functions for accessing RMON configuration
data from the RMON agent on a specified local or
remote target platform."
FUNC-LIST "1.0" {
rmon_control_index,
rmon_pdir_index_by_name,
rmon_pdir_index_by_oid
}
IMPORTS "1.0"
DisplayString
FROM SNMPv2-SMI
SnmpAdminString
FROM SNMP-FRAMEWORK-MIB
InterfaceIndex
FROM IF-MIB
SnmpEngineIdOrNone
FROM ENTITY-MIB
InetAddressType, InetAddress
FROM INET-ADDRESS-MIB;
FUNCTION rmon_control_index
FUNC-DECL "uint rmon_control_index (
INREF STRING target_engine,
INREF STRING target_context,
IN int target_addr_type,
INREF STRING target_addr,
IN OID control_entry,
IN int if_index,
IN int search_mode);"
FUNC-DESCR
Expires August 15, 2001 [Page 157]
Internet Draft SEE Specification February 2001
"Retrieve an RMON control table entry on a specified
interface, from a specified SNMP engine."
ACCESS-BITS { getPDUs(4) }
ACCESS-DESCR
"The calling task must be permitted to conduct SNMP Get
transactions in order to use this function."
PARAM target_engine { SnmpEngineIdOrNone }
"The SNMP engine containing the RMON objects to query."
PARAM target_context { SnmpAdminString }
"The SNMP contextName containing the RMON objects to query."
PARAM target_addr_type { InetAddressType }
"The type of formatted address string contained in
the target_addr parameter."
PARAM target_addr { InetAddress }
"The formatted string specifying the network address
of the target for this SNMP transaction."
PARAM control_entry { OBJECT IDENTIFIER }
"The OBJECT IDENTIFIER value of the 'fooEntry' node
in the MIB tree, where 'foo' is the particular RMON
control table to query (e.g. etherStatsEntry or
hostControlTable). The specified entry must contain
a DataSource object."
PARAM if_index { InterfaceIndex }
"The interface index value to use in the DataSource
object in the specified control table,"
PARAM search_mode { 1 .. 4 }
"The type of search that should be conducted, in the event
more than one control entry exists for the specified
collection type on the specified data source.
The value '1' indicates the search should stop
when any matching control entry is found. No particular
search order is defined.
The value '2' indicates the search should be completed for
all possible rows, and the collection which has been
running the longest should be returned.
The value '3' indicates the search should be completed
for all possible rows, and the collection which has the
most data elements associated with it should be returned.
The value '4' indicates the search should continue until
the first 'monitor-owned' matching entry is found (e.g.
with an OwnerString object containing the sub-string
Expires August 15, 2001 [Page 158]
Internet Draft SEE Specification February 2001
'monitor'). The search will fail if there is no
control entry matching this criteria."
RETURN { 0 .. 65535 }
"The search results. The value zero indicates no match was
found. A non-zero value indicates a successful search, and
identifies the control table index value that best matched
the search criteria."
FUNCTION rmon_pdir_index_by_name
FUNC-DECL "uint rmon_pdir_index_by_name (
INREF STRING target_engine,
INREF STRING target_context,
IN int target_addr_type,
INREF STRING target_addr,
INREF STRING protocol_name);"
FUNC-DESCR
"Retrieve the protocolDirLocalIndex value for a
protocol specified by name (e.g 'wild-ether2.ip.udp.snmp'),
as identified by the protocolDirDescr object.
ACCESS-BITS { getPDUs(4) }
ACCESS-DESCR
"The calling task must be permitted to conduct SNMP Get
transactions in order to use this function."
PARAM target_engine { SnmpEngineIdOrNone }
"The SNMP engine containing the RMON objects to query."
PARAM target_context { SnmpAdminString }
"The SNMP contextName containing the RMON objects to query."
PARAM target_addr_type { InetAddressType }
"The type of formatted address string contained in
the target_addr parameter."
PARAM target_addr { InetAddress }
"The formatted string specifying the network address
of the target for this SNMP transaction."
PARAM protocol_name { DisplayString }
"The textual string identifying the protocolDirDescr
object to find in the protocolDirTable."
RETURN { 0 .. 2147483647 }
"The search results. The value zero indicates no match was
found. A non-zero value indicates a successful search, and
identifies the protocolDirLocalIndex value that matched
the 'protocol_name' parameter value."
FUNCTION rmon_pdir_index_by_oid
Expires August 15, 2001 [Page 159]
Internet Draft SEE Specification February 2001
FUNC-DECL "uint rmon_pdir_index_by_oid (
INREF STRING target_engine,
INREF STRING target_context,
IN int target_addr_type,
INREF STRING target_addr,
INREF OID pd_index);"
FUNC-DESCR
"Retrieve the protocolDirLocalIndex value for a
protocol specified by instance part of its INDEX value in
the protocolDirTable, as identified by the protocolDirID
and protocolDirParameters objects."
ACCESS-BITS { getPDUs(4) }
ACCESS-DESCR
"The calling task must be permitted to conduct SNMP Get
transactions in order to use this function."
PARAM target_engine { SnmpEngineIdOrNone }
"The SNMP engine containing the RMON objects to query."
PARAM target_context { SnmpAdminString }
"The SNMP contextName containing the RMON objects to query."
PARAM target_addr_type { InetAddressType }
"The type of formatted address string contained in
the target_addr parameter."
PARAM target_addr { InetAddress }
"The formatted string specifying the network address
of the target for this SNMP transaction."
PARAM pd_index { OBJECT IDENTIFIER }
"The OID value identifying the instance portion
of an INDEX value to find in the protocolDirTable. Only
components after 'protocolDirEntry' should be specified."
RETURN { 0 .. 2147483647 }
"The search results. The value zero indicates no match was
found. A non-zero value indicates a successful search, and
identifies the protocolDirLocalIndex value that matched
the 'pd_index' parameter value."
END
CliLib LIBRARY-TYPE ::=
BEGIN
STATUS current
SUPPORT optional
IDENTITY { seeLibraries 7 }
VERSION "1.0"
LIB-DESCR
Expires August 15, 2001 [Page 160]
Internet Draft SEE Specification February 2001
"Contains functions for managing CLI sessions and
executing synchronous CLI transactions with local
or remote targets. If the target platform identified
in each function call is the same as the host platform,
then the agent is not required to construct actual
network transactions (e.g. telnet) for the session,
and may choose instead to interface directly with
the local proprietary Command Line Interface software.
The actual syntax and semantics of a particular
CLI command set is beyond the scope of this document.
This library is intended to provide scripts with a common
API for CLI session creation/deletion and 'opaque' CLI
command execution.
The following parameter values must be accepted to access
local target objects, if the seeCapsAllowedTargets object
is equal to 'localTarget(1)' or 'localAndRemoteTargets(3)',
for all functions in this library:
target_addr_type = 'unknown(0)'
target_addr = zero-length string "
FUNC-LIST "1.0" {
cli_session_open,
cli_session_close,
cli_command
}
IMPORTS "1.0"
InetAddressType, InetAddress
FROM INET-ADDRESS-MIB
SeeResultCode
FROM SEE-MIB;
FUNCTION cli_session_open
FUNC-DECL "int cli_session_open (
IN int target_addr_type,
INREF STRING target_addr,
INREF STRING cli_type,
INREF int min_major_ver,
INREF int min_minor_ver,
INREF STRING username,
INREF STRING password,
OUT int session_id,
OUT STRING ret_cli_type,
OUT int major_ver,
Expires August 15, 2001 [Page 161]
Internet Draft SEE Specification February 2001
OUT int minor_ver );"
FUNC-DESCR
"Open a CLI session with the specified parameters."
ACCESS-BITS ( }
PARAM target_addr_type { InetAddressType }
"The type of formatted address string contained in
the target_addr parameter."
PARAM target_addr { InetAddress }
"The formatted string specifying the network address
of the target for this CLI session."
PARAM cli_type { }
"The string that identifies the type of operating system
CLI environment expected by the calling task.
Actual string values are vendor-specific and outside
the scope of this document. The empty string indicates
that the agent should not perform the CLI type check."
PARAM min_major_ver { 0..2147483647 }
"The major version component of the CLI environment
identifier. Actual version values are vendor-specific
and outside the scope of this document.
If this parameter and the min_minor_ver parameters are
both set to zero, then the agent will not perform the
minimum CLI version check."
PARAM min_minor_ver { 0..2147483647 }
"The minor version component of the CLI environment
identifier. Actual version values are vendor-specific
and outside the scope of this document.
If this parameter and the min_major_ver parameters are
both set to zero, then the agent will not perform the
minimum CLI version check."
PARAM username { }
"The username to apply (if required) in any login sequence
required to establish the CLI session. A zero-length string
is allowed to indicate thet no username is provided."
PARAM password { }
"The initial password to apply (if required) in the login
sequence as the CLI session is established. A zero-length
string is allowed to indicate thet no password is provided."
PARAM session_id { 1..2147483647 }
"The internal CLI session identifier handle, which is
used to access the session via the cli_command function."
PARAM ret_cli_type { }
"The string that identifies the type of operating system
CLI environment in use for this CLI session.
Actual string values are vendor-specific and outside
Expires August 15, 2001 [Page 162]
Internet Draft SEE Specification February 2001
the scope of this document."
PARAM major_ver { 1..2147483647 }
"The major version component of the CLI environment
identifier."
PARAM minor_ver { 0..2147483647 }
"The minor version component of the CLI environment
identifier."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
FUNCTION cli_session_close
FUNC-DECL "int cli_session_close (IN int session_id);"
FUNC-DESCR
"Close a CLI session previously opened with the
cli_session_open function."
ACCESS-BITS ( }
ACCESS-DESCR
"The calling task must be the same as the task
that opened the CLI session. The agent will
automatically close any CLI sessions associated
with a task, if the task invocation terminates
and this function has not been called."
PARAM session_id { 1..2147483647 }
"The internal session identifier handle of the
CLI session to terminate."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
FUNCTION cli_command
FUNC-DECL "int cli_command (
IN int session_id,
INREF STRING in_buffer,
OUT STRING out_buffer);
FUNC-DESCR
"Execute a CLI command within the specified session."
ACCESS-BITS ( writeConfig(6) }
ACCESS-DESCR
"The 'writeConfig' bit must be set in the
seeTaskControlPermissions object for the
Expires August 15, 2001 [Page 163]
Internet Draft SEE Specification February 2001
calling task in order to invoke any CLI function
which creates, modifies, or deletes any
system configuration parameters on either
the host or target platforms. Also, the
calling task must be the same as the task that opened
the CLI session."
PARAM session_id { 1..2147483647 }
"The internal session identifier handle of the
CLI session for the specified CLI command."
PARAM in_buffer { }
"The textual command string that will be executed."
PARAM out_buffer { }
"The textual output (if any) generated by the CLI
command specified in the in_buffer. This should
include all of the command output, such as any
status messages or a new command prompt."
RETURN { SeeResultCode }
"The return status. Zero indicates success, and
a non-zero value indicates that the specific error
that occurred."
END
8. External MIB Implementation Requirements
8.1. Script MIB
Portions of the Script MIB must be implemented to support the script
execution environment. This section describes the SEE agent
implementation requirements for this MIB.
8.1.1. Mapping of the smLangTable
Full implementation of the smLangTable is mandatory, in order to
identify the programming language(s) supported by the agent.
The agent must include an entry for the SEE language, in the following
manner:
smLangIndex
Any valid index value.
smLangLanguage
The 'seeLanguage' OBJECT IDENTIFIER registration value defined in
Expires August 15, 2001 [Page 164]
Internet Draft SEE Specification February 2001
the SEE MIB.
smLangVersion
The string "1.0". This value will be updated if the language
definition is updated.
smLangVendor
Any valid value identifying the product vendor.
smLangRevision
Any valid value identifying the product revision.
smLangDescr
Any valid value describing the SEE language implementation. The
value must start with the string "SEE".
This document does not place any constraints on possible values of
additional entries in the smLangTable.
8.1.2. Mapping of the smExtsnTable
The SEE agent uses the Language Extensions table to identify the SEE MIB
itself, and any system libraries that are present in the script
execution environment.
Full implementation of the smExtsnTable is mandatory, in order to
identify the programming language extensions supported by the agent.
8.1.2.1. Entry for the SEE MIB
The smExtsnTable must include the following entry, for whatever
language(s) are present which support the SEE MIB. An set of entries for
the SEE language (as defined in the previous section) must be present in
this table.
Each column is configured in the following manner:
smExtsnIndex
Any valid index value is allowed.
smExtsnExtension
The registration OBJECT IDENTIFIER 'seeMIB', from the MODULE-
IDENTIFY macro, identifying the root of this MIB.
Expires August 15, 2001 [Page 165]
Internet Draft SEE Specification February 2001
smExtsnVersion
The constant value "1.0".
smExtsnVendor
Any valid value is allowed.
smExtsnRevision
Any valid value is allowed.
smExtsnDescr
The string constant "SEE MIB".
8.1.2.2. Entry for Each System Library
The smExtsnTable must include an entry for each system library
supported, as an extension to the smLangEntry for the SEE language.
smExtsnIndex
Any valid index value is allowed.
smExtsnExtension
The registration OBJECT IDENTIFIER derived from the <lib-id> field
of the LIBRARY-TYPE macro for the library.
smExtsnVersion
The library version string, e.g., "1.0", derived from the 'VERSION'
clause of the LIBRARY-TYPE macro for the library.
smExtsnVendor
Any valid value is allowed.
smExtsnRevision
Any valid value is allowed.
smExtsnDescr
The string constant "System Library" should appear in this string,
along with the library name, derived from the 'lib-name' field of
the LIBRARY-TYPE macro for the library.
8.1.3. Mapping of the smScriptTable
The Script Table is used to identify and store all of the scripts
available to the agent for execution.
Expires August 15, 2001 [Page 166]
Internet Draft SEE Specification February 2001
Full implementation of the smScriptTable is not required. The SEE agent
implementation requirements are listed below.
smScriptOwner
Any valid value for this object is allowed. This index is also
used in certain tables in the SEE MIB.
smScriptName
Any valid value for this object is allowed. This index is also
used in certain tables in the SEE MIB.
smScriptDescr
Any valid value for this object is allowed.
smScriptLanguage
Any valid value for this object is allowed. The SEE MIB extensions
must be present for this language, as described in the previous
section.
smScriptSource
Implementation of the 'script-pull' load model is not required. An
agent may require this object to contain a zero length string.
smScriptAdminStatus
Write access to this object is not required. An agent may restrict
the value of this object to the constant 'enabled(1)'.
smScriptOperStatus
Implementation of this object is required.
smScriptStorageType
Implementation of this object is required.
smScriptRowStatus
Implementation of this object is required. The agent may restrict
write access to an instance of this object while active
seeTaskControlEntries reference that same instance.
8.1.4. Mapping of the smCodeTable
The SEE agent uses the Code Table to store the source code for each
script used in the system.
Full implementation of the smCodeTable is mandatory. This MIB does not
place any constraints on possible values of any objects in the
Expires August 15, 2001 [Page 167]
Internet Draft SEE Specification February 2001
smCodeTable.
The agent may restrict write access to an instance of the
smCodeRowStatus object while active seeTaskControlEntries reference an
entry with the same smScriptOwner and smScriptName index values.
8.1.5. Mapping of the smLaunchTable
The SEE agent does not use the Launch Table to invoke scripts. The
seeTaskControlTable is used instead to configure individual tasks.
The smLaunchArgument object is replaced in the execution environment by
a pre-defined set of invocation parameters, based on the application
profile and particular configuration of each management task.
8.1.6. Mapping of the smRunTable
The SEE agent does not use the Run Table to record script results or
control script invocation, Instead the seeTaskControlTable contains
objects to control logging of task actions, which are recorded in the
seeLogTable.
Script Exit Codes
The error codes defined in the Script MIB for smRunExitCode object
are used as the basis of the SeeResultCode TC, used by scripts and
functions within the script execution environment. The
seeTaskControlastResCode object is used to store the script return
status. Refer to the SeeResultCode TC in the SEE-MIB module for
more details.
Script Results
The smRunResult object is replaced by the seeTaskControlResultType,
seeTaskControlLastResult, and seeLogTable objects. Each application
profile defines the manner in which the seeTaskControlLastResult
object is used, if at all.
Runtime Control
The smRunControl object is removed from the system design.
Management tasks are controlled solely from from
seeTaskControlTable. An application must deactivate an entry in
this table to abort script execution. The 'suspend' and 'resume'
modes are not supported at all by the SEE agent. The 'nop' mode is
supported, and identified by the 'debugRunMode(3)' enumeration of
the seeTaskControlRunMode object.
Expires August 15, 2001 [Page 168]
Internet Draft SEE Specification February 2001
Runtime Status
The smRunState status object is not supported. Instead the
simplified seeTaskControlTaskRunning TruthValue object is used to
identify if a task is currently running or not running.
8.1.7. Mapping of the Script MIB Notifications
The smScriptAbort and smScriptResult notifications are replaced by the
seeTaskAbort and seeTaskAlarm notifications in the SEE-MIB module. The
OBJECTS clause is no longer relevant because the smRunTable is not used.
8.2. Scheduling MIB
The Scheduling MIB is required for SEE agent implementations which
support the 'Calendar' application profile. The schedLocalTime object
is required for all SEE agents which can maintain a time-of-day clock
with timezone. This section describes the SEE agent implementation
requirements for this MIB.
8.2.1. Mapping of the schedLocalTime object
This object is mandatory for any SEE agent with Time-of-Day
capabilities. The _TRIGGER_TIME_OF_DAY environment variable is derived
from this object.
8.2.2. Mapping of schedTable
This table is mandatory for SEE agents which support the 'Calendar'
application profile. Not all possible features are required for
implementation of the SEE agent. The implementation requirements for
each object are listed in this section.
schedOwner
This object should be set to the smScriptOwner index value of the
seeTaskControlEntry to be scheduled with the schedTable. However,
any valid value is allowed.
schedName
This object should be set to a string containing the smScriptName
value appended with the textual representation of the
seeTaskControlIndex value, of the seeTaskControlEntry to be
scheduled with the schedTable. However, any valid value is
allowed.
Expires August 15, 2001 [Page 169]
Internet Draft SEE Specification February 2001
schedDescr
The description of the schedule should include the term 'SEE MIB',
but any valid value is allowed.
schedInterval
This object is not used, because it has been replaced by the
'Periodic' application profile. This object should be set to the
value '0'.
schedWeekDay
Implementation of this object is required.
schedMonth
Implementation of this object is required.
schedDay
Implementation of this object is required.
schedHour
Implementation of this object is required.
schedMinute
Implementation of this object is required.
schedContextName
This object must identify the context which contains the SEE MIB
objects. Configuration of this value is outside the scope of the
SEE MIB. However, the SEE MIB should only be contained in the
default context since it is not designed to provide more than one
execution environment per host SNMP engine.
schedVariable
This object must be set to the instance of the
seeTaskControlRunButton object associated with the task to be
scheduled (identified by the smScriptOwner, smScriptName, and
seeTaskControlIndex objects).
schedValue
This object must be set to the constant 'runTask(1)'.
schedType
This object should be set to the constant 'calendar(2)'. The SEE
agent is not required to support the other scheduling modes, since
they have been replaced by application profile model used in the
seeTaskControlTable.
Expires August 15, 2001 [Page 170]
Internet Draft SEE Specification February 2001
schedAdminStatus
Implementation of this object is required.
schedOperStatus
Implementation of this object is required.
schedFailures
Implementation of this object is required.
schedLastFailure
Implementation of this object is required.
schedLastFailed
Implementation of this object is required.
schedStorageType
Implementation of this object is required.
schedRowStatus
Implementation of this object is required. The SEE agent should
not couple activation of a schedEntry with activation or
deactivation of any seeTaskControlEntries referenced by that
schedEntry.
An application should activate the seeTaskControlEntry to be
scheduled before the associated schedEntry is activated.
The Scheduling MIB agent should allow the schedVariable to
reference inactive or non-existent seeTaskControl entries, to
remove row creation order dependencies.
9. Open Issues
This draft contains the following open issues:
- Specify high-level interactions between application profiles
and SNMP engine components such as the message dispatcher,
security sub-system, and other co-located SNMP applications.
- Specify log format output requirements for 'trace' run modes
- Is initial programming language definition complete?
- Should the language specification be removed in favor
of a widely available language, such as java?
Can java extensions be defined which capture the runtime
environment for each application profile, and specialized
SNMP features such as OID expressions?
- Is initial system library set complete?
Expires August 15, 2001 [Page 171]
Internet Draft SEE Specification February 2001
- Is initial application profile set complete?
- Design documentation template (i.e. SCRIPT-TYPE macro) for
scripts, like the LIBRARY-TYPE macro for system libraries
- Add example scripts for each application profile
- Specify USM (& other?) security parameter mappings for
functions in the 'SnmpMsgLib' system library
- Specify VACM parameter mappings for all library functions
which access the local SNMP engine
- When and how to support SMIng data types?
- Should the SNMP-NOTIFICATION-MIB be required,
and the snmp_notify function changed to use an SnmpTagValue
parameter instead of an InetAddress?
- Should the SNMP-TARGET-MIB be required, and the snmp_get*
and snmp_set functions changed to use an SnmpTagValue
parameter instead of an InetAddress?
Expires August 15, 2001 [Page 172]
Internet Draft SEE Specification February 2001
10. Intellectual Property
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to pertain
to the implementation or use of the technology described in this
document or the extent to which any license under such rights might or
might not be available; neither does it represent that it has made any
effort to identify any such rights. Information on the IETF's
procedures with respect to rights in standards-track and standards-
related documentation can be found in BCP-11. Copies of claims of
rights made available for publication and any assurances of licenses to
be made available, or the result of an attempt made to obtain a general
license or permission for the use of such proprietary rights by
implementors or users of this specification can be obtained from the
IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary rights
which may cover technology that may be required to practice this
standard. Please address the information to the IETF Executive
Director.
Expires August 15, 2001 [Page 173]
Internet Draft SEE Specification February 2001
11. References
[ANSI_C_89]
American National Standards Institute, "Programming Language - C",
ANSI X3.159-1989, December, 1989.
[RFC1155]
Rose, M., and K. McCloghrie, "Structure and Identification of
Management Information for TCP/IP-based Internets", RFC 1155,
Performance Systems International, Hughes LAN Systems, May 1990.
[RFC1157]
Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network
Management Protocol", RFC 1157, SNMP Research, Performance Systems
International, Performance Systems International, MIT Laboratory
for Computer Science, May 1990.
[RFC1212]
Rose, M., and K. McCloghrie, "Concise MIB Definitions", RFC 1212,
Performance Systems International, Hughes LAN Systems, March 1991.
[RFC1215]
M. Rose, "A Convention for Defining Traps for use with the SNMP",
RFC 1215, Performance Systems International, March 1991.
[RFC1901]
SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Introduction to Community-based SNMPv2", RFC 1901,
SNMP Research, Inc., Cisco Systems, Inc., Dover Beach Consulting,
Inc., International Network Services, January 1996.
[RFC1905]
SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Protocol Operations for Version 2 of the Simple
Network Management Protocol (SNMPv2)", RFC 1905, SNMP Research,
Inc., Cisco Systems, Inc., Dover Beach Consulting, Inc.,
International Network Services, January 1996.
[RFC1906]
SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S.
Waldbusser, "Transport Mappings for Version 2 of the Simple Network
Management Protocol (SNMPv2)", RFC 1906, SNMP Research, Inc., Cisco
Systems, Inc., Dover Beach Consulting, Inc., International Network
Services, January 1996.
Expires August 15, 2001 [Page 174]
Internet Draft SEE Specification February 2001
[RFC2021]
S. Waldbusser, "Remote Network Monitoring MIB (RMON-2)", RFC 2021,
International Network Services, January 1997.
[RFC2026]
Bradner, S., "The Internet Standards Process -- Revision 3", RFC
2026, Harvard University, October, 1996.
[RFC2570]
Case, J., Mundy, R., Partain, D., and B. Stewart, "Introduction to
Version 3 of the Internet-standard Network Management Framework",
RFC 2570, SNMP Research, Inc., TIS Labs at Network Associates,
Inc., Ericsson, Cisco Systems, April 1999.
[RFC2571]
Harrington, D., Presuhn, R., and B. Wijnen, "An Architecture for
Describing SNMP Management Frameworks", RFC 2571, Cabletron
Systems, Inc., BMC Software, Inc., IBM T. J. Watson Research, April
1999.
[RFC2572]
Case, J., Harrington D., Presuhn R., and B. Wijnen, "Message
Processing and Dispatching for the Simple Network Management
Protocol (SNMP)", RFC 2572, SNMP Research, Inc., Cabletron Systems,
Inc., BMC Software, Inc., IBM T. J. Watson Research, April 1999.
[RFC2573]
Levi, D., Meyer, P., and B. Stewart, "SNMPv3 Applications", RFC
2573, SNMP Research, Inc., Secure Computing Corporation, Cisco
Systems, April 1999.
[RFC2574]
Blumenthal, U., and B. Wijnen, "User-based Security Model (USM) for
version 3 of the Simple Network Management Protocol (SNMPv3)", RFC
2574, IBM T. J. Watson Research, April 1999.
[RFC2575]
Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based Access
Control Model (VACM) for the Simple Network Management Protocol
(SNMP)", RFC 2575, IBM T. J. Watson Research, BMC Software, Inc.,
Cisco Systems, Inc., April 1999.
[RFC2578]
McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M.,
and S. Waldbusser, "Structure of Management Information Version 2
Expires August 15, 2001 [Page 175]
Internet Draft SEE Specification February 2001
(SMIv2)", RFC 2578, STD 58, Cisco Systems, SNMPinfo, TU
Braunschweig, SNMP Research, First Virtual Holdings, International
Network Services, April 1999.
[RFC2579]
McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M.,
and S. Waldbusser, "Textual Conventions for SMIv2", RFC 2579, STD
58, Cisco Systems, SNMPinfo, TU Braunschweig, SNMP Research, First
Virtual Holdings, International Network Services, April 1999.
[RFC2580]
McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M.,
and S. Waldbusser, "Conformance Statements for SMIv2", RFC 2580,
STD 58, Cisco Systems, SNMPinfo, TU Braunschweig, SNMP Research,
First Virtual Holdings, International Network Services, April 1999.
[RFC2591]
Levi, D., and J. Schoenwaelder, "Definitions of Managed Objects for
Scheduling Management Operations", RFC 2591, Nortel Networks, TU
Braunschweig, May 1999.
[RFC2592]
Levi, D., and J. Schoenwaelder, "Definitions of Managed Objects for
the Delegation of Management Scripts", RFC 2592, Nortel Networks,
TU Braunschweig, May 1999.
Expires August 15, 2001 [Page 176]
Internet Draft SEE Specification February 2001
12. Security Considerations
There are a number of management objects defined in this MIB that have a
MAX-ACCESS clause of read-write and/or read-create. Such objects may be
considered sensitive or vulnerable in some network environments. The
support for SET operations in a non-secure environment without proper
protection can have a negative effect on network operations.
There is at least one managed object in this MIB that may contain
sensitive information. The seeLogChunk object exposes script logging
output generated on behalf of management tasks running in the system.
It is thus important to control even GET access to this object and
possibly to even encrypt the values of these object when sending them
over the network via SNMP. Not all versions of SNMP provide features
for such a secure environment.
SNMPv1 by itself is not a secure environment. Even if the network
itself is secure (for example by using IPSec), even then, there is no
control as to who on the secure network is allowed to access and GET/SET
(read/change/create/delete) the objects in this MIB.
It is recommended that the implementers consider the security features
as provided by the SNMPv3 framework. Specifically, the use of the User-
based Security Model RFC 2574 [RFC2574] and the View-based Access
Control Model RFC 2575 [RFC2575] is recommended.
It is then a customer/user responsibility to ensure that the SNMP entity
giving access to an instance of this MIB, is properly configured to give
access to the objects only to those principals (users) that have
legitimate rights to indeed GET or SET (change/create/delete) them.
13. Author's Address
Andy Bierman
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA USA 95134
Phone: +1 408-527-3711
Email: abierman@cisco.com
Expires August 15, 2001 [Page 177]
Internet Draft SEE Specification February 2001
14. Full Copyright Statement
Copyright (C) The Internet Society (2001). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it or
assist in its implementation may be prepared, copied, published and
distributed, in whole or in part, without restriction of any kind,
provided that the above copyright notice and this paragraph are included
on all such copies and derivative works. However, this document itself
may not be modified in any way, such as by removing the copyright notice
or references to the Internet Society or other Internet organizations,
except as needed for the purpose of developing Internet standards in
which case the procedures for copyrights defined in the Internet
Standards process must be followed, or as required to translate it into
languages other than English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an "AS
IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.
Expires August 15, 2001 [Page 178]