Update OAM Principles

Language cleaned up by the technical writers xsipewe and tmanevik
from Combitech. Proofreading and corrections by Björn Gustavsson.

1 files changed, 187 insertions, 204 deletions

diff --git a/system/doc/oam/oam_intro.xml b/system/doc/oam/oam_intro.xml
index f4f990393e..de4867ca16 100644
--- a/system/doc/oam/oam_intro.xml
+++ b/system/doc/oam/oam_intro.xml
@@ -28,241 +28,224 @@
     <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>
+  <marker id="oam principles"></marker>
+  <p>The Operation and Maintenance (OAM) support in OTP consists of a
+  generic model for management subsystems in OTP, and some components
+  to be used in these subsystems. This section describes the model.</p>
+
+  <p>The main idea in the model is that it is not tied to any specific
+  management protocol. An Application Programming Interface (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. Notice that
+  such a complete management application is not in the scope of this
+  generic functionality. However, this section includes examples
+  illustrating how such an application can be built.</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>
+    <p>The protocol-independent architectural model on the network level
+    is the well-known client-server model for management operations. This
+    model is based on the client-server principle, where the manager
+    (client) sends a request from a manager to an agent (server) when it
+    accesses management information. The agent sends a reply back to the
+    manager. There are two main differences to the normal
+    client-server model:</p>
+    <list type="bulleted">
+      <item><p>Usually a few managers communicate with many agents.</p></item>
+      <item><p>The agent can spontaneously send a notification, for example,
+      an alarm, to the manager.</p></item>
+    </list>
+    <p>The following picture 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>
+
+    <p>The manager is often referred to as the <em>Network Management
+    System (NMS)</em>, 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 <em>Network
+    Element (NE)</em>. In OTP, the NE can be a distributed system,
+    meaning that the distributed system is managed as one entity.
+    Of course, the agent can 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 a <em>Management
+    Information Base (MIB)</em>. 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 protocol has its 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.</p>
+
+    <p>Usually, the entities defined in the MIB are
+    called <em>Managed Objects (MOs)</em>, although they do not
+    have to be objects in the object-oriented way. For example,
+    a simple scalar variable defined in a MIB is called an MO. The
+    MOs 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>
+    <p>This section presents the generic protocol-independent model
+    for use within an OTP-based NE. This model is used by
+    all OAM components and can 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. The same resources can therefore be managed with
+    different protocols.</p>
+
+    <p>The entities involved in this model are the agent, which
+    terminates the management protocol, and the resources, which
+    is to be managed, that is, 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 a
+    translation mechanism is needed, 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 <em>instrumentation
+    function</em>. 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, for example, generates an HTML page for some
+    resources.</p>
+
+    <p>When a manager makes a request to the agent, the following
+    illustrates the situation:</p>
+
     <image file="../oam/snmp_model_1.gif">
-      <icaption>Request to an agent by a manager</icaption>
+      <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>
+
+    <p>The mapping between an instrumentation function and a
+    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 it to calls to one or
+    more instrumentation functions. These functions perform
+    operations on the resources to implement the semantics
+    associated with the MO.</p>
+
+    <p>For example, a system that is managed with SNMP and HTTP
+    can be structured as follows:</p>
+
     <image file="../oam/snmp_model_2.gif">
-      <icaption>Structure of a system managed with SNMP and HTTP</icaption>
+      <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>
+
+    <p>The resources can send notifications to the manager as well.
+    Examples of notifications are events and alarms. The resource
+    needs 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>
+      <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>
+
+    <p>The main idea is that the resource sends the notifications 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 translates 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>
+    <title>SNMP-Based OAM</title>
+    <p>For all OAM components, SNMP adaptations are provided. Other
+    adaptations might 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>
+    SNMP MIBs. These MIBs are written in SNMPv2 SMI syntax, as
+    defined in RFC 1902. For convenience we also deliver the SNMPv1
+    SMI equivalent. All MIBs are designed to be v1/v2 compatible,
+    that is, 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>
+      <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>
+include/OTP-MIB.hrl
+priv/mibs/OTP-MIB.bin</code>
+
+      <p>An application that needs to import this MIB into another
+      MIB is to 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>
+      <c>.hrl</c> file, it is to 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 following MIBs are defined in the OTP system:</p>
+      <list type="bulleted">
+	<item><p><c>OTP-REG)</c> (in <c>sasl</c>) contains the top-level
+	OTP registration objects, used by all other MIBs.</p></item>
+	<item><p><c>OTP-TC</c> (in <c>sasl</c>) contains the general
+	Textual Conventions, which can be used by any other MIB.</p></item>
+	<item><p><c>OTP-MIB</c> (in <c>sasl</c>) contains objects for
+	instrumentation of the Erlang nodes, the Erlang machines,
+	and the applications in the system.</p></item>
+	<item><p><c>OTP-OS-MON-MIB</c> (in <c>oc_mon</c>) contains
+	objects for instrumentation of disk, memory, and CPU use
+	of the nodes in the system.</p></item>
+	<item><p><c>OTP-SNMPEA-MIB</c> (in <c>snmp</c>)
+	contains objects for instrumentation and control of the extensible
+	SNMP agent itself. The agent also implements the standard SNMPv2-MIB
+	(or v1 part of MIB-II, if SNMPv1 is used).</p></item>
+	<item><p><c>OTP-EVA-MIB</c> (in <c>eva</c>) contains objects
+	for instrumentation and control of the events and alarms in
+	the system.</p></item>
+	<item><p><c>OTP-LOG-MIB</c> (in <c>eva</c>) contains objects
+	for instrumentation and control of the logs and FTP transfer of
+	logs.</p></item>
+	<item><p><c>OTP-EVA-LOG-MIB</c> (in <c>eva</c>) contains objects
+	for instrumentation and control of the events and alarm logs
+	in the system.</p></item>
+	<item><p><c>OTP-SNMPEA-LOG-MIB</c> (in <c>eva</c>) contains
+	objects for instrumentation and control of the SNMP audit
+	trail log in the system.</p></item>
+      </list>
+
       <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>
+      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
+      manual page for each application for a description of how
+      to load each MIB.</p>
     </section>
   </section>
 </chapter>