Error codes in Agent X

[0001] The invention is related to the reporting of error information. More particularly, this invention relates to the reporting of very specific error information when using a management protocol.

[0002] When a configuration command fails, the SNMP protocol sends an error code back to the user. Examples of a configuration command include setting the line speed on a peripheral. An error will occur if that peripheral can't support the line speed. However, SNMP only permits a limited number of error codes. Consequently, many times there is not enough information contained in the code for the operator to know exactly what's wrong. More specifically, in the Agent X standard (RFC 2741) the error status field of a response message is limited to a few AgentX-specific error codes (not applicable to the 7770 RCP architecture), plus the 18 SNMP error status values defined in RFC 1905. This means that the applications may only report one of the 18 error codes defined by SNMP. In the majority of error situations, more specific information about the error is known. However, when the standard SNMP protocol is used, this additional specific information can not be passed back to the user. Consequently, the human operator may be unable to determine exactly why the management operation failed. Thus, he will be unable to correct the error.

[0003] In a preferred embodiment, the invention is a method of generating an error code, comprising the steps of placing additional information in an error status field by reserving lower bits for SNMP error codes and placing additional error information in upper bits.

[0004] In another preferred embodiment, the error status field is a 32-bit field, wherein said lower bits are 5 bits and said upper bits are 27 bits.

[0005] In still another preferred embodiment, the error status field is a 16-bit field, wherein said lower bits are 5 bits and said upper bits are 11 bits.

[0006] In still another preferred embodiment, the error code comprises 3 sections, wherein the 3 sections comprise top bits to identify a group of error codes, middle bits to identify a code within a range of said group of error codes, and lower bits reserved for SNMP error code.

[0007] In still another preferred embodiment, the invention further comprises an apparatus to generate error codes, comprising a master agent comprising a processor, at least one subagent operably connected to the master agent, a handler operably connected to said master agent comprising an API stored in memory; and a database operably connected to the handler.

[0008] In still another preferred embodiment, the API is MapErrorCode lookup function, the memory is RAM memory, the handler is a Web handler or a CLI handler or a Web and CLI handler.

[0009] In still another preferred embodiment, the database is an error code look-up database, whereby said handler looks up an error code in said database.

[0021] The standard AgentX error status field of a response message is limited to a few AgentX-specific error codes (ERR), plus the 18 standard SNMP error status values (ERRS). This means that very little information is normally available to assist a human operator at a Web or CLI interface to recover from a problem such as a configuration error.

[0022] The present invention comprises an extension to the AgentX protocol and the SNMP Master Agent (MA) processing for a multi-interface management architecture that is modeled using SNMP internally. The extension allows information to be reported back to CLI and WEB operators. In a preferred embodiment, this extension is used in a 7770 RCP router. The code used by the SNMP Master Agent (MA) to map messages between protocols is effectively a filter.

AgentX

[0023] An agent monitors and accumulates operational data and detects exceptional events for each network element. There can be one agent for the whole box, or we can have one master agent (MA) and a subagent (SA) for each major software application that we have running. The master agent (MA) communicates with the subagents (SA) through a protocol called AgentX.

Standard SNMP/AgentX Subagent Architecture

[0024] Many network devices, such as the router described in copending U.S. patent application, SNMP Trap and Inform Shaping Mechanism, Ser. No. 10/118894, filed Apr. 10, 2002, page 3, line 26 to page 5, line 25 and FIG. 1–3, hereby incorporated by reference, use an SNMP Master Agent-Subagent (MA-SA) architecture internally for processing management operations. The Master Agent (MA) receives SNMP messages from external SNMP managers, and distributes them internally as AgentX messages to multiple subagents (SA) within the router (RI). The subagents (SA) route the messages to corresponding applications. The subagents (SA) return responses from the applications to the Master Agent (MA). Each management subagent (SA) may service multiple applications. Typically, a subagent (SA) services one type of application (e.g., IP forwarding) on all boards. In the 7770 RCP router the subagent (SA) can service up to 30 TLKs, although the present invention can apply to systems where each subagent (SA) can service even greater numbers.

[0025] FIG. 1 discloses a SNMP Master Agent-Subagent (MA-SA) architecture. In FIG. 1, configuration commands (CMD) are sent as AgentX messages to the subagents (SA) that support internal applications. Data or error notifications from internal applications are sent back as AgentX response messages (RESP) towards the Master Agent (MA). See RFC 2741, Daniele, January 2000, Agent Extensibility (AgentX) Protocol Version 1, hereby incorporated by reference. Then, they are translated into SNMP response packets (PKT) containing either data or an SNMP-defined error status value (ERRS). See RFC 1905, Case, January 1996, Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2), hereby incorporated by reference.

Multi-Protocol/AgentX Subagent Architecture.

[0026] The 7770 RCP Master Agent-Subagent (MA-SA) architecture of the present invention also includes a link to a Web Interface and a Command Line Interface (CLI). The Web commands and the CLI commands are translated into AgentX messages. They share the same internal processing as the equivalent SNMP commands.

Preferred Embodiment

[0027] The solution involves placing additional information in the AgentX error status field (STSF). See FIG. 2. In a preferred embodiment, the Agent X error status field (STSF) is a 32-bit field. The lower 5 bits (LB) are reserved for the SNMP-defined error codes (ERR) which are very general in nature and, therefore, communicate limited information. Additional error information or specific error codes (ERR) are placed in the upper 27 bits (UB). As a result, thousands of very specific error codes (ERR) can be communicated by the AgentX packet to the human operator, thereby allowing the operator to know exactly what is wrong. Generic error codes (ERR) can be used by all subagents (SA) and applications. Specific error codes (ERR) (and the corresponding messages) are arranged into groups, with ranges per subagent (SA). The CLI and Web logic access these error messages via the MapErrorCode Application Programming Interface (API) discussed infra, whose input is the value of the error code (ERR) to be translated into a text string.

[0028] As stated above the lower 5 bits (LB), bits 0–4, are reserved for SNMP-defined error codes (ERR) (100). The next 11 bits, upper bits (UB), bits 5–15, are used to store an internal portion of the additional error information, or stated another way, additional error messages to the 18 SNMP error status values (ERRS) defined in RFC 1905 (110). In a preferred embodiment, 500 additional error messages can be stored.

[0029] Each subagent (SA) or group of subagents (SA) is assigned a range of values to ensure each is uniquely identified (120). The message code values and the text of the messages are defined in global files. This will ensure consistency. In addition, it could also be used to provide language translation or customization.

[0030] The error codes (ERR) in the AgentX error status field (STSF) are transmitted to the Master Agent (MA) by the subagent (SA) (200). See FIG. 3. Next, the Master Agent (MA) processes the error code (ERR) in the following manner (210). (The master agent (MA) uses a processor (P1) to process the error code. (The processor can be a microprocessor, a central processing unit or any of a number of processing means such including analog processing means). It inquires “Does the management request originate from an SNMP manager? (215) If the management request originated from an SNMP manager, the Master Agent (MA) will only process the lowest 5 bits (LB) of the AgentX status field (STSF) because the SNMP operator will only be able to recognize the 18 SNMP error status values defined in RFC 1905 (220). Therefore, these 5 bits map to one of the 18 SNMP defined error status values (ERRS) (230).

[0031] If the management request originated from a Web or a CLI interface, then the Master Agent (MA) passes the full error code (ERR) from the AgentX error status field (STSF) to the CLI or Web software or operator (240). The Web interface or CLI handler then looks up an appropriate error message corresponding to this error message in a error code lookup database (ERRDB) to display on the user interface (250). (See FIG. 4).

[0032] The Web handler (H1) or CLI handler (H1) uses a global library function, MapErrorCode, to locate an appropriate error message. The MapErrorCode look-up function is an Application Programming Interface (API). An API is a specification which defines what procedures are followed by an application program when it invokes a defined set of services. It is stored in software (or firmware) located in memory (M1, M2) in the Web interface (Web i/f) or the CLI interface (CLI i/f). The memory can be RAM, ROM, PROM, EPROM. The handler inputs two parameters into MapErrorCode, the error code value and a pointer to the memory where the error text string will be returned by the library function. MapErrorCode retrieves the error text string corresponding to a given error code (ERR). In effect, it translates the error code (ERR) to an error string. MapErrorCode also adds the appropriate prefix, as necessary, and returns the complete error (or warning) string, ready for display to the operator. If the error string for a specified error code (ERR) is not defined in the generic error mapping TDL file, then the MapErrorCode API returns the error string defined for the “genError” code.

[0033] In a preferred embodiment, the internally-defined error code (ERR) is a 16-bit number—the lower 5 bits (LB), bits 0–4, reserved for SNMP-defined error codes and the next 11 bits (UB), bits 5–15, used to store an internal portion of the additional error information. See FIG. 5(a). The lower 5 bits (LB) of the internally defined error code (ERR) is the code that will be seen by the SNMP manager. Therefore, it conforms to the SNMP protocol rules.

[0034] The 16-bit field can also be divided into 3 sections (S1, S2, S3): The top 5 bits (S1) identify the group of error codes (groups are assigned to teams or to software modules). The middle 6 bits (S2) identify a unique code within that range. The lowest 5 bits (LB) are reserved for the SNMP error code (ERR). See FIG. 5(b). In other embodiments, 32 bits are available for the internally defined error code (ERR).

[0035] CLI and Web interfaces will display the error code (ERR) as a number, plus the error text message. For read operations (such as internal Gets or GetNext messages, Web monitoring or display of attributes, CLI show or view commands, etc.), the subagents (SA) use the value genErr=5 as the SNMP-specific portion (or lower 5 bits) of any error that they detect. The upper bits (UB) may take on specific values corresponding to one of the 500 additional error messages or specific error messages. For write operations (such as Web or CLI configuration or action commands), the values defined in RFC 1905 and shown in FIG. 6 are used for the SNMP-specific portion of the code.

[0036] FIG. 7 shows the steps taken in the C language programming code to assign the additional error information, or bits 5–15, of the error codes (ERR). It illustrates the assignment of the proprietary portion of the error code.

[0037] FIG. 8 contains examples of specific error messages all of which map to SNMP error code genErr=5.

[0038] FIG. 9 illustrates how the Web and CLI interface component or handler (H1) sends commands in the 7770 RCP Master Agent-Subagent (MA-SA) architecture. In the present invention, this component can be the Web interface (Web i/f) or the Command Line Interface (CLI i/f). In the example, the operator sends a command to a peripheral (e.g., an OC-3 line card) to set the line speed to 1.5 Mb/s (300). See FIG. 10. The operator does this by sending a Set function call (SET) to the Master Agent (MA) using the CLI interface (CLI i/f). The Master Agent (MA) sends an AgentX command (CMD) or message to a subagent (SA) handling the peripheral (310). The subagent (SA) determines if the peripheral can support the desired line speed. Subagent asks the question, “Can peripheral support desired line speed?” (320). If it can't, then the command is inconsistent with the peripheral's configuration. If the peripheral can't support the desired line speed, then the subagent (SA) will send an error status or error code (ERR), along with its response (RESP), to the Master Agent (MA) (325). The next query is “Is the management protocol SNMP? (330). In the present example, the error code (ERR) is 0×5120C. If the answer is no, the Master Agent (MA) knows that the response along with the error code (ERR) came from within, and passes it along to the Web and CLI interface component or handler (H1) (340). The Web and CLI interface component (H1) will look up the error code (ERR) in a error code lookup database (ERRDB) using the MapErrCode API (350). The error code lookup database (ERRDB) can be any of a variety of means for storing information such as RAM, ROM, PROM or EPROM, etc. In the database, 0×5120C means speed not valid for an OC-3 card. The Web or CLI interface handler (H1) software will pass the associated error message (ERM) along to the operator (360). In a preferred embodiment, the operator can access the command line interface (CMD i/f) using a terminal (T1).

[0039] If the peripheral can't support the desired line speed and the management protocol was SNMP, then the response (RESP) from the subagent (SA) would go to the Master Agent (MA) and then to the operator using one of the 18 standard SNMP error messages (ERM) (370). Non SNMP protocols such as the Web or the CLI management protocols support the extended error messages. SNMP doesn't have a look-up table or database (dB) to translate the commands.

[0040] If the peripheral can support desired line speed, the command is passed along to the peripheral (380).

[0041] While the invention has been disclosed in this patent application by reference to the details of preferred embodiments of the invention, it is to be understood that the disclosure is intended in an illustrative, rather than a limiting sense, as it is contemplated that modifications will readily occur to those skilled in the art, within the spirit of the invention and the scope of the appended claims and their equivalents.