Internet Draft Andy Bierman Cisco Systems, Inc. 15 February 2001 Script Execution Environment Specification For Distributed Management Platforms 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 . 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 , 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 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 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 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 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 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 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 token applies to the SeeIdentifierString textual convention, as well as to tokens within SEE scripts. MIB values of type SeeIdentifierString and SEE 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 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 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 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 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 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 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 , 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 -- token does not actually exist in the language. = "/*" "*/" = ( | ) = any member of the source character set -- Identifiers -- -- The token defines the syntax for -- the SeeIdentifierString TC = ( | | ) = ( "a" .. "z" | "A" .. "Z" | "_" ) -- underscore Expires August 15, 2001 [Page 36] Internet Draft SEE Specification February 2001 = ( | "0" ) = ( "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ) -- Constants -- -- includes all forms except the -- double floating point, and long character constants = ( | | ) -- this construct is only present if the 'float' -- data type is supported = ( [] | ) = ( [] "." | "." ) = ( "E" [] | "e" [] ) = ( "+" | "-" ) = ( | ) = ( | hexadecimal-constant> ) = ( | ) Expires August 15, 2001 [Page 37] Internet Draft SEE Specification February 2001 = ( "0x" | "0X" | ) = ( | ) = ( "a" | "b" | "c" | "d" | "e" | 'f" | "A" | "B" | "C" | "D" | "E" | 'F" ) = "'" "'" -- Escape Sequences -- -- does not includes octal constants = ( | ) = ( "\'" | -- 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 = ( "\x" | ) -- String Literals -- -- does not include long (unicode) string constants = Expires August 15, 2001 [Page 38] Internet Draft SEE Specification February 2001 """ [ ] """ = ( | ) = ( | ) = 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: -- -> -- ? -- : -- # -- ## = ( "[" | "]" | "(" | ")" | "." | "++" | "--" | "&" | "*" | "+" | "-" | "~" | "!" | "/" | "%" | "<<" | ">>" | "<" | ">" | "<=" | ">=" | "==" | "!=" | "^" | "|" | "&&" | "||" | "=" | "*=" | "/=" | "%=" | "+=" | "-=" | "<<=" | ">>=" | "&=" | "^=" | "|=" | "," | "sizeof" ) -- expression statements -- -- The constructs derived from the -- implicitly define the operator precedence hierarchy -- -- The following constructs are not included: -- "." -- "->" -- cast expressions -- unary operators: & * -- "?" ":" -- -- "," = Expires August 15, 2001 [Page 39] Internet Draft SEE Specification February 2001 ( | | | "(" ")" ) = ( | "[" "]" | "(" ")" | "++" | "--" ) = ( | "," ) = ( | "++" | "--" ) = ( "+" | "-" | "~" | "!" ) = ( | "*" | "/" | "%" ) = ( | "+" | "-" ) = ( | "<<" | ">>" ) = ( | "<" | ">" | "<=" | Expires August 15, 2001 [Page 40] Internet Draft SEE Specification February 2001 ">=" ) = ( | "==" | "!=" ) = ( | "&" ) = ( | "^" ) = ( | "|" ) = ( | "&&" ) = ( | "||" ) = = ( | ) = ( "=" | "*=" | "/=" | "%=" | "+=" | "-=" | "<<=" | ">>=" | "&=" | "^=" | "|=" ) = -- 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 value as the contents of an OID variable. -- -- The '+=' operator is supported to append an -- value to the contents of an OID variable. = ( "=" | "+=" ) -- OID expressions are comprised of OID parts, -- Leading or trailing dot '.' tokens are not allowed = ( | "." ) -- -- 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 = ( | "[" "]" | | ) = ( | Expires August 15, 2001 [Page 42] Internet Draft SEE Specification February 2001 ) -- -- Declarations -- -- Features not included: -- 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 like 'const' are not supported = ( | ) = ( | | ) -- only the simple scalar constants are supported -- at this time, such as 'const int foo = 6;' -- non-scalar constant declarations are TBD = "const" "=" ";" = ";" = ( | "," ) = Expires August 15, 2001 [Page 43] Internet Draft SEE Specification February 2001 ";" = ( | "," ) -- New Construct: -- e.g.: -- BITS testbits[6]; -- declares a local variable named 'testbits' -- with 6 bits in it, numbered 0..5 -- the must be greater than zero = "[" "]" -- type definitions simplified -- new data types can be represented in C -- with '#define' statements -- the float data type is optional = ( | ) = ( "boolean" | "char" | "float" | "int" | "long" | "uint" | "ulong" | "void" ) = ( "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 = ( | | | | | ) = ( "case" ":" | "default" ":" ) = "{" [ ] "}" = ( | ) = [ ] ";" = ( "if" "(" ")" "{" "}" | "if" "(" ")" "{" "}" "else" "{" "}" | "switch" "(" ")" ) = ( "while" "(" ")" | "do" "while" "(" ")" ";" | "for" "(" [ ] ";" [ ] ";" [ ] ")" ) = ( "continue" ";" | "break" ";" | "return" [ ] ";" ) -- 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: -- variants of the token -- complex forms of -- complex forms of = "(" [ ] ")" = ( | "," "..." ) = ( | "," ) -- only simple token can be used as the -- name of a parameter; complex forms not supported = ( ) -- 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 = ( "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 token -- and allowing only the variant = ( | ) = ( | ) -- local parameters can only be defined at the -- top level of a function block, -- not within nested blocks = "{" [] [ ] "}" 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 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 ( 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 ( 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 ( 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 ( 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 ( 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 ( 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 ( 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 = ( | ) -- a library definition = "LIBRARY-TYPE" "::=" "BEGIN" "STATUS" "SUPPORT" "IDENTITY" "{" "}" "VERSION" "LIB-DESCR" [ "OBSOLETES" ] "END" = = ( "current" | "deprecated" | "obsolete" ) = ( "mandatory" | "conditional" | "optional" ) = ( | ) = "IMPORTS" string ";" = Expires August 15, 2001 [Page 79] Internet Draft SEE Specification February 2001 ( | ) = "FROM" = ( | ) = "FUNC-LIST" string "{" "}" = ( | "," ) = ( | | ) = ( "a" .. "z" | "A" .. "Z" ) = ( "a" .. "z" | "A" .. "Z" | "-" ) -- single dash char = value(OBJECT IDENTIFIER) = ( | ) = "FUNCTION" "FUNC-DECL" """ """ "FUNC-DESCR" "ACCESS-BITS" "{" "}" [ "ACCESS-DESCR" ] [ ] [ ] = ( | "," ) Expires August 15, 2001 [Page 80] Internet Draft SEE Specification February 2001 = "(" ")" = ( | ) = "PARAM" ( | "..." ) = "RETURN" -- very simple type constraint expressions in this version = "{" [ ( | | ) ] [ ] "}" -- the 2 constants must be the same type, and the 2nd one -- must represent a value greater than the first one = ".." -- all constants in the list must be the same type -- and the same value must not appear more than once = ( | "," ) -- the array-part is mandatory for array parameters -- and not allowed for non-array parameters = "[" "]" -- , , , -- and 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 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 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 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 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 " 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 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 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 (void);' With return value: ' (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 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 ' = '." 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 ' = ' or '[n] = ' 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 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]