diff options
Diffstat (limited to 'system/doc/oam')
| -rw-r--r-- | system/doc/oam/Makefile | 21 | ||||
| -rw-r--r-- | system/doc/oam/book.xml | 21 | ||||
| -rw-r--r-- | system/doc/oam/oam_intro.xml | 412 | ||||
| -rw-r--r-- | system/doc/oam/part.xml | 21 | ||||
| -rw-r--r-- | system/doc/oam/xmlfiles.mk | 21 |
5 files changed, 242 insertions, 254 deletions
diff --git a/system/doc/oam/Makefile b/system/doc/oam/Makefile index ca07d82f75..0638a4dbd6 100644 --- a/system/doc/oam/Makefile +++ b/system/doc/oam/Makefile @@ -3,16 +3,17 @@ # # Copyright Ericsson AB 1997-2012. All Rights Reserved. # -# 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. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. # # %CopyrightEnd% # diff --git a/system/doc/oam/book.xml b/system/doc/oam/book.xml index 5f429fbee2..93f5fe344a 100644 --- a/system/doc/oam/book.xml +++ b/system/doc/oam/book.xml @@ -8,16 +8,17 @@ <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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/system/doc/oam/oam_intro.xml b/system/doc/oam/oam_intro.xml index f4f990393e..22a2080fd9 100644 --- a/system/doc/oam/oam_intro.xml +++ b/system/doc/oam/oam_intro.xml @@ -8,16 +8,17 @@ <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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -28,241 +29,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> diff --git a/system/doc/oam/part.xml b/system/doc/oam/part.xml index 9d44d6e0ad..efbaa05b94 100644 --- a/system/doc/oam/part.xml +++ b/system/doc/oam/part.xml @@ -8,16 +8,17 @@ <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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> diff --git a/system/doc/oam/xmlfiles.mk b/system/doc/oam/xmlfiles.mk index 0610bdb989..5876243466 100644 --- a/system/doc/oam/xmlfiles.mk +++ b/system/doc/oam/xmlfiles.mk @@ -3,16 +3,17 @@ # # Copyright Ericsson AB 2009. All Rights Reserved. # -# 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. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. # # %CopyrightEnd% # |