← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to system/doc/oam/oam_intro.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/oam/oam_intro.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1997</year><year>2009</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
    </legalnotice>
 
23
 
 
24
    <title>Introduction</title>
 
25
    <prepared>Martin Bj&ouml;rklund</prepared>
 
26
    <docno></docno>
 
27
    <date>1997-11-01</date>
 
28
    <rev>A</rev>
 
29
    <file>oam_intro.xml</file>
 
30
  </header>
 
31
  <p>The operation and maintenance support in OTP consists of a
 
32
    generic model for management subsystems in OTP, and some
 
33
    components to be used in these subsystems.  This document
 
34
    describes the model.
 
35
    </p>
 
36
  <p>The main idea in the model is that it is management protocol
 
37
    independent.  Thus, it is not tied to any specific management
 
38
    protocol.  An API is defined which can be used to write
 
39
    adaptations for specific management protocols.
 
40
    </p>
 
41
  <p>Each OAM component in OTP is implemented as one sub application,
 
42
    which can be included in a management application for the system.
 
43
    Note that such a complete management application is not in the
 
44
    scope of this generic functionality.  Examples illustrating how such an
 
45
    application can be built are included however.
 
46
    </p>
 
47
 
 
48
  <section>
 
49
    <title>Terminology</title>
 
50
    <p>The protocol independent architectural model on the network
 
51
      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
 
52
      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
 
53
      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
 
54
      differences to the normal client-server model.  First, there are
 
55
      usually a few managers that communicate with many agents; and
 
56
      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
 
57
      manager.  The picture below illustrates the idea.</p>
 
58
    <image file="../oam/terminology.gif">
 
59
      <icaption>Terminology</icaption>
 
60
    </image>
 
61
    <p>The manager is often referred to as the <term id="NMS"></term>, to
 
62
      emphasize that it usually is realized as a program that presents
 
63
      data to an operator.
 
64
      </p>
 
65
    <p>The agent is an entity that executes within a <term id="NE"></term>.
 
66
      In OTP, the network element may be a distributed system, meaning
 
67
      that the distributed system is managed as one entity.  Of
 
68
      course, the agent may be configured to be able to run on one of
 
69
      several nodes, making it a distributed OTP application.
 
70
      </p>
 
71
    <p>The management information is defined in an <term id="MIB"></term>.
 
72
      It is a formal definition of which information the agent makes
 
73
      available to the manager.  The manager accesses the MIB through
 
74
      a management protocol, such as SNMP, CMIP, HTTP or CORBA.  Each
 
75
      of these protocols have their own MIB definition language.  In
 
76
      SNMP, it is a subset of ASN.1, in CMIP it is GDMO, in HTTP it is
 
77
      implicit, and using CORBA, it is IDL.  Usually, the entities
 
78
      defined in the MIB are called <term id="MO"></term>, although these
 
79
      objects do not have to be objects in the OO way,for example, a simple
 
80
      scalar variable defined in an MIB is called a Managed Object.
 
81
      The Managed Objects are logical objects, not necessarily with a
 
82
      one-to-one mapping to the resources.
 
83
      </p>
 
84
  </section>
 
85
 
 
86
  <section>
 
87
    <title>Model</title>
 
88
    <p>In this section, the generic protocol independent model for use
 
89
      within an OTP based network element is presented.  This model is
 
90
      used by all operation and maintenance components, and may be
 
91
      used by the applications.  The advantage of the model is that it
 
92
      clearly separates the resources from the management protocol.
 
93
      The resources do not need to be aware of which management
 
94
      protocol is used to manage the system.  This makes it possible
 
95
      to manage the same resources with different protocols.
 
96
      </p>
 
97
    <p>The different entities involved in this model are the <term id="agent"></term>which terminates the management protocol, and the
 
98
      <term id="resources"></term>which is to be managed, i.e. the actual
 
99
      application entities.  The resources should in general have no
 
100
      knowledge of the management protocol used, and the agent should
 
101
      have no knowledge of the managed resources.  This implies that
 
102
      some sort of translation mechanism must be used, to translate
 
103
      the management operations to operations on the resources.  This
 
104
      translation mechanism is usually called
 
105
      <em>instrumentation</em>, and the function that implements it is
 
106
      called <term id="instrumentation function"></term>.  The
 
107
      instrumentation functions are written for each combination of
 
108
      management protocol and resource to be managed.  For example, if
 
109
      an application is to be managed by SNMP and HTTP, two sets of
 
110
      instrumentation functions are defined; one that maps SNMP
 
111
      requests to the resources, and one that e.g. generates an HTML
 
112
      page for some resources.
 
113
      </p>
 
114
    <p>When a manager makes a request to the agent, we have the
 
115
      following picture:</p>
 
116
    <image file="../oam/snmp_model_1.gif">
 
117
      <icaption>Request to an agent by a manager</icaption>
 
118
    </image>
 
119
    <p>Note that the mapping between instrumentation function and
 
120
      resource is not necessarily 1-1.  It is also possible to write
 
121
      one instrumentation function for each resource, and use that
 
122
      function from different protocols.
 
123
      </p>
 
124
    <p>The agent receives a request and maps this request to calls to
 
125
      one or several instrumentation functions.  The instrumentation
 
126
      functions perform operations on the resources to implement the
 
127
      semantics associated with the managed object.
 
128
      </p>
 
129
    <p>For example, a system that is managed with SNMP and HTTP may be
 
130
      structured in the following way:</p>
 
131
    <image file="../oam/snmp_model_2.gif">
 
132
      <icaption>Structure of a system managed with SNMP and HTTP</icaption>
 
133
    </image>
 
134
    <p>The resources may send notifications to the manager as well.
 
135
      Examples of notifications are events and alarms.  There is a
 
136
      need for the resource to generate protocol independent
 
137
      notifications.  The following picture illustrates how this is
 
138
      achieved:</p>
 
139
    <image file="../oam/snmp_model_3.gif">
 
140
      <icaption>Notification handling</icaption>
 
141
    </image>
 
142
    <p>The main idea is that the resource sends the notfications as
 
143
      Erlang terms to a dedicated <c>gen_event</c> process.  Into this
 
144
      process, handlers for the different management protocols are
 
145
      installed.  When an event is received by this process, it is
 
146
      forwarded to each installed handler.  The handlers are
 
147
      responsible for translating the event into a notification to be
 
148
      sent over the management protocol.  For example, a handler for
 
149
      SNMP would translate each event into an SNMP trap.
 
150
      </p>
 
151
  </section>
 
152
 
 
153
  <section>
 
154
    <title>SNMP based OAM</title>
 
155
    <p>For all OAM components, SNMP adaptations are provided.  Other
 
156
      adaptations may be defined in the future.
 
157
      </p>
 
158
    <p>The OAM components, and some other OTP applications, define
 
159
      SNMP MIBs.  All these MIBs are written in SNMPv2 SMI syntax, as
 
160
      defined in RFC1902.  For convenience we also deliver the SNMPv1
 
161
      SMI equivalent.  All MIBs are designed to be v1/v2 compatible,
 
162
      i.e. the v2 MIBs do not use any construct not available in v1.
 
163
      </p>
 
164
 
 
165
    <section>
 
166
      <title>MIB structure</title>
 
167
      <p>The top-level OTP MIB is called <c>OTP-REG</c>, and it is
 
168
        included in the <c>sasl</c> application.  All other OTP mibs
 
169
        import some objects from this MIB.
 
170
        </p>
 
171
      <p>Each MIB is contained in one application.  The MIB text files
 
172
        are stored under <c><![CDATA[mibs/<MIB>.mib]]></c> in the application
 
173
        directory. The generated <c>.hrl</c> files with constant
 
174
        declarations are stored under <c><![CDATA[include/<MIB>.hrl]]></c>, and
 
175
        the compiled MIBs are stored under
 
176
        <c><![CDATA[priv/mibs/<MIB>.bin]]></c>.  For example, the <c>OTP-MIB</c>
 
177
        is included in the <c>sasl</c> application:
 
178
        </p>
 
179
      <code type="none">
 
180
sasl-1.3/mibs/OTP-MIB.mib
 
181
         include/OTP-MIB.hrl
 
182
         priv/mibs/OTP-MIB.bin</code>
 
183
      <p>An application that needs to IMPORT this mib into another
 
184
        MIB, should use the <c>il</c> option to the snmp mib compiler:
 
185
        </p>
 
186
      <code type="none">
 
187
snmp:c("MY-MIB", [{il, ["sasl/priv/mibs"]}]).</code>
 
188
      <p>If the application needs to include the generated
 
189
        <c>.hrl</c> file, it should use the <c>-include_lib</c>
 
190
        directive to the Erlang compiler.
 
191
        </p>
 
192
      <code type="none">
 
193
-module(my_mib).
 
194
 
 
195
-include_lib("sasl/include/OTP-MIB.hrl").</code>
 
196
      <p>The following MIBs are defined in the OTP system:
 
197
        </p>
 
198
      <taglist>
 
199
        <tag>OTP-REG  (sasl)</tag>
 
200
        <item>
 
201
          <p>This MIB contains the top-level OTP registration
 
202
            objects, used by all other MIBs.
 
203
            </p>
 
204
        </item>
 
205
        <tag>OTP-TC  (sasl)</tag>
 
206
        <item>
 
207
          <p>This MIB contains the general Textual Conventions,
 
208
            which can be used by any other MIB.
 
209
            </p>
 
210
        </item>
 
211
        <tag>OTP-MIB  (sasl)</tag>
 
212
        <item>
 
213
          <p>This MIB contains objects for instrumentation of the
 
214
            Erlang nodes, the Erlang machines and the applications in
 
215
            the system.
 
216
            </p>
 
217
        </item>
 
218
        <tag>OTP-OS-MON-MIB  (os_mon)</tag>
 
219
        <item>
 
220
          <p>This MIB contains objects for instrumentation of disk,
 
221
            memory and cpu usage of the nodes in the system.
 
222
            </p>
 
223
        </item>
 
224
        <tag>OTP-SNMPEA-MIB  (snmp)</tag>
 
225
        <item>
 
226
          <p>This MIB contains objects for instrumentation and
 
227
            control of the extensible snmp agent itself.  Note that
 
228
            the agent also implements the standard SNMPv2-MIB (or v1
 
229
            part of MIB-II, if SNMPv1 is used).
 
230
            </p>
 
231
        </item>
 
232
        <tag>OTP-EVA-MIB  (eva)</tag>
 
233
        <item>
 
234
          <p>This MIB contains objects for instrumentation and
 
235
            control of the events and alarms in the system.
 
236
            </p>
 
237
        </item>
 
238
        <tag>OTP-LOG-MIB  (eva)</tag>
 
239
        <item>
 
240
          <p>This MIB contains objects for instrumentation and
 
241
            control of the logs and FTP transfer of logs.
 
242
            </p>
 
243
        </item>
 
244
        <tag>OTP-EVA-LOG-MIB  (eva)</tag>
 
245
        <item>
 
246
          <p>This MIB contains objects for instrumentation and
 
247
            control of the events and alarm logs in the system.
 
248
            </p>
 
249
        </item>
 
250
        <tag>OTP-SNMPEA-LOG-MIB  (eva)</tag>
 
251
        <item>
 
252
          <p>This MIB contains objects for instrumentation and
 
253
            control of the snmp audit trail log in the system.
 
254
            </p>
 
255
        </item>
 
256
      </taglist>
 
257
      <p>The different applications use different strategies for
 
258
        loading the MIBs into the agent.  Some MIB implementations are
 
259
        code-only, while others need a server.  One way, used by the
 
260
        code-only mib implementations, is for the user to call a
 
261
        function such as <c>otp_mib:init(Agent)</c> to load the MIB,
 
262
        and <c>otp_mib:stop(Agent)</c> to unload the MIB.  See the
 
263
        application manual page for each application for a description
 
264
        of how to load each MIB.
 
265
        </p>
 
266
    </section>
 
267
  </section>
 
268
</chapter>
 
269