The R13B03 release.OTP_R13B03

1 files changed, 269 insertions, 0 deletions

diff --git a/system/doc/oam/oam_intro.xml b/system/doc/oam/oam_intro.xml
new file mode 100644
index 0000000000..bd7369b84c
--- /dev/null
+++ b/system/doc/oam/oam_intro.xml
@@ -0,0 +1,269 @@
+<?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>Introduction</title>
+    <prepared>Martin Bj&ouml;rklund</prepared>
+    <docno></docno>
+    <date>1997-11-01</date>
+    <rev>A</rev>
+    <file>oam_intro.xml</file>
+  </header>
+  <p>The operation and maintenance support in OTP consists of a
+    generic model for management subsystems in OTP, and some
+    components to be used in these subsystems.  This document
+    describes the model.
+    </p>
+  <p>The main idea in the model is that it is management protocol
+    independent.  Thus, it is not tied to any specific management
+    protocol.  An API is defined which can be used to write
+    adaptations for specific management protocols.
+    </p>
+  <p>Each OAM component in OTP is implemented as one sub application,
+    which can be included in a management application for the system.
+    Note that such a complete management application is not in the
+    scope of this generic functionality.  Examples illustrating how such an
+    application can be built are included however.
+    </p>
+
+  <section>
+    <title>Terminology</title>
+    <p>The protocol independent architectural model on the network
+      level is the well-known <term id="Manager-Agent       model"><termdef>Client-Server model for management operations</termdef></term>.  This model is based on the client-server
+      principle, where the manager (client) sends <term id="requests"><termdef>A request is sent from a manager to an agent when it accesses management information.</termdef></term>to the
+      agent (server), the agent sends <term id="replies"><termdef>A reply is sent from the agent as a response to a request from a manager.</termdef></term>back to the manager.  There are two main
+      differences to the normal client-server model.  First, there are
+      usually a few managers that communicate with many agents; and
+      second, the agent may spontaneously send <term id="notifications"><termdef>A notification is sent spontaneously from an agent to a manager, e.g. an alarm.</termdef></term>to the
+      manager.  The picture below illustrates the idea.</p>
+    <image file="../oam/terminology.gif">
+      <icaption>Terminology</icaption>
+    </image>
+    <p>The manager is often referred to as the <term id="NMS"></term>, to
+      emphasize that it usually is realized as a program that presents
+      data to an operator.
+      </p>
+    <p>The agent is an entity that executes within a <term id="NE"></term>.
+      In OTP, the network element may be a distributed system, meaning
+      that the distributed system is managed as one entity.  Of
+      course, the agent may be configured to be able to run on one of
+      several nodes, making it a distributed OTP application.
+      </p>
+    <p>The management information is defined in an <term id="MIB"></term>.
+      It is a formal definition of which information the agent makes
+      available to the manager.  The manager accesses the MIB through
+      a management protocol, such as SNMP, CMIP, HTTP or CORBA.  Each
+      of these protocols have their own MIB definition language.  In
+      SNMP, it is a subset of ASN.1, in CMIP it is GDMO, in HTTP it is
+      implicit, and using CORBA, it is IDL.  Usually, the entities
+      defined in the MIB are called <term id="MO"></term>, although these
+      objects do not have to be objects in the OO way,for example, a simple
+      scalar variable defined in an MIB is called a Managed Object.
+      The Managed Objects are logical objects, not necessarily with a
+      one-to-one mapping to the resources.
+      </p>
+  </section>
+
+  <section>
+    <title>Model</title>
+    <p>In this section, the generic protocol independent model for use
+      within an OTP based network element is presented.  This model is
+      used by all operation and maintenance components, and may be
+      used by the applications.  The advantage of the model is that it
+      clearly separates the resources from the management protocol.
+      The resources do not need to be aware of which management
+      protocol is used to manage the system.  This makes it possible
+      to manage the same resources with different protocols.
+      </p>
+    <p>The different entities involved in this model are the <term id="agent"></term>which terminates the management protocol, and the
+      <term id="resources"></term>which is to be managed, i.e. the actual
+      application entities.  The resources should in general have no
+      knowledge of the management protocol used, and the agent should
+      have no knowledge of the managed resources.  This implies that
+      some sort of translation mechanism must be used, to translate
+      the management operations to operations on the resources.  This
+      translation mechanism is usually called
+      <em>instrumentation</em>, and the function that implements it is
+      called <term id="instrumentation function"></term>.  The
+      instrumentation functions are written for each combination of
+      management protocol and resource to be managed.  For example, if
+      an application is to be managed by SNMP and HTTP, two sets of
+      instrumentation functions are defined; one that maps SNMP
+      requests to the resources, and one that e.g. generates an HTML
+      page for some resources.
+      </p>
+    <p>When a manager makes a request to the agent, we have the
+      following picture:</p>
+    <image file="../oam/snmp_model_1.gif">
+      <icaption>Request to an agent by a manager</icaption>
+    </image>
+    <p>Note that the mapping between instrumentation function and
+      resource is not necessarily 1-1.  It is also possible to write
+      one instrumentation function for each resource, and use that
+      function from different protocols.
+      </p>
+    <p>The agent receives a request and maps this request to calls to
+      one or several instrumentation functions.  The instrumentation
+      functions perform operations on the resources to implement the
+      semantics associated with the managed object.
+      </p>
+    <p>For example, a system that is managed with SNMP and HTTP may be
+      structured in the following way:</p>
+    <image file="../oam/snmp_model_2.gif">
+      <icaption>Structure of a system managed with SNMP and HTTP</icaption>
+    </image>
+    <p>The resources may send notifications to the manager as well.
+      Examples of notifications are events and alarms.  There is a
+      need for the resource to generate protocol independent
+      notifications.  The following picture illustrates how this is
+      achieved:</p>
+    <image file="../oam/snmp_model_3.gif">
+      <icaption>Notification handling</icaption>
+    </image>
+    <p>The main idea is that the resource sends the notfications as
+      Erlang terms to a dedicated <c>gen_event</c> process.  Into this
+      process, handlers for the different management protocols are
+      installed.  When an event is received by this process, it is
+      forwarded to each installed handler.  The handlers are
+      responsible for translating the event into a notification to be
+      sent over the management protocol.  For example, a handler for
+      SNMP would translate each event into an SNMP trap.
+      </p>
+  </section>
+
+  <section>
+    <title>SNMP based OAM</title>
+    <p>For all OAM components, SNMP adaptations are provided.  Other
+      adaptations may be defined in the future.
+      </p>
+    <p>The OAM components, and some other OTP applications, define
+      SNMP MIBs.  All these MIBs are written in SNMPv2 SMI syntax, as
+      defined in RFC1902.  For convenience we also deliver the SNMPv1
+      SMI equivalent.  All MIBs are designed to be v1/v2 compatible,
+      i.e. the v2 MIBs do not use any construct not available in v1.
+      </p>
+
+    <section>
+      <title>MIB structure</title>
+      <p>The top-level OTP MIB is called <c>OTP-REG</c>, and it is
+        included in the <c>sasl</c> application.  All other OTP mibs
+        import some objects from this MIB.
+        </p>
+      <p>Each MIB is contained in one application.  The MIB text files
+        are stored under <c><![CDATA[mibs/<MIB>.mib]]></c> in the application
+        directory. The generated <c>.hrl</c> files with constant
+        declarations are stored under <c><![CDATA[include/<MIB>.hrl]]></c>, and
+        the compiled MIBs are stored under
+        <c><![CDATA[priv/mibs/<MIB>.bin]]></c>.  For example, the <c>OTP-MIB</c>
+        is included in the <c>sasl</c> application:
+        </p>
+      <code type="none">
+sasl-1.3/mibs/OTP-MIB.mib
+         include/OTP-MIB.hrl
+         priv/mibs/OTP-MIB.bin</code>
+      <p>An application that needs to IMPORT this mib into another
+        MIB, should use the <c>il</c> option to the snmp mib compiler:
+        </p>
+      <code type="none">
+snmp:c("MY-MIB", [{il, ["sasl/priv/mibs"]}]).</code>
+      <p>If the application needs to include the generated
+        <c>.hrl</c> file, it should use the <c>-include_lib</c>
+        directive to the Erlang compiler.
+        </p>
+      <code type="none">
+-module(my_mib).
+
+-include_lib("sasl/include/OTP-MIB.hrl").</code>
+      <p>The following MIBs are defined in the OTP system:
+        </p>
+      <taglist>
+        <tag>OTP-REG  (sasl)</tag>
+        <item>
+          <p>This MIB contains the top-level OTP registration
+            objects, used by all other MIBs.
+            </p>
+        </item>
+        <tag>OTP-TC  (sasl)</tag>
+        <item>
+          <p>This MIB contains the general Textual Conventions,
+            which can be used by any other MIB.
+            </p>
+        </item>
+        <tag>OTP-MIB  (sasl)</tag>
+        <item>
+          <p>This MIB contains objects for instrumentation of the
+            Erlang nodes, the Erlang machines and the applications in
+            the system.
+            </p>
+        </item>
+        <tag>OTP-OS-MON-MIB  (os_mon)</tag>
+        <item>
+          <p>This MIB contains objects for instrumentation of disk,
+            memory and cpu usage of the nodes in the system.
+            </p>
+        </item>
+        <tag>OTP-SNMPEA-MIB  (snmp)</tag>
+        <item>
+          <p>This MIB contains objects for instrumentation and
+            control of the extensible snmp agent itself.  Note that
+            the agent also implements the standard SNMPv2-MIB (or v1
+            part of MIB-II, if SNMPv1 is used).
+            </p>
+        </item>
+        <tag>OTP-EVA-MIB  (eva)</tag>
+        <item>
+          <p>This MIB contains objects for instrumentation and
+            control of the events and alarms in the system.
+            </p>
+        </item>
+        <tag>OTP-LOG-MIB  (eva)</tag>
+        <item>
+          <p>This MIB contains objects for instrumentation and
+            control of the logs and FTP transfer of logs.
+            </p>
+        </item>
+        <tag>OTP-EVA-LOG-MIB  (eva)</tag>
+        <item>
+          <p>This MIB contains objects for instrumentation and
+            control of the events and alarm logs in the system.
+            </p>
+        </item>
+        <tag>OTP-SNMPEA-LOG-MIB  (eva)</tag>
+        <item>
+          <p>This MIB contains objects for instrumentation and
+            control of the snmp audit trail log in the system.
+            </p>
+        </item>
+      </taglist>
+      <p>The different applications use different strategies for
+        loading the MIBs into the agent.  Some MIB implementations are
+        code-only, while others need a server.  One way, used by the
+        code-only mib implementations, is for the user to call a
+        function such as <c>otp_mib:init(Agent)</c> to load the MIB,
+        and <c>otp_mib:stop(Agent)</c> to unload the MIB.  See the
+        application manual page for each application for a description
+        of how to load each MIB.
+        </p>
+    </section>
+  </section>
+</chapter>
+