diff options
author | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
---|---|---|
committer | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
commit | 84adefa331c4159d432d22840663c38f155cd4c1 (patch) | |
tree | bff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/snmp/doc/src/snmp_agent_funct_descr.xml | |
download | otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2 otp-84adefa331c4159d432d22840663c38f155cd4c1.zip |
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/snmp/doc/src/snmp_agent_funct_descr.xml')
-rw-r--r-- | lib/snmp/doc/src/snmp_agent_funct_descr.xml | 947 |
1 files changed, 947 insertions, 0 deletions
diff --git a/lib/snmp/doc/src/snmp_agent_funct_descr.xml b/lib/snmp/doc/src/snmp_agent_funct_descr.xml new file mode 100644 index 0000000000..9a1bf28ab1 --- /dev/null +++ b/lib/snmp/doc/src/snmp_agent_funct_descr.xml @@ -0,0 +1,947 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Agent Functional Description</title> + <prepared></prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date></date> + <rev></rev> + <file>snmp_agent_funct_descr.xml</file> + </header> + <p>The SNMP agent system consists of one Master Agent and + optional Sub-agents. + </p> + <p>The tool makes it easy to dynamically extend an SNMP agent in + run-time. MIBs can be loaded and unloaded at any time. It is also + easy to change the implementation of an MIB in run-time, without + having to recompile the MIB. The MIB implementation is clearly + separated from the agent. + </p> + <p>To facilitate incremental MIB implementation, the tool can + generate a prototype implementation for a whole MIB, or parts + thereof. This allows different MIBs and management applications to + be developed at the same time. + </p> + + <section> + <title>Features</title> + <marker id="features"></marker> + <p>To implement an agent, the programmer writes instrumentation + functions for the variables and the tables in the MIBs that the + agent is going to support. A running prototype which handles <c>set</c>, + <c>get</c>, and <c>get-next</c> can be created without any programming. + </p> + <p>The toolkit provides the following: + </p> + <list type="bulleted"> + <item>multi-lingual multi-threaded extensible SNMP agent</item> + <item>easy writing of instrumentation functions with a + high-level programming language</item> + <item>basic fault handling such as automatic type checking</item> + <item>access control</item> + <item>authentication</item> + <item>privacy through encryption</item> + <item>loading and unloading of MIBs in run-time</item> + <item>the ability to change instrumentation functions without + recompiling the MIB</item> + <item>rapid prototyping environment where the MIB compiler can + use generic instrumentation functions, which later can be + refined by the programmer</item> + <item>a simple and extensible model for transaction handling and + consistency checking of set-requests</item> + <item>support of the sub-agent concept via distributed Erlang</item> + <item>a mechanism for sending notifications (traps and informs)</item> + <item>support for implementing SNMP tables in the Mnesia DBMS.</item> + </list> + </section> + + <section> + <title>SNMPv1, SNMPv2 and SNMPv3</title> + <marker id="versions"></marker> + <p>The SNMP development toolkit works with all three versions of + Standard Internet Management Framework; SNMPv1, SNMPv2 and SNMPv3. + They all share the same basic structure and components. And they + follow the same architecture.</p> + <p>The versions are defined in following RFCs</p> + <list type="bulleted"> + <item>SNMPv1 RFC 1555, 1157 1212, 1213 and 1215</item> + <item>SNMPv2 RFC 1902 - 1907</item> + <item>SNMPv3 RFC 2570 - 2575</item> + </list> + <p>Over time, as the Framework has evolved from SNMPv1 , through SNMPv2, + to SNMPv3 the definitions of each of these architectural components + have become richer and more clearly defined, but the fundamental + architecture has remained consistent.</p> + <p>The main features of SNMPv2 compared to SNMPv1 are: + </p> + <list type="bulleted"> + <item>The <c>get-bulk</c> operation for transferring large + amounts of data. + </item> + <item>Enhanced error codes. + </item> + <item>A more precise language for MIB specification</item> + </list> + <p>The standard documents that define SNMPv2 are incomplete, in + the sense that they do not specify how an SNMPv2 message looks + like. The message format and security issues are left to a + special Administrative Framework. One such framework is the + Community-based SNMPv2 Framework (SNMPv2c), which uses the same + message format and framework as SNMPv1. Other + experimental frameworks as exist, e.g. SNMPv2u and SNMPv2*. + </p> + <p>The SNMPv3 specifications take a modular + approach to SNMP. All modules are + separated from each other, and can be extended or replaced + individually. Examples of modules are Message definition, + Security and Access Control. The main features of SNMPv3 are: + </p> + <list type="bulleted"> + <item>Encryption and authentication is added. + </item> + <item>MIBs for agent configuration are defined.</item> + </list> + <p>All these specifications are commonly referred to as "SNMPv3", + but it is actually only the Message module, which defines a new + message format, and Security module, which takes care of + encryption and authentication, that cannot be used with SNMPv1 or + SNMPv2c. In this version of the agent toolkit, all the standard + MIBs for agent configuration are used. This includes MIBs for + definition of management targets for notifications. These MIBs + are used regardless of which SNMP version the agent is configured + to use. + </p> + <p>The extensible agent in this toolkit understands the SNMPv1, + SNMPv2c and SNMPv3. Recall that SNMP consists of two separate + parts, the MIB definition language (SMI), and the protocol. On + the protocol level, the agent can be configured to speak v1, v2c, + v3 or any combination of them at the same time, i.e. a v1 request + gets an v1 reply, a v2c request gets a v2c reply, and a v3 request + gets a v3 reply. On the MIB level, the MIB compiler can compile + both SMIv1 and SMIv2 MIBs. Once compiled, any of the formats can + be loaded into the agent, regardless of which protocol version the + agent is configured to use. This means that the agent translates + from v2 notifications to v1 traps, and vice versa. For example, + v2 MIBs can be loaded into an agent that speaks v1 only. The + procedures for the translation between the two protocols are + described in RFC 1908 and RFC 2089. + </p> + <p>In order for an implementation to make full use of the enhanced + SNMPv2 error codes, it is essential that the instrumentation + functions always return SNMPv2 error codes, in case of error. + These are translated into the corresponding SNMPv1 error codes by + the agent, if necessary.</p> + <note> + <p>The translation from an SMIv1 MIB to an SNMPv2c or SNMPv3 reply + is always very straightforward, but the translation from a v2 MIB + to a v1 reply is somewhat more complicated. There is one data + type in SMIv2, called <c>Counter64</c>, that an SNMPv1 manager cannot + decode correctly. Therefore, an agent may never send a <c>Counter64</c> + object to an SNMPv1 manager. The common practice in these + situations is to simple ignore any <c>Counter64</c> objects, when sending + a reply or a trap to an SNMPv1 manager. For example, if an SNMPv1 + manager tries to GET an object of type <c>Counter64</c>, he will get a + <c>noSuchName</c> error, while an SNMPv2 manager would get a + correct value.</p> + </note> + </section> + + <section> + <title>Operation</title> + <marker id="operations"></marker> + <p>The following steps are needed to get a running agent:</p> + <list type="ordered"> + <item> + <p>Write your MIB in SMI in a text file.</p> + </item> + <item> + <p>Write the instrumentation functions in Erlang and compile them.</p> + </item> + <item> + <p>Put their names in the association file.</p> + </item> + <item> + <p>Run the MIB together with the association file through the + MIB compiler.</p> + </item> + <item> + <p>Configure the application (agent).</p> + </item> + <item> + <p>Start the application (agent).</p> + </item> + <item> + <p>Load the compiled MIB into the agent.</p> + </item> + </list> + <p>The figures in this section illustrate the steps involved in + the development of an SNMP agent.</p> + <marker id="image-1"></marker> + <image file="snmp-um-1-image-1.gif"> + <icaption>MIB Compiler Principles</icaption> + </image> + <p>The compiler parses the SMI file and associates each table or + variable with an instrumentation function (see the figure <seealso marker="#image-1">MIB Compiler Principles</seealso>). The actual + instrumentation functions are not needed at MIB compile time, only + their names. + </p> + <p>The binary output file produced by the compiler is read by the + agent at MIB load time (see the figure <seealso marker="#image-2">Starting the Agent</seealso>). The instrumentation is ordinary Erlang code which + is loaded explicitly or automatically the first time it is called.</p> + <marker id="image-2"></marker> + <image file="snmp-um-1-image-2.gif"> + <icaption>Starting the Agent</icaption> + </image> + <p>The SNMP agent system consists of one Master Agent and optional + sub-agents. The Master Agent can be seen as a special kind of + sub-agent. It implements the core agent functionality, UDP packet + processing, type checking, access control, trap distribution, and + so on. From a user perspective, it is used as an ordinary + sub-agent. + </p> + <p>Sub-agents are only needed if your application requires special + support for distribution from the SNMP toolkit. A sub-agent can + also be used if the application requires a more complex set + transaction scheme than is found in the master agent. + </p> + <p>The following illustration shows how a system can look in runtime.</p> + <marker id="snmp_ch2_fig3"></marker> + <image file="snmp-um-1-image-3.gif"> + <icaption>Architecture</icaption> + </image> + <p>A typical operation could include the following steps:</p> + <list type="ordered"> + <item>The Manager sends a request to the Agent.</item> + <item>The Master Agent decodes the incoming UDP packet.</item> + <item>The Master Agent determines which items in the request + that should be processed here and which items should be + forwarded to its subagent.</item> + <item>Step 3 is repeated by all subagents.</item> + <item>Each sub-agent calls the instrumentation for its loaded MIBs.</item> + <item>The results of calling the instrumentation are propagated + back to the Master Agent.</item> + <item>The answer to the request is encoded to a UDP Protocol + Data Unit (PDU).</item> + </list> + <p>The sequence of steps shown is probably more complex than + normal, but it illustrates the amount of functionality which is + available. The following points should be noted: + </p> + <list type="bulleted"> + <item>An agent can have many MIBs loaded at the same time.</item> + <item>Sub-agents can also have sub-agents. Each sub-agent can have + an arbitrary number of child sub-agents registered, forming a + hierarchy.</item> + <item>One MIB can communicate with many applications.</item> + <item>Instrumentation can use Distributed Erlang to communicate + with an application.</item> + </list> + <p>Most applications only need the Master Agent because an agent + can have multiple MIBs loaded at the same time.</p> + </section> + + <section> + <title>Sub-agents and MIB Loading</title> + <marker id="sub_agent_mib_loading"></marker> + <p>Since applications tend to be transient (they are dynamically + loaded and unloaded), the management of these applications must be + dynamic as well. For example, if we have an equipment MIB for a + rack and different MIBs for boards, which can be installed in the + rack, the MIB for a card should be loaded when the card is + inserted, and unloaded when the card is removed. + </p> + <p>In this agent system, there are two ways to dynamically install + management information. The most common way is to load an MIB into + an agent. The other way is to use a sub-agent, which is controlled + by the application and is able to register and unregister itself. A + sub-agent can register itself for managing a sub-tree (not to be mixed up + with <c>erlang:register</c>). The sub-tree is identified by an + Object Identifier. When a sub-agent is registered, it receives all + requests for this particular sub-tree and it is responsible for + answering them. It should also be noted that a sub-agent can be + started and stopped at any time. + </p> + <p>Compared to other SNMP agent packages, there is a significant + difference in this way of using sub-agents. Other packages normally + use sub-agents to load and unload MIBs in run-time. In Erlang, it is + easy to load code in run-time and it is possible to load an MIB + into an existing sub-agent. It is not necessary to create a new process + for handling a new MIB. + </p> + <p>Sub-agents are used for the following reasons: + </p> + <list type="bulleted"> + <item>to provide a more complex set-transaction scheme than + master agent</item> + <item>to avoid unnecessary process communication</item> + <item>to provide a more lightweight mechanism for loading and + unloading MIBs in run-time</item> + <item>to provide interaction with other SNMP agent toolkits.</item> + </list> + <p>Refer to the chapter + <seealso marker="snmp_advanced_agent">Advanced Agent Topics</seealso> + in this User's Guide for more information about these topics. + </p> + <p>The communication protocol between sub-agents is the normal + message passing which is used in distributed Erlang systems. This + implies that sub-agent communication is very efficient compared to + SMUX, DPI, AgentX, and similar protocols.</p> + </section> + + <section> + <title>Contexts and Communities</title> + <marker id="context_and_communities"></marker> + <p>A context is a collection of management information accessible + by an SNMP entity. An instance of a management object may exist in + more than one context. An SNMP entity potentially has access to + many contexts.</p> + <p>Each managed object can exist in many instances within a + SNMP entity. To identify the instances, specified by an MIB module, + a method to distinguish the actual instance by its 'scope' or + context is used. Often the context is a physical or a logical device. + It can include multiple devices, a subset of a single device or a + subset of multiple devices, but the context is always + defined as a subset of a single SNMP entity. To be able to + identify a specific + item of management information within an SNMP entity, the context, + the object type and its instance must be used.</p> + <p>For example, the managed object type <c>ifDescr</c> from RFC1573, is + defined as the description of a network interface. To identify + the description of device-X's first network interface, four pieces + of information are needed: the snmpEngineID of the SNMP entity + which provides access to the management information at device-X, + the <c>contextName</c> (device-X), the managed object type + (<c>ifDescr</c>), and the instance ("1"). + </p> + <p>In SNMPv1 and SNMPv2c, the community string in the message was + used for (at least) three different purposes: + </p> + <list type="bulleted"> + <item> + <p>to identify the context</p> + </item> + <item> + <p>to provide authentication</p> + </item> + <item> + <p>to identify a set of trap targets</p> + </item> + </list> + <p>In SNMPv3, each of these usage areas has its own unique + mechanism. A context is identified by the name of the SNMP + entity, <c>contextEngineID</c>, and the name of the context, + <c>contextName</c>. Each SNMPv3 message contains values for these + two parameters. + </p> + <p>There is a MIB, SNMP-COMMUNITY-MIB, which maps a community + string to a <c>contextEngineID</c> and <c>contextName</c>. Thus, + each message, an SNMPv1, SNMPv2c or an SNMPv3 message, always + uniquely identifies a context. + </p> + <p>For an agent, the <c>contextEngineID</c> identified by a received + message, is always equal to the <c>snmpEngineID</c> of the agent. + Otherwise, the message was not intended for the agent. If the + agent is configured with more than one context, the + instrumentation code must be able to figure out for which context + the request was intended. There is a function + <c>snmpa:current_context/0</c> provided for this purpose. + </p> + <p>By default, the agent has no knowledge of any other contexts + than the default context, <c>""</c>. If it is to support more + contexts, these must be explicitly added, by using an appropriate + configuration file + <seealso marker="snmp_agent_config_files">Agent Configuration Files</seealso>. + </p> + </section> + + <section> + <title>Management of the Agent</title> + <marker id="management"></marker> + <p>There is a set of standard MIBs, which are used to control and + configure an SNMP agent. All of these MIBs, with the exception of + the optional SNMP-PROXY-MIB (which is only used for proxy agents), + are implemented in this agent. Further, it is configurable which + of these MIBs are actually loaded, and thus made visible to SNMP + managers. For example, in a non-secure environment, it might be a + good idea to not make MIBs that define access control visible. + Note, the data the MIBs define is used internally in the + agent, even if the MIBs not are loaded. This chapter describes + these standard MIBs, and some aspects of their implementation. + </p> + <p>Any SNMP agent must implement the <c>system</c> group and the + <c>snmp</c> group, defined in MIB-II. The definitions of these + groups have changed from SNMPv1 to SNMPv2. MIBs and implementations + for both of these versions are Provided in the + distribution. The MIB file for SNMPv1 is called STANDARD-MIB, and the + corresponding for SNMPv2 is called SNMPv2-MIB. If the agent is + configured for SNMPv1 only, the STANDARD-MIB is loaded by default; + otherwise, the SNMPv2-MIB is loaded by default. It is possible to + override this default behavior, by explicitly loading another + version of this MIB, for example, you could choose to implement + the union of all objects in these two MIBs. + </p> + <p>An SNMPv3 agent must implement the SNMP-FRAMEWORK-MIB and + SNMP-MPD-MIB. These MIBs are loaded by default, if the agent is + configured for SNMPv3. These MIBs can be loaded for other + versions as well. + </p> + <p>There are five other standard MIBs, which also may be loaded + into the agent. These MIBs are: + </p> + <list type="bulleted"> + <item> + <p>SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB, which defines + managed objects for configuration of management targets, + i.e. receivers of notifications (traps and informs). These + MIBs can be used with any SNMP version. + </p> + </item> + <item> + <p>SNMP-VIEW-BASED-ACM-MIB, which defined managed objects + for access control. This MIB can be used with any SNMP + version. + </p> + </item> + <item> + <p>SNMP-COMMUNITY-MIB, which defines managed objects for + coexistence of SNMPv1 and SNMPv2c with SNMPv3. This MIB is + only useful if SNMPv1 or SNMPv2c is used, possibly in + combination with SNMPv3. + </p> + </item> + <item> + <p>SNMP-USER-BASED-SM-MIB, which defines managed objects + for authentication and privacy. This MIB is only useful + with SNMPv3. + </p> + </item> + </list> + <p>All of these MIBs should be loaded into the Master Agent. Once + loaded, these MIBs are always available in all contexts. + </p> + <p>The ASN.1 code, the Erlang source code, and the generated + <c>.hrl</c> files for them are provided in the distribution and are + placed in the directories <c>mibs</c>, <c>src</c>, and <c>include</c>, + respectively, in the <c>snmp</c> application. + </p> + <p>The <c>.hrl</c> files are generated with + <c>snmpc:mib_to_hrl/1</c>. Include these files in your code as in + the following example: + </p> + <code type="none"> +-include_lib("snmp/include/SNMPv2-MIB.hrl"). + </code> + <p>The initial values for the managed objects defined in these + tables, are read at start-up from a set of configuration files. + These are described in <seealso marker="snmp_config">Configuration Files</seealso>. + </p> + + <section> + <title>STANDARD-MIB and SNMPv2-MIB</title> + <p>These MIBs contain the <c>snmp-</c> and <c>system</c> groups + from MIB-II which is defined in RFC1213 (STANDARD-MIB) or + RFC1907 (SNMPv2-MIB). They are implemented in the + <c>snmp_standard_mib</c> module. The <c>snmp</c> counters all + reside in volatile memory and the <c>system</c> and + <c>snmpEnableAuthenTraps</c> variables in persistent memory, + using the SNMP built-in database (refer to the Reference Manual, + section <c>snmp</c>, module <c>snmpa_local_db</c> for more + details).</p> + <p>If another implementation of any of these variables is needed, + e.g. to store the persistent variables in a Mnesia database, + an own implementation of the variables must be made. That MIB + will be compiled and loaded instead of the default MIB. + The new compiled MIB + must have the same name as the original MIB (i.e. STANDARD-MIB + or SNMPv2-MIB), and be located in the SNMP configuration + directory (see <seealso marker="snmp_config">Configuration Files</seealso>.) + </p> + <p>One of these MIBs is always loaded. If only SNMPv1 is used, + STANDARD-MIB is loaded, otherwise SNMPv2-MIB is loaded. + </p> + + <section> + <title>Data Types</title> + <p>There are some new data types in SNMPv2 that are useful in + SNMPv1 as well. In the STANDARD-MIB, three data types are + defined, <c>RowStatus</c>, <c>TruthValue</c> and + <c>DateAndTime</c>. These data types are originally defined + as textual conventions in SNMPv2-TC (RFC1903). + </p> + </section> + </section> + + <section> + <title>SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB</title> + <p>The SNMP-FRAMEWORK-MIB and SNMP-MPD-MIB define additional + read-only managed objects, which + is used in the generic SNMP framework defined in RFC2271 and the + generic message processing and dispatching module defined in + RFC2272. They are generic in the sense that they are not tied + to any specific SNMP version. + </p> + <p>The objects in these MIBs are implemented in the modules + <c>snmp_framework_mib</c> and <c>snmp_standard_mib</c>, + respectively. All objects reside in volatile memory, and the + configuration files are always reread at start-up. + </p> + <p>If SNMPv3 is used, these MIBs are loaded by default. + </p> + </section> + + <section> + <title>SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB</title> + <p>The SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB define managed + objects for configuration of notification receivers. They + are described in detail in RFC2273. Only a brief description + is given here. + </p> + <p>All tables in these MIBs have a column of type + <c>StorageType</c>. The value of this column specifies how each + row is stored, and what happens in case of a restart of the + agent. The implementation supports the values <c>volatile</c> + and <c>nonVolatile</c>. When the tables are initially filled + with data from the configuration files, these rows will + automatically have storage type <c>nonVolatile</c>. Should the + agent restart, all <c>nonVolatile</c> rows survive the restart, + while the <c>volatile</c> rows are lost. + The configuration files are not read at restart, by default. + </p> + <p>These MIBs are not loaded by default. + </p> + + <section> + <title>snmpNotifyTable</title> + <p>An entry in the <c>snmpNotifyTable</c> selects a set + of management targets, which should receive notifications, + as well as the type (trap or inform) of notification that + should be sent to each selected management target. + When an application sends a notification using + the function <c>send_notification/5</c> or the function + <c>send_trap</c> the parameter <c>NotifyName</c>, specified in + the call, is used as an index in the table. The notification + is sent to the management targets selected by that entry. + </p> + </section> + + <section> + <title>snmpTargetAddrTable</title> + <p>An entry in the <c>snmpTargetAddrTable</c> defines + transport parameters (such as + IP address and UDP port) for each management target. Each row + in the <c>snmpNotifyTable</c> refers to potentially many rows + in the <c>snmpTargetAddrTable</c>. Each row in the + <c>snmpTargetAddrTable</c> + refers to an entry in the <c>snmpTargetParamsTable</c>. + </p> + </section> + + <section> + <title>snmpTargetParamsTable</title> + <p>An entry in the <c>snmpTargetParamsTable</c> defines + which SNMP version to use, and which security parameters to use. + </p> + <p>Which SNMP version to use is implicitly defined by + specifying the Message Processing Model. This version of the + agent handles the models <c>v1</c>, <c>v2c</c> and <c>v3</c>. + </p> + <p>Each row specifies which security model to use, along with + security level and security parameters. + </p> + </section> + </section> + + <section> + <title>SNMP-VIEW-BASED-ACM-MIB</title> + <p>The SNMP-VIEW-BASED-ACM-MIB defines managed objects to + control access to the the managed objects for the managers. + The View Based Access Control Module (VACM) can be used with + any SNMP version. However, if it is used with SNMPv1 or SNMPv2c, + the SNMP-COMMUNITY-MIB defines additional objects to map + community strings to VACM parameters. + </p> + <p>All tables in this MIB have a column of type <c>StorageType</c>. + The value of this column specifies how each + row is stored, and what happens in case of a restart of the + agent. The implementation supports the values <c>volatile</c> + and <c>nonVolatile</c>. When the tables are initially filled + with data from the configuration files, these rows will + automatically have storage type <c>nonVolatile</c>. Should the + agent restart, all <c>nonVolatile</c> rows survive the restart, + while the <c>volatile</c> rows are lost. + The configuration files are not read at restart by default. + </p> + <p>This MIB is not loaded by default. + </p> + <p>VACM is described in detail in RFC2275. Here is only a brief + description given. + </p> + <p>The basic concept is that of a <em>MIB view</em>. An MIB view + is a subset of all the objects implemented by an agent. A + manager has access to a certain MIB view, depending on which + security parameters are used, in which context the request is + made, and which type of request is made. + </p> + <p>The following picture gives an overview of the mechanism to + select an MIB view:</p> + <image file="MIB_mechanism.gif"> + <icaption>Overview of the mechanism of MIB selection</icaption> + </image> + + <section> + <title>vacmContextTable</title> + <p>The <c>vacmContextTable</c> is a read-only table that lists all + available contexts. + </p> + </section> + + <section> + <title>vacmSecurityToGroupTable</title> + <p>The <c>vacmSecurityToGroupTable</c> maps a <c>securityModel</c> + and a + <c>securityName</c> to a <c>groupName</c>. + </p> + </section> + + <section> + <title>vacmAccessTable</title> + <p>The <c>vacmAccessTable</c> maps the <c>groupName</c> (found in + <c>vacmSecurityToGroupTable</c>), <c>contextName</c>, + <c>securityModel</c>, and <c>securityLevel</c> to an MIB view + for each type of operation (read, write, or notify). The MIB + view is represented as a <c>viewName</c>. The definition of + the MIB view represented by the <c>viewName</c> is found in + the <c>vacmViewTreeFamilyTable</c></p> + </section> + + <section> + <title>vacmViewTreeFamilyTable</title> + <p>The <c>vacmViewTreeFamilyTable</c> is indexed by the + <c>viewName</c>, and defines + which objects are included in the MIB view. + </p> + <p>The MIB definition for the table looks as follows:</p> + <pre> +VacmViewTreeFamilyEntry ::= SEQUENCE + { + vacmViewTreeFamilyViewName SnmpAdminString, + vacmViewTreeFamilySubtree OBJECT IDENTIFIER, + vacmViewTreeFamilyMask OCTET STRING, + vacmViewTreeFamilyType INTEGER, + vacmViewTreeFamilyStorageType StorageType, + vacmViewTreeFamilyStatus RowStatus + } + +INDEX { vacmViewTreeFamilyViewName, + vacmViewTreeFamilySubtree + } + </pre> + <p>Each <c>vacmViewTreeFamilyViewName</c> refers to a + collection of sub-trees. + </p> + + <section> + <title>MIB View Semantics</title> + <p>An MIB view is a collection of included and excluded + sub-trees. A sub-tree is identified by an OBJECT IDENTIFIER. A + mask is associated with each sub-tree. + </p> + <p>For each possible MIB object instance, the instance + belongs to a sub-tree if: + </p> + <list type="bulleted"> + <item>the OBJECT IDENTIFIER name of that MIB object + instance comprises at least as many sub-identifiers as + does the sub-tree, and + </item> + <item>each sub-identifier in the name of that MIB object + instance matches the corresponding sub-identifier of the + sub-tree whenever the corresponding bit of the associated + mask is 1 (0 is a wild card that matches anything).</item> + </list> + <p>Membership of an object instance in an MIB view is + determined by the following algorithm: + </p> + <list type="bulleted"> + <item>If an MIB object instance does not belong to any of + the relevant sub-trees, then the instance is not in the + MIB view. + </item> + <item>If an MIB object instance belongs to exactly one + sub-tree, then the instance is included in, or excluded + from, the relevant MIB view according to the type of + that entry. + </item> + <item>If an MIB object instance belongs to more than one + sub-tree, then the sub-tree which comprises the greatest + number of sub-identifiers, and is the lexicographically + greatest, is used. + </item> + </list> + <note> + <p>If the OBJECT IDENTIFIER is longer than an OBJECT + IDENTIFIER of an object type in the MIB, it refers to + object instances. Because of this, it is possible to + control whether or not particular rows in a table shall be + visible.</p> + </note> + </section> + </section> + </section> + + <section> + <title>SNMP-COMMUNITY-MIB</title> + <p>The SNMP-COMMUNITY-MIB defines managed objects that is used + for coexistence between SNMPv1 and SNMPv2c with SNMPv3. + Specifically, it contains objects for mapping between community + strings and version-independent SNMP message parameters. In + addition, this MIB provides a mechanism for performing source address + validation on incoming requests, and for selecting community + strings based on target addresses for outgoing notifications. + </p> + <p>All tables in this MIB have a column of type + <c>StorageType</c>. The value of this column specifies how each + row is stored, and what happens in case of a restart of the + agent. The implementation supports the values <c>volatile</c> + and <c>nonVolatile</c>. When the tables are initially filled + with data from the configuration files, these rows will + automatically have storage type <c>nonVolatile</c>. Should the + agent restart, all <c>nonVolatile</c> rows survive the restart, + while the <c>volatile</c> rows are lost. + The configuration files are not read at restart, by default. + </p> + <p>This MIB is not loaded by default. + </p> + </section> + + <section> + <title>SNMP-USER-BASED-SM-MIB</title> + <p>The SNMP-USER-BASED-SM-MIB defines managed objects that is + used for the User-Based Security Model. + </p> + <p>All tables in this MIB have a column of type + <c>StorageType</c>. The value of the column specifies how each + row is stored, and what happens in case of a restart of the + agent. The implementation supports the values <c>volatile</c> + and <c>nonVolatile</c>. When the tables are initially filled + with data from the configuration files, these rows will + automatically have storage type <c>nonVolatile</c>. Should the + agent restart, all <c>nonVolatile</c> rows survive the restart, + while the <c>volatile</c> rows are lost. + The configuration files are not read at restart, by default. + </p> + <p>This MIB is not loaded by default. + </p> + </section> + + <section> + <title>OTP-SNMPEA-MIB</title> + <p>The OTP-SNMPEA-MIB was used in earlier versions of the agent, before + standard MIBs existed for access control, MIB views, and trap + target specification. All objects in this MIB are now obsolete. + </p> + </section> + </section> + + <section> + <title>Notifications</title> + <marker id="notifications"></marker> + <p>Notifications are defined in SMIv1 with the TRAP-TYPE macro in + the definition of an MIB (see RFC1215). The corresponding + macro in SMIv2 is NOTIFICATION-TYPE. When an application + decides to send a notification, it calls one of the following + functions: + </p> + <code type="none"> +snmpa:send_notification(Agent, Notification, Receiver + [, NotifyName, ContextName, Varbinds]) +snmpa:send_trap(Agent, Notification, Community [, Receiver, Varbinds]) + </code> + <p>providing the registered name or process identifier of the + agent where the MIB, which defines the notification is loaded and + the symbolic name of the notification. + </p> + <p>If the <c>send_notification/3,4</c> function is used, all + management targets are selected, as defined in RFC2273. The + <c>Receiver</c> parameter defines where the agent should send + information about the delivery of inform requests. + </p> + <p>If the <c>send_notification/5</c> function is used, an + <c>NotifyName</c> must be provided. This parameter is used as an + index in the <c>snmpNotifyTable</c>, and the management targets + defined by that single entry is used. + </p> + <p>The <c>send_notification/6</c> function is the most general + version of the function. A <c>ContextName</c> must be specified, + from which the notification will be sent. If this parameter is + not specified, the default context (<c>""</c>) is used. + </p> + <p>The function <c>send_trap</c> is kept for backwards + compatibility and should not be used in new code. Applications + that use this function will + continue to work. The <c>snmpNotifyName</c> is used as the + community string by the agent when a notification is sent. + </p> + + <section> + <title>Notification Sending</title> + <p>The simplest way to send a notification is to call the function + <c>snmpa:send_notification(Agent, Notification, no_receiver)</c>. + In this case, the agent performs a get-operation to retrieve the + object values that are defined in the notification + specification (with the TRAP-TYPE or NOTIFICATION-TYPE macros). + The notification is sent to all managers defined in the target + and notify tables, either unacknowledged as traps, or + acknowledged as inform requests. + </p> + <p>If the caller of the function wants to know whether or not + acknowledgments are received for a certain notification + (provided it is sent as an inform), the <c>Receiver</c> + parameter can be specified as <c>{Tag, ProcessName}</c> (refer + to the Reference Manual, section snmp, module <c>snmp</c> for + more details). In this case, the agent send a message + <c>{snmp_notification, Tag, {got_response, ManagerAddr}}</c> or + <c>{snmp_notification, Tag, {no_response, ManagerAddr}}</c> for + each management target. + </p> + <p>Sometimes it is not possible to retrieve the values for some + of the objects in the notification specification with a + get-operation. However, they are known when the + <c>send_notification</c> function is called. This is the case if + an object is an element in a table. It is possible to give the + values of some objects to the <c>send_notification</c> function + <c>snmpa:send_notification(Agent, Notification, Receiver, Varbinds)</c>. In this function, <c>Varbinds</c> is a list of + <c>Varbind</c>, where each <c>Varbind</c> is one of: + </p> + <list type="bulleted"> + <item><c>{Variable, Value}</c>, where <c>Variable</c> is the + symbolic name of a scalar variable referred to in the notification + specification. + </item> + <item><c>{Column, RowIndex, Value}</c>, where <c>Column</c> is + the symbolic name of a column variable. <c>RowIndex</c> is a + list of indices for the specified element. If this is the + case, the OBJECT IDENTIFIER sent in the trap is the + <c>RowIndex</c> appended to the OBJECT IDENTIFIER for the + table column. This is the OBJECT IDENTIFIER which specifies + the element. + </item> + <item><c>{OID, Value}</c>, where <c>OID</c> is the OBJECT + IDENTIFIER for an instance of an object, scalar variable or + column variable. + </item> + </list> + <p>For example, to specify that <c>sysLocation</c> should have the + value <c>"upstairs"</c> in the notification, we could use one of: + </p> + <list type="bulleted"> + <item><c>{sysLocation, "upstairs"}</c> or</item> + <item><c>{[1,3,6,1,2,1,1,6,0], "upstairs"}</c></item> + </list> + <p>It is also possible to specify names and values for extra + variables that should be sent in the notification, but were not + defined in the notification specification. + </p> + <p>The notification is sent to all management targets found in + the tables. However, make sure that each manager has access to + the variables in the notification. If a variable is outside a + manager's MIB view, this manager will not receive the + notification. + </p> + <note> + <p>By definition, it is not possible to send objects with + ACCESS <c>not-accessible</c> in notifications. However, + historically this is often done and for this reason we allow + it in notification sending. If a variable has ACCESS + <c>not-accessible</c>, the user must provide a value for the + variable in the <c>Varbinds</c> list. It is not possible for + the agent to perform a get-operation to retrieve this value. + </p> + </note> + </section> + + <section> + <title>Notification Filters</title> + <p>It is possible to add <em>notification filters</em> to an agent. + These filters will be called when a notification is to be + sent. Their purpose is to allow modification, suppression or + other type of actions.</p> + <p>A notification filter is a module implementing the + <seealso marker="snmpa_notification_filter">snmpa_notification_filter</seealso> behaviour. A filter is added/deleted using the functions: + <seealso marker="snmpa#register_notification_filter">snmpa:register_notification_filter</seealso> and + <seealso marker="snmpa#unregister_notification_filter">snmpa:unregister_notification_filter</seealso>.</p> + <p>Unless otherwise specified, the order of the registered filters + will be the order in which they are registered.</p> + </section> + + <section> + <title>Sub-agent Path</title> + <p>If a value for an object is not given to the + <c>send_notification</c> function, the sub-agent will perform a + get-operation to retrieve it. If the object is not implemented + in this sub-agent, its parent agent tries to perform a + get-operation to retrieve it. If the object is not implemented + in this agent either, it forwards the object to its parent, and + so on. Eventually the Master Agent is reached and at this point + all unknown object values must be resolved. If some object is + unknown even to the Master Agent, this is regarded as an error + and is reported with a call to <c>user_err/2</c> of the + error report module. No notifications are sent in this case. + </p> + <p>For a given notification, the variables, which are referred to + in the notification specification, must be implemented by the + agent that has the MIB loaded, or by some parent to this + agent. If not, the application must provide values for the + unknown variables. The application must also provide values for + all elements in tables. + </p> + </section> + </section> + + <section> + <title>Discovery</title> + <marker id="discovery"></marker> + <p>The <em>sender</em> is <em>authoritative</em> for messages containing + payload which does <em>not</em> expect a response (for example + SNMPv2-Trap, Response or Report PDU). </p> + <p>The <em>receiver</em> is <em>authoritative</em> for messages containing + payload which expects a response (for example + Get, GetNext, Get-Bulk, Set or Inform PDU). </p> + <p>The agent can both perform and respond to discovery.</p> + <p>The agent responds to discovery autonomously, without interaction + by the user. </p> + <p>Initiating discovery towards a manager is done by calling the + <seealso marker="snmpa#discovery">discovery</seealso> function. + The <c>EngineId</c> field of the target (manager) entry in the + <seealso marker="snmp_agent_config_files#target_addr">target_addr.conf</seealso> file has to have the value <c>discovery</c>. + Note that if the manager does not respond, the <c>Timeout</c> and + <c>RetryCount</c> + fields decide how long the function will hang before it returns. </p> + <p>Discovery can only be performed towards one manager at a time.</p> + </section> + +</chapter> + |